Proposals and reviews

Review SpecsGraph proposals from agents and people: read the diff, discuss any node in a review thread, then approve, request changes or comment.

What a proposal is

A proposal is a set of changes to the graph that waits for review. Nothing in a proposal is part of the spec until a person approves it and it is published. Proposals come from two places.

An agent over MCP. Write tools such as propose_requirement, propose_term and propose_structure_change open a proposal, and later calls extend the same one. An agent's proposal opens ready for review. Its author reads "Coding agent via MCP", together with the person whose token the agent used.
A person in the web app. Start a proposal from Reviews, or begin editing a node on the map. It starts as a Draft, and reviewers are not notified until you choose Request review.

Each proposal has its own branch under spec/, such as spec/checkout-reserve. The branch name appears on the proposal. When the proposal is approved, SpecsGraph commits the change to that branch and opens a pull request from it, and merging that pull request publishes the proposal. Branches and pull requests covers what happens in GitHub.

Who acts next

Every proposal has one status. How the spec workflow works describes each transition; for day-to-day reviewing, what matters is whose turn it is.

Status	Whose turn it is
Draft	The author, who is still putting the change together.
Open	Reviewers. The owning team shown on each context the proposal touches tells you who should look.
Changes requested	The author, person or agent, who revises the proposal. It returns to Open after the revision.
Approved	Whoever merges pull requests in your repository. SpecsGraph has committed to the proposal branch and opened a pull request, which follows your usual merge rules.
Published	Nobody. The pull request is merged and the change is part of the spec.
Withdrawn	Nobody. The proposal and its threads stay readable.

Read the diff

Open a proposal from Reviews to see its changes. Every node it adds, changes or removes is listed, grouped by context, with the version before and the version after side by side.

Requirements show the statement and every scenario, compared step by step. A new scenario appears in full.
Glossary terms show the old and new definitions, plus the requirements that use the term, so you can see what a new definition changes in practice.
Structure changes to contexts, services and relationships appear on the Map tab with the touched nodes highlighted.
Decisions drafted in the proposal appear in full, with the requirements they link to.

The diff also lists linked nodes that the proposal does not edit but that depend on what it changes. A change to ORD-12 brings BIL-04 into view, because Billing's rule assumes stock is already reserved. Check that those links still hold before you approve.

When two proposals change the same node

Several proposals can be open at once, and two of them can touch the same node, for example two changes to the idle timeout in ORD-13. Review them one at a time:

Approve and merge the one that should land first.
Before you approve the second, read its diff again against the version that is now current, and ask its author to revise it if the change no longer fits.
An agent author can reread the node with get_requirement and the proposal with get_proposal, then revise.

Review threads

Start a thread on any node in the proposal: a requirement, one of its scenarios, a glossary term, a context, a relationship or a decision. The discussion stays attached to the thing it is about instead of scattering across chat.

Every member of the workspace can comment, Viewers included. The author replies in the thread and revises the proposal. Resolve a thread once its question is answered. Resolved threads stay on the proposal and in history, so later readers can see how each question ended.

Thread on BIL-04 in spec/checkout-reserveText

BIL-04  Capture payment only once stock is reserved

Kofi (Billing)
  What happens if the reservation lapses between payment authorization
  and capture? ORD-13 releases it after 15 minutes idle.

Coding agent via MCP, for Ana
  Added the scenario "Capture is refused when the reservation has lapsed":
  the authorization is voided and the Customer is asked to check out again.
  The scenario links ORD-13.

Kofi (Billing)
  That covers it. Resolving.

Review actions

Action	What happens	Who can do it
Comment	Adds a thread or a reply. The status does not change.	Every member. Agents reply in existing threads through `comment_on_proposal`.
Request changes	Moves the proposal to Changes requested and notifies the author.	Editor and above.
Approve	Moves the proposal to Approved. SpecsGraph commits to the proposal branch and opens a pull request, and merging it makes the proposal Published.	Editor and above, in the web app only.
Withdraw	Closes the proposal without publishing.	Editor and above, usually the author: before approval, or after the pull request was closed without merging.

Reviewers with the Editor role or above can also edit an open proposal directly. Their edits appear in the diff under their own name. That is the quickest route for a typo or a clearer title; for anything the author should understand, ask in a thread instead.

Note

Who can approve

Members with the Editor, Admin or Owner role, signed in to the web app. Agents never approve, whatever token they hold. The person whose token an agent used may approve that agent's proposal, though a second reviewer is worth it when a change touches another team's context. Members and roles lists every role.

Agents in review threads

An agent reads the threads on a proposal with get_proposal and replies with comment_on_proposal. When the answer is a change, it revises the proposal with the same write tools it used to draft it, and the proposal returns to Open for another look. Agents cannot resolve threads: the person who asked decides whether the answer is good enough.

PromptText

Read the review threads on the proposal spec/checkout-reserve.
For each unresolved thread, either revise the proposal or reply with your
reasoning. Leave resolving threads to the reviewers.

Tips for reviewing agent proposals

Check the words. An agent that writes "stock hold" where the glossary says Reservation has missed a term. Ask it to use the glossary and revise.
Read the scenarios first. Concrete numbers and names show what the agent understood faster than the statement does.
Look for the missing case. Agents cover the main path well. Ask about expiry, retries, partial failure and the boundaries between contexts.
Check the scope. A proposal should match the task it came from. Ask the agent to split unrelated changes into their own proposals.
Check where things landed. A new requirement belongs in the context that owns the rule, with the right key: a capture rule is BIL, not ORD.
Ask for the why. If the change reverses an earlier rule, ask the agent to draft a decision in the same proposal.

Next steps

How the spec workflow works: every proposal status and transition.
Decision log: record the reasoning a review settles.
Branches and pull requests: what happens in GitHub after approval.
Working well with agents: prompts that produce proposals worth reviewing.