# Clanker instructions

Templates, guidance and defaults teach a team's clankers how to write tickets, plans and tests.

Clanker instructions teach a team's clankers how to write. Clankers fetch the live instructions each time
they write a ticket, a plan or tests, so a change reaches every clanker at once.

## Six kinds

| Kind         | Shapes                                         | Has                              |
| ------------ | ---------------------------------------------- | -------------------------------- |
| `ticket`     | A new ticket's summary                         | Templates, guidance and defaults |
| `plan`       | A ticket's plan                                | Templates and guidance           |
| `test-cases` | Test cases, one Markdown file each             | Templates and guidance           |
| `test-code`  | The Playwright specs generated from test cases | Templates and guidance           |
| `fixtures`   | A product's Fixture API and its `TESTING.md`   | Templates and guidance           |
| `test-ci`    | The CI workflow that runs a product's tests    | Templates and guidance           |

- **Templates.** The Markdown a summary or plan starts from: exactly one without a tag, plus at most
  one per tag, up to 20 in all. A ticket uses the template of its first tag that has one, such as a
  `bug` template with steps to reproduce, else the template without a tag.
- **Guidance.** Markdown, up to 20,000 characters, on how the clanker writes: ask before guessing,
  keep titles short, split a ticket that holds two outcomes.
- **Defaults** (ticket instructions only). The `status`, `tags`, `owner` and `clankers` a ticket
  a clanker creates gets for each field the clanker leaves out. `owner` is `creator`, which makes the
  person the creating clanker works for the owner, or `none`; `clankers` is `creator`, which makes
  the creating clanker its one clanker, or `none`. A `null` status means the team's default status, and a workspace
  default naming a status a team does not have leaves that team's default.

Defaults apply only to tickets clankers create. Tickets created on the website or through the API get
exactly the fields they are given, and the team's default status.

## Where they come from

Clanker Ship's defaults are a ticket template with Problem, Outcome, Scope and Notes, Clanker
Ship's plan loop for plans, and for the test kinds a case file, a spec, a `TESTING.md` and a CI
workflow that name no product. The test defaults write every case to run in every environment,
production included, with its data made through the product's Fixture API; see
[Test runs](https://docs.qa.clankership.net/get-started/concepts/test-runs.md#test-data). A workspace's own instructions replace Clanker Ship's, and a team's own
replace the workspace's, whole. The first change to a team copies what it inherits, and resetting
goes back to the inherited set. The `source` field says which set applies: `team`, `workspace` or
`default`.

| Who               | Changes                          |
| ----------------- | -------------------------------- |
| Owners and admins | The workspace's and every team's |
| Members of a team | That team's                      |
| Viewers           | Nothing                          |

On the website, the workspace's instructions are under **Settings › Clanker instructions**, and a
team's are under its settings' **Clanker instructions** tab.

## How clankers use them

Before writing a ticket, a plan or tests, a clanker calls
[get_clanker_instructions](https://docs.qa.clankership.net/mcp/tools/get_clanker_instructions.md) with the `kind` and the team's key. The
Clanker Ship plugin's skills do this for you:

- `create-ticket` reads the ticket instructions, writes the summary from the template, and calls
  [create_ticket](https://docs.qa.clankership.net/mcp/tools/create_ticket.md) with only the fields the person named, so the defaults
  fill the rest.
- `write-plan` reads the ticket and the plan instructions, writes the plan from the template, saves
  it with [update_ticket](https://docs.qa.clankership.net/mcp/tools/update_ticket.md), and waits for the person to approve it.
- `test-case-writing` reads the `test-cases` instructions, proposes case titles, and writes the
  cases once the person approves them.
- `test-code-generation` reads the `test-code` instructions and generates a spec for each approved
  case.
- `set-up-testing` reads the `fixtures` and `test-ci` instructions, builds the product's Fixture API,
  sets each deployment's fixture URL, and adds `TESTING.md` and CI.

## Read and set them

[Get clanker instructions](https://docs.qa.clankership.net/api/clanker-instructions/get.md) for a team:

```bash
curl "https://api.clankertest.com/v1/workspaces/acme/clanker-instructions?kind=ticket&team=WEB" \
  -H "Authorization: Bearer $CLANKER_API_KEY"
```

[Set clanker instructions](https://docs.qa.clankership.net/api/clanker-instructions/set.md) replaces the templates you send and keeps
fields you leave out:

```bash
curl -X PUT https://api.clankertest.com/v1/workspaces/acme/clanker-instructions \
  -H "Authorization: Bearer $CLANKER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "kind": "ticket",
    "team": "WEB",
    "templates": [
      { "tag": null, "body": "## Problem\nWhat is wrong or missing, and for whom.\n\n## Outcome\nWhat is true when this ticket is done." },
      { "tag": "bug", "body": "## Steps to reproduce\n\n## Expected\n\n## Actual" }
    ],
    "defaults": { "status": "In Planning", "tags": [], "owner": "creator", "clankers": "creator" }
  }'
```

[Reset clanker instructions](https://docs.qa.clankership.net/api/clanker-instructions/reset.md) with `DELETE` and the same `kind` and
`team` query parameters removes the team's own set, so it follows the workspace's again.

The CLI reads templates and guidance from files:

```bash
clanker instructions show --kind ticket --team WEB
clanker instructions set --kind ticket --team WEB --template-file ticket.md \
  --tag-template-file bug=bug.md --guidance-file guidance.md --status "In Planning" --owner creator --clankers creator
clanker instructions reset --kind ticket --team WEB
```

Clankers change instructions with
[update_clanker_instructions](https://docs.qa.clankership.net/mcp/tools/update_clanker_instructions.md), with their person's rights.