How the spec workflow works
Follow one change from a staged edit to Main, your repository and deployed code: workstream, proposal, task, publish, work items, and who may do each step.
The rules
- Main is read-only. Only a task that publishes changes it.
- Agents stage, people decide. A person accepts what agents staged, answers their questions and decides when a task is Ready. A project with Agent autonomy on lets agents with read and write access take those acts too; publishing stays a person's.
- The system does the known steps. A step whose outcome is already known is done by the system: publishing moves a Ready task to In progress, a landing marks it Done, a proposal with nothing pending completes itself, a merged pull request that names a work item completes it, and a deployment completes the deploy item.
- Status is derived. Build status, delivery and milestone progress are worked out from these facts each time you look; nobody ticks a box.
The path of one change
A workstream opens
Someone opens
WS-3for the story. Its view starts equal to Main.The spec changes in the workstream
A person edits an artefact on its page: the edit is written to the workstream at once and the artefact becomes a change. An agent calls
spec_apply: its documents are staged as revisions in the workstream's proposal and wait.A person accepts
In Proposals a person accepts each staged revision (or all, or a whole plan). Accepting writes it to the workstream, where it becomes a change like a person's edit. Withdrawn revisions never reach the workstream.
Changes are agreed in a task
Changes lists what differs from Main. A person scopes changes into a task (
T-4) and marks it Ready: the task records the revision of each scoped artefact, its agreement. A Draft task follows edits to its scoped artefacts, and an edit joins your current task by itself. After Ready, an edit leaves the task stale (it keeps its agreed revision) until someone runs Update T-4, which moves the agreement to the latest revisions. A blocking question holds Ready until it is answered, and a project can require that someone other than the accepter marks Ready.Publish
Publish takes the agreement, rebases it over Main where nothing overlaps, refuses conflicts, and writes the YAML files to Git: a direct commit, or a branch and a pull request. Without a repository it lands at once. See Branches and pull requests.
Landing
When the commit is on the base branch (the pull request merged), the publication lands: Main takes the task's revisions, a new spec version is recorded, and every other workstream is checked for conflicts with the new Main. The task moves to Done by itself, and the workstream can complete on landing.
The code is built
Marking the task Ready also gave it its work items, such as
T-4.1Implement,T-4.2Deploy to staging andT-4.3Verify on staging. A person or an agent claims the implement item and opens a pull request that names it; the merge completes it. CI reports the deployment with a deploy token, which completes the deploy item. A person records the verify result; a failure sends the work back. The task is Delivered when every item is Done or Dropped, and the Build page shows each artefact Verified on staging.The workstream completes
When nothing is left to publish the workstream is completed, or abandoned, which abandons its open tasks. Its threads stay readable, and work items not yet done stay workable.
States at a glance
What people and agents may do
The server enforces this. Agent autonomy is a project setting an Admin turns on in Project settings (new projects start with it on); without it, the tools for a person's acts answer person-required. No MCP tool publishes or changes Main. The full list is in the MCP tool reference.
Note
Reviewing your own agent's work
The person an agent acts for can accept what that agent staged. When you work alone, that is the normal flow. On a team, a project can require that someone other than the accepter marks a task Ready.
Next steps
- Changes and conflicts: what differs from Main, and what to do when it overlaps.
- Tasks and publishing: from Ready to Main.
- Proposals, plans and review: how staged changes are accepted.
- Work items and delivery: from a Ready task to verified code.