Code shows what exists. Specs define what should exist.
Code records what exists; specifications record what should exist. Strata19 keeps both as durable project artifacts, so a later coding conversation can start from the current intent and evidence rather than a fading transcript.
What exists now
What should exist
Intent, implementation, and evidence stay connected
The problem
Your artifacts are already out of sync.
You start a project in Claude or Codex. You upload the artifacts you have, then use conversation to produce more — some of it reference material, some of it implementation plans. Within days those artifacts have diverged from each other and from the code, and every platform, conversation, and session is working from a different version of the truth.
Instruction files do not solve this, because they carry rules and never carry state. Your CLAUDE.md can tell an agent the conventions. It cannot tell it what was decided yesterday, what work is in flight, or which approach was already tried and rejected.
And a stale instruction file is worse than a stale README, not better. A human reading an out-of-date README applies judgment. An agent reading an out-of-date instruction file complies with it perfectly. Meanwhile the same knowledge gets copied into CLAUDE.md, AGENTS.md, .cursorrules, and copilot-instructions.md — and each copy drifts on its own schedule.
No live sync
Chat project knowledge does not stay current with your repository. Changed documents have to be re-uploaded by hand, which makes a person the sync mechanism — and people forget.
Open issues on Claude Code: #25983, #10841, #10647
~30%
of AI conversations require re-prompting information that was already provided. Models persist nothing between calls, so every session restarts from zero unless something outside the model remembers.
O'Reilly Radar; Augment Code
66%
of developers name "almost right, but not quite" as their single biggest frustration with AI coding tools. Being close is the failure mode, and it is what happens when an agent is working from the wrong version of the intent.
Stack Overflow Developer Survey
Why now
We already knew design was the hard part.
Software engineering spent decades learning that the expensive mistakes happen before anyone writes a line of code. Waterfall's failure taught the industry to iterate. It never taught anyone to skip the design.
01
The discipline was never in dispute
Requirements, interfaces, and contracts before implementation. Every methodology that lasted, from the ones that argued bitterly with each other, agreed on that much.
02
Then it got skipped, and the result was measured
Prompt to code, with nothing in between. The outcome is not a matter of taste — it shows up in the repositories.
- Duplicated code blocks up 81% since 2023
- Reuse-refactoring down 70%
- Legacy refactoring down 74%
- In 2024, for the first time, more code was copy-pasted than moved
GitClear, 623 million code changes, 2023–2026. DORA 2025 reports the same shape: throughput up 2–18%, instability up with it.
03
Design matters more now, not less
This is the part that gets missed. A developer carried unwritten intent in their head from Tuesday to Thursday — the constraint nobody wrote down, the approach already ruled out. An agent carries nothing between two messages. The design artifact now has to hold what a person's memory used to hold for free. The discipline everyone relaxed is precisely the one that became load-bearing.
04
Spec-driven got the diagnosis right
Spec Kit and Kiro remembered that design comes first, and the market agreed — Spec Kit has 93,000+ stars and supports 30+ agents. The step that was missing is what happens after: the spec is treated as a launch document, so it drifts the moment code generation starts.
Keeping specifications and code in sync is not a new ambition. Literate programming, Design by Contract, model-driven architecture, executable specifications — the industry has been reaching for this for forty years. It never stuck because a human had to maintain the specification by hand, and the maintenance cost exceeded the value.
What changed is not the idea. It is the cost of keeping it true.
What spec-native means
A spec that can't disagree with the code isn't a spec.
Code can only ever express what a system currently is. It has no way to express what it is supposed to be. That gap is where every AI coding failure lives: an agent reading only the repository can be perfectly faithful to the code and still build the wrong thing, because the code cannot disagree with itself.
Spec-native means the intended system is a first-class, machine-readable artifact that is allowed to disagree with the code — and that the distance between them is measured, surfaced as work, and closed deliberately. The spec is not documentation of the code. It is the contract the code is converging toward.
| Approach | Spec lifecycle | The gap |
|---|---|---|
| Instruction files (AGENTS.md, CLAUDE.md) | Hand-maintained prose | Carries rules, never state. Drifts silently. |
| Chat project knowledge | Manual re-upload | No live sync. The human is the sync mechanism. |
| Spec Kit / Kiro | Spec authored up front | Treated as a launch document. Drifts once codegen starts. |
| Strata19 | Living contract, both directions | — |
Every other spec tool writes the spec once. We keep proving the code still matches it.
Spec Kit has 93,000+ stars and supports 30+ agents. The category is validated. Its shared failure is that specs are written once and abandoned.
Two artifacts
Two stores. Two different jobs.
Conflating them is the most common mistake in messaging, because most competing tools only have one.
| Specbook | Library | |
|---|---|---|
| Answers | What should this system do? | What do we know that informs it? |
| Relationship to code | Binding. The delta between it and the code is work. | Non-binding. Reference material an agent consults. |
| Content | Obligations, behaviors, contracts, acceptance criteria | Research, decisions, standards, domain knowledge, vendor docs, prior art |
| When it changes | A change is a proposal that creates convergence work | Edited freely. No convergence obligation. |
| If it goes stale | Code converges toward the wrong target | An agent reasons from outdated background |
| Analogy | The build contract | The reference shelf |
Specbook
Answers
What should this system do?
Relationship to code
Binding. The delta between it and the code is work.
Content
Obligations, behaviors, contracts, acceptance criteria
When it changes
A change is a proposal that creates convergence work
If it goes stale
Code converges toward the wrong target
Analogy
The build contract
Library
Answers
What do we know that informs it?
Relationship to code
Non-binding. Reference material an agent consults.
Content
Research, decisions, standards, domain knowledge, vendor docs, prior art
When it changes
Edited freely. No convergence obligation.
If it goes stale
An agent reasons from outdated background
Analogy
The reference shelf
Files
Repository inventory. What the code contains.
Specbook
Canonical, controlled project intent.
Library
Editable supporting knowledge.
Today both live in the same undifferentiated pile — a project's uploaded files, a folder of markdown, a chat history — where everything is treated as equally authoritative and equally stale. Separating them lets the binding artifact be held to a convergence standard while the reference material stays free-form.
Inside a specbook
One store. Five ways to read it.
The specbook is generated from your repository and written back into it as reviewable markdown, layered from the system down to individual files. These five views are projections over the same sections — a section edited in one view is edited in all of them, because there is only one of it.
For the PM / founder
What the project is supposed to do, with none of the how.
Requirements at the system and container level, and nothing else. No design notes, no implementation detail, no per-file summaries. This is the view you hand to someone who needs to agree that the intent is right before anyone argues about how to build it.
What appears in this view
The system SHALL issue an invoice when a subscription renews.
WHEN a payment fails, the system SHALL retry on a documented schedule before suspending access.
Shows sections where level is 1 or 2 and kind is req.
Sections carry a kind — req, design, impl_note, test — and a level from the whole system down to a single file. Acceptance criteria are held to EARS grammar; a criterion that fails the grammar is dropped rather than stored loose.
Inside the library
The reference shelf, kept separate on purpose.
The specbook holds obligations the code has to meet. The library holds everything that informs them — and is never allowed to become them by accident.
Notes, research, architecture rationale, customer context, benchmarks, design references, imported material — and bounded excerpts from the conversations where the thinking actually happened. Each capture records its source, the actor, a timestamp, a digest, and its provenance.
The distinction that matters: a capture is not a transcript replay. It stores a short excerpt that can be retrieved from a new conversation without replaying the conversation it came from. That is the direct answer to the problem of a decision being made in one session and lost to every session after it.
The library is explicitly not a file browser and not a second specbook. Your repository already knows what files exist.
The convergence loop
Change the specbook. The code converges toward it.
Convergence runs in both directions, but the two directions are not equal — and which one you work in decides whether you end up with a contract or a mirror.
The encouraged direction
Intent moves first, and the code follows it.You change the specbook
Intent moves first
Add an obligation, tighten an acceptance criterion, or ratify something that until now was only a proposal.
The intended system is now ahead of the code.
The delta becomes work
Gap, not report
The difference between what the specbook requires and what the code contains is not a status page. It is a queue with names in it.
Unimplemented obligations are named, not summarised.
Agents converge the code
Convergence
Implement the portions of the specbook that do not yet exist in the code. Convergence is reached when no unimplemented obligation remains.
Done is a property of the project, not a claim in a chat.
If the code moves first, the specbook can only ever describe what the code already is. It degrades into a mirror — redundant with the repository, incapable of disagreeing with it, and therefore incapable of expressing intent.
A mirror cannot generate work. A contract can.
The safety net
For when the code moves first anyway — because it will.Code moves without the spec
Reality
Someone ships a change and does not touch the specbook. A hotfix, a refactor, a Friday afternoon. This is not a failure case to design against; it is the normal case.
The specbook is now behind, and knows it.
The change cascades
Propagation
A changed file invalidates its own section, its ancestors up the tree, and — the non-obvious half — the files it imports and the files that import it. This propagation is the thing that makes staying in sync affordable: without it you either regenerate the whole specbook on every commit, or you update only the file that literally moved and miss everything whose meaning just changed underneath it.
Sections whose meaning changed are found, not just the ones whose text did.
A human decides the rest
Escalation
Where the change cannot be reconciled — an obligation the code now contradicts, an ambiguity the system cannot resolve — it stops and asks rather than guessing.
Unresolvable conflicts surface as questions, not as silent edits.
Review and approval
It is a git repository. The contents are specs.
Nothing enters or leaves the specbook without passing through you.
The specbook is markdown written into your repository. Not a database you query through a web app, not a hosted document — files, in your tree, under the version control you already run. Diff, blame, revert, branch, and pull-request review already work on it. There is no second review tool to learn.
Every change arrives as a proposal
Generation proposes. Sync proposes. Promoting something out of the library proposes. You are the merge gate on all three, and the specbook does not move until you say so.
Origin is authorship
Every section records whether a model drafted it, a person wrote it, or a person explicitly affirmed it. The same job blame does, carried on the section itself rather than reconstructed from history.
Changes arrive as patches, not rewrites
When the code moves, sync emits a diff against the existing section rather than regenerating it wholesale. That is partly a cost decision and mostly a review one: a patch is something you can read line by line and disagree with.
An agent cannot merge its own work
An agent may open a proposal — it is often best placed to notice that a decision made three sessions ago should have become a requirement. Approving it is a separate act, reserved for a person. An agent that attempts to approve its own proposal is rejected outright.
You decide once. It cascades.
A change does not stop where you made it. Approve one, and it propagates to every section that depended on it — up the tree, and outward through what the code imports and what imports it. This is the half that makes the gate worth having: without propagation you are approving paperwork, and without the gate propagation is just automated drift.
What this looks like on day one
The first generation writes a set of files rather than gating each section individually — you review that the way you review any other commit, as a diff. From that point on the guarantee tightens: any section you have edited is detected by content hash and is never regenerated over again. The model may propose a change to it. It cannot make one.
The honesty model
There is no “verified” status.
A generated spec is a proposal about intent, and the system structurally cannot say otherwise.
Every section carries its origin
A model drafted it. A proposal about what the code intends.
A human wrote or edited it. Sync may only propose changes to it, never overwrite it.
A human explicitly affirmed it. Outranks both.
Evidence has tiers, in increasing authority
Deterministic. Computed by code from the index — an exported symbol, path, or test-name match. Reproducible.
Model-proposed. Never promotes anything.
Ratified by a person.
Status is only unmeasured or evidenced
There is deliberately no value that means verified. Only a T0 or human link moves a section off unmeasured. Model-proposed evidence never promotes anything, no matter how confident the model is.
Your edits win permanently
Hand-edited sections are detected by content hash and promoted to authored. Sync will never regenerate over them again. The model may only propose a change, which you review.
An agent cannot approve its own work
Promoting reference material into canonical intent creates a reviewable proposal. Only a human can approve it. An agent that tries to self-approve is rejected.
Partial coverage is disclosed on the record
A section that describes only some of what sits beneath it prints a warning saying so, in its own output. Incomplete is reported as incomplete, not as covered.
Generation reports estimated versus actual cost, and aborts before spending anything if the estimate exceeds your budget.
The role
The spec owner and the implementer are now the same person.
In a conventional software organization, a project manager owns the specification and distributes the work; developers implement it. Spec-native merges those roles: you manage the Specbook — the project-manager function — and direct agents to converge the code toward it, which is the implementation function.
Everyone has noticed the role is shifting. Nobody has shipped the artifact that role needs. A product manager without a spec is just someone with opinions.
“Today coding is practically solved… We're going to start to see the title of software engineer go away. It's just going to be ‘builder’ or ‘product manager.’”
Boris Cherny, creator of Claude Code, February 2026
81% of developers report spending more time reviewing AI-generated code than they used to.
Spec-native gives the merged role its instrument.
Give your project something the code cannot say on its own.
Install the free local plugin. Generate a specbook from the repository you already have.
Install Free