Spec-Driven Change Workflow (OpenSpec)

A change moves through four authored artifacts, an execution phase, and a closing phase. Each artifact answers a different question, and each builds on the one before it:

proposal.md → specs/**/*.md → design.<side>.md → tasks.<side>.md → apply → archive
WHY           WHAT            HOW                 WORK BREAKDOWN    EXECUTE  RECONCILE & SHIP

The whole point of doing this up front is that decisions get cheaper the earlier you make them. The proposal pins down why and what scope; the specs pin down observable behavior; the design pins down technical approach; the tasks turn all of that into a checklist someone can execute and track. Skipping straight to code loses the contract these documents create with each other — most notably the Capabilities contract between the proposal and the specs. And the lifecycle only closes at archive: until the implemented change is merged and its delta specs are folded into the shipped specs, the source of truth is not yet updated.

Where artifacts live

The OpenSpec tree root resolves through SPEC_VAULT_PATH — set it in the host repo's .claude/settings.json env block or the shell — and falls back to ./openspec in the host repo when unset. Pointing it at a shared vault (a plain folder of Markdown that is itself a git repository, typically also opened in Obsidian as the human's reader) lets sessions in different host repos — a backend repo and a frontend repo — read and write the same truth. Access is always plain filesystem (Read/Write/Glob/git) against the local checkout; the operative truth never depends on an MCP being available.

A change lives in its own directory under <root>/changes/<slug>/. Generated artifacts:

proposal.md          ← the change proposal, with `status:` frontmatter (always)
specs/<capability>/spec.md   ← one delta spec file per capability (always)
design.<side>.md     ← per-side technical design (only when warranted)
tasks.<side>.md      ← per-side implementation checklist (always)

<side> is backend or frontend. The suffix applies always — even when a feature touches only one side — so every consumer (architects, delivery loops, archive) parses exactly one format instead of detecting variants. proposal.md and specs/ are never split per side: they are product truth (a requirement like "user exports CSV" doesn't belong to a repo), while design and tasks are execution truth that each repo's loop owns and updates without write contention.

What makes the per-side split pull its weight (not just mirror the folders) are two artifacts the references detail: each side's design carries a machine-readable task manifest (files_owned / deps / exports_promised, in references/tasks-and-apply.md), and any shared boundary (a contract field, an enum like the set of cancellable states) is named in a cross-side ripple note so a change on one side is visibly tracked on the other (see references/loop-integration.md). When you author a cross-side change, produce both — they're the difference between two task lists and two coordinated task lists.

Existing, already-shipped specs live under <root>/specs/<capability>/spec.md. Read those before proposing changes to existing capabilities — the proposal and the delta specs reference them by their exact folder name. When the feature carries an API contract, it lives as OpenAPI YAML under <root>/contracts/ (the archive phase projects it to Postman; the file is master, Postman is never edited directly).

The change lifecycle

status: frontmatter in proposal.md tracks the change through four states (a missing field reads as in-progress, for changes authored before this convention):

draft → in-progress → in-review → archived

• draft — being authored: proposal → specs → design → tasks.
• in-progress — under implementation. The delivery loops act as the apply phase: they check off tasks.<side>.md as their gates pass, and the spec is the authority — an approved deviation is amended into the change folder and committed at approval time, never deferred (product/UX/contract drift is approved synchronously by the human; purely technical reconciliations are auto-amended with a marker and ratified asynchronously — the two-tier gate in references/loop-integration.md).
• in-review — every tasks.<side>.md is complete; the human is reviewing/merging the MR(s). Review feedback re-enters through the loops as ## R<n> task sections and flips the change back to in-progress until the round closes.
• archived — the MR(s) merged and the archive phase ran. Shipped specs describe merged code only: archive is gated on the merge, not on task completion.

The loop orchestrators maintain the field; only the archive phase may set archived.

Templates

Each artifact has a starter template in templates/ — read the relevant one before authoring and copy its skeleton into the target file, then fill it in. The templates carry the exact section headers and HTML-comment guidance the workflow expects, so starting from them keeps the artifacts parseable downstream.

Dependency order

Honor the requires chain — never author a downstream artifact before its inputs exist:

• proposal requires nothing — it is the foundation.
• specs require the proposal (one spec per capability the proposal names).
• design requires the proposal. The design phase is a routing gate, not hand-authoring: it detects which side(s) the change touches and dispatches frontend-architect / backend-architect to author each side's design.<side>.md — skipping a side whose design already exists, or whose slice is too small to warrant one. See references/design.md.
• tasks require both specs and design.
• apply requires tasks.
• archive requires the change to be in-review with the MR(s) merged — see references/archive.md for the full precondition gate.

If the user asks for a later artifact and an earlier one is missing or stale, say so and offer to create or refresh it first rather than guessing at the missing contract.

References

Read the reference for the phase you're authoring — each carries the sections, format rules, and worked examples for that artifact:

• references/proposal.md — the WHY: sections, the load-bearing Capabilities contract, researching existing specs · read before writing proposal.md.
• references/specs.md — the WHAT: delta operations (ADDED/MODIFIED/REMOVED/RENAMED), requirement/scenario format (#### exactly), the MODIFIED full-block workflow · read before writing any specs/<capability>/spec.md.
• references/design.md — the HOW: the architect-routing gate (detect side(s) → dispatch the architect, skip a side whose design exists), when a design is warranted (it's conditional — skip it when not), and its sections · read before deciding on / writing design.<side>.md.
• references/tasks-and-apply.md — the checklist format the apply phase parses (- [ ] X.Y), how execution is delegated to the delivery loops, and the inline fallback · read before writing tasks.<side>.md or applying.
• references/archive.md — the RECONCILE & SHIP: the precondition gate (merged MRs, no open review round, clean vault tree), merging delta specs into shipped specs, the Postman contract sync, the project-doc reconciliation sweep (catch the CLAUDE.md / ADRs / runbooks / architecture blueprints / tech-debt / config the change made stale), and filing the change away · read before archiving.
• references/loop-integration.md — how a delivery loop drives a change through the lifecycle: attach, cycle-boundary vault sync, task tracking, the drift gate, cross-side ripple, the closing protocol, MR-review re-entry · read by the delivery-loop orchestrators (all three loops link here so the rules live in one place).