- name
- spec-graph
- description
- Use when locating, reading, creating, updating, or validating project specs, or when work is governed by or may alter a documented boundary, contract, invariant, behavior, or architecture decision.
Spec graph
Specs are the ground truth
- Specs describe the architecture, decisions, contracts, and boundaries behind the code — the intent
that the code alone does not reveal. Treat them as authoritative.
- Consult the owning spec when it governs the work. When work depends on, checks, explains, or
may alter a documented boundary, contract, invariant, behavior, or architecture decision, use
spec_search / spec_grep / spec_get / spec_graph to find the applicable record and align with it. If a change contradicts a recorded
decision, surface and reconcile the contradiction rather than silently diverging.
- Keep lookup proportional. Specs are the map for decisions and boundaries; code confirms the
implementation. A localized fix, explanation, or check that changes no documented decision may
inspect only the files it needs without reading unrelated specs.
- Keep them honest. A change that moves or blurs a boundary, or overturns a decision, updates the
spec as part of the same change. Specs that drift from the code stop being ground truth.
What a spec is
- A durable, declarative document. It states the world as it is — the intent, decisions, contracts, and
boundaries behind the code — not plans, tasks, phases, or a work journey.
- Concise and readable. It captures what is not obvious from the code; it never restates the code.
- The bar: reading the relevant specs should be enough to understand an area and to formulate a task to
improve it.
Keep specs lean
- Explain intent, not inventory. Describe what a module is for, what it owns, and where its boundaries
are — not a file-by-file transcript of its directory. The reader can see the files; the spec exists for
what the files don't say.
- Record the edges that matter. State the module's boundary (allowed / forbidden deps) and the
dependency edges between its sub-modules. List a part only when its role or its edges aren't obvious from
its name — e.g. a small table that carries a real dependency DAG earns its place; a table that just
pairs
foo.ts with "the foo tool" is noise, so say it in a sentence instead.
- Say each thing once. A fact lives in exactly one spec; others link to it by
id rather than restate
it. If a paragraph is being copied between specs, move it to the spec that owns the concept and point at
it. Duplicated prose drifts and turns into contradictions.