If the spec is the source of truth, it needs a lifecycle

A team moves to spec-driven development and for the first few weeks it works as described. Specifications are written and reviewed, agents implement against them, acceptance criteria become tests. The specs are good, because everybody is still paying attention to them.

Then a production defect is fixed directly in the code, because it is two in the morning. A small behaviour change agreed in a chat thread goes to the agent as a one-line instruction. A reviewer suggests a better approach in the diff and it is applied there. Each of these is reasonable. Three months later the specification says one thing and the system does another, and the next time an agent regenerates the module from the spec, it quietly brings the old behaviour back.

Being the source of truth is not a property a document has. It is a rule about which direction changes flow.

Why specifications rot faster than code

Code has a compiler, a test suite and production, all of which complain when it is wrong. A specification has only readers, and nothing fails when it falls behind.

Every shortcut also runs code-first. The hotfix, the small tweak, the improvement spotted in review: all of them touch the code and leave the specification for later, and later does not come.

Agents make the gap more expensive than it used to be. In a hand-written codebase a stale document is merely misleading, and people learn to ignore it. In a spec-driven one the stale document is an instruction. The agent reads it literally and implements it faithfully, including the parts that were deliberately changed since.

The rule that keeps it true

Changes flow from the specification to the code, never the other way round. That includes hotfixes: under pressure the code can go first, but the specification change follows the same day, and the incident is not closed until it does.

For review, the consequence is concrete. A pull request that changes behaviour without changing a specification is incomplete, in the same way that a change without tests is incomplete. Reviewers can ask for the missing part, and in time the pipeline can check for it.

Everything else is machinery that makes the rule cheap enough to follow.

Infographic

The lifecycle of a specification

1. 01Change the specEvery change in behaviour starts as an edit to the specification.
2. 02Review the intentThe decision is made on the spec, not on the code.
3. 03Derive the testsAcceptance criteria become tests before anything is generated.
4. 04Generate and verifyAgents implement; the pipeline checks the result against the tests.
5. 05Feed backHotfixes and incidents return to the spec the same day.

What the lifecycle consists of

The spec lives next to the code. Same repository, same pull request. A specification change and the code it causes are reviewed together, so intent and implementation are read in one place.

Traceability in both directions. Every acceptance criterion maps to a test, and every test maps to a criterion. An orphan test is usually behaviour nobody decided on; an orphan criterion is a promise nothing checks.

An owner per specification. Not whoever wrote it, but whoever decides when it changes, which is usually the person who owns that area of the code.

The out-of-scope section survives. It is the part people delete first, and the part that stops an agent from helpfully adding things nobody asked for.

Retirement is explicit. When a feature goes, its specification goes in the same change. A dead spec is worse than a missing one, because an agent reading it finds instructions for something that no longer exists.

A test you can run this week

Pick a module that was built from a specification. In a branch, have an agent regenerate it from the current spec alone, then run the existing tests against the result.

If it passes and behaves the same, the specification is still the source of truth. If it fails, the differences are a list of decisions that were made in the code and never written down. And if the team is reluctant even to try, that is the answer.

Repeat it every few months. It is cheap, and it is the only check that tests the specification itself rather than the code built from it.

Discipline, not tooling

None of this needs a new tool. It needs one rule, applied when it is inconvenient, and a few habits that make applying it cheap.

It is also the part of the method that is easiest to skip, because the cost of skipping it arrives months later and in somebody else’s change. In spec-driven development it pays to agree from the start not only how a spec is written but how it changes, because a specification that is written once and never touched again is just a better ticket.