You installed Spec Kit, ran the workflow, and got a clean spec. The agent read it, built the feature, and the tests went green. On day one this feels like the answer to everything wrong with vibe coding.
Then day thirty arrives. You change the pricing logic, the agent touches three files, and the spec on disk still describes the old behavior. Nobody updated it because updating it was nobody’s job. The document that was supposed to be the source of truth is now the most confident liar in the repository.
This is not a criticism of Spec Kit. GitHub’s Spec Kit does something genuinely useful: it forces you to write down intent, constraints, and a plan before an agent starts typing. That first act of writing catches a huge class of misunderstandings. The question this article is about is the one that comes next. What does spec-driven development need after the spec is written?
The spec is an event, the contract is a process
Most tooling in this space treats the spec as an event. You run a command, you produce a document, you hand it to an agent, you move on. The artifact is the deliverable.
That framing is where the trouble starts. A spec that exists only at the moment of creation is a snapshot of intent taken before anyone knew what the code would actually look like. The moment the first line ships, reality and the document begin to diverge. Left alone, they never reconcile.
The useful unit is not the document. It is the living contract between what you meant and what the system does, maintained across every change that follows. Writing the spec is the cheap part. Keeping it true is the work.
What breaks after the spec
Three things go wrong once the spec leaves the tool that wrote it.
It loses its link to the code. A markdown file in a specs/ folder points at nothing. It says “the checkout flow validates the coupon before applying it,” but it does not know which functions, files, or tests implement that sentence. When the coupon logic moves, the sentence stays put and quietly becomes false. This is spec drift, and it is the default outcome, not the exception.
It loses its evidence. The spec said what a correct result looks like. Did anyone check? A green build is not proof the acceptance criteria were met, as a green build is not a correct feature argues in detail. The spec described the contract; nothing connected that contract to a run that actually exercised it. So you are left trusting a checkbox.
It loses its portability. The next agent, the next editor, or you in three weeks cannot reconstruct why the spec says what it says. The decisions behind it lived in a chat transcript that is gone. This is the argument for treating specifications as portable artifacts rather than files trapped in one workflow.
None of these are failures of the writing step. They are failures of everything the writing step doesn’t cover.
After the spec: three jobs nobody assigned
If the spec is going to stay useful, three jobs have to happen continuously, and right now a person does all three by hand without naming them.
Keep it linked
Every claim in a spec should be attached to the code that implements it. Not “see the repository,” but the actual functions, modules, and tests that make the sentence true. When one of them changes, the system should know which spec claims are now in question. That is the difference between documentation that rots and documentation that raises its hand.
Keep it verified
The spec’s acceptance criteria are only worth anything if something runs them against the real result and keeps the outcome attached to the contract. Verification is not a phase you do once at the end. It is the ongoing answer to “is the contract still met?” This is the whole reason verifying AI-generated code needs evidence rather than self-reported success.
Keep it alive
When the code changes, the spec has to change with it, or the drift compounds until the document is worthless. A spec that updates alongside the code is worth ten specs that were perfect on the day they were written and never touched again.
Right now, on most teams, all three of these jobs are done by one person, by hand, without anyone naming them as work. You are the thing that remembers the spec exists. You are the one who notices, sometimes, that a change made it stale. You are the memory that connects the merged code back to the sentence it was supposed to satisfy. It works until the volume of agent output outruns your attention, which happens fast. The reason the spec rots is not that people are careless. It is that keeping it true was never assigned to anything but a human holding it all in their head.
Respect the entry point, extend the workflow
Spec Kit is a good front door. It captures intent at the moment intent is cheapest to capture, before the agent has committed to an implementation. There is no reason to replace it, and the framing of “Spec Kit alternatives” mostly misses what is actually missing.
What is missing is the back half of the loop. The spec needs somewhere to live where it stays connected to the product model, the repository, the tasks, and the evidence, and where it can leave again without being flattened into prose. The front door writes the contract. The rest of the house is where the contract has to survive contact with a changing codebase.
Where PaellaDoc fits
This is the problem PaellaDoc is built around. A change can come in as a spec, from Spec Kit or any similar workflow, and instead of becoming a static file it becomes a maintained node in a local model of the product. The spec’s claims attach to the code that implements them. Acceptance criteria connect to the runs that exercise them. When the code drifts, the affected parts of the contract surface instead of silently going stale.
The spec is not the deliverable. It is the beginning of a contract that has to stay true while many agents write, fail, recover, and ship. Writing it was never the hard part. Keeping it true is.
FAQ
Is PaellaDoc a Spec Kit alternative? No. Spec Kit writes the spec at the front of the workflow, and it does that well. The gap is what happens afterward: keeping the spec linked to code, verified against evidence, and updated as the code changes. That back half is the part worth building around.
Why does a spec stop being useful over time? Because nothing keeps it connected to the code. As the implementation changes, the document stays frozen and slowly describes a system that no longer exists. Without a mechanism to detect that drift, the spec becomes actively misleading.
Can I keep using Spec Kit and still solve this? Yes. The point is not to drop your entry tool. It is to give the spec a place to live where it stays linked to the code and the evidence after the agent has built the feature.