The Spectrum
How much process does rename a config variable deserve? A full Spec-Driven Development framework gives it too much. The ceremony is right for a large API redesign, and absurd for a one-line rename. The structure that protects a risky change suffocates a trivial one.
Consider a team that writes no specs at all, operating on prompts and conversation history alone. Features work until a later session extends them. Then a reviewer asks why the validation is in the controller, and the only answer is git blame.
Through 2025 and into 2026, the Spec-Driven Development (SDD) tooling spread into a spectrum, from no artifact to full governance. SDD is the practice: per-change intent with testable acceptance criteria. GSD, spec.md, OpenSpec, LeanSpec, and Spec-Kit are implementations of it at different levels of formality. The tools below are a mid-2026 snapshot, not a settled field.
BMAD Method, Taskmaster, and other frameworks occupy the same category. The diagram below marks formality levels, not a ranking of the field.
Formality and audit trail rise left to right, and so does overhead. The rung that fits a change is the one whose ceremony matches its risk, not the heaviest one available.
The light end
At the minimal end is the raw prompt. Describe the feature in the chat window and let the agent implement. No artifact, no audit trail. Acceptable for throwaway code, local experiments, prototypes that will not last the week.
One step up is a concise intent note: write down the target, run the agent, commit. The note preserves the request, but the team still needs rules for task tracking, verification, and retirement.
GSD (Get Shit Done) names a specific development system. As checked in October 2026, its original repository points to GSD Core, whose documented phases cover discussion, planning, execution, verification, and shipping with archiving. Treat GSD as a framework option. The light rung in this diagram is an intent note without a managed lifecycle.
Next is a spec.md file in the repo: one Markdown file with purpose, scope, acceptance criteria, scenarios, task notes, and verification rules. Written before implementation and committed with the code, it is this book's lightweight alternative to a managed change folder.
For teams with stable review rules, spec.md becomes a local framework. The file starts small, then picks up house rules: where it lives, which headings are mandatory, who reviews it, how scenarios map to tests, when it becomes historical, and how stale specs stop acting as live instructions. Local formats stay viable when those rules match the team's existing review and release mechanics better than the generic template does.
The cost is ownership. A custom spec.md gives maximum fit and almost no tooling burden, but the team owns the lifecycle around it. Without those rules, spec.md is a better prompt. With them, it becomes a spec-driven workflow.
Sources: GSD original repository README and GSD Core README (reviewed October 21, 2026), named framework, project move, and phase lifecycle. The intent-note and custom spec.md rungs are this book's synthesis.
OpenSpec
OpenSpec is the next level: a structured change-folder workflow with four parts, each answering a distinct question.
| Part | File | Question |
|---|---|---|
| Propose | proposal.md | What is changing, why does it matter, and what follows from it? |
| Design | design.md (optional) | Which implementation approach should stand? |
| Specs | specs/<capability>/spec.md | How should the capability behave after the change? |
| Tasks | tasks.md | What should be implemented, and in what order? |
Acceptance criteria are written in Gherkin's WHEN/THEN notation. The book borrows that notation as a specification language, not the practice it came from. The payoff is that the scenario reads the same whether the agent targets Java, Kotlin, Python, or Go: a reviewer checks the acceptance criteria without knowing the implementation language or its test framework, the same way nobody reviews behavior by reading the assembler a compiler emits.
BDD also uses examples to guide development before implementation. The workflow here borrows scenario notation without requiring Cucumber step definitions or adopting the full collaborative BDD practice. The agent generates tests from the reviewed scenarios. Why the spec outranks the code it produces is the argument in Docs > Specs > Code.
The change folder manages the scenarios through the change lifecycle. A proposal records additions, updates, or removals to capability requirements. Before or during archive, sync those deltas into openspec/specs/<capability>/spec.md. The change folder then moves to openspec/changes/archive/ with its proposal, design, specs, and tasks preserved.
OpenSpec is the concrete workflow used here. It is not the only one that works. The closest alternative is the plain spec.md your team has already shaped into a local workflow.
The portable pieces are stated intent, an implementation approach when the change needs one, behavioral specs, an execution plan, and an archive rule. A framework holding those gives inactive specs a status, scope a task list, and intent testable criteria.
The selection rule is simpler than the tool names make it sound: pick the lightest framework that is already closest to the artifact set and lifecycle you want. A plain spec.md plus four house rules for a proposal, tasks, archive, and review is already a framework. Pretending otherwise only hides the maintenance cost.
OpenSpec is the choice here because it supplies the lifecycle without hiding the files. One change folder holds a single unit of intent, carrying delta specs for the behavior changes, Gherkin-style scenarios to make the acceptance criteria concrete, and tasks.md for the agent's execution path. Archiving then keeps active intent apart from the historical record.
Synchronization updates the canonical acceptance criteria under openspec/specs/; the archived folder preserves the change history. Later changes diff against the current criteria, and tests carry links back to their identifiers. The design those criteria serve lives in docs/. This split adds file and process overhead, and it fits best where several developers ship changes into the same production codebase.
Sources: Fission AI, OpenSpec, the four-part change-folder workflow, delta specs, tasks.md, and the archive as a canonical capability model. Cucumber, "Gherkin reference" and "Behaviour-Driven Development" (reviewed October 21, 2026), scenario notation and collaborative examples before implementation. The framework-selection rule and closest-alternative framing above are this book's synthesis.
LeanSpec and Spec-Kit
LeanSpec argues for concise specifications that evolve with the work. This book uses that scope advice while teaching OpenSpec's change-folder lifecycle.
GitHub's 2025 Spec-Kit launch post includes security and compliance requirements among the inputs to its specification and plan. This book places that more structured workflow toward the formal end of its spectrum. The placement is an editorial comparison, not a measured ranking.
Sources: LeanSpec documentation, concise and evolving specs. GitHub Blog, "Spec-driven development with AI: Get started with a new open source toolkit" (September 2, 2025), security and compliance requirements as specification inputs. The formality comparison is this book's synthesis.
Match formality to risk
Match formality to risk is LeanSpec's framing. The table below is this book's working synthesis of it. The error is not picking the wrong tool; it is applying one tool to every change regardless of risk.
| Change type | Appropriate formality |
|---|---|
| Local prototype, will not merge | Raw prompt |
| Small bug fix, clear scope, no edge cases | spec.md or skip entirely |
| New feature, single developer, medium complexity | spec.md, LeanSpec, or OpenSpec if the project will keep accumulating specs |
| New feature, team collaboration, reviewable | OpenSpec change folder |
| Compliance-sensitive, multi-team, production | OpenSpec or Spec-Kit |
This is a heuristic, not a decision tree. The real question is the cost of discovering the wrong intent after implementation. Low cost, low formality. High cost, high formality.
Read the table per project, not only per change. A solo developer shipping one agent-assisted feature might stay with spec.md. A solo developer shipping twenty changes into the same codebase has a different problem: old intent, current intent, test evidence, and archive history start piling up. At that point, OpenSpec's lifecycle stops looking like a ceremony and starts looking like bookkeeping you were going to need anyway.
The same dial governs how you stage the change, not only which framework you reach for. A change carrying a real decision earns a spec PR before any implementation, so the intent is corrected while correcting it is cheap. A change whose intent is visible in the diff ships as one PR. The trunk-based development chapter works the mechanics.
Sources: Rick Hightower, "Agentic Coding: GSD vs Spec Kit vs OpenSpec vs Taskmaster AI" (February 27, 2026), the formality-to-risk tradeoffs that distinguish the SDD tools across the spectrum.
Keep the framework replaceable
Ask one more question before you adopt a framework: what does leaving cost? I treat a low exit cost as a requirement for an SDD framework, on the same footing as vendor independence for the agent. If the acceptance criteria only make sense inside one tool, replacing the tool means rewriting them.
Leaving is never free, and I would not make full portability an ultimatum. You lose the framework's validator and archive command and have to replace them with house rules. The aim is a migration you are able to write down as a short list of file moves before you commit to the tool.
Four checks cover most of the answer:
- Every artifact the framework writes is plain text in your repo, readable without the tool.
- Durable records sit apart from work in progress, so you know which files to carry over.
- Acceptance criteria use a notation another tool or a plain agent reads, such as Gherkin-style
WHEN/THEN. - The design and the decisions live in
docs/, outside the framework's directory.
OpenSpec passes the first three by layout. The accumulated criteria are Markdown under openspec/specs/ and the change history is Markdown under openspec/changes/archive/. Both move to a directory such as docs/acceptance/ with git mv. Test links hold after the move because the AC IDs are text in the scenarios, so no tool has to resolve them.
The fourth check is yours. OpenSpec's sync and archive operations update openspec/specs/ and the archive folder, and in my use they have never edited a file under docs/. The rule keeping docs/ current belongs in your agent instructions, and Spec Lifecycle shows one. A team whose design record exists only inside one framework's folders has made the framework the source of truth.
I have not run this test against Spec-Kit, BMAD Method, or the other frameworks, so apply the four checks yourself before choosing one. I expect most of them to accept a docs-update rule in the agent instructions, though I have not tested the expectation.
Sources: Fission AI, OpenSpec "Concepts" (reviewed October 22, 2026), delta-spec sync into the main specs and the archive folder. The exit-cost requirement, the four checks, and the migration sketch are this book's synthesis. The remark on docs/ reports the author's use of OpenSpec during 2026, not a documented guarantee.
The trade-off
More formality means more audit trail, better traceability, and less room for improvisation. It also means more upfront time, more overhead per change, and more places for the process to become theater if nobody tends it.
Teams underestimate the theater risk. A heavy framework adopted by a small team produces specs written to satisfy the framework rather than guide the implementation: correct structure, shallow content, twenty minutes from a developer who wants to get to the code. They look complete and are not.
The right level of formality is the one your team will maintain under deadline pressure. Start lower than you think you need. Add ceremony when you feel the pain of not having it.
Picking the rung is the easy part. The lifecycle that carries a spec from proposal to archive, and back into the codebase as evidence, is where most of the work hides.