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.