The knowledge base

The knowledge base is plain markdown in your own repository. specd holds a derived index it can rebuild from scratch — which means leaving costs you nothing you would miss.

What is in it

Grounding writes a starting tree; you shape it from there. This repository's own knowledge base — specd develops specd — has the layout the scaffold produces:

knowledge/
  README.md            the map — what to read, and when
  architecture.md      module boundaries, data flow, the shape of the system
  conventions.md       how code is written here: layout, lint, test patterns
  glossary.md          domain terms, defined once
  decisions/           ADRs — why a choice was made, numbered and dated
  runbooks/            how to run, deploy and debug it
  specs/               as-built records of everything delivered
  research/            point-in-time analyses of external systems
  open-questions.md    what nobody has answered yet

Why it lives in your repository

Because git already solves the hard parts

History, blame, review, branching, access control. A knowledge base in a vendor database re-implements all of that, worse.

Because docs must ride the change

The working agreement is that documentation is updated in the same pull request as the code it describes. That is only possible if the docs are in the same repository as the code.

Because leaving must be free

Delete your specd project and the knowledge base is still there, in markdown, in your repo, readable without any tool. What you lose is the index, and an index rebuilds.

AGENTS.md — the working agreements

Grounding also installs an AGENTS.md at the repository root: a numbered list of rules for any agent working in the repo, with CLAUDE.md importing it so Claude Code picks it up automatically. The rules that matter most:

1. Read knowledge/README.md and the docs it maps to your task before implementing anything.
2. Ground design choices in knowledge/, and cite the file you relied on.
3. Update knowledge/ in the same pull request as the code it describes. Docs ride the change; they never trail it.
4. knowledge/specs/ is a historical record. Never rewrite an old spec — append a "Deviations" section if reality diverged.
5. When the knowledge base does not answer you, do not invent the answer. Check open-questions.md, and say so.

How specd reads it

Indexing is deterministic and atomic, and no model ever runs at index time. Documents are chunked on headings, embedded, and their links extracted with parser rules across five deterministic kinds — citation, wikilink, symbolref, mdlink, coderef. A hallucinated edge would poison retrieval invisibly, so the indexer is not allowed to invent one.

It also indexes your code: the file tree and its declarations, for TypeScript, Go and Python. That is what lets a doc citing RunnerJobsService.claim() resolve to the real symbol, and lets retrieval serve the function's actual source as a citable excerpt. The full mechanism is in The retrieval engine.

Health — knowing when it has rotted

A knowledge base is only load-bearing if you can tell when it stops being true. specd scores four things it can count honestly:

Drift is measured against the code, not the calendar. Doc↔code coupling is mined from a bounded window of git history, so the signal reads "6 commits touched `apps/api/src/runners/` since this doc last moved with it" — which names the code to go read. A 90-day timer only measures time passing.

Keeping it good

• Answer UNVERIFIED markers as you meet them, in the pull request where you learned the answer — and delete the marker in the same change.
• Keep knowledge/README.md as a real map. Every doc should be reachable from it; that is what makes the orphan count meaningful.
• Write decisions down when you make them, not when you are asked to justify them. An ADR is cheap the day of, expensive a quarter later.
• Let knowledge/specs/ accumulate. It is the corpus the next spec retrieves — see The learning loop.