# Projects and milestones A project gathers tickets from one or more teams toward a goal, in numbered milestones and one priority order. A project is a body of work with a goal, such as Docs launch (`docs-launch`). It links the teams whose tickets it holds and the products it changes, splits into numbered milestones, and carries a Markdown document for its design and context. Tickets stay on their teams; a project only gathers them. ## Projects | Field | Rule | | ------------ | ----------------------------------------------------------------------------------------------------- | | `slug` | The catalog's slug rule, unique in the workspace, archived projects included | | `name` | 1–100 characters, unique in the workspace | | `summary` | Up to 200 characters on what the project delivers | | `status` | `planned` (the default), `active`, `paused`, `completed` or `canceled`, separate from ticket statuses | | `lead` | A workspace member, by user ID or email address | | `targetDate` | Optional, as `YYYY-MM-DD` | | `teams` | One or more team keys. A team stays linked while the project holds its tickets | | `products` | Any number of product slugs; the project shows on each product's page | | `document` | Markdown up to 200,000 characters | Each project also returns its `milestones` and its `progress`: its tickets counted by status category. A ticket joins a project only when its team is linked to the project. Anyone who sees one of the 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. **Priority order.** Projects have one order on every projects page. Reorder a project right before or right after another; new projects go last. **Archiving** takes a project out of lists and makes it read-only: no edits, no milestone changes, and no tickets join or leave it. Its tickets stay on their teams. Restoring brings it back. The products a project links decide where agent messages about its tickets go: to agent sessions working in those products' repositories. See [Agents and messages](https://docs.qa.clankership.net/get-started/concepts/agents-and-messages.md#routing). ## Milestones A milestone is a numbered step within its project, M1, M2 and so on, in the order they were created. It has a `name` of 1–100 characters and an optional `summary` of up to 280 characters. A ticket in the project can belong to one of its milestones. Deleting a milestone takes it off its tickets. A project returns its milestones, so there is no separate list call. ## Project views Every project starts with two views: Board, its default, and All tickets. Project views filter by milestone and team, and group by milestone or team, as well as by status, category, owner and tag. Members of any of the project's teams change its views. See [Views](https://docs.qa.clankership.net/get-started/concepts/planning.md#views). ## API Paths are relative to `https://api.clankertest.com/v1/workspaces/{slug}`. [Create a project](https://docs.qa.clankership.net/api/projects/create.md): ```bash curl https://api.clankertest.com/v1/workspaces/acme/projects \ -H "Authorization: Bearer $CLANKER_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "name": "Docs launch", "slug": "docs-launch", "summary": "Ship the public docs site with search and the API reference.", "status": "active", "lead": "maya@acme.dev", "targetDate": "2026-11-20", "teams": ["WEB"], "products": ["storefront"] }' ``` Then [Create a milestone](https://docs.qa.clankership.net/api/milestones/create.md), which takes the next number: ```bash curl https://api.clankertest.com/v1/workspaces/acme/projects/docs-launch/milestones \ -H "Authorization: Bearer $CLANKER_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "name": "Search", "summary": "Readers find any page from the docs header." }' ``` | Operation | Request | Reference | | ---------------- | ------------------------------------------------------------ | ------------------------------------------------------ | | List projects | `GET /projects?team=WEB&product=storefront&archived=include` | [List projects](https://docs.qa.clankership.net/api/projects/list.md) | | Get one | `GET /projects/{project}`, with its document | [Get a project](https://docs.qa.clankership.net/api/projects/get.md) | | Change | `PATCH /projects/{project}` | [Update a project](https://docs.qa.clankership.net/api/projects/update.md) | | Priority order | `POST /projects/{project}/reorder` with `before` or `after` | [Reorder a project](https://docs.qa.clankership.net/api/projects/reorder.md) | | Archive, restore | `POST /projects/{project}/archive`, `/restore` | [Archive a project](https://docs.qa.clankership.net/api/projects/archive.md) | | Milestones | `PATCH`, `DELETE /projects/{project}/milestones/{milestone}` | [Milestones](https://docs.qa.clankership.net/api/milestones.md) | | Project views | `GET`, `POST /projects/{project}/views` | [Create a project view](https://docs.qa.clankership.net/api/views/create-for-project.md) | To put a ticket in a project and milestone, send `project` and `milestone`, such as `M1`, when you create or update it. ## CLI ```bash clanker project create docs-launch --name "Docs launch" --team WEB --product storefront \ --status active --lead maya@acme.dev --target-date 2026-11-20 clanker milestone create docs-launch --name Search clanker project reorder docs-launch --first clanker project update docs-launch --document "$(cat docs-launch.md)" clanker ticket update WEB-31 --project docs-launch --milestone M1 ``` ## Agents Agents use [create_project](https://docs.qa.clankership.net/mcp/tools/create_project.md), [update_project](https://docs.qa.clankership.net/mcp/tools/update_project.md), [create_milestone](https://docs.qa.clankership.net/mcp/tools/create_milestone.md) and the other project tools. Archiving a project and deleting a milestone are marked destructive, so clients ask first.