Skip to content

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

  1. A workstream opens

    Someone opens WS-3 for the story. Its view starts equal to Main.

  2. 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.

  3. 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.

  4. 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.

  5. 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.

  6. 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.

  7. The code is built

    Marking the task Ready also gave it its work items, such as T-4.1 Implement, T-4.2 Deploy to staging and T-4.3 Verify 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.

  8. 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

ThingStates
WorkstreamActive, Completed, Abandoned
Staged revisionPending (needs attention while a thread is open on it), Accepted, Superseded, Withdrawn
ProposalDraft, Ready, Completed, Discarded
TaskDraft, Ready, In progress, Done, Abandoned
PublicationNot published, Publishing, Awaiting merge, Published, Outdated, Failed, Blocked
Work itemTo do, Doing, Done, Dropped; blocked while it waits on other work or a blocking question
Build statusNot started, Planned, In dev, Merged, On env, Verified, Outdated, Rolled back
MilestoneOpen (Not started, Active or Complete), Closed, Dropped

What people and agents may do

ActPerson (Editor or above)AgentAgent with Agent autonomy
Edit an artefact in a workstreamYes, directlyStages it insteadYes, directly
Accept a staged revisionYesNoYes
Open, rename, describe or assign a taskYesYesYes
Scope changes into a taskYesNo; it proposes a planYes
Mark a task Ready, mark DoneYesNoYes
PublishYesNoNo
Ask and answer questionsYesAsks; answers stay with peopleAsks and answers
Resolve a conflictYesStages an edit merge for a person to acceptYes, directly
Complete or abandon a workstreamYesNoYes
Claim an implement, docs, regression or other itemYesYesYes
Mark a work item done, or edit the items of a taskYesNo; a merge completes its itemNo
Record a verify or uat resultYesNoNo
Mark code as implementedYesNoNo
Create or order milestonesYesNo; reads the roadmapNo

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