Standards Research

Spec-Driven Development — Twenty Thousand Repositories, No Grammar

Three toolkits taught a generation of developers to write the specification before the code. None of them wrote a specification for the specification, and nothing any of them produces can be checked by a machine.

On the standard: Spec-Driven Development · Updated September 2026 · Evidence as of 19 September 2026

This is my standing research position on spec-driven development — updated as the toolkits move, and written to be argued with. If I have something wrong, the fastest way to change this page is to point me at the artifact.

What they got right, and it is not a small thing

Start here, because the criticism below only matters if the achievement is real. It is.

Agentic coding has one failure mode that dominates all the others: the requirements live in a chat transcript. A transcript cannot be reviewed before the work starts, cannot be diffed, cannot be approved, and cannot be pointed at afterwards when the result is wrong. Spec-driven development moved that conversation into files in the repository, and in doing so made the plan the reviewable unit instead of the diff. That is a genuinely good idea, and the adoption numbers say developers agree.

They also converged, independently and fast. Kiro entered preview in July 2025, Spec Kit and OpenSpec were both created that August, and all three arrived at substantially the same artifacts: a statement of requirements, a technical design, and a sequenced task list. When three teams solve a problem separately and produce the same three documents, the documents are probably right.

What I measured

All counts below are from GitHub code search on 19 September 2026, over public repositories, excluding forks. Each file I counted is one-per-repository by construction — a sample of 100 results for the OpenSpec marker returned 100 distinct repositories with no duplicates and no forks — so the file count stands in for a repository count. GitHub indexes a subset of public code and these numbers are a floor, not a census. Private repositories, which is where most of this work happens, are not visible to any instrument I have.

Installing a toolkit is not using one, so I counted the work as well. OpenSpec repositories have published 164,608 change proposals (openspec/changes/*/proposal.md) and Kiro repositories 30,848 feature task files (.kiro/specs/*/tasks.md). Those are not installs. Those are features somebody actually specified before building.

I could not measure Spec Kit’s feature artifacts, and the reason is itself a finding. OpenSpec namespaces its work under openspec/ and Kiro under .kiro/, so their artifacts are addressable — you can ask a question about them and get an answer. Spec Kit puts features in a generic specs/ directory at the repository root, which cannot be distinguished from every other specs/ folder on GitHub. I will not publish a contaminated number, so there is no Spec Kit row for work done. A convention that cannot be told apart from the ambient filesystem cannot be measured, by me or by anyone, including the people who maintain it.

Where it falls down

There is no specification of spec-driven development. Not a disputed one, not a draft one — none. Three vendors publish three sets of conventions defined by their CLIs and their documentation, and each can move them in a release. Spec Kit shipped 54 releases in the last 90 days, roughly one every forty hours. There is nothing wrong with shipping fast; there is something wrong with shipping fast against conventions that thousands of repositories now encode on disk, with no versioned contract saying what those conventions are.

Nothing produced is machine-checkable. This is the part that should bother anyone who works with API contracts. A requirement in OpenSpec is a ### Requirement: heading with a SHALL statement and #### Scenario: blocks using **WHEN** and **THEN**. A requirement in Kiro is a user story with acceptance criteria. Both are prose conventions inside Markdown. No grammar defines them, no schema constrains them, and no validator checks that a requirement says anything in particular. The CLIs validate that files exist and are shaped roughly right. Nothing validates the content, which is the only part that matters.

A false friend worth naming. OpenSpec has a schema.yaml, and it is not what an API person will assume. It defines which artifacts a workflow emits and in what order — the shape of the process, not the shape of a requirement. It is a workflow bundle, closer to a template manifest than to JSON Schema. Reading “schema” here as “something that validates my content” is the mistake the word invites, and the docs do not go out of their way to prevent it.

The artifacts do not interoperate at all. A change folder written for one toolkit does not read in another. There is no shared grammar for a requirement, no shared directory, no conformance notion, and no converter. Twenty thousand repositories have committed to a vendor’s conventions, and the only exit is a rewrite.

The comparison nobody is making

API-first is the same instinct, twenty years older: agree the interface before you build it, because discovering it afterwards costs more. The difference is the artifact.

API-first produced OpenAPI — a document with a published specification, a JSON Schema, linters, generators, a conformance notion and an ecosystem that can argue about whether a given document is valid. That is why the specification map on this site can name, for every edge between nine specifications, the property that proves it. The contracts are checkable, so claims about them are checkable.

Spec-driven development has produced prose for a language model to read. It is a real practice with real adoption and no artifact anyone can verify. That is not a moral failing — the toolkits are two years old and optimising for adoption, which is the correct thing to optimise for at two years old. But it is the gap, and it is the whole question.

What I think happens next

One of three things.

It converges on something checkable. Someone publishes a grammar for a requirement — plausibly built on the BDD scenario form all three already borrow — plus a validator and a conformance suite. The practice becomes a standard, and this page gets rewritten.

It stays three house styles. Each vendor evolves its conventions alone, the artifacts stay unreadable to each other, and spec-driven development is remembered as a moment in tooling rather than a standard. The Markdown survives; the interoperability never arrives.

The agents absorb it. Models get good enough at reading arbitrary planning prose that the conventions stop mattering, and the whole category dissolves into “write it down somewhere.” This is the outcome the vendors should fear most and the one their own product improvements make likelier.

My position is the second, absent a forcing function — and the forcing function this category has never had is a buyer who requires portability. Nobody procures spec-driven development. Until somebody does, three vendors have no reason to agree.

What I am building

Three things, all on this site.

I have catalogued all three toolkits and the practice itself — OpenSpec, Spec Kit, Kiro and spec-driven development — each stating plainly what it is not: no specification document, no governing body, no interoperability. The practice is filed as a methodology beside BDD and API-first, because that is the company it keeps.

I am re-running the counts above each quarter, so the adoption curve and the grammar question move together on one page. If a validator ships, that is the quarter this page changes its mind.

And I am watching one number in particular: whether anything ever appears that can read another toolkit’s artifacts. It has been two years and the answer is zero. The day it stops being zero is the day this becomes a standard rather than three products.

Correct me

Every number here is reproducible — the queries are named in the method above, and anyone with a GitHub token can re-run them. If you maintain one of these toolkits and I have described your artifacts wrongly, or if a grammar or validator exists that I have missed, point me at it and I will re-measure and re-date this page. That is cheaper for you than letting it stand.