Claude Cursor Skill

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

LLM Mart · 0 points · 6 views 160 listing impressions 0 install-command copies

#research

Download ejklock-living-docs-skill-skills_living-docs-2d29395.zip · 60 KB

Install

skills CLI npx skills add https://github.com/ejklock/living-docs-skill/tree/main/skills/living-docs
Claude Code claude plugin marketplace add https://llmmart.ai/marketplace.json && claude plugin install ejklock-living-docs-skill@llmmart
Git 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 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.
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.

No comments yet.

Reviews (0)

No reviews yet.