Planning

Planning tracks work as tickets:

• A team groups workspace members and numbers its tickets with its key, such as WEB-31. Open teams are listed for everyone; private teams only for their members.
• A ticket is any unit of work. It has a title, a Markdown summary, a Markdown plan (the document an agent implements), a status, tags, an owner agent, and at most one project and milestone.
• A project gathers tickets from one or more teams toward a goal. It has a status, a lead, an optional targetDate, linked teams and products, numbered milestones (M1, M2) and a Markdown document.
• Every status belongs to a category: backlog, unstarted, started, completed or canceled. The defaults are Backlog, Todo, In Progress, In Review, Done, Canceled and Duplicate. A new team copies the workspace's statuses and owns its copy.
• Tags belong to the workspace, or to one team and only its tickets.
• Agent instructions teach a team's agents to write tickets and plans: a template per kind (and optionally per tag), guidance, and for tickets the defaults an agent's new ticket gets. A team's own replace the workspace's, which replace Clanker Ship's.
• A view saves filters, a groupBy, an orderBy and a layout (list or board) for one team or one project. Teams start with All tickets, Active and Backlog; projects with Board and All tickets. The default view opens when no view is named.

Rules

• Team keys are 2–5 capital letters and change only while the team has no tickets. Ticket numbers are never reused.
• A ticket joins a project only when its team is linked to the project, and a milestone only from its own project. A team stays linked to a project while the project holds its tickets.
• Moving a ticket to another team gives it a new ID; the old ID still finds it.
• Archived projects are read-only. A team with tickets is archived, not deleted.
• Viewers read. Members change tickets, projects and milestones. Owners and admins create teams, change keys and visibility, and change workspace tags; team members change their team's tags and members.
• Anyone who can open a project reads all its tickets, a private team's included, but only the team's members change them.
• Every category keeps at least one status. The default status for new tickets is a Backlog or Unstarted status and cannot be deleted. Deleting a status that tickets use needs moveTo, another status of the same team.
• Owners and admins change statuses. Members of a view's team, or of one of a project's teams, change its views; the default view cannot be deleted.
• Tickets have one order. Every view ordered by hand (manual) shows it, and reorder moves a ticket before or after another.

Views

Filters combine with "and", values within one filter with "or". A project grouped by status uses its teams' statuses as columns when they match and the five categories when they differ.

HTTP

Paths are relative to /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.

POST /v1/workspaces/acme/tickets
Authorization: Bearer ctk_…

{ "team": "WEB", "title": "Stacked promo codes fail at checkout", "tags": ["bug"] }

The response is the ticket with its ID, such as WEB-31. Change its status by name:

PATCH /v1/workspaces/acme/tickets/WEB-31

{ "status": "In Progress" }

Save a view, then read it with its tickets:

POST /v1/workspaces/acme/teams/WEB/views

{ "name": "Checkout bugs", "filters": { "tags": ["bug"], "projects": ["checkout-v2"] }, "layout": "board" }

GET /v1/workspaces/acme/teams/WEB/views/checkout-bugs

CLI

clanker team list
clanker ticket create --team WEB --title "Stacked promo codes fail at checkout" --tag bug
clanker ticket update WEB-31 --status "In Progress"
clanker ticket move WEB-31 --team PAY
clanker project create checkout-v2 --name "Checkout v2" --team WEB --team PAY
clanker milestone create checkout-v2 --name Wallets
clanker ticket reorder WEB-31 --before WEB-29
clanker status create "In QA" --category started --team PAY
clanker view create "Checkout bugs" --team WEB --tag bug --in-project checkout-v2 --layout board
clanker view show checkout-bugs --team WEB
clanker instructions show --kind ticket --team WEB
clanker instructions set --kind ticket --team WEB --tag-template-file bug=bug.md --owner creator

Agents

The MCP tools mirror the HTTP operations: list_teams, get_team, create_team, update_team, join_team, add_team_member, remove_team_member, list_projects, get_project, create_project, update_project, reorder_project, archive_project, restore_project, create_milestone, update_milestone, delete_milestone, list_tickets, get_ticket, create_ticket, update_ticket, move_ticket, reorder_ticket, list_views, get_view, create_view, update_view, delete_view, list_ticket_statuses, list_tags, list_agents, get_agent_instructions and update_agent_instructions. Agents act with their person's role; an agent of a member cannot create a team. An agent names itself as a ticket's owner with "owner": "me", and works through a view with get_view, such as "work through the Checkout bugs view".

Before writing a ticket or a plan, an agent calls get_agent_instructions with the kind and the team. A ticket an agent creates gets the instructions' default status, tags and owner for what it leaves out. The plugin's create-ticket and write-plan skills do this.

show_work, show_ticket and show_inbox answer with My work, a ticket or the agent's inbox. Clients with MCP Apps draw them as screens the person can act on; others get text with the website link. See Agents and MCP.