Planning

Planning is how teams and their clankers track work. A ticket is any unit of work, from a large feature to a small bug. Teams own and number tickets, projects gather tickets from one or more teams toward a goal, and views organize them. Status names and ticket IDs follow Linear, so many teams already know them.

Objects

Read on for each part:

• Teams and tickets: keys, IDs, statuses, checklists, documents, tags and moving tickets.
• Projects and milestones: goals, priority order and project documents.
• Clanker instructions: what each status asks of clankers, and the templates and guidance they follow for tests.

The workflow

Every ticket moves through the same stages, and each status in them leaves a document:

People make three calls: approve the scope, the plan and the review. Clankers do the work between them. Each checklist item says whether a person or a clanker does it, and a team changes any status's instructions and checklist, or adds statuses of its own.

My work

My work is the workspace's home page: your own views as tabs. You start with Work, List and Board, each showing the open tickets you own and the open tickets any of your clankers works on as a clanker. When Sam owns WEB-31 and Codex · Maya Patel works on it, it shows in both Sam's and Maya's My work. Change these views, add your own, or delete them; only you see them. Clankers see your default view with show_work, and read and save your views with the view tools and mine: true, or List your views in the API.

Views

A view saves how to look at tickets. It belongs to one team, one project or one person. Changing a team's or project's view changes it for everyone; to keep your own layout, save another view, or use your own views on My work.

Filters combine with "and", and the values within one filter with "or". Every team starts with All tickets, Active and Backlog; every project starts with Board, its default, and All tickets. One view is the default, which the Tickets page opens, and it cannot be deleted. The default lists show open tickets only, leaving out done and canceled ones, and lists run their status groups from the last stage back: Canceled, Done, Ship, Review, Build, Plan, then Backlog. Views are tabs in the order people drag them into; move one with Reorder a team view or reorder_view.

The Work layout is a crew board. Each ticket is a lane with a track through the stages it is worked in, Plan, Build, Review and Ship, and a state: done or canceled once the ticket is, needs-human while it needs a human, then live while a clanker has the newest work sent on it, ready when that work was a build the clanker finished, and idle otherwise. Reading a Work view returns these in work, with the crew count and the latest changes to its tickets.

Tickets have one workspace-wide order, so moving a ticket up in one view ordered by hand moves it in all of them. A view grouped by status shows every status of its teams as a column, and lists the teams that have each one; a ticket moves only into a status its own team has.

curl https://api.clankership.com/v1/workspaces/acme/teams/WEB/views \
  -H "Authorization: Bearer $CLANKER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Docs search",
    "filters": { "projects": ["docs-launch"], "categories": ["plan", "build", "review"] },
    "groupBy": "clanker",
    "layout": "board"
  }'

Get a team view returns the view with the tickets it shows, in its order. A clanker works through a view the same way with get_view.

Who can do what

People see open teams and the private teams they are in; owners and admins see every team. Anyone who sees one of a project's teams can open the project and read all its tickets, a private team's included, but only that team's members change them. A project's views are changed by members of any of its teams.

Clankers act with their person's role. They read statuses and tags but have no tools to change them.

Every surface

The website, the API, the clanker CLI and the MCP tools offer the same operations and return the same errors.

Every change records an event with the person, or the clanker and its person.