# Spec Driven > Default OpenSpec change workflow — scaffold a change through proposal → specs → design → tasks, apply it, then archive once merged. Use to start a change, write a proposal/spec/design/tasks, implement a tasks checklist, or archive a merged change. - Skill: `jgamaraalv/spec-driven` (Agent Skill, multi-file: 11 files) - Install (CLI): `npx skillmds@latest add jgamaraalv/spec-driven` - Raw SKILL.md: https://api.skillmd.com/api/skills/jgamaraalv/spec-driven/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Productivity - Author: jgamaraalv (https://skillmd.com/u/jgamaraalv) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/jgamaraalv/spec-driven --- # 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..md → tasks..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 `/changes//`. Generated artifacts: ``` proposal.md ← the change proposal, with `status:` frontmatter (always) specs//spec.md ← one delta spec file per capability (always) design..md ← per-side technical design (only when warranted) tasks..md ← per-side implementation checklist (always) ``` `` 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`](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`](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 `/specs//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 `/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..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`](references/loop-integration.md)). - **in-review** — every `tasks..md` is complete; the human is reviewing/merging the MR(s). Review feedback re-enters through the loops as `## R` 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/`](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..md` — skipping a side whose design already exists, or whose slice is too small to warrant one. See [`references/design.md`](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`](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`](references/proposal.md) — the WHY: sections, the load-bearing **Capabilities** contract, researching existing specs · read before writing `proposal.md`. - [`references/specs.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//spec.md`. - [`references/design.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..md`. - [`references/tasks-and-apply.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..md` or applying. - [`references/archive.md`](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`](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).