Guide
What is spec-driven development?
Spec-driven development (SDD) is a workflow where a written specification, committed to the repo, is the source of truth for what gets built. People write and review the spec; AI coding agents implement against it. This guide covers where the practice came from, how it sits inside the six stages of the AI-native software lifecycle, the tools involved, and what happens to product management once the specs start multiplying.
The definition
The spec, not the ticket, drives the work
In spec-driven development, every meaningful change starts as a spec: a markdown document that captures the intent, requirements, and acceptance criteria for a piece of work. The spec lives in the repository next to the code it describes. It is versioned in git, reviewed in pull requests, and readable by both people and machines.
GitHub's Spec Kit announcement describes it as flipping the script on traditional development: instead of code being king and specs being scaffolding you throw away, the spec becomes the contract that tools and agents use to generate, test, and validate code. Kiro's spec docs make the same move from the IDE side: specs are structured artifacts that bridge product requirements and technical implementation, approved by a human before an agent writes a line of code.
Why now
AI coding agents made the spec the unit of work
Coding agents can now implement large changes autonomously, but the quality of what they build is bounded by the quality of what they are told. A chat thread is disposable context; a spec is durable context. Anthropic's Claude Code best practices make this point from the agent's side: separate planning from implementation, and keep the instructions that matter in files the agent reads on every run rather than in conversation history.
The ecosystem has standardized around this idea. AGENTS.md gives every coding agent a predictable place to find repo-level instructions, with OpenAI Codex, Cursor, Jules, and others reading it before doing any work. The Model Context Protocol extends the same principle beyond the repo, letting agents read and act on structured project state. Specs are the natural next layer: durable, reviewable statements of intent that both your team and your agents build from.
The wider model
Six stages, and specs sit in the middle of them
Anthropic's AI-native SDLC playbook describes the whole lifecycle once code stops being the bottleneck. The specify, plan, tasks, implement loop that Spec Kit and Kiro run is stages two and three of it.
Plan
An idea stops waiting for someone to write it up properly. The originator talks it through with an agent and commits the result in their own words, so intent is captured once rather than reconstructed from a ticket later.
intent.md
Design
Requirements and design collapse into one session. The organisation's policies are applied while the spec is written, instead of being discovered in a review weeks afterwards, and concerns get flagged for a human to work through first.
spec.md
Build
Nothing is implemented without an accepted plan. The agent reads the codebase and proposes how it will make the change; the engineer corrects that before any code exists. Institutional knowledge becomes files the agent reads rather than lore.
plan.md, CLAUDE.md
Test
Every session gets a way to check its own work, so it fixes its own mistakes before a person sees them. The configuration that steers the agent is regression-tested like the code it produces.
one test command
Deploy
Review runs in both directions: the agent reviews incoming changes against policy, and addresses comments on its own. Human attention moves up a level, to whether the change did what the plan intended. The agent works up to the production gate and cannot pass it.
REVIEW.md, hooks
Maintain
The loop closes. A deterministic trigger invokes an agent with no person in the invocation path; what it diagnoses re-enters the pipeline as a new intent, in the same format Plan started with.
back to intent.md
The model is Anthropic's, not ours. Read it first-hand in the AI-native SDLC playbook.
The toolchain
Three layers of spec-driven tooling
Authoring tools produce the specs, coding agents implement them, and open standards keep everyone reading from the same context.
Spec authoring
Tools that turn intent into structured, reviewable specs in your repo. Spec Kit writes specs/<feature>/spec.md; Kiro generates requirements, design, and tasks; OpenSpec manages specs as change proposals.
Coding agents
The agents that implement against specs. Each reads the spec and project instructions from the repo, plans, and executes tasks, whether it runs in a terminal, an IDE, or CI.
Shared context standards
Open standards that let people, tools, and agents share one view of the work: AGENTS.md for repo-level instructions, and the Model Context Protocol (MCP) for structured access to project state like a backlog.
The missing layer
The bottleneck moved to either side of the coding session
Every tool above is session-scoped: it takes one idea from intent to implementation, then forgets. That was fine when writing the code was the slow part. It is not the slow part any more, and the playbook's central observation is that the constraint simply moved to the steps on either side of it.
Adopt spec-driven development for real and you feel this quickly. Dozens of spec.md files across products and repos, each authored by a different mix of product managers, engineers, and agents. Then the questions arrive, and none of them are answerable from inside a session: which spec do we build next? Who owns it? What is blocked on what? What ships in this release? An agent starting work tomorrow has no memory of what the team decided today.
Traditional trackers answer those questions by copying specs into a second system of record, which is exactly the duplication spec-driven development was meant to end, and they answer them to people rather than to agents. Specboards answers them in place. It indexes the spec files already in your repo, layers intake, a prioritized backlog, a board, a roadmap, releases, and goals over them, and exposes the whole thing over MCP. The agents implementing your specs read the same plan, take work from it, write specs back to git, link their pull requests, and move their own cards. Several can do that at once without colliding, because they share one board and one validated workflow. You keep the decisions worth keeping: what is worth building, and whether what came back is right.
Where we fit
Three stages substantially, two partly, one not at all
Specboards is built to be compatible with that model, not dependent on it. Nothing here requires you to adopt the playbook, we did not write it, and none of this implies an endorsement. So that the mapping is worth reading, every row says what we do not do.
| Stage | What Specboards does | Where it stops |
|---|---|---|
| Plan | Ideas intake is where an intent lands. Promoting one creates the work item, and the spec is committed into your repo, version-controlled from the first line. | Not the brainstorming session itself. That is your agent, writing back to us when it is done. |
| Design | Specs are written to specs/**/spec.md and committed, so a specification arrives as a reviewable diff. The workflow says out loud whether design is still open. | Not the skills that constrain the spec. Brand, security, and compliance policy live in your agent's configuration. |
| Build | The ready stage is the accepted-plan boundary: work is not picked up before it. Typed dependencies say what is blocked, and the hierarchy says what a change belongs to. | Not plan mode, CLAUDE.md, worktrees, or the coding session. We are what the session reads and writes, not the session. |
| Test | Nothing. Your CI does this. Failing checks show up on the board through linked pull request state, which is reporting rather than testing. | All of it. |
| Deploy | Live pull request, issue, and branch state reconciles onto the board on every push. Agent identities, scoped keys, quotas, and an audit trail of every spec write are the governance surface. | Not the review passes themselves. |
| Maintain | An unattended agent identity with a scoped key is the no-person-in-the-path shape, and what it finds re-enters as an idea or a work item, in the backlog people already work from. | Not the trigger. Watching production should stay deterministic, and it is not ours. |
That is the honest shape of a tool sitting between coding sessions rather than inside them. The longer version, with the reasoning behind each row, is in the repository.
Further reading
Core material from the platforms
First-party docs and posts from the teams building spec-driven agentic development.
Anthropic
The AI-native SDLC playbook
The six-stage model this page is built around: what plan, design, build, test, deploy, and maintain each become once code is no longer the bottleneck, and which artifact carries the work between them.
GitHub
Spec-driven development with AI: get started with a new open source toolkit
GitHub's announcement of Spec Kit, and the clearest statement of the core idea: the spec becomes the contract your agents use to generate, test, and validate code.
GitHub
Spec Kit documentation
The official docs for the specify, plan, tasks, implement workflow, with support for 30+ coding agents including Copilot, Claude Code, and Gemini CLI.
Kiro (AWS)
Specs: concepts and workflow
How Kiro structures a spec into requirements.md, design.md, and tasks.md, and runs agents against the approved plan.
Anthropic
Best practices for Claude Code
The agent-side case for specs: separate planning from implementation, and keep durable instructions in files the agent can read instead of chat history.
OpenAI
Custom instructions with AGENTS.md
How Codex discovers and layers AGENTS.md instruction files before doing any work, from global scope down to the repo.
agents.md
AGENTS.md: an open format for guiding coding agents
The cross-vendor standard (stewarded under the Linux Foundation) that gives every agent a predictable place to find project instructions.
Model Context Protocol
modelcontextprotocol.io
The open protocol that lets agents reach beyond the repo: read a backlog, update status, and act on structured project state.
martinfowler.com
Understanding spec-driven development: Kiro, Spec Kit, and Tessl
A critical, tool-by-tool comparison of the leading approaches, useful for understanding the trade-offs before you pick a workflow.
OpenSpec
OpenSpec on GitHub
A lightweight, agent-agnostic take on SDD: change proposals and specs as markdown in git, reviewed before any code is written.
Already writing specs? Give your agents the backlog around them.
Specboards turns the specs in your repo into a backlog, board, and roadmap that your team and your agents both work from. Open source, so you can run the whole thing yourself.