Where Spec4 sits in spec-driven development

The taxonomy most people use

The most widely used way to sort SDD tools comes from Birgitta Böckeler's analysis of Kiro, Spec Kit, and Tessl on martinfowler.com (Understanding Spec-Driven Development). She describes three levels of ambition:

The same three levels appear in Deepak Babu Piskala's preprint Spec-Driven Development: From Code to Contract in the Age of AI Coding Assistants. It is the paper most often cited when someone needs an arXiv reference for SDD. Piskala goes further than Böckeler on one point. He defines SDD as treating specifications as the source of truth, with code as a derived artifact, and he argues that what separates SDD specs from old-fashioned design documents is that they are enforced rather than advisory: tests fail and builds break when code diverges.

It's worth being clear that none of this is settled. A September 2026 paper on SDD for agentic software engineering, from Díaz, Gayoso, Cimminio, and Pérez at the Universidad Politécnica de Madrid, notes that the term was named in practitioner discourse, and no peer-reviewed study has yet defined it, delimited its scope, or measured its effects. The Thoughtworks Technology Radar tracks it as a technique, not a standard.

Where Spec4 lands: none of the three, on purpose

Spec4 doesn't fit neatly on the ladder, and it would be misleading to pretend it does. Its different parts sit at different levels.

The phase files are spec-first. Phaser writes phases/phase1.md … phaseN.md for one round. You hand them to your coding agent, and once the round is marked IMPLEMENTED they are history. Nobody maintains them.

The intent layer is roughly spec-anchored. vision.json and feature_specs.json carry forward from round to round. In a revision round, Brainstormer records which features were added, modified, and removed, and every downstream agent works only on that delta. This is the one layer that is kept up over time, but it describes what the product is for and what each feature must do, not how the code is built.

Spec-as-source is rejected outright. Spec4 assumes you and your agent will edit the code directly, and that other tools will too. A hotfix, a refactor, or a week of work done without Spec4 is simply what the next round plans against.

The best short description of the overall position is code-anchored, re-derived per round:

The plan is never the source of truth for long. The code is, and each round re-reads it.

Every round after the first starts with CodeScanner reading the repository as it actually is, not as the last plan said it would be. That runs directly against the principle, in Piskala and again in Díaz et al., that when spec and code disagree the spec wins and the code is re-derived. By Piskala's own spectrum Spec4 is still SDD: spec-first is his entry level, and he defines it as a spec that may be discarded once the code exists. What Spec4 fails is his enforcement criterion, and that is the argument worth having. Here is my side of it.

Why re-derive instead of maintain

There are four broad answers to spec drift:

1. Tolerate it. Write the spec, build, and move on. Böckeler observed that most current tools end up here in practice, whatever they aim for.
2. Continuously reconcile it. Keep the spec true as code changes, for example with an LLM that proposes spec updates. NotarAI is one tool that explicitly targets this gap.
3. Make it impossible. Never let humans edit code (spec-as-source).
4. Make it irrelevant at the boundaries. Let the code drift from the plan between rounds, then re-read the code before planning anything new. This is Spec4's answer.

Option 4 gives up something real: between rounds, nothing tells you the code has diverged from the plan. In exchange, it works in brownfield repositories, it tolerates hand edits and other tools, and it never asks you to keep a document in sync on faith. Inside the artifact chain itself, drift is tracked: every artifact is dated against the ones upstream of it, and the project page flags stale inputs when you re-run an earlier agent.

How Spec4 compares with the tools people know

Spec4's overall shape — specify, then plan, then tasks — is the same one GitHub Spec Kit and Kiro use. The differences are these:

Two things in this table are unusual enough to call out.

Decisions are recorded, not just specs. At every step after Brainstormer, Spec4 lays out options and tradeoffs, and you choose. Agentifier, for example, writes the tool's recommended AI tier and your decision, with your rationale, into the same record. When the two disagree, the file shows both, so anyone reading the spec later can see where you overrode the tool and why.

The scope goes well beyond the feature. Most SDD tools specify the change in front of you. Spec4 also specifies:

• where AI belongs in the product, and how much of it, on a nine-tier ladder that starts at deterministic code;
• an approved dependency list, which Phaser cannot go beyond without your explicit yes;
• a deployment plan written as complete files.

That is more ceremony, and Piskala names it as a pitfall: teams that drown in generated plans, task lists, and intermediate documents. I take the point. Spec4's answer is that the whole-system scope is for the first round of a system you intend to ship, and that half the pipeline is optional: Agentifier, Designer, and Deployer can be skipped, and Spec4's own three rounds skipped two of them. SnarkCheck ran all six, because it was a new system with model calls in it and a deployment to plan — the case the full pipeline is for. If you run all seven agents on a small change, that is the sledgehammer problem below, and it is on you.

Being outside the agent has a real cost too. Spec Kit and Kiro keep planning and implementation in the same loop. With Spec4 you hand the phase files over yourself, and there are no commands inside your coding agent. I chose this for agent-agnosticism, and it is a trade, not a free win.

The objections, answered honestly

"It's just waterfall."

This is the most common critique. François Zaninotto put it well in Spec-Driven Development: The Waterfall Strikes Back (HN discussion). The worry is that a big spec gets written up front, the code drifts from it, and a month later the plan describes a program that doesn't exist.

Spec4's unit of work is the round, not the spec. A round covers one feature or one rework. Each round is planned against the current code, and a revision round plans only the delta, not the whole application. Built With Spec4 took nine rounds, with hand edits in between. Spec4 has been used on itself for three rounds; that history is committed under .spec4/ in the repo.

The up-front work has a size. SnarkCheck's whole plan — vision, feature specs, AI tiers, mock, stack, seven phases, deployment — took 51 minutes of dialogue and $3.44 in model calls, and the coding agent built from it.

That said, within a round, Spec4 does plan everything before the agent writes any code, and a round is a meaningful amount of up-front work. If you want to discover the design by writing code, Spec4 will get in your way.

"It's a sledgehammer for small changes."

Critics often point out that SDD tools produce pages of requirements for a one-line bug fix. I agree. Spec4 doesn't solve this; it tells you where the line is. A round is the unit for a feature or a rework. For a quick script, a refactor, or a small feature in a mature codebase, don't run one. Use your coding agent directly.

"It's just BDD with branding."

Bryan Finster makes this case in Spec-Driven Development Isn't New, and he's largely right about the underlying idea. Writing down intended behavior before building is decades old, and Spec4's feature_specs.json (inputs, outputs, success criteria, failure modes) will look familiar to anyone who has written acceptance criteria.

What's new is who the audience is. The phase files are written for a coding agent, not a human team, so they cover the things agents get wrong:

• a risk assessment naming where the agent is likely to hallucinate;
• a pinned stack, so the agent doesn't choose its own dependencies;
• a Verification section containing the exact command that proves the phase is done. SnarkCheck's phase7-verification.md records that section being run, and what was not run.

"Specs aren't enforced, so what's the point?"

This is the strongest objection to Spec4 specifically. Piskala's central distinction between SDD and old-fashioned design documents is that SDD specs are enforced: tests fail and builds break when code diverges.

Spec4 does not enforce anything. It stops at the spec. Building and verifying the code is your coding agent's job and yours. No spec can force an agent to comply. Every phase ends with a Verification section that is a command you can run, not a description of what "done" looks like. But Spec4 doesn't run it, doesn't gate on it, and doesn't wire it into your CI. The dependency list is the same story: Phaser can't add a library without your visible yes, but nothing stops your coding agent adding one at build time. By Piskala's definition, Spec4 produces very well-structured advisory specs with executable acceptance checks attached.

SnarkCheck shows how that plays out. Its coding agent added no library beyond stack.json. It also left out the Sentry integration the deployment plan called for, and it made the LLM proxy a private service where the plan had said web service with a shared secret — stricter than asked. Omission, improvement, and compliance, none of them enforced, all of them visible because the plan is in the repository next to the code. SnarkCheck

I think that's the right boundary for a tool that doesn't know or control which coding agent you use. But if enforcement is what you mean by SDD, Spec4 only gets you partway there.

"The model writes the spec, so it's the model's opinion."

Nothing moves forward without your confirmation, and where the tool's recommendation and your decision differ, both are recorded. You can still click through without thinking, and a spec is only as good as the decisions put into it.

When Spec4 is the wrong tool

• You want the spec to be the permanent, authoritative description of your system → look at spec-anchored or spec-as-source tools.
• You want planning inside your agent's loop, with no hand-off → Spec Kit or Kiro will feel smoother.
• You need spec compliance enforced in CI → Spec4 gives you the verification commands, but the enforcement is yours to build.
• The change is small → skip the round.
• You're vibe coding, hacking on a throwaway prototype, or still exploring what to build → a coding agent on its own is faster. Spec4 is for code you intend to ship and maintain. If a prototype turns into something real, run a round against it then: CodeScanner will plan from what's there.

When it fits

• You're starting a real system, or making a substantial change to one, and you want the decisions made and written down before an agent starts guessing.
• You work in a brownfield repository that other people, other tools, and you by hand all edit.
• You want the plan to cover production concerns — failure modes, non-functional goals, deployment, where AI belongs and how much — not just the happy path.
• You switch coding agents, or use more than one.
• You want every artifact as a plain file in your repo, generated on your machine with your own model provider, and a record of what each step cost. SnarkCheck's usage.json is one such record.

Sources

• Böckeler, B. Understanding Spec-Driven Development: Kiro, spec-kit, and Tessl. martinfowler.com, Oct 2025.
• Piskala, D. B. Spec-Driven Development: From Code to Contract in the Age of AI Coding Assistants. arXiv:2602.00180, Jan 2026.
• Díaz, J., Gayoso, J., Cimminio, A., and Pérez, J. Spec-Driven Development for Agentic Software Engineering: Harnessing Human–Agent Teamwork. arXiv:2609.00252, Sep 2026.
• Agarwal, S., Singhal, A., Breaux, T., and Vasilescu, B. SpecMine: A Large-Scale Corpus of Spec-Driven Development Artifacts. arXiv:2608.25202, Aug 2026.
• Thoughtworks. Spec-Driven Development. Technology Radar, 2025.
• Zaninotto, F. Spec-Driven Development: The Waterfall Strikes Back. Marmelab, Nov 2025. (HN)
• Finster, B. 5-Minute DevOps: Spec-Driven Development Isn't New. Medium, Nov 2025.
• GitHub Spec Kit · Kiro · Tessl · NotarAI
• Specification-driven development. Wikipedia.