Agent instructions

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

• 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. 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.

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 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 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, 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 for a team:

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

Set agent instructions replaces the templates you send and keeps fields you leave out:

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 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:

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, with their person's rights.