The Spec Workflow

A team picks up a ticket, opens a blank file, and starts briefing the coding agent. The first sentence describes what the feature should do. The second explains why. The third, without any change in register, specifies which library to use. By paragraph four the file is listing acceptance criteria; by paragraph six it is sketching an implementation order. Nothing marks where one kind of decision ends and the next begins, because the file was never designed to mark that — it grew the way a Slack thread grows, one more thought bolted onto the last.

The agent reads all of it as one undifferentiated brief, and it behaves accordingly. It starts writing code before the requirements are settled, because nothing in the document told it requirements were still open. It picks a data model nobody actually agreed to, because the “how” was buried inside the “what” and it had to guess which sentences were binding. When the output is wrong, there is no smaller artifact to point at and say which part broke — only the one file, now three times longer, with the disagreement folded in as another paragraph. This is what spec-driven development exists to prevent. Chapter 4 covered its first move: a constitution, the standing principles that sit above any single feature. This chapter is about everything downstream of it — the actual shape of turning one intent into working code.

What the field converged on

Two tools reached for almost the same answer within about six weeks of each other, without any visible coordination. Amazon’s Kiro shipped in July 2025 with specs built from three documents — requirements, design, and tasks. GitHub open-sourced Spec Kit that September, breaking the same problem into phases of its own, with a constitution step layered in as the tool matured and quality-gate commands added on top once early users hit the same ambiguity GitHub had set out to avoid. GitHub’s stated rationale for the split is direct: a single request like “add photo sharing to my app” forces a model to guess at, in the company’s own words, “potentially thousands of unstated requirements,” and a phased brief removes that guessing one phase at a time instead of all at once. Neither team was reacting to the other; both were reacting to the same failure mode, and both landed on a structure a reader will now meet across most agent-native tooling, not vocabulary this Library is inventing.

The same problem this Library already named

A single spec.md degrades the same way an overloaded context window degrades, because it is the same failure wearing a different name. Volume II spent a full volume on what happens when a session’s working set holds more than it can keep straight — relevant and irrelevant information compressed into one undifferentiated stream, with no signal for which parts still matter. A planning document that mixes requirements, architecture, and task order is that same undifferentiated stream, just written down before the session even starts and handed to the agent as if it were one coherent thought. The fix in both cases is structural, not stylistic: draw a boundary, decide what belongs inside it, and refuse everything else until the next phase deliberately opens a new one.

Spec-kit’s five phases and three gates

Spec-kit’s canonical chain — verified against the live tool rather than a launch-week summary — runs five commands in sequence, each one consuming the previous command’s output as its own input:

1. /speckit.constitution — writes the standing governing principles (Chapter 4’s territory) that every later phase has to respect.
2. /speckit.specify — defines what to build: user stories and functional requirements, deliberately excluding technology choices.
3. /speckit.plan — commits to how: tech stack, architecture, and the implementation decisions specify was designed to keep out.
4. /speckit.tasks — breaks the plan into an ordered, dependency-aware list of small, ideally independently completable units of work.
5. /speckit.implement — generates the actual code, working from the accumulated constitution, spec, plan, and task artifacts rather than from a single brief.

Three more commands sit alongside that chain as optional quality gates rather than required steps, and their placement in the sequence is deliberate. /speckit.clarify runs before plan, surfacing underspecified requirements through structured, sequential questioning while the cost of asking is still low. /speckit.analyze runs after tasks and before implement, checking spec, plan, and tasks against each other for contradictions before any of them reach code. /speckit.checklist generates a custom validation list against whatever quality criterion the team names, run at whichever point they want a second look. Each gate exists to catch the exact failure this chapter opened with — ambiguity discovered mid-generation, when it is most expensive to unwind — and to catch it earlier instead.

Kiro’s three documents

Kiro reaches a recognizably similar decomposition through three artifacts instead of eight commands. Requirements.md captures user stories with acceptance criteria written, in Martin Fowler’s account of using the tool directly, in explicit “given…when…then” structure — a coarser-grained cousin of specify, doing the “what” inside one document rather than one command plus an optional clarify pass. Design.md documents the technical architecture and implementation approach: plan’s job, folded into a second document instead of kept as a separate command. Tasks.md then generates the discrete, trackable implementation units, with Kiro’s own documentation describing dependency analysis that groups independent tasks into concurrent waves rather than a strictly linear queue. Plan and tasks in spec-kit, design and tasks in Kiro, are doing recognizably the same decomposition at a different granularity — not a different one.

Two decompositions of the same question

Laid side by side, the two shapes answer the same short list of questions in a different number of moves.

The gap that matters is not the artifact count. It is where each tool places the validation step. Spec-kit externalizes it into three separate commands a team can run, skip, or run selectively — clarify, analyze, and checklist are opt-in by design, invisible to a team that never learns they exist. Kiro folds the equivalent checking into approval gates built into its three-phase flow by default, so a team has to actively choose a faster “quick plan” path to skip it. Neither choice is more rigorous in the abstract. One trades a shorter artifact list for gates a team has to remember to invoke; the other trades that memory requirement for two more documents and six more commands to learn.

What this predicts, and what nobody has measured yet

If the phase-boundary argument holds, it should show up in session traces as a specific, checkable pattern: technical decisions pinned down before the first code-writing tool call, not folded into the same turn as implementation; spec and plan artifacts that stop changing once implementation starts, rather than being edited alongside the code they were meant to constrain; optional gate commands that get invoked on the sessions where later rework was avoided, and skipped on the sessions where it wasn’t. Operon does not yet have this instrumented across spec-workflow commands specifically — it is a claim worth checking, not one this Library has verified against its own trace data yet. The sidebar below states the kind of telemetry that claim should be checked against, not a finding.

The size question neither shape answers

Both shapes assume the decomposition is worth its own overhead, and neither flexes much when it isn’t. Fowler’s own hands-on account is the clearest evidence available on this point: pointing Kiro at a small bug fix produced four user stories and sixteen acceptance criteria for a change that needed none of that ceremony — in his words, “like using a sledgehammer to crack a nut” — and running spec-kit against a mid-sized feature felt like overkill for the same reason, one artifact and one command too many for the size of the problem in front of it. A two-hour bug fix and a two-month feature plausibly call for different amounts of process. Neither tool, as shipped, currently hands a team a smaller version of its own workflow to reach for.

An effective SDD tool would at the very least have to provide flexibility for a few different core workflows, for different sizes and types of changes.

Martin Fowler, on using spec-kit and Kiro directly

This is a question this chapter is naming, not resolving. Chapter 6 picks the thread back up from a different direction — not how many phases a workflow should have, but whether the artifacts those phases produce are meant to keep living once the code ships, or whether they were only ever scaffolding to discard. For now the practical move is smaller: treat the five-plus-three shape and the three-document shape as the two verified reference points for what “phased” can mean in practice, and expect to compress both of them by hand — skipping gates, merging documents, running the whole chain in one sitting for small work — until a tool ships that does the compressing automatically.