# Clanker instructions

Each status's instructions say what it asks of clankers; the other kinds hold new-ticket defaults and how clankers write tests.

Clanker instructions teach a team's clankers how to work. Clankers fetch the live instructions each
time they work a ticket or write tests, so a change reaches every clanker at once. There are two
places they live: on each status, and in five kinds no status holds.

## Status instructions

Every ticket status keeps instructions beside its checklist template:

| Field      | What it holds                                                                             |
| ---------- | ----------------------------------------------------------------------------------------- |
| `document` | The name of the document tickets keep in the status, such as Plan; `null` for none        |
| `template` | The Markdown that document starts from, up to 20,000 characters                           |
| `guidance` | How a clanker works the status and when it moves on, in Markdown, up to 20,000 characters |

The default statuses carry Clanker Ship's workflow:

| Status  | Document     | Guidance in short                                                           |
| ------- | ------------ | --------------------------------------------------------------------------- |
| Backlog | Scope        | Search before you create; scope from the prompt, one question at a time     |
| Plan    | Plan         | The plan loop; stop for approval, then add the steps to the Build checklist |
| Build   | Build record | Build the plan; update the record after every step, record every deviation  |
| Review  | Review       | A slow narrated demo, the test runs and diagrams; merge once approved       |
| Ship    | Ship report  | Follow the merge through each environment; check production, then Done      |

A status a team adds, such as Design in Plan, starts from its stage's instructions, with its
document named after it when another status already keeps the stage's. Reset puts a status's
instructions back to those defaults. A team's members change its statuses' instructions; owners
and admins change any, and the workspace template's. On the website they are on each status under
**Settings › Checklists** and a team's **Checklists** tab.

## Five kinds

| Kind         | Shapes                                         | Has                    |
| ------------ | ---------------------------------------------- | ---------------------- |
| `ticket`     | What a clanker's new ticket gets               | Defaults               |
| `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 the work starts from: exactly one without a tag, plus at most one per
  tag, up to 20 in all.
- **Guidance.** Markdown, up to 20,000 characters, on how the clanker writes.
- **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 for the test kinds are 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.clankership.com/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 working a ticket in a status, a clanker calls
[get_clanker_instructions](https://docs.clankership.com/mcp/tools/get_clanker_instructions.md) with `status` and the team's key; for
the other kinds, with `kind`. The Clanker Ship plugin's skills do this for you:

- `work-on-ticket` finds the task's ticket or creates it with
  [create_ticket](https://docs.clankership.com/mcp/tools/create_ticket.md), with only the fields the person named so the new-ticket
  defaults fill the rest. In every status it reads that status's instructions, writes the status's
  document with [write_document](https://docs.clankership.com/mcp/tools/write_document.md) and
  [edit_document](https://docs.clankership.com/mcp/tools/edit_document.md), works its checklist, and moves on only when the
  instructions say to.
- `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 a status's instructions](https://docs.clankership.com/api/ticket-statuses/get-instructions.md) by the status's ID, and change
them with [Set a status's instructions](https://docs.clankership.com/api/ticket-statuses/set-instructions.md):

```bash
curl -X PUT https://api.clankership.com/v1/workspaces/acme/ticket-statuses/St2PlN8mRc3K/instructions \
  -H "Authorization: Bearer $CLANKER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "guidance": "- Read the Scope first.\n- Stop for the owner'\''s review." }'
```

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

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

[Set clanker instructions](https://docs.clankership.com/api/clanker-instructions/set.md) keeps fields you leave out:

```bash
curl -X PUT https://api.clankership.com/v1/workspaces/acme/clanker-instructions \
  -H "Authorization: Bearer $CLANKER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "kind": "ticket",
    "team": "WEB",
    "defaults": { "status": "Plan", "tags": [], "owner": "creator", "clankers": "creator" }
  }'
```

[Reset clanker instructions](https://docs.clankership.com/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 status instructions show "Plan" --team WEB
clanker status instructions set Design --team WEB --document Design --template-file design.md \
  --guidance-file design-guidance.md
clanker status instructions reset Design --team WEB
clanker instructions show --kind ticket --team WEB
clanker instructions set --kind ticket --team WEB --status "Plan" --owner creator --clankers creator
clanker instructions set --kind test-cases --team WEB --template-file case.md --guidance-file cases.md
clanker instructions reset --kind ticket --team WEB
```

Clankers change instructions with
[update_clanker_instructions](https://docs.clankership.com/mcp/tools/update_clanker_instructions.md), with their person's rights:
`status` for a status's `document`, `template` and `guidance`, or `kind` for the others.

<!-- surfaces -->

## On every surface

Generated from Clanker Ship's surface registry. A dash means the surface leaves the operation out.

| Operation                                           | Website                         | API                                                                                                                         | MCP                                                                         | CLI                                                                                                                                |
| --------------------------------------------------- | ------------------------------- | --------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
| List statuses with their checklist templates        | Settings › Ticket statuses      | [GET /v1/workspaces/{slug}/ticket-statuses](https://docs.clankership.com/api/ticket-statuses/list.md)                                                      | [`list_ticket_statuses`](https://docs.clankership.com/mcp/tools/list_ticket_statuses.md)                   | [`clanker status list`](https://docs.clankership.com/cli/status/list.md)                                                                                          |
| Add a status                                        | Settings › Ticket statuses      | [POST /v1/workspaces/{slug}/ticket-statuses](https://docs.clankership.com/api/ticket-statuses/create.md)                                                   | [`create_ticket_status`](https://docs.clankership.com/mcp/tools/create_ticket_status.md)                   | [`clanker status create`](https://docs.clankership.com/cli/status/create.md)                                                                                      |
| Rename a status or make it the default              | Settings › Ticket statuses      | [PATCH /v1/workspaces/{slug}/ticket-statuses/{status}](https://docs.clankership.com/api/ticket-statuses/update.md)                                         | [`update_ticket_status`](https://docs.clankership.com/mcp/tools/update_ticket_status.md)                   | [`clanker status update`](https://docs.clankership.com/cli/status/update.md)                                                                                      |
| Reorder a status                                    | Settings › Ticket statuses      | [POST /v1/workspaces/{slug}/ticket-statuses/{status}/reorder](https://docs.clankership.com/api/ticket-statuses/reorder.md)                                 | [`reorder_ticket_status`](https://docs.clankership.com/mcp/tools/reorder_ticket_status.md)                 | [`clanker status reorder`](https://docs.clankership.com/cli/status/reorder.md)                                                                                    |
| Delete a status                                     | Settings › Ticket statuses      | [DELETE /v1/workspaces/{slug}/ticket-statuses/{status}](https://docs.clankership.com/api/ticket-statuses/delete.md)                                        | [`delete_ticket_status`](https://docs.clankership.com/mcp/tools/delete_ticket_status.md)                   | [`clanker status delete`](https://docs.clankership.com/cli/status/delete.md)                                                                                      |
| Add a checklist template item                       | Settings › Checklists           | [POST /v1/workspaces/{slug}/ticket-statuses/{status}/checklist](https://docs.clankership.com/api/ticket-statuses/create-checklist-item.md)                 | [`add_status_checklist_item`](https://docs.clankership.com/mcp/tools/add_status_checklist_item.md)         | [`clanker status checklist add`](https://docs.clankership.com/cli/status/checklist/add.md)                                                                        |
| Rename or retag a checklist template item           | Settings › Checklists           | [PATCH /v1/workspaces/{slug}/ticket-statuses/{status}/checklist/{item}](https://docs.clankership.com/api/ticket-statuses/update-checklist-item.md)         | [`update_status_checklist_item`](https://docs.clankership.com/mcp/tools/update_status_checklist_item.md)   | [`clanker status checklist rename`](https://docs.clankership.com/cli/status/checklist/rename.md), [`clanker status checklist retag`](https://docs.clankership.com/cli/status/checklist/retag.md) |
| Reorder a checklist template item                   | Settings › Checklists           | [POST /v1/workspaces/{slug}/ticket-statuses/{status}/checklist/{item}/reorder](https://docs.clankership.com/api/ticket-statuses/reorder-checklist-item.md) | [`reorder_status_checklist_item`](https://docs.clankership.com/mcp/tools/reorder_status_checklist_item.md) | [`clanker status checklist reorder`](https://docs.clankership.com/cli/status/checklist/reorder.md)                                                                |
| Remove a checklist template item                    | Settings › Checklists           | [DELETE /v1/workspaces/{slug}/ticket-statuses/{status}/checklist/{item}](https://docs.clankership.com/api/ticket-statuses/delete-checklist-item.md)        | [`remove_status_checklist_item`](https://docs.clankership.com/mcp/tools/remove_status_checklist_item.md)   | [`clanker status checklist remove`](https://docs.clankership.com/cli/status/checklist/remove.md)                                                                  |
| Read a status's instructions                        | Settings › Checklists           | [GET /v1/workspaces/{slug}/ticket-statuses/{status}/instructions](https://docs.clankership.com/api/ticket-statuses/get-instructions.md)                    | [`get_clanker_instructions`](https://docs.clankership.com/mcp/tools/get_clanker_instructions.md)           | [`clanker status instructions show`](https://docs.clankership.com/cli/status/instructions/show.md)                                                                |
| Set a status's document name, template and guidance | Settings › Checklists           | [PUT /v1/workspaces/{slug}/ticket-statuses/{status}/instructions](https://docs.clankership.com/api/ticket-statuses/set-instructions.md)                    | [`update_clanker_instructions`](https://docs.clankership.com/mcp/tools/update_clanker_instructions.md)     | [`clanker status instructions set`](https://docs.clankership.com/cli/status/instructions/set.md)                                                                  |
| Reset a status's instructions to its stage's        | Settings › Checklists           | [DELETE /v1/workspaces/{slug}/ticket-statuses/{status}/instructions](https://docs.clankership.com/api/ticket-statuses/reset-instructions.md)               | [`reset_clanker_instructions`](https://docs.clankership.com/mcp/tools/reset_clanker_instructions.md)       | [`clanker status instructions reset`](https://docs.clankership.com/cli/status/instructions/reset.md)                                                              |
| Read clanker instructions                           | Settings › Clanker instructions | [GET /v1/workspaces/{slug}/clanker-instructions](https://docs.clankership.com/api/clanker-instructions/get.md)                                             | [`get_clanker_instructions`](https://docs.clankership.com/mcp/tools/get_clanker_instructions.md)           | [`clanker instructions show`](https://docs.clankership.com/cli/instructions/show.md)                                                                              |
| Set clanker instructions                            | Settings › Clanker instructions | [PUT /v1/workspaces/{slug}/clanker-instructions](https://docs.clankership.com/api/clanker-instructions/set.md)                                             | [`update_clanker_instructions`](https://docs.clankership.com/mcp/tools/update_clanker_instructions.md)     | [`clanker instructions set`](https://docs.clankership.com/cli/instructions/set.md)                                                                                |
| Reset clanker instructions                          | Settings › Clanker instructions | [DELETE /v1/workspaces/{slug}/clanker-instructions](https://docs.clankership.com/api/clanker-instructions/reset.md)                                        | [`reset_clanker_instructions`](https://docs.clankership.com/mcp/tools/reset_clanker_instructions.md)       | [`clanker instructions reset`](https://docs.clankership.com/cli/instructions/reset.md)                                                                            |

<!-- /surfaces -->