# Teams and tickets Teams own and number tickets, and each ticket moves through its team's statuses with tags and an agent owner. 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 | Field | Rule | | ----------- | ------------------------------------------------------------------------------ | | `title` | 1–200 characters | | `summary` | Markdown up to 2,000 characters on what and why | | `plan` | Markdown up to 200,000 characters: the document an agent implements | | `status` | One of the team's statuses, by name; new tickets get the team's default status | | `owner` | An agent, by ID, or none. The agent's person sees the ticket in My work | | `tags` | Workspace tags and the team's own tags; another team's tag is refused | | `project` | At most one, and only a project linked to the ticket's team | | `milestone` | At most one, from the ticket's project. Changing the project clears it | 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. **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 five fixed categories: | Category | Default statuses | Meaning | | ----------- | ---------------------- | ----------------------------------------------- | | `backlog` | Backlog (the default) | Captured, not yet committed to | | `unstarted` | Todo | Committed to and ordered, not yet picked up | | `started` | In Progress, In Review | Being worked on, or in review in a pull request | | `completed` | Done | Shipped and accepted | | `canceled` | Canceled, Duplicate | Will not be done, or another ticket covers it | Owners and admins add, rename, reorder and delete statuses, in the workspace's template or in one team's set. A status keeps its category. Every category keeps at least one status, and the default status for new tickets is a Backlog or Unstarted 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`. ## 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.clankertest.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](https://docs.qa.clankership.net/api/tickets/create.md): ```bash curl https://api.clankertest.com/v1/workspaces/acme/tickets \ -H "Authorization: Bearer $CLANKER_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "team": "WEB", "title": "Add docs search", "summary": "Readers cannot find a page without browsing the sidebar. Add a search box to the docs header.", "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](https://docs.qa.clankership.net/api/tickets/update.md): ```bash curl -X PATCH https://api.clankertest.com/v1/workspaces/acme/tickets/WEB-31 \ -H "Authorization: Bearer $CLANKER_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "status": "In Progress" }' ``` | Operation | Request | Reference | | ------------------------- | ------------------------------------------------------------- | ------------------------------------------ | | List tickets | `GET /tickets?team=WEB&owner=mine&category=unstarted,started` | [List tickets](https://docs.qa.clankership.net/api/tickets/list.md) | | Get one, with its plan | `GET /tickets/{ticket}` | [Get a ticket](https://docs.qa.clankership.net/api/tickets/get.md) | | Move to another team | `POST /tickets/{ticket}/move` with `team` | [Move a ticket](https://docs.qa.clankership.net/api/tickets/move.md) | | Reorder | `POST /tickets/{ticket}/reorder` with `before` or `after` | [Reorder a ticket](https://docs.qa.clankership.net/api/tickets/reorder.md) | | Teams | `GET`, `POST /teams`; `GET`, `PATCH`, `DELETE /teams/{team}` | [Teams](https://docs.qa.clankership.net/api/teams.md) | | Join, add, remove members | `POST /teams/{team}/join`, `POST /teams/{team}/members` | [Add a team member](https://docs.qa.clankership.net/api/teams/add-member.md) | | Statuses | `GET /ticket-statuses?team=WEB`, `POST /ticket-statuses` | [Ticket statuses](https://docs.qa.clankership.net/api/ticket-statuses.md) | | Tags | `GET /tags?team=WEB`, `POST /tags` | [Tags](https://docs.qa.clankership.net/api/tags.md) | Lists return every ticket the caller can read, without plans; see [Pagination](https://docs.qa.clankership.net/api/pagination.md). ## CLI ```bash 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 update WEB-31 --status "In Progress" clanker ticket list --team WEB --owner mine --category unstarted,started clanker ticket move WEB-31 --team DOCS clanker ticket reorder WEB-31 --before WEB-29 clanker status create "In QA" --category started --team WEB clanker tag create search --color teal --team WEB ``` ## Agents Agents use [create_ticket](https://docs.qa.clankership.net/mcp/tools/create_ticket.md), [update_ticket](https://docs.qa.clankership.net/mcp/tools/update_ticket.md), [move_ticket](https://docs.qa.clankership.net/mcp/tools/move_ticket.md) and the other planning tools with their person's role. An agent names itself as a ticket's owner with `"owner": "me"`. A ticket an agent creates takes the status, tags and owner it leaves out from the team's [agent instructions](https://docs.qa.clankership.net/get-started/concepts/planning/agent-instructions.md), and a ticket with no team goes to the agent's default team.