# Planning Teams, tickets, projects and views track the work; each status's documents, checklists and instructions say what it takes. 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 | Object | Meaning | | ------------ | ----------------------------------------------------------------------------------------------------------------- | | Team | A group of workspace members that numbers its own tickets, such as WEB | | Ticket | The unit of work, such as `WEB-31`: a title, a status, tags, an owner and clankers, with checklists and documents | | Project | A body of work with a goal, such as `docs-launch`; it links teams and the products it changes | | Milestone | A numbered step within a project: M1, M2 | | Status | Where a ticket is, such as Build; every status belongs to one of seven stages and keeps its own instructions | | Document | A ticket's Markdown for one status, such as its Scope or Plan, with revisions | | Tag | A colored label on tickets, such as `bug` | | View | A saved filter, grouping, order and layout for one team's or one project's tickets | | Clanker | A clanker working for a member, shown as client and person: Codex · Maya Patel | | Instructions | What each status asks of clankers, new-ticket defaults, and how clankers write tests | Read on for each part: - [Teams and tickets](https://docs.clankership.com/get-started/concepts/planning/tickets.md): keys, IDs, statuses, checklists, documents, tags and moving tickets. - [Projects and milestones](https://docs.clankership.com/get-started/concepts/planning/projects.md): goals, priority order and project documents. - [Clanker instructions](https://docs.clankership.com/get-started/concepts/planning/clanker-instructions.md): 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: | Stage | Default status | Document | Moves on when | | -------- | -------------- | ------------ | ----------------------------------------------------------------------------- | | Backlog | Backlog | Scope | A person approves the scope and wants it built now | | Planning | Plan | Plan | A person approves the plan and its test cases | | Build | Build | Build record | Every Build checklist item is checked and the pull request is open and linked | | Review | Review | Review | A person approves the review, and the clanker merges | | Ship | Ship | Ship report | The change is seen working in production | | Done | Done | — | — | 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](https://docs.clankership.com/mcp/tools/show_work.md), and read and save your views with the view tools and `mine: true`, or [List your views](https://docs.clankership.com/api/views/list-mine.md) 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. | Field | Values | | --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `filters` | `statuses`, `categories`, `tags`, `owners` (user IDs, `me` or `none`), `clankers` (clanker IDs, `mine` or `none`), `mine: true` and `needsHuman: true`, plus `projects` for team views, `milestones` (`M1`, `none`) and `teams` for project views, or `projects` and `teams` for your own views | | `groupBy` | `status`, `category`, `owner`, `clanker`, `tag` or `none`, plus `project` for team views, `milestone` and `team` for project views, or `project` and `team` for your own views | | `orderBy` | `manual` (the order people set by hand), `created` (newest first) or `updated` (most recently changed) | | `layout` | `list`, `board` or `work`; a board's columns are the groups, and work shows each ticket as a lane with its state | 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](https://docs.clankership.com/api/views/reorder-for-team.md) or [reorder_view](https://docs.clankership.com/mcp/tools/reorder_view.md). 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](https://docs.clankership.com/get-started/concepts/planning/tickets.md#needs-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. ```bash 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](https://docs.clankership.com/api/views/get-for-team.md) returns the view with the tickets it shows, in its order. A clanker works through a view the same way with [get_view](https://docs.clankership.com/mcp/tools/get_view.md). ## Who can do what | Action | Viewer | Member | Admin, owner | | --------------------------------------------------------- | ------ | ----------- | ------------ | | Read teams, projects and tickets they can see | yes | yes | yes | | Create and change tickets, projects and milestones | no | yes | yes | | Join an open team, leave a team | yes | yes | yes | | Add or remove team members | no | in the team | yes | | Change team tags and save, change or delete team views | no | in the team | yes | | Change a team's clanker instructions | no | in the team | yes | | Change ticket statuses and workspace tags | no | no | yes | | Change the workspace's clanker instructions | no | no | yes | | Create teams, change keys and visibility, archive, delete | no | no | yes | 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. | Operation | API (`/v1/workspaces/{slug}`) | MCP | CLI | | ----------------------- | ---------------------------------------------------------- | -------------------------------------------------------------------------------------------- | ------------------------------------------ | | Teams | [Teams](https://docs.clankership.com/api/teams.md) | [list_teams](https://docs.clankership.com/mcp/tools/list_teams.md), [create_team](https://docs.clankership.com/mcp/tools/create_team.md) | `clanker team …` | | Tickets | [Tickets](https://docs.clankership.com/api/tickets.md) | [list_tickets](https://docs.clankership.com/mcp/tools/list_tickets.md), [create_ticket](https://docs.clankership.com/mcp/tools/create_ticket.md) | `clanker ticket …` | | Projects and milestones | [Projects](https://docs.clankership.com/api/projects.md), [Milestones](https://docs.clankership.com/api/milestones.md) | [create_project](https://docs.clankership.com/mcp/tools/create_project.md), [create_milestone](https://docs.clankership.com/mcp/tools/create_milestone.md) | `clanker project …`, `clanker milestone …` | | Views | [Views](https://docs.clankership.com/api/views.md) | [list_views](https://docs.clankership.com/mcp/tools/list_views.md), [create_view](https://docs.clankership.com/mcp/tools/create_view.md) | `clanker view …` | | Statuses and tags | [Ticket statuses](https://docs.clankership.com/api/ticket-statuses.md), [Tags](https://docs.clankership.com/api/tags.md) | [list_ticket_statuses](https://docs.clankership.com/mcp/tools/list_ticket_statuses.md), [list_tags](https://docs.clankership.com/mcp/tools/list_tags.md) | `clanker status …`, `clanker tag …` | | Clanker instructions | [Clanker instructions](https://docs.clankership.com/api/clanker-instructions.md) | [get_clanker_instructions](https://docs.clankership.com/mcp/tools/get_clanker_instructions.md) | `clanker instructions …` | Every change records an event with the person, or the clanker and its person.