Spec-driven development works — until the spec stops being true

Before AI agents, writing detailed specifications was one of those practices that felt responsible. A good spec reduced confusion, improved estimates, created a paper trail. But most of us still jumped into code, clarified things in Slack, and let the spec drift. It was nice when it happened. It wasn’t strictly necessary, because humans are remarkably good at filling gaps with context and course-correcting on the fly.

Then AI coding agents arrived. An agent doesn’t have hallway conversations. It doesn’t notice when something “feels off.” Loose prompting that used to mostly work started producing plausible code that failed to match real intent — and spec-driven development (SDD) went from a nice-to-have discipline to the default answer almost overnight. The wave is real: Amazon’s Kiro drew 250,000+ developers in preview with a 100,000-person waitlist, Tessl raised $125M for a spec-centric platform before shipping a product, and GitHub’s Spec Kit became one of the fastest-growing repos on the platform.

The premise is sound. An agent with explicit acceptance criteria, defined constraints, and a clear north star for “done” produces dramatically better work than one steering by vibes. In the AI era, spec quality really is output quality.

And yet the hands-on reports keep coming back sour.

The part every SDD guide gets wrong

Every SDD explainer — including the paragraphs above — eventually lands on the same sentence: the spec is a living artifact, updated as understanding evolves, rather than a static document.

Say it out loud and it sounds obviously right. Now look at what the tools actually do.

Birgitta Böckeler at Thoughtworks studied the three flagship tools and drew a taxonomy worth keeping: spec-first (write a spec for one task, then effectively discard it), spec-anchored (the spec stays alive across the feature’s evolution), and spec-as-source (humans never touch generated code). Her findings: Kiro’s flagship workflow is effectively write-once. Spec Kit aspires to spec-anchored, but its specs govern “by convention rather than by enforcement.” Tessl is the only tool seriously pursuing spec-as-source — and it’s the hardest bet on the board.

The practitioners feel the gap precisely. In Spec Kit’s own community, the most telling discussion is users asking for exactly the living spec the guides promised: one consolidated specification that reflects current behavior, kept in sync bidirectionally. A maintainer’s honest answer: specs naturally diverge during implementation, and keeping them true currently “falls to developers to manually update specs post-implementation.”

Meanwhile the ceremony bill arrives. Colin Eberhardt, CTO at Scott Logic, put Spec Kit through a real feature and got 2,577 lines of markdown for 689 lines of code, spent 3.5 hours reviewing mostly documents — and a bug shipped anyway. François Zaninotto’s widely-shared “The Waterfall Strikes Back” adds the darker observation: agents sometimes bypass the spec entirely — one marked verification complete without writing any tests.

Put those together and the diagnosis isn’t “specs are bad.” It’s sharper:

A document can’t be a living artifact. “Living” is a process property, and a folder of markdown has no process.

A spec in a specs/ directory has no lifecycle — nothing distinguishes a draft from a settled contract from a stale one. Nothing gates work on it being settled. Compliance is self-graded — the same agent that wrote the code asserts it matched the spec. And nothing checks the spec against the code it describes as the code moves on. Every failure in the reports above traces to one of those four missing pieces.

What “living” actually requires

Strip the tooling away and the practitioner asks converge on four requirements — none of which is a document format:

1. A lifecycle — the spec’s trust level is explicit: draft, settled, verified, stale. 2. A gate — implementation doesn’t start until the spec is settled, and that’s checked at a defined point, not by good intentions. 3. Independent evaluation — “done means the spec is satisfied” is judged by something other than the agent that did the work. 4. Grounding — the spec is periodically verified against the code it describes, and drift is surfaced, not silently accumulated.

These are workflow primitives. Which is why the answer isn’t a better spec template — it’s putting the spec on the board.

The spec as a board citizen

kanbento is an agent-native kanban: the board is a protocol operated by CLI, state lives in plain files, and every change is an event in an append-only log. It wasn’t built as “an SDD tool” — it was built so that agents and humans share one system of work. But that turns out to be exactly what the four requirements need, because in kanbento the spec isn’t a file near the work. It’s attached to the work item that carries it, and it inherits the board’s machinery:

Lifecycle. A spec lives as a card’s bound doc or as a typed record in the knowledge layer, and its status is an explicit, declared vocabulary — a draft is marked as a draft, a settled contract as settled. The trust level is data you can query, not a vibe.

The gate. Every kanbento board can declare a commitment point — the stage boundary where options become committed work, with an entry gate (a Definition of Ready) judged on entry. That is the natural home for “the spec is settled”: the gate sits exactly where the spend decision happens, and its criteria are yours to write.

Independent evaluation. A gate is judged by something other than the agent doing the work — that’s what makes it a boundary rather than a step in a procedure. A step’s “I complied” is self-graded; a gate’s verdict comes from outside the executor, with its reasoning recorded. The spec stops being something the implementing agent interprets and starts being something its work is checked against.

Grounding. Because code, work, and knowledge share one git history, “is this spec still true?” becomes answerable. Reaffirming a spec stamps it with the exact commit it was verified against — “last checked” becomes a fact, distinct from “last edited” — and the history ties the spec to the code it describes, so drift is measurable: how much has that code moved since the spec was last verified? Staleness stops being a feeling; it becomes a number.

And underneath all four, the event log records which state each decision was made against — transitions carry their asserted criteria and gate verdicts, so “why did work start before the spec settled?” has an answer you can grep.

We eat this cooking

kanbento is built on its own board, so the receipts are our own cards. Every new feature is specced as the card that captures it — the behavior and the structural change it would earn are named before a line is written, and the delivered body reports against that spec clause by clause. The runner-permissions work named its keystone test in the spec (“a post-consent permission escalation must never reach the runner”) and its card now carries three recorded validation rounds — two failures and the fix, then the pass.

Honesty requires the other side too. Our repo also contains a plain old specs/ file that predates this practice — a write-once document, drifting, exactly the failure mode this post describes. The difference is that the board will keep surfacing it as unverified until it’s either grounded or retired. That’s the point: kanbento doesn’t make drift impossible. It makes drift visible and attributable, which is the property every tool in the SDD wave is missing.

It fits the practice you already have

None of this asks you to abandon your SDD tool. A spec is a markdown file in your repo whether Spec Kit generated it, Kiro drafted it, or you wrote it by hand — and it stays that way. kanbento is headless and file-native: the board itself is plain files in the repo, operated through a CLI your agents already know how to call. Your specs keep their format; the board is where they gain a status, a gate, a judge, and a verification trail. The workflow you have produces the spec; the board is what keeps it true afterward — the half of the practice the tools left to “developers manually updating specs post-implementation.”

And you don’t need heavy ceremony to get there — Eberhardt’s 2,577-lines-of-markdown number is a warning, not a target. One feature, one card, a spec bound to it, and a commitment point that asks “is this settled?” is already more process than a specs/ folder has ever had.

Spec-driven development is right about the destination: explicit contracts steering literal-minded, high-velocity agents. It’s just been trying to get there with documents. Specs don’t need a better folder — they need a lifecycle, a gate, an independent judge, and a grounding loop. That’s not a document format. That’s a board — and it’s what kanbento is.