Chapter 0 · Sprint Zero · Lesson 0.3
Spec-Driven Development & the Toolkit Trio
Write down what you want before the agent writes code - and see how Spec Kit, OpenSpec, and agent-skills each bring that discipline to your agent.
- 0.1 · The model landscape
- 0.2 · What a harness is (and how it evolved)
- 0.3 · Spec-driven development & the toolkit trio
- 1.1 · The ratchet
- 1.2+ · CLAUDE.md, hooks, spec-before-code, review
What spec-driven development is
The tempting way to use a coding agent is to type a wish and hope: "build me a login page." That's vibe coding - fast, fine for throwaways, and unreliable for anything real, because the agent quietly fills every gap you left with its own guesses.
Spec-driven development (SDD) flips this. You first write a short, structured spec - what you're building, why, and how you'll know it's done - and the agent generates code from that spec. The core idea:
Most SDD tools use the same gated chain, each step reviewed before the next:
SPECIFY → PLAN → TASKS → IMPLEMENT
(what) (how) (steps) (code)Why bother? A vague request forces the model to guess, and guesses compound into wrong code. Nailing the decisions up front is the single cheapest quality lever there is - one write-up puts it at roughly a 33× improvement from planning alone versus one-shot prompting, per My Experiments With AI. The rule of thumb: vibe-code for prototypes, spec-drive for anything you'll keep. OpenSpec's README says the same in one line: "Generating code is now cheap. Correctness is still expensive."
The trio - three ways to bring SDD to your agent
You asked about Spec Kit, OpenSpec, and agent-skills. Good news: all three are genuinely spec-driven - they're not rival agents, they're three ways to add the SDD discipline to whatever agent you already use. The real difference is packaging and weight:
- Spec Kit (GitHub) - a standalone SDD toolkit. Thorough and structured, with rigid phase gates. Install its
specifyCLI and it drops slash commands into your agent. - OpenSpec (Fission AI) - a lightweight standalone SDD framework. Its unit of work is "the change" (a bounded, reviewable delta), and it's built brownfield-first - it can even reverse-engineer baseline specs from an existing codebase.
- agent-skills - the same SDD discipline delivered as a drop-in harness skill (no separate CLI). You load its
spec-driven-developmentskill into a harness like Claude Code and it runs the gated workflow.
| Spec Kit | OpenSpec | agent-skills | |
|---|---|---|---|
| What it is | GitHub's SDD toolkit (agent-neutral) | Fission AI's lightweight SDD framework | SDD packaged as a drop-in skill |
| Unit of work | a feature: constitution → specify → plan → tasks → implement | "the change" - a delta: propose → apply → archive | a spec doc: specify → plan → tasks → implement |
| Weight & setup | Heavier, rigid phase gates; Python/uv, ~30-min setup | Lightweight, actions not gates; no Python, ~5-min setup | Minimal - just load the skill, no separate CLI |
| Best at | Big, long-lived, greenfield projects wanting full ceremony | Existing (brownfield) codebases; reverse-engineers baseline specs | Harnesses that already load skills (e.g. Claude Code) |
| How you run it | specify CLI installs slash commands into 30+ agents | openspec CLI adds /opsx:* commands to 20+ agents | The harness invokes the skill - nothing else to install |
| Reach for it when | You want a thorough, repeatable, structured process | You want fast, iterative SDD on a codebase that already exists | You're in a skill-capable agent and want SDD without new tooling |
The honest summary: all three make "spec = source of truth" their purpose - the split is packaging. Spec Kit is the heavyweight, phase-gated toolkit; OpenSpec is the lightweight, change-based toolkit built for existing code; agent-skills is the same discipline clipped straight into a harness you already run. Per OpenSpec's own comparison, the headline contrast is Spec Kit's thoroughness vs OpenSpec's 5-minute, no-Python lightness.
All three are ways to shape the harness so the agent works from clear intent instead of guessing. That habit of turning intent - and failure - into durable structure is the ratchet, which opens Chapter 1.
Check yourself
The central idea of spec-driven development is that -
In SDD the spec is the durable source of truth and code is generated output that serves it - the reverse of writing code first and documenting later.
Spec Kit, OpenSpec, and agent-skills are all -
All three are spec-driven development approaches, not rival agents. They differ in packaging: two standalone toolkits (Spec Kit, OpenSpec) and one drop-in skill (agent-skills).
OpenSpec's distinctive unit of work is -
OpenSpec centres on "the change" - a bounded, reviewable delta (propose → apply → archive) - and is built brownfield-first, unlike Spec Kit's heavier feature-level phase gates.
Do this now (5 min)
Pick a small thing you'd ask an AI to build. Before prompting, write a five-line spec:
Objective: [what + why, one sentence]
In scope: [what to build]
Out of scope: [what NOT to touch]
Done when: [a testable condition]
Constraints: [language, style, anything fixed]Notice how much guessing you just removed. That five-line habit is 80% of the benefit of every tool in the table - before you install any of them.
Go deeper
Primary sources: GitHub Spec Kit (the most-adopted, structured SDD toolkit) and OpenSpec (the lightweight, change-based alternative). Skim both READMEs side by side to feel the heavy-vs-light contrast.
Wisdom: r/ChatGPTCoding - active, cross-tool debate on spec-driven vs vibe workflows.