Living Documents for Domain State
SDD works with two spec types. Feature Specs describe what to change and flow through the pipeline once. Anchor Specs describe how the system is and update deliberately. The distinction matters because AI agents executing changes need to know not just what to do, but what the system is — and documentation drift defeats AI’s value at scale. Anchor Specs solve three problems: onboarding a new person to a domain from one document, preserving architectural “why” through team turnover, and generating initial documentation from existing codebases.
What an Anchor Is
An Anchor Spec represents a domain’s current state, synthesized from the transactional Feature Specs that have shaped it. Each Anchor has:
- Overview — what the domain is, in two or three paragraphs.
- Architectural Decisions — the permanent record of why. Each decision notes what was chosen, the reasoning, the trade-off accepted, and the spec or conversation that originated it.
- Sections — the domain’s components, each with field-level detail.
- Integration Map — external systems the domain talks to, with interface and contract notes.
- Frontmatter — a header that tracks which specs have been squashed into the body and which are still pending.
The Squash Operation
Anchors do not update automatically as specs land. They accumulate a pending_changes list, and the Architecture Gate owner periodically collapses that list into the body of the Anchor — the squash.
Squashing is deliberately human-initiated. It is the moment when recent change gets reconciled with standing architectural description — updated, contradicted, or accepted. A squash increments the Anchor’s snapshot version and moves consumed specs from pending_changes into derived_from.
This operation is where Anchor Specs earn their keep. It is also where a team catches architectural drift before it becomes invisible.
Anchor Impact at the Architecture Gate
Every spec passing through the Arch Gate gets one explicit question:
does this create a new decision, or modify an existing Anchor
constraint? The answer is a boolean: anchor_impact: yes or
anchor_impact: no.
When yes, the implementation stage invokes the
anchor-generator agent to produce an Anchor update that
reflects what was actually built — not the spec as written. The
update ships in the same pull request as the code, and the QA Gate
verifies it is present, accurate, and internally consistent.
SPEC-034 is the canonical recent example: the spec revised the ANCHOR-001 "No custom authentication" constraint with a scoped carve-out for Preview Mode, and the Anchor update was required to land in the same PR as the auth implementation. No lag, no eventual consistency, no "we’ll document it later."
Apply This to a Portfolio Company.
Anchor Specs are how a domain’s architectural state stays documented through team turnover and leadership transitions. They land in real portfolio engagements as part of how GeekByte runs the work — alongside the Spec-Driven Development pipeline. If you want to see how this applies inside a value-creation plan, the conversation is the place to start.
Discuss a Growth Advisory Engagement