Mid-build amendments.

Most spec tools assume you finish the spec, freeze it, then implement. Real projects don't work that way — mid-build you realize you need a new feature, the team flags a missing edge case, a stakeholder asks for an export format. SpecGraph treats this as the normal case: a wish or an amendment becomes a new story, the coding agent picks it up on its next /sg-dev, your dashboard reflects it within seconds. This page is the practical guide to that loop.

The loop #

file wish / propose amendment
        ↓
   accept / apply
        ↓
new feature in features.features
        ↓
composer derives a new story file
        ↓
sprint-status.yaml + pack browser update
        ↓
   /sg-dev picks it up

Each step is something already documented elsewhere — the value is the loop itself. You can keep editing the spec while the agent is shipping; story keys for in-flight work stay stable; new features land as new stories without renumbering anything that came before.

Two front doors #

Both paths converge on the same outcome — a new feature in project.features.features. Pick whichever fits the situation.

Amendments — formal, fastest #

Use when you know what to add and can describe it in three fields. One panel, one click.

1. Right rail → Amendments (FilePen icon).
2. Propose amendment tab. Set:
   • Type: add-feature
   • Title: the feature name
   • Rationale: why now
   • Details: the user story (optional but useful — it becomes the story's body)
3. Submit. The amendment appears in the Ledger as proposed.
4. Click Apply.

A green sonner toast fires:

Story X.Y created — Title — status: ready-for-dev. Coding agent will pick it up next. [Open in pack browser]

Click the action; you land in the pack browser with the new story file in the file tree.

Wishes — collaborative, supports stakeholders #

Use when the request comes from someone who shouldn't (or doesn't want to) edit the spec directly — a teammate from another department, an invited stakeholder via the public portal. Wishes are conversational; amendments are commits.

1. The submitter files a wish targeting the Features phase. (The wish panel's submission form, or the stakeholder portal's "File a wish" button.)
2. You open Wishes (Sparkles icon), see it in the Pending group.
3. Click Accept — runs a conflict check against existing wishes + features.
4. The wish moves to Handled. Click Merge into section on the wish row.
5. The AI proposes a surgical edit — usually one new feature appended, sometimes more if the wish covered multiple ideas.
6. Apply in the merge dialog.

Same toast fires as the amendment path. If the merge added more than one feature, the toast pluralizes:

3 stories created — Wish merged into the features phase — coding agent will pick them up next.

Why the new story has a stable key #

Every feature in your project has an FR-id (FR-001, FR-002, …). Story keys are derived from these. Without care, adding a new feature could renumber existing FRs — meaning a story key the coding agent had partway through 2-3-something would silently move to 2-4-something next time it pulled. That breaks the loop.

SpecGraph fixes this two ways:

1. Max + 1 assignment. New features get the next number above any existing FR-id (so a 4th feature added to a 3-feature project always gets FR-004, never FR-003).
2. Persistence on save. When you click Save pack in the pack browser, the assigned frId is written back onto the feature so it sticks across recompositions. Subsequent reads return the same key.

What this means in practice: once you've saved the pack, story keys for in-flight work are immutable. You can add ten more features tomorrow, reorder them, edit their content — the keys for stories the agent already started don't move.

Test it in 60 seconds #

If you just want to confirm the loop works:

1. Open any project with at least 2 features. Open the pack browser — note the existing story keys (e.g. 1-1-…, 1-2-…).
2. Right rail → Amendments → Propose amendment → type add-feature, fill any title + rationale + details. Submit.
3. Ledger tab → Apply.
4. Watch for the sonner toast. Click Open in pack browser.
5. Assert: the new story appears in implementation-artifacts/ with ready-for-dev badge. Existing stories' keys are unchanged.
6. Add a 4th feature directly via the Features phase. Click Save pack in the browser.
7. Assert: the FR-IDs of the existing 3 features did NOT shift. The 4th got the next number up.

If both assertions pass, the loop is live. The coding agent's next /sg-dev --loop will see the new story and pick it up.

What about the other phases #

The wish flow works against every phase, not just features. A wish on Vision edits the vision section; a wish on Architecture edits the architecture section. Only features-phase wishes produce new stories — that's the only phase whose entries map 1:1 to BMAD stories. Wishes on other phases still update the corresponding planning artifact (so the agent reads the new vision next time it pulls read_product_brief), they just don't add to the sprint.

That's a deliberate split:

• Features-phase wishes add work to the sprint.
• Other-phase wishes clarify or change context for work already in flight.

If a vision-phase wish implies a new feature ("we should also serve enterprise customers" → probably a new feature for SSO), file the implied feature as a separate amendment. The wish documents the reasoning; the amendment ships the work.

What about an architecture decision #

Some amendments aren't features at all — "switch from Postgres to MySQL" is an architecture change. The right path:

1. File the change as a wish or amendment against Architecture.
2. Apply it. SpecGraph appends a new ADR to architecture.md; existing ADRs are not rewritten.
3. The agent's next read_architecture call sees both the old ADR (with full context/rationale) and the new one (with the override). project-context.md stays unchanged unless the new pattern needs a new rule.

Stable rules = stable agent. We append; we don't rewrite.

When the agent is mid-story #

If you apply an amendment while /sg-dev is currently working a story, nothing breaks:

• The agent's current story keeps its key (FR-IDs are stable).
• The new story sits in ready-for-dev until the agent finishes its current one.
• On the next /sg-dev, the agent calls get_sprint_status, sees the new ready-for-dev row, and starts on it (highest priority first, by appearance order in the sprint).

You don't have to pause the agent. The amendment becomes visible to it on the next tool call — that's why MCP is read-on-demand rather than read-once.

If you want the agent to pick up the new story immediately (jump the queue), pass the key explicitly:

/sg-dev <new-story-key>

That overrides the auto-select and runs the named story next.

When something goes wrong #

Related #

• Wishes & amendments — the underlying mechanisms (statuses, conflict-check, merge dialog).
• Connecting coding agents (MCP) — the agent side of the loop, including /sg-dev and the bootstrap flow.
• Collecting wishes — end-to-end stakeholder workflow.