living-docs
Run a project's engineering decisions as a living log — MADR-lite ADRs (supersede, never delete) for decisions expensive to reverse, issues for the work (and its cheap-to-reverse choices), research artifacts, an optional PRD, a project constitution, and living Mermaid architectur
#research
Install
npx skills add https://github.com/ejklock/living-docs-skill/tree/main/skills/living-docs
claude plugin marketplace add https://llmmart.ai/marketplace.json && claude plugin install ejklock-living-docs-skill@llmmart
git clone https://github.com/ejklock/living-docs-skill.git
The skills CLI installs just this skill, for any of its supported agents. Claude Code installs the whole ejklock/living-docs-skill collection as a plugin from our marketplace. Git is the plain clone.
Skill manifest
Living Docs
Living Docs is a decision log with a gate. It records the engineering decisions a future reader would pay to rediscover, traces each from its rationale to the code, and refuses to let a record exist unindexed, untyped, or silently rewritten. The spine — every piece of knowledge has exactly one home, that home is indexed, and a material decision ships with its record — carries a small set of record types: ADRs, issues, research, a constitution, an optional PRD, and living architecture views.
This skill is stack-agnostic. It governs how decisions are recorded and maintained, never what technology a project uses.
Using this skill (progressive disclosure)
This SKILL.md is a slim stub — a trigger plus a task→topic router. The living-docs CLI
holds the full, authoritative conventions and templates and discloses them progressively.
Before authoring anything, load the topic for your task and operate from it, not from this
stub:
living-docs read guide --list— discover every topic.living-docs read guide <topic>— load that topic's full rules (+ template).
Piped output is minified JSON (machine default); --plain for human text, --json to force
JSON.
Write ONLY the body below the closing ---. Frontmatter and indexes are CLI-owned: living-docs write set / write supersede.
- An MCP client can call the same verbs as tools:
living-docs mcp --docs-dir docsserves them over stdio (setup:claude mcp add living-docs -- living-docs mcp --docs-dir docs; themcpServersJSON and npx forms are in the README at https://github.com/ejklock/living-docs-skill). - The spine invariants →
living-docs read guide spine. - Authoring mechanics — CLI owns every deterministic step, you write only the prose →
living-docs read guide procedure.
The one rule that decides whether to write a record
Write an ADR when a future reader would pay to rediscover why you chose this over the alternatives — i.e. the decision is expensive to reverse. Otherwise put the choice in the issue that carries the work. When in doubt, it is an issue. A record is earned by materiality, never by the fact that a change touched structure or behavior — do not manufacture a record per layer.
When to invoke
- Standing up documentation for a project (creating
docs/structure, the docs index, ADR/issue directories) →living-docs read guide procedure. - Adopting living-docs in an existing/brownfield project (decisions already made but undocumented) →
living-docs read guide procedure, Adopting living docs in an existing project: inventory the decisions, confirm each with the user before recording any ADR, never back-fill by inference alone. A bundle authored under an older organization is brought current byliving-docs manage indexandliving-docs manage fmt, thenliving-docs check. - Writing or editing an ADR (a decision expensive to reverse, with its rejected alternatives) →
living-docs read guide adr(loadread guide procedurefirst if not already loaded this session). A test-strategy decision (non-default level/technique, bar deviation) is an ADRtags: [testing], not a new record type. - Writing or editing a PRD (an optional product/feature spec: who asked, what is out of scope, what success looks like) →
living-docs read guide prd(loadread guide procedurefirst). A PRD without who-asked/out-of-scope is just a large issue — keep it an issue. - Establishing or amending the constitution (foundational scope, non-negotiables) →
living-docs read guide constitution(loadread guide procedurefirst). - Creating or editing an issue/ticket (the unit of work; it carries any cheap-to-reverse decision inline) →
living-docs read guide issue-workflow(loadread guide procedurefirst). - Recording research (technology evaluation, external trade-offs) → load the
research-artifactsskill. It owns the OKF research-note format, the source discipline, and the research → decision → issue traceable chain, and links back here for the ADR/issue artifacts. Pairs with thedeep-researchskill. - Drawing or updating an architecture, data-flow, or tool-calling diagram →
living-docs read guide architecture-diagrams. - A doc has grown too large or mixes concerns → split into a semantic index →
living-docs read guide semantic-index. - Reading the corpus as an agent (what governs X now) → run
living-docs read records(active records only, supersede chains collapsed; superseded, deprecated, closed and done records are withheld and counted inwithheld, and--allincludes them, in--links-toand--impacttoo;--topic <term>to filter,--contractfor the contract sections,--fullfor whole bodies — ADRs 0050, 0064), neverindex.mddirectly. Before a supersede or an edit, runliving-docs read records --links-to <TYPE/NNNN>(who links it) and--impact <TYPE/NNNN>(who reaches it through a chain, with distance) to see what to revisit. A raw record whose body opens with aSUPERSEDEDorDEPRECATEDcallout is history — follow the successor link or discard it, never plan on it. - Handing the search of the bundle and code to a cheaper subagent (it returns
TYPE/NNNNrefs with quotes; the session reads them) →living-docs read guide delegated-exploration. - Sizing a record's body (aim ~100 lines,
checkadvises at 120; research exempt; never trim a load-bearing rationale) →living-docs read guide size-targets. - Enforcing the no-drift maintenance rule after any structural change → run
living-docs check; treat a non-zero exit as blocked; treat each advisory (SIZE,OWNER,HEADING,LIVENESS stale-proposed,MOVED-SOURCE,LINK-STYLE,BLOCKED-BY;living-docs check --helplists them all) as work to schedule. Detail →living-docs read guide check; the maintaining loop →read guide procedure. - Authoring or checking the OKF format of any doc (frontmatter
type, reservedindex.md/log.md, relative links,# References) →living-docs read guide okf-format. - Understanding the doc trail (constitution → PRD → ADR → issues → code) and which record type answers which question →
living-docs read guide doc-trail.
Files (living-docs-skill)
-
hooks
-
decision-prompt.sh 3.7 KB
Loading… -
pre-commit 1.8 KB · in bundle
-
session-context.sh 2.7 KB
Loading…
-
-
rules
-
adr-conventions.md 7.3 KB
Loading… -
architecture-diagrams.md 10.3 KB
Loading… -
check.md 5.7 KB
Loading… -
constitution-conventions.md 3.5 KB
Loading… -
delegated-exploration.md 2.1 KB
Loading… -
doc-trail.md 4 KB
Loading… -
issue-workflow.md 4.9 KB
Loading… -
okf-format.md 2.7 KB
Loading… -
prd-conventions.md 3.8 KB
Loading… -
procedure.md 9.8 KB
Loading… -
semantic-index.md 5.3 KB
Loading… -
size-targets.md 1.5 KB
Loading… -
spine.md 1.4 KB
Loading…
-
-
templates
-
adr.md 1.1 KB
Loading… -
architecture-view.md 495 B
Loading… -
claude-hard-rules.md 9 KB
Loading… -
constitution.md 1.2 KB
Loading… -
context-index.md 921 B
Loading… -
issue.md 772 B
Loading… -
prd.md 1.1 KB
Loading… -
research.md 952 B
Loading…
-
-
tests
-
fixtures
-
01-fence-link-clean
-
docs
-
foo.md 144 B
Loading… -
index.md 27 B
Loading…
-
-
-
02-fence-link-dirty
-
docs
-
foo.md 62 B
Loading… -
index.md 27 B
Loading…
-
-
-
03-link-forms
-
docs
-
bar.md 58 B
Loading… -
foo.md 145 B
Loading… -
index.md 45 B
Loading…
-
-
-
04-frontmatter-quoted-commented
-
docs
-
a.md 78 B
Loading… -
b.md 78 B
Loading… -
c.md 96 B
Loading… -
index.md 51 B
Loading…
-
-
-
05-nested-key-trap
-
docs
-
foo.md 38 B
Loading… -
index.md 27 B
Loading…
-
-
-
06-block-scalar-ok
-
docs
-
foo.md 82 B
Loading… -
index.md 27 B
Loading…
-
-
-
07-supersede-broken
-
docs
-
0001-old.md 65 B
Loading… -
index.md 32 B
Loading…
-
-
-
08-reference-link-broken
-
docs
-
foo.md 75 B
Loading… -
index.md 27 B
Loading…
-
-
-
09-okf-canonical
-
docs
-
datasets
-
crypto_bitcoin.md 2 KB
Loading… -
index.md 181 B
Loading…
-
-
tables
-
blocks.md 728 B
Loading… -
index.md 434 B
Loading… -
inputs.md 2.1 KB
Loading… -
outputs.md 2.2 KB
Loading… -
transactions.md 5.5 KB
Loading…
-
-
index.md 297 B
Loading…
-
-
PROVENANCE.md 1.4 KB
Loading…
-
-
10-mermaid-valid
-
doc.md 287 B
Loading…
-
-
11-mermaid-invalid
-
doc.md 141 B
Loading…
-
-
-
run.sh 3.7 KB
Loading…
-
-
SKILL.md 7 KB
--- name: living-docs description: Run a project's engineering decisions as a living log — MADR-lite ADRs (supersede, never delete) for decisions expensive to reverse, issues for the work (and its cheap-to-reverse choices), research artifacts, an optional PRD, a project constitution, and living Mermaid architecture views, where every record has exactly one home, indexes never drift, and a record is earned by materiality, not written per layer. Use when setting up or maintaining project docs, writing an ADR/PRD/constitution/issue/research note, drawing or updating an architecture diagram, or enforcing the no-drift maintenance rule. version: "0.30.0" metadata: type: skill layer: procedural tags: [documentation, adr, prd, constitution, issues, research, architecture] --- # Living Docs Living Docs is a **decision log with a gate**. It records the engineering decisions a future reader would pay to rediscover, traces each from its rationale to the code, and refuses to let a record exist unindexed, untyped, or silently rewritten. The spine — **every piece of knowledge has exactly one home, that home is indexed, and a material decision ships with its record** — carries a small set of record types: ADRs, issues, research, a constitution, an optional PRD, and living architecture views. This skill is stack-agnostic. It governs *how* decisions are recorded and maintained, never *what* technology a project uses. --- ## Using this skill (progressive disclosure) This SKILL.md is a **slim stub** — a trigger plus a task→topic router. The `living-docs` CLI holds the full, authoritative conventions and templates and discloses them progressively. **Before authoring anything, load the topic for your task and operate from it, not from this stub:** - `living-docs read guide --list` — discover every topic. - `living-docs read guide <topic>` — load that topic's full rules (+ template). Piped output is minified JSON (machine default); `--plain` for human text, `--json` to force JSON. Write ONLY the body below the closing ---. Frontmatter and indexes are CLI-owned: `living-docs write set` / `write supersede`. - An MCP client can call the same verbs as tools: `living-docs mcp --docs-dir docs` serves them over stdio (setup: `claude mcp add living-docs -- living-docs mcp --docs-dir docs`; the `mcpServers` JSON and npx forms are in the README at https://github.com/ejklock/living-docs-skill). - The spine invariants → `living-docs read guide spine`. - Authoring mechanics — CLI owns every deterministic step, you write only the prose → `living-docs read guide procedure`. ## The one rule that decides whether to write a record Write an **ADR** when a future reader would pay to rediscover *why* you chose this over the alternatives — i.e. the decision is expensive to reverse. Otherwise put the choice in the **issue** that carries the work. When in doubt, it is an issue. A record is earned by materiality, never by the fact that a change touched structure or behavior — do not manufacture a record per layer. --- ## When to invoke - Standing up documentation for a project (creating `docs/` structure, the docs index, ADR/issue directories) → `living-docs read guide procedure`. - **Adopting living-docs in an existing/brownfield project** (decisions already made but undocumented) → `living-docs read guide procedure`, *Adopting living docs in an existing project*: inventory the decisions, **confirm each with the user before recording any ADR**, never back-fill by inference alone. A bundle authored under an older organization is brought current by `living-docs manage index` and `living-docs manage fmt`, then `living-docs check`. - Writing or editing an **ADR** (a decision expensive to reverse, with its rejected alternatives) → `living-docs read guide adr` (load `read guide procedure` first if not already loaded this session). A test-strategy *decision* (non-default level/technique, bar deviation) is an ADR `tags: [testing]`, not a new record type. - Writing or editing a **PRD** (an optional product/feature spec: who asked, what is out of scope, what success looks like) → `living-docs read guide prd` (load `read guide procedure` first). A PRD without who-asked/out-of-scope is just a large issue — keep it an issue. - Establishing or amending the **constitution** (foundational scope, non-negotiables) → `living-docs read guide constitution` (load `read guide procedure` first). - Creating or editing an **issue/ticket** (the unit of work; it carries any cheap-to-reverse decision inline) → `living-docs read guide issue-workflow` (load `read guide procedure` first). - Recording **research** (technology evaluation, external trade-offs) → load the **`research-artifacts`** skill. It owns the OKF research-note format, the source discipline, and the research → decision → issue traceable chain, and links back here for the ADR/issue artifacts. Pairs with the `deep-research` skill. - Drawing or updating an **architecture, data-flow, or tool-calling diagram** → `living-docs read guide architecture-diagrams`. - A doc has grown too large or mixes concerns → **split into a semantic index** → `living-docs read guide semantic-index`. - **Reading the corpus as an agent** (what governs X *now*) → run `living-docs read records` (active records only, supersede chains collapsed; superseded, deprecated, closed and done records are withheld and counted in `withheld`, and `--all` includes them, in `--links-to` and `--impact` too; `--topic <term>` to filter, `--contract` for the contract sections, `--full` for whole bodies — ADRs 0050, 0064), **never `index.md` directly**. Before a supersede or an edit, run `living-docs read records --links-to <TYPE/NNNN>` (who links it) and `--impact <TYPE/NNNN>` (who reaches it through a chain, with distance) to see what to revisit. A raw record whose body opens with a `SUPERSEDED` or `DEPRECATED` callout is history — follow the successor link or discard it, never plan on it. - Handing the **search of the bundle and code** to a cheaper subagent (it returns `TYPE/NNNN` refs with quotes; the session reads them) → `living-docs read guide delegated-exploration`. - Sizing a record's body (aim ~100 lines, `check` advises at 120; research exempt; never trim a load-bearing rationale) → `living-docs read guide size-targets`. - Enforcing the **no-drift maintenance rule** after any structural change → run `living-docs check`; treat a non-zero exit as blocked; treat each advisory (`SIZE`, `OWNER`, `HEADING`, `LIVENESS stale-proposed`, `MOVED-SOURCE`, `LINK-STYLE`, `BLOCKED-BY`; `living-docs check --help` lists them all) as work to schedule. Detail → `living-docs read guide check`; the maintaining loop → `read guide procedure`. - Authoring or checking the **OKF format** of any doc (frontmatter `type`, reserved `index.md`/`log.md`, relative links, `# References`) → `living-docs read guide okf-format`. - Understanding the **doc trail** (constitution → PRD → ADR → issues → code) and which record type answers which question → `living-docs read guide doc-trail`.
Comments (0)
Sign in to join the conversation.
Reviews (0)
No reviews yet.
No comments yet.