Living Docs

Run a project's documentation as a living system — not a write-once artifact that rots.

Living Docs is an AI agent skill for documentation-as-code that keeps a codebase's docs 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 docs are organized and maintained (Architecture Decision Records, Behavior Decision Records, PRDs, a constitution, a glossary, living Mermaid diagrams), 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 that scaffolds records (new, brief), drives their lifecycle (status, describe, supersede), rebuilds indexes (index, fmt), validates the invariants (check), and serves ranked full-text search (search) over a derived read-model — embedded SQLite + FTS5 or ParadeDB. 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 nothing structural ships without its doc.

Everything else — the constitution, ADRs, BDRs, PRDs, issues, research notes, architecture diagrams, and the semantic context index — 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 and requirements 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

Every change follows one chain, from the foundational source of truth down to code:

flowchart LR
  C[constitution] --> P[PRD]
  P --> A[ADR]
  P --> B[BDR]
  A --> I[issues]
  B --> I
  I --> K[code]

What's in the box

This repo bundles the Living Docs skill together with its composition dependencies and the prior-art research that backs its honesty claims:

Each skill is self-describing — open its SKILL.md for the full operational detail. Living Docs and OKF compose but do not overlap: Living Docs governs which docs exist and the no-drift discipline; OKF governs how a knowledge bundle's markdown and frontmatter are shaped.

Installation

The skill is plain markdown instruction files — nothing to compile or install to use it. The optional living-docs CLI — deterministic authoring, checking, and full-text search — is a single self-contained Rust binary with no host-tool dependencies at all: native frontmatter and link parsing (no lychee/yq/jq) and — since v0.6.0 — in-process Mermaid validation via the pure-Rust merman-core parser, so --mermaid-only no longer needs Docker. Install it with ./install.sh cli or make cli-install. Installing Living Docs always means the same thing: put the three skills/ directories (or a generated rule file) where your tool discovers instructions, then start a fresh session. A cross-platform installer and a Makefile do this for every supported tool. Clone once:

git clone https://github.com/ejklock/living-docs-skill.git
cd living-docs-skill

Quick start — install.sh / make

./install.sh                 # Claude Code, global (~/.claude/skills) — the default
./install.sh cursor          # Cursor rule in the current project
./install.sh copilot         # GitHub Copilot instruction in the current project
./install.sh opencode        # OpenCode (~/.config/opencode/skills)
./install.sh codex           # Codex (~/.codex/skills)
./install.sh pi              # Pi (~/.pi/agent/skills + AGENTS.md)
./install.sh all             # every supported harness at once

Useful flags: --project (install into the current repo instead of the global user dir), --dir <path> (custom skills directory), --uninstall, --dry-run, --help. The same targets are available via make:

make help            # list every target
make install         # Claude Code, global
make install-cursor  # or install-copilot / install-opencode / install-codex / install-pi / install-all
make project-claude  # install into the current project
make uninstall-all   # remove from every harness
make check           # full gate: version sync · living-docs check the example ·
                     #   validate mermaid · hostile parser fixtures · bash -n all
                     #   scripts · dry-run every harness
make build           # build the living-docs binary natively -> target/release/living-docs
make cli-install     # install the living-docs binary onto PATH (fetches the latest GitHub release; LIVING_DOCS_VERSION pins a tag)
make test-fixtures   # run the hostile/negative fixtures guarding the parsers

Where each tool loads from

Claude Code, OpenCode, and Codex share the same model: they auto-discover folders of SKILL.md files from their skills directory, so the installer just copies the three skills there (OpenCode additionally reads .claude/skills, so a Claude install already covers it). For Cursor and Copilot the installer generates the rule/instruction file with the right frontmatter header (globs / applyTo scoped to docs/** and **/*.md) from living-docs/SKILL.md. Pi has no native skills directory — after the skills are copied, reference them once from your AGENTS.md:

## Living Docs
Follow the documentation discipline in skills/living-docs/SKILL.md,
skills/okf-knowledge-format/SKILL.md, and skills/research-artifacts/SKILL.md.

Then restart the session so the tool picks up the skills.

Enforcement — write-time gates, not just instructions

./install.sh ships skills only — it copies markdown instructions and never touches a hook script or wires any settings file (ADR 0023). The write-gate, the session-teaching hook, and the pre-commit doc-gate are distributed through two separate, deterministic channels:

• Claude Code plugin (Claude Code only): /plugin marketplace add ejklock/living-docs-skill then /plugin install living-docs@living-docs (add --scope project to commit the choice to the repo). Installs the write-gate (PreToolUse on Write|Edit|MultiEdit, blocking hand-written docs before they land) and the session-teaching hook (SessionStart), both resolved through ${CLAUDE_PLUGIN_ROOT} so no checkout of this bundle is required.
• living-docs hooks install [--dir <project>] [--docs-dir <bundle>] [--dry-run] (every harness): materializes the two hook scripts into .living-docs/hooks/, wires .claude/settings.json with the resolved bundle pinned as LIVING_DOCS_BUNDLE=, and installs the pre-commit doc-gate at .githooks/pre-commit (pointing core.hooksPath at it). The pre-commit gate is git-level and catches every harness at commit time; the .claude/settings.json wiring is what gives Claude Code its write-time gate. Remove everything it wrote with the sibling living-docs hooks uninstall [--dir <project>] [--dry-run] — install and uninstall are separate subcommands, not a flag.

Cursor and GitHub Copilot have no write-time hook surface at all — neither tool exposes a pre-write hook, so they rely entirely on the pre-commit gate and CI to catch a hand-written doc after the fact.

One caveat worth knowing: plugin hooks and .claude/settings.json hooks fire independently, with no deduplication. Installing both channels in the same Claude Code project duplicates the SessionStart notice and the (still correct) block — an accepted trade-off recorded in ADR 0023.

Skill content — served by the CLI, not copied to disk

Native harnesses (Claude Code, OpenCode, Codex, Pi) only get each skill's slim SKILL.md stub (plus okf-knowledge-format/reference/, the vendored spec) — the full per-doc-type conventions (rules/) and starter templates (templates/) travel inside the living-docs binary (ADR 0014) and are reached with living-docs skill, not by reading files off disk:

living-docs skill --list                          # every embedded skill and its topics
living-docs skill living-docs                      # the full living-docs/SKILL.md body
living-docs skill living-docs --topic adr           # just the adr topic's rules (+ template)

Output is context-aware: piped or otherwise non-TTY output defaults to minified single-line JSON (the machine-friendly shape another agent parses); a real terminal gets human-readable plain text. --json and --plain override the autodetection in either direction and are mutually exclusive. This is why a native harness install is a small, stable footprint on disk while the authoritative detail stays centralized in one versioned binary — see ADR 0014.

Any other tool

Copy skills/living-docs/, skills/okf-knowledge-format/, and skills/research-artifacts/ into wherever that tool loads instructions from, or just read the SKILL.md files — they are plain markdown meant to be read by humans and agents alike.

Companion skills (Matt Pocock) — recommended, not bundled

Living Docs composes with but does not bundle Matt Pocock's skills. His grill-me (design interview before a load-bearing decision) pairs directly with Living Docs, and his to-prd / to-issues are kindred to the PRD/issues workflow here. They are best installed straight from the source so they stay canonical and up to date — his repo is MIT-licensed, so cloning and using it is permitted (keep his LICENSE notice if you copy files):

./install.sh pocock          # git clones his repo (default ~/.matt-pocock-skills)
# or by hand:
git clone https://github.com/mattpocock/skills.git
# his repo ships a `setup-matt-pocock-skills` skill that wires them up

See ATTRIBUTION.md for how Living Docs relates to his work.

When to invoke

• Standing up documentation for a project (docs/ structure, the docs index, ADR/issue/BDR/constitution directories).
• Writing or editing an ADR, PRD, BDR, constitution, or issue → load the matching rules/ + templates/ file.
• Recording research → the research-artifacts skill.
• Drawing or updating an architecture / data-flow / sequence diagram (living Mermaid, in-repo text that must match the code).
• Defining a term or acronym → the glossary, one home per term.
• A doc grew too large or mixes concerns → split into a semantic index.
• Enforcing the no-drift maintenance rule after any structural change.

Composition with other skills

Living Docs is deliberately small and composes with the rest of your toolchain rather than absorbing it: design grilling before a load-bearing ADR, an architecture-improvement pass that reads the context index and ADRs, a deep-research step that gathers the evidence research-artifacts then formats, and an implementation-review step that checks code honors the ADRs/BDRs. See the "Composition with other skills" section in skills/living-docs/SKILL.md for the full map.

The design-grilling step composes with grill-me by Matt Pocock (github.com/mattpocock/skills) — referenced, not bundled here. See ATTRIBUTION.md.

Provenance — honest attribution

This work instrumentalizes established practices; it does not invent them. "Living documentation" is Cyrille Martraire's named methodology; ADRs are Michael Nygard's (supersede-don't-delete is the adr-tools convention); BDRs wrap Specification by Example / BDD (Adzic; North); the file format is Google Cloud Platform's OKF, vendored verbatim; the architecture diagrams are Mermaid (Knut Sveidqvist & the mermaid-js community). None of the doc types are invented here. What is original is modest and concrete: the composition + the governance invariants carried in frontmatter as a fact contract and enforced by a checker — the enforcement, not the invention.

Full credits and the per-source links are in ATTRIBUTION.md and references/prior-art-landscape.md.

Contributing

Issues and PRs welcome — the project dogfoods its own rules. See CONTRIBUTING.md for the repo layout, the invariants it holds itself to, how to refresh the vendored OKF spec, and how to validate a change — make check runs the full gate: version sync, the docs linter, the hostile parser fixtures, bash -n on every script, and a dry-run of every installer.

FAQ

What is an "agent skill"? A skill is a folder of markdown instructions (a SKILL.md plus optional rules/ and templates/) that an AI coding agent loads and follows. Living Docs is a skill that teaches the agent how to keep documentation in sync with code.

Which tools does Living Docs work with? Claude Code, OpenCode, and Codex (native SKILL.md skills), Cursor (.cursor/rules), GitHub Copilot (.github/instructions), and Pi (AGENTS.md). Because the skill is plain markdown, any agent that reads instruction files can use it. See Installation.

How is this different from a documentation generator or a wiki? Living Docs is not a generator and not a hosting tool. It is a discipline — five no-drift governance invariants plus a doc trail (constitution → PRD → ADR + BDR → issues → code). The agent follows the discipline as it works; a deterministic CLI authors the mechanical half (living-docs new / status / supersede / index) and verifies it (living-docs check) when you wire it into CI or the agent's loop. Prompt-level guidance plus a machine check — not one pretending to be the other. Your docs live in the repo, in Git, next to the code.

What is an ADR / BDR / PRD? An ADR (Architecture Decision Record) captures how the system is structured and why. A BDR (Behavior Decision Record) captures what the system must observably do (Given/When/Then). A PRD captures the product/feature requirements. Each has a convention file and a starter template under skills/living-docs/.

What is OKF (Open Knowledge Format)? A vendor-neutral format from Google Cloud Platform — markdown with YAML frontmatter, a required type, reserved index.md/log.md, and bundle-relative links. Living Docs stores every doc as an OKF concept so the corpus stays portable and agent-parseable. The spec is vendored under skills/okf-knowledge-format/.

What does the living-docs check checker catch — and not catch? It is a deterministic checker over a documented input shape, not a general markdown/YAML validator, and its three fragile parsers (link extraction, link resolution, frontmatter reading) are guarded by hostile/negative fixtures (make test-fixtures). One known limit: the structural-graph checks — directory-index membership and index reachability — read only inline links in index.md, so a file indexed solely via a reference-style link ([x][ref]) is not yet detected there and would be reported as a false-positive orphan. Link validity itself is checked natively by pulldown-cmark, which parses every link form (inline, titled, angle-bracket, reference-style, and images).

Is it tied to a specific language or framework? No. Living Docs is stack-agnostic — it governs documentation organization and lifecycle, not your tech stack.

Did you invent this? No, and the repo says so. Living Docs composes established practices (Martraire's living documentation, Nygard's ADRs, Specification by Example for BDRs, Google's OKF). Full, sourced credits in ATTRIBUTION.md and references/prior-art-landscape.md.

License

MIT © 2026 Evaldo Klock.

Vendored third-party content under reference/ directories remains subject to its own upstream license — see ATTRIBUTION.md.

Keywords: living documentation · documentation as code · docs-as-code · AI agent skill · Claude Code skill · Cursor rules · GitHub Copilot instructions · OpenCode · Codex · Pi · Architecture Decision Records (ADR) · Behavior Decision Records (BDR) · PRD · project constitution · glossary · Mermaid architecture diagrams · semantic index · Open Knowledge Format (OKF) · deterministic docs CLI · full-text search · SQLite FTS5 · public docs export · leak gate · knowledge management · technical writing · software architecture · markdown documentation · no-drift docs.