Teams and tickets

A team is a group of workspace members that numbers its own tickets. Its key starts each ticket's ID: the Web team, key WEB, owns WEB-31 Add docs search. Each team has its own statuses and can have its own tags and views.

Teams

• key: 2–5 capital letters, unique in the workspace, such as WEB. Lowercase input is raised. Because it prefixes ticket IDs, it changes only while the team has no tickets.
• name: 1–80 characters, unique in the workspace ignoring case.
• visibility: an open team is listed for everyone, and anyone in the workspace can join it. A private team is listed only for its members and for owners and admins, and grows when a member or an admin adds people.

The person who creates a team joins it. A new team copies the workspace's status template and owns its copy, so later template changes reach only teams created afterwards. A team without tickets can be deleted; a team with tickets is archived instead, which keeps its tickets readable and takes no changes until it is restored.

Tickets

The ID is the team key and the team's next number, and numbers are never reused. Tickets are never deleted: Canceled and Duplicate are statuses. What the work is and how it is done live in the ticket's documents, such as its Scope and Plan.

Moving a ticket to another team gives it that team's next number and records the old ID, which still finds it. Its status follows by name, then by category, else the new team's default. The old team's tags come off, and it leaves its project unless the new team is linked to that project.

Ordering. Tickets have one workspace-wide order. Every view ordered by hand shows it, and reordering places a ticket right before or right after another.

Statuses

Every status belongs to one of seven fixed categories, the stages every ticket moves through. A team names its own statuses, and Clanker Ship reads the stage: which tickets are open, how far a project has come, and where a ticket lands when it moves to another team.

Owners and admins add, rename, reorder and delete statuses, in the workspace's template or in one team's set, such as an In QA status in review. A status keeps its category. A new status starts from its stage's checklist template and instructions. Every category keeps at least one status, and the default status for new tickets is a Backlog status, deleted only after another status becomes the default. Deleting a status that tickets use moves them to another status of the same team, named with moveTo.

Status instructions

Every status keeps instructions beside its checklist template: what it asks of clankers.

• Document. The name of the document its tickets keep there, such as Plan, unique within the team. Blank for a status that keeps 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: Scope in Backlog, the plan loop's Plan in Planning, a Build record in Build, the Review in Review and the Ship report in Ship. A status a team adds, such as Design in Plan, starts from its stage's instructions; its document takes the stage's name, or the status's own when another status already keeps that one. Reset puts a status's instructions back to these defaults. A team's members change its statuses' instructions; owners and admins change any, and the workspace template's.

Clankers read a status's instructions with get_clanker_instructions and status, and change them with update_clanker_instructions.

Checklists

A ticket keeps its own checklists, one for each status of its team, of what has to be done there. A status can hold a checklist template. The first time a ticket enters the status, its checklist for that status starts as a copy of the template, or empty when the status has none. From then on the items are the ticket's own: people and clankers add, rename, reorder, remove, start and check them. Changing a template reaches only tickets that enter the status afterwards, and a ticket that comes back to a status keeps the checklist it had.

An item is not started, in progress or done. Starting an item marks it in progress and shows who started it; checking it shows who checked it and when; clearing it takes it back to not started. Starting a done item takes it back to work. On the ticket page, clicking an item's checkbox moves it on: not started, in progress, done, then not started again. A clanker marks a Clanker item in progress when it starts it, so the ticket shows what is being worked.

Every item says who does it: human, such as an approval or a review, or clanker, the default. People check any item. A clanker does Clanker items, and hands one over by tagging it Human. A Human item is a person's: a clanker checks one only when its own person approves it in their conversation, passing the person's words as approval, and the item then shows who approved it, through which clanker, and what they said. A clanker cannot clear, start, stop, rename, retag or remove a Human item.

A ticket can also start a checklist for a status it has not reached yet, such as listing Build tasks during Plan. Items are added in batches, all or none. A checklist or template holds up to 30 items of up to 120 characters, each title once. Open items do not stop a status change.

New workspaces start with these templates:

In My work's Work layout, each lane's track fills the stages before the ticket's, and fills its own stage's stretch by the share of the ticket's items for that stage that are done, then in amber by the share in progress. The ticket page's tab for the ticket's status shows the same shares. Moving a ticket to another team takes its checklists along to the matching statuses. Deleting a status moves tickets' checklists for it to the status its tickets move to.

Name an item by its ID, or by its title when only one of the ticket's checklists has it. Start or check one with Update a checklist item: inProgress: true starts it, done: true checks it and done: false clears it.

curl -X PATCH "https://api.clankership.com/v1/workspaces/acme/tickets/WEB-31/checklist/Index%20drafts" \
  -H "Authorization: Bearer $CLANKER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "inProgress": true }'

Documents

A ticket keeps a document for each status of its team that keeps one: by default its Scope, Plan, Build record, Review and Ship report. A document is Markdown up to 200,000 characters. One nobody has written yet reads as its status's template at revision 0, and every write makes the next revision, kept with who wrote it.

Each write names the revision it was made from with baseRevision. A write from an older revision than the latest answers 409 and names the latest, so nobody overwrites a change they have not seen. Edit a document replaces exact passages, all or none; each must appear once in that revision. Name a document by its name or slug, such as build-record. A document keeps its name and stage, so it stays on the ticket when its status is deleted or the ticket moves to a team without a status that keeps it.

Write a document:

curl -X PUT https://api.clankership.com/v1/workspaces/acme/tickets/WEB-31/documents/scope \
  -H "Authorization: Bearer $CLANKER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "body": "## Goal\nReaders find any docs page from the header.", "baseRevision": 0 }'

Needs human

A ticket needs a human when it waits on a person:

Nobody sets it. Clanker Ship works it out from the ticket each time it is read, so checking the last Human item, answering the question or sending new work clears it, and the status stays as it is. Backlog's Human items, such as Scope approved, never set it, and done and canceled tickets never need a human. Every ticket carries needsHuman: its reasons, the waiting Human items, the open questions and the work that came back, or null.

On the website it shows as a banner on the ticket page and a badge on list rows, board cards and Work lanes, and a view can filter to the tickets that need a human. The ticket's owner gets a notification when someone asks a question on it, and when someone else's change, or one of their own clankers', leaves only Human items on its current checklist.

Questions

A clanker asks with ask_human when it needs a decision it cannot make: a question of up to 1,000 characters and up to four suggested answers. Asking again on the same ticket replaces its own open question. People answer on the ticket page's banner, choosing a suggested answer or writing another, and a clanker records its person's answer from their conversation with answer_question. The answer, up to 2,000 characters, goes on the ticket as a comment that quotes the question, and the asking clanker gets it in its inbox. With several open questions, name the one you answer by its ID.

Branch links

A ticket links to the branches it is worked on, each a repository as owner/name and a branch name. The plugin's hook reports each session's repository and branch, and Clanker Ship answers with the branch's tickets: the linked ones first, then the ticket whose ID the branch's name carries, such as WEB-31 in codex/web-31-promo. The hook adds a line about each to the clanker's prompt. Clankers link a branch with link_ticket_branch; the ticket page lists a ticket's branches and unlinks one.

Pull requests

A ticket links the GitHub pull requests its work is in, up to 10. Name one by its link, such as https://github.com/acme/web/pull/142, or as acme/web#142. Linking one the ticket already has changes nothing, and one pull request can link to several tickets. The ticket page lists them under Branches, each opening on GitHub, with Link pull request and an unlink button for people who change the ticket. Clankers link the pull request they open at the end of Build with link_ticket_pull_request, and Review and Ship merge and follow each linked pull request. Clanker Ship does not read GitHub, so a pull request shows no title or state on the ticket.

Tags

New workspaces start with the tags bug, feature and tech debt. A tag belongs to the workspace and works on every ticket, or belongs to one team and works only on that team's tickets. A tag name names one tag on any ticket, so a team tag cannot share a workspace tag's name. Colors are gray, red, orange, amber, green, teal, cobalt, iris and pink.

Renaming or deleting a status, a tag, a project slug or a team key updates the saved view filters that name it.

Create and change tickets

Paths are relative to https://api.clankership.com/v1/workspaces/{slug}. Teams are named by key, projects by slug and tickets by ID. PATCH changes only the fields you send, and null clears an optional field.

Create a ticket:

curl https://api.clankership.com/v1/workspaces/acme/tickets \
  -H "Authorization: Bearer $CLANKER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "team": "WEB",
    "title": "Add docs search",
    "project": "docs-launch",
    "tags": ["feature"]
  }'

The response is the ticket, with status 201, its identifier such as WEB-31, and its status, tags and project. Change its status by name with Update a ticket:

curl -X PATCH https://api.clankership.com/v1/workspaces/acme/tickets/WEB-31 \
  -H "Authorization: Bearer $CLANKER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "status": "Build" }'

Lists return every ticket the caller can read, without documents or checklists; see Pagination. query finds tickets whose title or Scope holds the words, or whose ID starts with them, open ones first.

CLI

clanker team list
clanker team create WEB --name Web
clanker ticket create --team WEB --title "Add docs search" --project docs-launch --tag feature
clanker ticket get WEB-31
clanker ticket doc show WEB-31 scope
clanker ticket update WEB-31 --status "Build"
clanker ticket list --team WEB --owner me --category plan,build,review
clanker ticket list --query "docs search"
clanker ticket list --needs-human
clanker ticket answer WEB-31 "Use the built-in index"
clanker ticket branch link WEB-31
clanker ticket pr link WEB-31 https://github.com/acme/web/pull/142
clanker ticket move WEB-31 --team DOCS
clanker ticket reorder WEB-31 --before WEB-29
clanker ticket checklist add WEB-31 "Search works offline" "Index drafts" --status "Build"
clanker ticket checklist start WEB-31 "Index drafts"
clanker ticket checklist stop WEB-31 "Index drafts"
clanker ticket checklist check WEB-31 "Plan approved"
clanker ticket doc write WEB-31 scope --file scope.md
clanker ticket doc edit WEB-31 plan --old "at build time" --new "at build time, skipping drafts"
clanker ticket doc history WEB-31 plan
clanker status create "In QA" --category review --team WEB
clanker status checklist add <status-id> "Design review" --doer human
clanker status instructions show "Plan" --team WEB
clanker status instructions set Design --team WEB --document Design --guidance-file design.md
clanker tag create search --color teal --team WEB

Clankers

Clankers use create_ticket, update_ticket, move_ticket and the other planning tools with their person's role. An clanker adds itself to a ticket's clankers with "clankers": ["me"], and names its person as the owner with "owner": "me". A ticket a clanker creates takes the status, tags, owner and clankers it leaves out from the team's clanker instructions, and a ticket with no team goes to the clanker's default team. Clankers keep a ticket's checklists with add_checklist_item and update_checklist_item, which starts and checks an item as the clanker and its person, and write its documents with get_document, write_document and edit_document. They read checklist templates with list_ticket_statuses but do not change them; they change a status's instructions with update_clanker_instructions. They ask their person for decisions with ask_human, link the branch they work on with link_ticket_branch, and find the tickets that need a human with list_tickets and needsHuman. The plugin's work-on-ticket skill does all of this for any task.

On every surface

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