Living Documents for Domain State
Specs capture change. Anchor Specs capture state. Together, they 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."
See an Anchor in Action
The GeekByte website is itself documented under an Anchor Spec (ANCHOR-001: Website Architecture). The anchors explorer renders the Anchor’s data as an interactive C4 diagram, a site map, and a linked text view — all built at compile time from the Anchor markdown.
The explorer is the same tool GeekByte uses internally. It is public because the Anchor is public, and the Anchor is public because the methodology is.