What is spec-driven development?
Spec-driven development means agreeing on what to build in a written spec before an AI agent writes code, then keeping that spec as the reference for the work. The agent turns the spec into a plan, tasks and code, and people review each step.
Birgitta Böckeler, a Distinguished Engineer at Thoughtworks, put it this way in her October 2025 review of SDD tools: "Spec-driven development means writing a 'spec' before writing code with AI ('documentation first'). The spec becomes the source of truth for the human and the AI." (martinfowler.com).
GitHub's Spec Kit methodology goes further. It calls SDD a "power inversion" in which code serves specifications, and it describes specs that are "versioned, created in branches, and merged" like code. Not every team goes that far. Böckeler describes three levels:
| Level | What it means |
|---|---|
| Spec-first | A spec is written first and used for the task at hand. |
| Spec-anchored | The spec is kept after the task is done and used to evolve and maintain the feature. |
| Spec-as-source | The spec is the main source file. People edit only the spec, never the code. |
In her words, "All SDD approaches and definitions I've found are spec-first, but not all strive to be spec-anchored or spec-as-source."
How does spec-driven development work?
It runs in four steps: specify, plan, break into tasks, then implement and check. A person reviews the output of each step before the next one starts. Spec Kit's README asks you to run its commands "one at a time, reviewing each result before continuing" (github/spec-kit). The steps:
- Specify. Describe what to build and why, as user-facing behavior. Spec Kit's command reference says to focus on "the what and why", not the tech stack, which belongs in the plan.
- Plan. Choose the stack, the architecture and the constraints. This is where technical detail goes.
- Tasks. Break the plan into small, ordered tasks. Spec Kit writes a dependency-ordered
tasks.mdin phases: Setup, Foundational, one phase per user story in priority order, then Polish (Spec Kit command reference). - Implement and check. The agent works through the tasks. Spec Kit's
convergestep then compares the code with the spec, plan and tasks. It adds any missing work as new tasks, and you repeat until it reports "Converged".
Spec Kit's own tasks template shows the format. Each line has an ID, an optional [P] marker for tasks that can run in parallel ("different files, no dependencies"), and its user story:
## Phase 3: User Story 1 - [Title] (Priority: P1) - [ ] T012 [P] [US1] Create [Entity1] model in src/models/[entity1].py - [ ] T013 [P] [US1] Create [Entity2] model in src/models/[entity2].py - [ ] T014 [US1] Implement [Service] in src/services/[service].py (depends on T012, T013)
Which tools support spec-driven development?
The best-known tools are GitHub's Spec Kit, AWS's Kiro and Fission AI's OpenSpec. All three keep specs as Markdown files in your project by default, and all three produce a tasks.md. They differ in how much process they add. This table is from each project's own docs, checked on October 21, 2026:
| Point | Spec Kit | Kiro | OpenSpec |
|---|---|---|---|
| What it is | Open source toolkit (MIT) that adds commands to your coding agent; latest release 1.2.2 | AWS's AI coding agent, with specs built in (IDE, CLI and web) | Open source CLI (MIT) that adds slash commands to your coding agent; latest release 1.14.3 |
| Where specs live | specs/<feature>/: spec.md, plan.md, tasks.md and design notes | .kiro/specs/<name>/: requirements.md (or bugfix.md), design.md, tasks.md | openspec/changes/<change>/: proposal.md, specs/, design.md, tasks.md |
| Main steps | constitution, specify, plan, tasks, implement, converge; optional clarify, checklist and analyze | requirements, design, tasks; Quick Spec does all three in one pass | propose, apply, archive; optional explore |
| Requirement style | User stories with acceptance scenarios | EARS notation: "WHEN [condition/event] THE SYSTEM SHALL [expected behavior]" | Requirements with WHEN/THEN scenarios |
| Task status | Checkboxes in tasks.md; an opt-in extension can turn tasks into GitHub issues | Live status in Kiro's task view | Checklist in tasks.md |
Sources: Spec Kit README and command reference, Kiro specs docs and feature specs, OpenSpec README. These tools change quickly; Spec Kit reached 1.0 in August 2026, for example, so check their docs before you rely on a detail. For hands-on runs through one tool, see our OpenSpec tutorial and GitHub Spec Kit tutorial.
When is spec-driven development worth it?
When the work is big enough to split into several tasks, or several people need to agree on it before code is written. For a small fix, the extra documents can cost more than they save, so skip the spec for typos, one-line fixes and ideas you are still exploring.
Böckeler's review is the most useful critique so far. When she asked Kiro to fix a small bug, "the workflow was like using a sledgehammer to crack a nut": the requirements turned it into 4 user stories with 16 acceptance criteria. With Spec Kit, she found the Markdown files "very verbose and tedious to review", and she "frequently saw the agent ultimately not follow all the instructions." Her review predates Spec Kit 1.0. As of October 2026, both tools offer lighter paths: Kiro's Quick Spec skips the approval gates for well-understood features, and both Kiro and Spec Kit have separate bug-fix workflows.
A rough guide, based on the points above:
| Situation | Spec first? |
|---|---|
| A typo, a one-line fix, a small refactor | No. A clear card with acceptance criteria is enough. |
| A new feature with several user stories | Yes. The spec and plan catch misunderstandings before the agent writes code. |
| Work split across several agents or people | Yes. Everyone builds against the same spec. |
| A vague idea you are still exploring | Not yet. Explore first, then write the spec once you know what you want. |
For a change that needs a plan but not a full spec, Claude Code's plan mode is the lighter option: Claude writes a plan in your session and edits nothing until you approve it.
Where does a task board fit in spec-driven development?
The spec says what to build. The board shows who is building which task right now and what is waiting for review. A tasks.md file works for one agent in one branch, but once tasks are split between agents, or a teammate wants progress, a checkbox in a branch nobody else has open is hard to see. Spec Kit's implement step marks each finished task [X] in that file.
Spec Kit itself points this way. Its opt-in github extension "optionally converts an existing tasks.md into actionable GitHub issues", using the GitHub MCP tools, and "checks existing task IDs to avoid duplicates". The same idea works with any tracker an agent can reach. On a Flux board the pieces divide like this:
| Piece | Lives in | Source of truth for |
|---|---|---|
| Spec (spec.md, requirements.md) | Your repository | What to build and why |
| Plan (plan.md, design.md) | Your repository | How to build it |
| Task list (tasks.md) | Your repository | Which tasks exist and in what order |
| Cards, one per task | The Flux board | Who has each task, its status, questions and review |
One rule keeps this clean: link to the spec, don't copy it onto cards. A card holds the task ID and the path to the files. If the spec changes, nobody has to update twenty card descriptions.
How do you turn tasks.md into cards on a Flux board?
Create one card per open task, with the feature folder and task ID in the title, in a Backlog column. A title like 001-photo-albums T014: <task text> keeps every card unique and easy to find, because the Flux search_cards tool matches titles only. You can create the cards over MCP or with a REST script.
Use the board layout from our kanban board for AI agents guide: Backlog, In Progress, Needs review and Done.
Option 1: ask your agent over MCP
If your coding agent is connected to the Flux MCP server with a key that has the Write scope, give it this prompt after the tasks step. Get the board and column UUIDs from the get_board tool first.
Read specs/001-photo-albums/tasks.md. For each unchecked task (a line that starts with "- [ ] T"), in file order: 1. Call search_cards with the feature folder and task ID followed by a colon, for example "001-photo-albums T014:". If a result with that title has boardId BOARD_UUID, skip the task. 2. Otherwise call create_card on board BOARD_UUID in column BACKLOG_COLUMN_UUID. Title: "001-photo-albums T014: <the task text>". Description: the path of tasks.md, the task ID, and "Read spec.md and plan.md in the same folder before you start." When you finish, list the cards you created and the tasks you skipped.
create_card adds each card to the bottom of the column, so creating them in file order keeps the order of tasks.md. Two limits to know, checked against the Flux server code in October 2026: search_cards returns at most 20 matches, and changes made over MCP are not yet recorded in the board's activity log.
Option 2: a script on the REST API
For an import you can re-run safely, use the REST API with an idempotency key. Flux accepts an X-Idempotency-Key header on POST /api/cards. The key must be a UUID. If Flux has already seen it, it returns the earlier result with "deduplicated": true instead of creating a second card. The script below builds a version 5 UUID from a secret of your own plus the board, feature and task ID, so the same task always gets the same key and nobody else can guess it. Pass the board UUID from get_board every time; the short ID from the URL gives different keys. After a converge step adds new tasks, run it again, and only the new tasks become cards.
"""Create one Flux card per open task in a Spec Kit tasks.md file.
Dry run: python3 tasks_to_flux.py specs/001-photo-albums/tasks.md BOARD_UUID COLUMN_UUID
Send: FLUX_API_KEY=flux_... FLUX_IMPORT_SECRET=... python3 tasks_to_flux.py ... --send
(FLUX_IMPORT_SECRET: a long random string; use the same one every run)
"""
import json, os, re, sys, uuid, urllib.request
path, board, column = sys.argv[1:4]
send = "--send" in sys.argv
feature = os.path.basename(os.path.dirname(os.path.abspath(path)))
task_line = re.compile(r"^- \[ \] (T\d+) (.+)$")
for line in open(path, encoding="utf-8"):
match = task_line.match(line.strip())
if not match:
continue
task_id, text = match.groups()
title = f"{feature} {task_id}: {text}"
if not send:
print("would create", title)
continue
# Same secret + board + feature + task ID gives the same key, so a re-run
# skips it. The secret keeps your keys unguessable.
key = str(uuid.uuid5(uuid.NAMESPACE_URL,
f"flux:{os.environ['FLUX_IMPORT_SECRET']}/{board}/{feature}/{task_id}"))
body = {
"boardId": board,
"columnId": column,
"title": title,
"description": f"Task {task_id} in `{path}`. Read spec.md and plan.md "
"in the same folder before you start.",
}
request = urllib.request.Request(
"https://flux.umin.ai/api/cards",
data=json.dumps(body).encode(),
method="POST",
headers={
"Authorization": f"Bearer {os.environ['FLUX_API_KEY']}",
"Content-Type": "application/json",
"User-Agent": "tasks-to-flux/1.0",
"X-Idempotency-Key": key,
},
)
with urllib.request.urlopen(request) as response:
result = json.load(response)
print("skipped" if result.get("deduplicated") else "created", title)
Without --send it only prints what it would create. We ran that dry run against Spec Kit's own tasks template, where it found 28 open tasks, and checked the request against the Flux API code, but we have not yet sent it to a live board. Try it on a test board first. The key includes the board but not the column, so a test run in a column of your real board would make the real run skip every task. Cards created through the REST API are recorded in the activity log under the name of the person who owns the API key. For how the key works, and what it does not protect against, see idempotency keys for AI agents.
Pick one way per feature. The script's keys know nothing about cards an agent made over MCP, so mixing the two can create duplicates.
How should agents work through the cards?
One card at a time, with the spec as the reference and a person as the last check. The agent moves its card to In Progress, comments, does the task, and moves the card to Needs review. A person moves it to Done after checking the work against the spec. Add a rule like this to the agent's instruction file, such as CLAUDE.md or AGENTS.md:
Work one card at a time from Backlog. Before you start, move the card to In Progress and post a comment that starts with your agent name. Read the files the card points to; the spec in the repo wins over the card. When the task is done, mark it [X] in tasks.md, post a comment with what you changed and how to check it, and move the card to Needs review. Never move a card to Done.
The comment matters because Flux has no task lock: any agent whose key can write to the board can move any card on it. Moving the card and commenting first is a convention, not a guarantee. API-key comments appear under the key owner's name, which is why each agent signs its own. Tasks marked [P] are the natural ones to hand to separate agents, each in its own git worktree, as described in how to coordinate multiple AI coding agents.
When every card has reached Needs review, run the converge step, import any new tasks, and repeat. The spec stays the record of what you meant to build, and the board shows how the work got there.