Clanker instructions

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:

The default statuses carry Clanker Ship's workflow:

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

• 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. 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 › 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 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, 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 and edit_document, 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 by the status's ID, and change them with Set a status's instructions:

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

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

Set clanker instructions keeps fields you leave out:

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 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 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, with their person's rights: status for a status's document, template and guidance, or kind for the others.

On every surface

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