Spec Graph

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.
• Reach for the spec tools first. Whenever you set out to explore the project, plan a change, investigate an area, or work with specs in any way, your first move is the spec tools (spec_grep / spec_get / spec_graph) — before grep, find, or reading source. The specs are the map; the code is the territory you confirm against it.
• Start from the specs, not the code. To understand an area or plan a change, read the relevant specs first and use them as the map; read code second, to confirm details.
• Check work against them. Before introducing a decision, a contract, or a boundary change, find what the specs already say and align with it. If a change contradicts a recorded decision, surface the contradiction and reconcile it — update the spec or change the approach — rather than silently diverging.
• 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.
• Prefer prose to exhaustive tables, and cut anything that only paraphrases code, filenames, or a sibling spec.

The graph

• parent links form a hierarchy that mirrors the code structure: a SPEC.md sits beside the module it describes (fractal — a package and its sub-directories each have one), and root documents sit at the repository root.
• depends-on, references, and implements form a dependency layer across the tree.

Frontmatter

• Required: id (a unique slug), type, title.
• Optional: status (lifecycle), parent (single link), depends-on / references / implements (link lists), covers, tags.
• A file is a spec when its frontmatter carries id and type.
• status tracks a spec's lifecycle: draft (being written) → active (in force), then stale (drifting from the code), done, or deprecated. It's optional, but keep it current as a spec firms up or ages.
• Types:
  • goal-and-requirements — the product goal and scope; the root of the graph.
  • architecture-design — system-wide topology, cross-cutting decisions, and invariants.
  • module-design — a package or module's responsibility and boundary.
  • submodule-design — the same, for a directory-level module inside a package.
  • task-spec — a temporary working document for a piece of work; not durable, and removed once the work lands.

Tools

Read:

• spec_grep — search within specs (content, narrowed by metadata filters).
• spec_get — a spec's frontmatter, its resolved links, and its path. Read the body with the normal read tool using that path.
• spec_graph — a bounded slice of the graph: a subtree, ancestors, or a node's neighbors, to a depth.

Manage:

• spec_create — a new spec with scaffolded frontmatter and headings.
• spec_update — a spec's frontmatter (fields and links). It does not touch the body.
• spec_delete — remove a spec.
• spec_validate — report dangling links, duplicate ids, and parent cycles.

Prose is written and edited with the normal write/edit tools; the spec tools own frontmatter and structure.

Working with specs

1. Orient. From a known root or the module you are touching, use spec_graph for the neighborhood, spec_get for a node's metadata, and read for its body. Use spec_grep to find specs by content.
2. Align. Reconcile the change with the decisions and contracts the specs record; surface contradictions before diverging.
3. Update. When the change alters a boundary, contract, or decision, update the spec — frontmatter (including status) with spec_update, prose with edit — and add spec_create for a new module.
4. Check. Run spec_validate after structural changes.