Skip to content

How the spec workflow works

Follow a SpecsGraph change from idea to Git commit: how agents propose over MCP, what each proposal status means, and why only people can approve.

From idea to commit

Every change to the spec, large or small, takes the same path. The model only changes through proposals, and a proposal only reaches your repository after a person approves it.

  1. Someone has an idea. An engineer asks their agent to update the spec, or starts a proposal in the web app.
  2. The agent reads the graph. Over MCP it calls read tools such as get_project_overview, get_context and list_glossary_terms to find where the change belongs and which words to use.
  3. The agent drafts a proposal. Write tools such as propose_requirement never edit the graph. They open a proposal, and later calls can add to the same one.
  4. People review it. Reviewers read the changes node by node, open threads and ask for changes. The agent can read the threads and revise.
  5. A person approves it. Approval is a web app action for members with the Editor role or above.
  6. SpecsGraph opens a pull request. The GitHub App commits the change under specsgraph/ on the proposal branch and, by default, opens a pull request to the base branch. A project can switch to direct commits instead; see Branches and pull requests.
  7. Merging publishes it. Merging the pull request marks the proposal Published, and the graph shows the change as the current revision.

Proposal statuses

A proposal is always in exactly one of these statuses. Other pages in these docs use the same names.

StatusWhat it meansHow it gets there
DraftA person is still putting the change together in the web app. Reviewers are not notified yet.A person starts a proposal in the web app.
OpenReady for review. Reviewers are notified, and anyone in the workspace can comment on the changed nodes.An agent's write tool call, or a person choosing Request review on a draft. Agent proposals start here.
Changes requestedA reviewer wants something changed. The author, person or agent, revises the proposal.A reviewer with the Editor role or above. The proposal returns to Open once the author revises it.
ApprovedA person accepted the change. Your GitHub App commits it to the proposal branch and opens a pull request to the base branch. The proposal stays Approved until that pull request is merged.A person with the Editor role or above. Never an agent.
PublishedThe pull request was merged, and the graph shows the change as the current revision.Merging the pull request in GitHub. In the Direct commit publish mode, the commit landing on the base branch.
WithdrawnClosed without publishing. The proposal and its threads stay readable in history.A member with the Editor role or above, usually the author: from any status before Approved, or from Approved once its pull request was closed without merging.
Status transitionsText
Draft -> Open -> Approved -> Published (pull request merged)
          |  ^
          v  |
   Changes requested

Draft, Open or Changes requested -> Withdrawn
Approved, pull request closed without merging -> Withdrawn

If a pull request is closed without merging, the proposal stays Approved and shows a warning. Reopen the pull request, choose Retry publish to open a new one, or withdraw the proposal. Several proposals can be open at once, even on the same node; Proposals and reviews explains how to review them in turn.

People approve, agents propose

Agents never publish on their own, and the tool surface enforces it. The MCP server exposes read tools and a small set of write tools (propose_requirement, propose_term, propose_structure_change, comment_on_proposal, record_decision, update_task), and none of them approves, publishes or merges anything. The full list is in the MCP tool reference.

  • An agent authenticates with a personal access token, so it acts as the person who created the token and can never do more than that person can.
  • Approval happens only in the web app, by a signed-in member with the Editor role or above.
  • The spec commit comes from your GitHub App after approval, not from the agent.
  • Merging the pull request follows your repository's own rules, such as branch protection and required reviewers, and marks the proposal Published.

Note

Reviewing your own agent's work

The person whose token an agent used can approve that agent's proposal. When you work alone, that is the normal flow. On a team, you may want a second person to approve anything that touches another team's context.

What the agent sees and what the reviewer sees

Agent over MCPReviewer in the web app
AccessAn MCP client using your personal access token.A signed-in member of the workspace.
The modelStructured results from read tools: contexts, requirements with scenarios, glossary terms, actors, relationships, decisions and workstreams.The system map, with the nodes a proposal touches highlighted.
A proposalIts diff, status and review threads, through get_proposal.A before and after view of each changed node, the author, the branch name and the threads.
ActionsDraft and extend proposals, reply in threads, draft decisions and update tasks.Comment, request changes, approve or withdraw.
Final sayNone. It waits for a person.Chooses Approve. SpecsGraph opens the pull request, and merging it publishes the change.

Example: spec/checkout-reserve

An engineer on the Orders team in Northwind Commerce is changing checkout so stock is reserved before payment. They ask Claude Code to update the spec first.

  1. The agent reads Orders and Billing

    It calls get_context for Orders and Billing and finds the glossary term Reservation, so it uses that word instead of "hold" or "lock".

  2. It opens one proposal with three requirements

    With propose_requirement it drafts ORD-12 "Reserve stock for every line item at checkout", ORD-13 "Release reservations after 15 minutes idle" and BIL-04 "Capture payment only once stock is reserved", each with scenarios. With record_decision it drafts a decision explaining why reservation comes before payment. The proposal "Checkout reserves stock before payment" is now Open on spec/checkout-reserve, with the author shown as "Coding agent via MCP".

  3. A Billing reviewer asks a question

    On BIL-04 a reviewer asks what happens if a reservation expires between payment authorization and capture, and requests changes. The agent reads the thread with get_proposal, adds a scenario for that case and replies with comment_on_proposal. The proposal returns to Open.

  4. The reviewer approves

    The reviewer resolves the thread and approves. The proposal moves to Approved.

  5. The pull request opens and merges

    SpecsGraph commits the files below to the proposal branch and opens a pull request. The workstream file is included because the proposal is linked to WS-3. The team merges the pull request alongside the code change, or on its own, following their usual rules, and the proposal becomes Published.

    Files changed on spec/checkout-reserveText
    specsgraph/contexts/orders/requirements/ORD-12.md
specsgraph/contexts/orders/requirements/ORD-13.md
specsgraph/contexts/billing/requirements/BIL-04.md
specsgraph/decisions/0007-reserve-stock-before-payment.md
specsgraph/workstreams/WS-3.md
specsgraph/README.md
specsgraph/graph.json

Next steps