Living Docs Governance

Living Docs Governance

Long-lived projects often rot at the documentation layer first: the README describes an old pipeline, architecture notes describe a refactor that never shipped, and every new session re-derives context that should already be available.

Living Docs Governance assigns four non-overlapping roles to the project's existing documentation, links those roles from the active agent harness, and defines small update rules that keep the sources useful. The roles matter; the filenames do not.

This is a maintain-phase practice. For one-time exploration of an unfamiliar repository, use codebase-onboarding first.

When to Activate

Activate when any of these are true:

• The repository has grown past a few modules and its docs are drifting from the code.
• Agents or teammates repeatedly rediscover the same structure and decisions.
• Nobody can quickly answer what is healthy, blocked, intentionally removed, or currently authoritative.
• Deleted files or abandoned approaches are recreated because their disposition was not preserved.
• The project needs a durable governance layer without adopting a large documentation platform.

Do not use this for a throwaway script or create a parallel documentation system when the repository already has one.

How It Works

1. Inventory before creating anything

Inspect the repository's current instruction and documentation surfaces first:

• harness instructions such as AGENTS.md, CLAUDE.md, .cursor/rules, or their equivalent;
• README, architecture docs, ADRs, runbooks, roadmaps, changelogs, status pages, and docs indexes;
• generated docs and external systems that may already be canonical.

Map the existing sources to the four roles below. Reuse and link them in place. A small repository may keep more than one role in a single file if the sections are clearly separated and each fact still has one canonical owner.

Only when a role is genuinely missing:

1. propose the smallest new section or document;
2. prefer the repository's established docs directory and naming conventions;
3. ask before adding a new top-level artifact.

2. Assign four roles

The discipline is one canonical owner per fact. Other files link to that owner rather than copying it. "Where is auth?" belongs to the map. "Is auth migration blocked?" belongs to status. "Why was the legacy auth path removed?" belongs to history or an ADR.

3. Wire the active harness honestly

Use the instruction surface for the harness that actually runs in the repository:

• Codex and harness-neutral projects commonly use AGENTS.md.
• Claude Code projects commonly use CLAUDE.md.
• Other harnesses should use their supported project-instruction surface.

Keep the harness file short. Add signposts to the canonical map, status, and recent history instead of copying their contents.

Do not claim that documents are read automatically unless a real harness instruction or lifecycle hook enables that behavior. Without such wiring, tell the operator to invoke this skill or perform the read sequence explicitly.

Recommended sequence after the active harness instructions are loaded:

1. Read the canonical map for navigation.
2. Read current status, especially blockers and the delete-zone.
3. Read only the recent or task-relevant history and ADRs.