Living Docs

Run a project's engineering decisions as a living log — not a write-once artifact that rots.

This is an experiment and it changes constantly. Verbs and record formats may change between releases without a deprecation window — see ADR 0059 for the latest cut. Pin a release tag rather than tracking main if you need stability.

Living Docs is an AI agent skill for documentation-as-code that keeps a codebase's decision log in sync with its code. It works with Claude Code, Cursor, GitHub Copilot, OpenCode, Codex, and Pi — any agent that loads markdown "skills" / instruction files. It is stack-agnostic: it governs how decisions are recorded and maintained (Architecture Decision Records, issues, research notes, an optional PRD, a constitution, living Mermaid architecture views), never what technology a project uses.

The mechanical half of that discipline is owned end-to-end by the bundled living-docs CLI — one self-contained Rust binary with ten verbs that scaffolds records (new), drives their lifecycle (set, supersede), rebuilds indexes (index, fmt), validates the invariants (check), compiles the in-force view an agent reads (read), and serves the skill corpus and the enforcement hooks (guide, install, uninstall). There is no LLM inside the tool: the agent writes only the judgment prose; everything mechanical is deterministic and reproducible.

The whole discipline collapses to one spine:

Every piece of knowledge has exactly one home, that home is indexed, and a material decision ships with its record.

Everything else — the constitution, ADRs, PRDs, issues, research notes and architecture views — hangs off that spine.

---

Why this exists

Most documentation rots because there is no contract keeping it honest. Living Docs adds five governance invariants that an agent (or a human) can re-derive every action from:

1. Docs-first. Author the body in the repo (docs/…) before publishing to any tracker or wiki. The repo file is the source of truth; the external copy is a mirror.
2. One home per fact. Each concept, decision, or requirement lives in exactly one file. Cross-reference instead of copying — duplicated prose is drift waiting to happen.
3. Indexed or it doesn't exist. Every doc is reachable from an index.md. No orphan files.
4. Supersede, never rewrite history. Decisions are append-only. When something changes, mark the old record superseded and write a new one — never silently edit the past.
5. No structural change without its doc. New module, moved files, schema change, new data flow → update the relevant doc and its diagram in the same change. No "I'll document it later."

These invariants are carried in YAML frontmatter as a fact contract and wired to a deterministic CLI (living-docs) that both authors the mechanical parts and checks them. The pitch is not novelty — arc42 + ADR + C4 + docs-as-code is a well-trodden stack — it is the explicit, agent-enforceable packaging of it. See Provenance.

---

The doc trail

Only what a change earns appears. A routine change is an issue and code; a decision expensive to reverse earns an ADR; a product spec worth pinning earns a PRD: