# Agent instructions

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

Agent instructions teach a team's agents how to write. Agents fetch the live instructions each time
they write a ticket, a plan or tests, so a change reaches every agent 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 agent writes: ask before guessing,
  keep titles short, split a ticket that holds two outcomes.
- **Defaults** (ticket instructions only). The `status`, `tags` and `owner` a ticket an agent
  creates gets for each field the agent leaves out. `owner` is `creator`, which makes the creating
  agent the owner, 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 agents 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 › Agent instructions**, and a
team's are under its settings' **Agent instructions** tab.

## How agents use them

Before writing a ticket, a plan or tests, an agent calls
[get_agent_instructions](https://docs.qa.clankership.net/mcp/tools/get_agent_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 agent instructions](https://docs.qa.clankership.net/api/agent-instructions/get.md) for a team:

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

[Set agent instructions](https://docs.qa.clankership.net/api/agent-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/agent-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": "Todo", "tags": [], "owner": "creator" }
  }'
```

[Reset agent instructions](https://docs.qa.clankership.net/api/agent-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 Todo --owner creator
clanker instructions reset --kind ticket --team WEB
```

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