**July 8, 2026**

# 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](https://aws.amazon.com/blogs/aws/aws-weekly-roundup-kiro-waitlist-ebs-volume-clones-ec2-capacity-manager-and-more-october-20-2025/),
Tessl raised [$125M for a spec-centric platform before shipping a product](https://techcrunch.com/2024/11/14/tessl-raises-125m-at-at-500m-valuation-to-build-ai-that-writes-and-maintains-code/),
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](https://martinfowler.com/articles/exploring-gen-ai/sdd-3-tools.html):
**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](https://github.com/github/spec-kit/discussions/152) 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](https://blog.scottlogic.com/2025/11/26/putting-spec-kit-through-its-paces-radical-idea-or-reinvented-waterfall.html)
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"](https://marmelab.com/blog/2025/11/12/spec-driven-development-waterfall-strikes-back.html)
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.

## Run your workflow as a protocol, not a board

kanbento is a headless, agent-native kanban — your agents operate the board through a CLI while state lives in plain files you can read and diff.

[Get in touch](/contact)