GitHub Spec Kit Taught Millions of Developers the Right Idea and Left the Hard Half Undone
GitHub Spec Kit did something for this category that no startup could have afforded. It spent a year and gathered well over 100,000 stars teaching several million developers that the specification, and not the code, should be the source of truth for what a system does.
That is category creation at enormous scale, funded entirely by somebody else, and it lands directly on the thesis we sell. This is tailwind for us rather than a threat, and the idea at the centre of it is correct.
Then you look at what the method actually requires, and two things become obvious.
How spec driven development works in practice
The Spec Kit flow is a forward flow. You write a specification describing what you want, the toolchain turns it into a plan, the plan becomes tasks, and an agent implements the tasks. The specification is the durable artifact and the code is downstream of it.
For a new project this is a genuinely better way to work. The agent is not guessing at intent, because intent was written down first. Review argues about the specification rather than about 3,000 lines of generated code. The whole thing composes with agents in a way that ad hoc prompting never did.
The assumption sitting underneath all of it is a blank page. Specification first means the specification exists before the code, which is true exactly once in the life of a system.
The two hardest parts, both left open
The first hard part is derivation. Almost nobody is starting from a blank page. A ten year old company is carrying millions of files of legacy that nobody currently employed has read, and that is where production actually breaks. To use spec driven development on that estate you first need a specification for code that already exists, which means reading all of it.
That is the part the method structurally cannot do. Deriving a specification from 10 million files by feeding them to a frontier model exceeds context limits by roughly four orders of magnitude. At a conservative 1,000 tokens per file, 10 million files is around 10 billion tokens, and a 1 million token window holds 0.01% of that.
The second hard part is verification. Once a specification exists, something has to check that the shipped code still matches it, on every change, forever. The ecosystem is fairly open about that being out of scope. Spec Kit generates from the specification and does not check back against it.
Both of those are the product. One of them is why we exist.
A note on notation, because it is not a roadmap gap
There is a related constraint worth understanding, because it comes up whenever spec driven tooling gets discussed alongside AWS Kiro.
EARS notation, which several of these tools adopt, is a future tense grammar. When a condition holds, the system shall do something. There is no sentence available in that syntax that describes what an existing function currently does. So the core artifact is structurally incapable of documenting a legacy estate, and that is a property of the notation chosen rather than something a future release fixes.
Tessl approaches the same territory from a different angle by holding a registry of specifications for open source libraries, something like 10,000 of them for public packages. That is a good product answering how an agent should use a well known framework. It says nothing at all about what your payments service does.
What derivation looks like when you actually build it
ByteBell is a verification layer generated on top of a codebase of any size below 10 million files, and the whole architecture exists to solve the derivation problem at a price somebody will pay.
Cheap open source models read every file once at indexing time. An agent detects the boundaries of classes, functions and every other language element, stores them separately, and then analyses each one in the context of its file, its module, its repository, and across every repository. The result for one file includes what the module does, why it exists in business terms, what users lose if it fails, the capabilities it provides, its edge cases, the contracts it provides, its preconditions, and the specific places where its behaviour is genuinely ambiguous.
That last field matters more than it looks. On a real store adapter module, the derived specification records what the code does and separately flags an open question about which equality function applies when neither a per call nor a default one is supplied, because that is what decides the equality semantics. A specification written forward would have stated an answer. A specification derived from running code correctly reports that the system has not decided.
All of it is written in plain English with the file and the line kept on every claim, which means a product manager can read a service without opening an editor and an engineer can check any line of it in about 10 seconds.
Then the direction reverses
Once the specification is derived, verification becomes possible in the direction that matters.
We trace what a proposed change touches, generate tests for it, run them, and then review each modified file against what that file promised at the indexed base rather than against what the diff claims it changed. Collateral damage is checked across the other repositories that read the same helper before anyone approves. You do not rebuild the code from the layer. You establish that the code still does what it was supposed to, which is how a hallucination gets caught before it merges instead of after it ships.
Change the intent once, then check every change across 100 repositories against it in lockstep. That is the round trip a forward only specification cannot close.
What it costs
Indexing runs about 0.89, against roughly 0.11.
Accuracy of code holds above 93% while token spend drops by roughly 80%. Both move in the same direction because the model reading the layer never has to run the chain of inference that establishes meaning, and that chain is where both the cost and the errors accumulate.
Where Spec Kit is the right tool
Starting a new service from scratch with an agent doing the implementation is exactly the case spec driven development was designed for, and we would use it there. It is free, it is well documented, and the discipline it imposes is good for teams regardless of tooling. The two approaches also compose well together. A forward specification for new work and a derived specification for everything that already exists are answering the same question from opposite ends of the same system.
The honest limitation
A derived specification is an inference about what code means rather than a statement of what somebody intended. Where the code is genuinely ambiguous, we report the ambiguity instead of resolving it, and there are cases where a human writing a forward specification would simply have made the call and been clearer for it. Our answer is that every claim carries a file and a line so nothing has to be trusted, and that the layer re-derives on every commit, though there is a window after a push where a claim can lag the branch.
We also do not cover every language. Mojo is not indexed today.
This is what ByteBell builds
Take the oldest service you own, the one where the person who wrote it left years ago. Ask a spec driven tool to tell you what it currently does. Then derive a specification from the running code and read it. The difference between those two experiences is the reason the derivation problem was worth two years of our time.
ByteBell is the verifiable context layer for code. We run the LLM compiler pattern, a one time pass where a model reads every file and lowers it into a verifiable code IR capturing purpose, business context and cross repository relationships, on your own infrastructure through Docker, with your source never leaving your environment. Every engineer, on any copilot, queries the same representation through a single MCP url, and every agent edit is checked against it before it lands, using per file SHA-256 diffing so only what actually changed gets examined again. Across 46 Kubernetes ecosystem repositories and 150,000 files we measured roughly 10% higher accuracy at 70% lower cost, on about a fifth of the tokens.