Pillar — Documentation & Knowledge

Prefix: DOC- What it measures: instructions agents rely on to work correctly — README quality, AGENTS.md / CLAUDE.md, environment documentation, operational runbooks, and architecture decision records.

The Documentation & Knowledge pillar most often distinguishes a usable codebase from an unusable one. An agent spawned into a well-documented repository reads the README, the AGENTS.md, and the env reference, then proceeds with a correct mental model. An agent in an undocumented repository has to infer conventions from scattered files, which is slow, error-prone, and produces inconsistent results across sessions.

Criteria in this pillar

DOC-010 — README present and substantive

Level: 1 · Scope: repository · Check: deterministic
A README.md (or README variant) exists at the repository root and is longer than 20 non-blank lines, referencing at minimum the project purpose, setup command, and primary development command.
Rationale: agents spawned into a repository read the README first to build a mental model; without one, every task begins with ambiguity and costly discovery.
Evidence expected: file exists at repo root; word count, section headings detected.

DOC-020 — Project purpose stated in README

Level: 2 · Scope: repository · Check: ai-assisted
The README contains a clear, one-paragraph description of what the project does and for whom.
Rationale: agents that understand intent make better local decisions — they refactor with goals in mind rather than preserving incidental structure.
Evidence expected: section heading detected plus AI-assisted judgment of whether the paragraph answers "what does this do and why."

DOC-030 — AGENTS.md or CLAUDE.md present

Level: 2 · Scope: repository · Check: deterministic
A canonical agent-context file (AGENTS.md, CLAUDE.md, or .cursor/rules) is present at the repo root and references stack, conventions, and common commands.
Rationale: agents behave better when given explicit rules than when inferring conventions from scattered files. This is the single highest-leverage artifact for agent readiness.
Evidence expected: file exists; contains sections matching ^##?\s*(Stack|Conventions|Commands|Setup).

DOC-040 — Environment variables documented

Level: 2 · Scope: application · Check: deterministic
Every environment variable the application requires is documented in docs/env.md, README.md, or an equivalent table, and a committed .env.example exists.
Rationale: agents cannot guess undocumented secrets or URLs; missing env documentation blocks every subsequent task.
Evidence expected: .env.example presence; ratio of env.* references in code to documented entries.

DOC-050 — Architecture Decision Records folder

Level: 3 · Scope: repository · Check: deterministic
An docs/adr/ (or docs/decisions/) folder exists with at least a template and one recorded decision.
Rationale: ADRs encode why — agents use them to avoid re-litigating settled questions and to respect hard constraints with non-obvious rationale.
Evidence expected: directory present; at least one NNNN-*.md ADR file.

DOC-060 — Runbook / operations documentation

Level: 3 · Scope: application · Check: ai-assisted
A docs/runbook.md (or equivalent) describes on-call procedures, common failure modes, dashboards, and rollback steps.
Rationale: agents that can read runbooks can assist during incidents; those that cannot are dead weight at the worst moments.
Evidence expected: file presence; AI-assisted judgment on content coverage.

DOC-070 — API reference auto-generated or hand-maintained

Level: 4 · Scope: application · Check: deterministic
API (REST, gRPC, GraphQL, or Server Actions) has a machine-readable specification or hand-maintained reference that is up-to-date with the code.
Rationale: agents consuming or extending an API benefit from a typed, machine-readable contract; without it, every change risks silent contract breakage.
Evidence expected: openapi.yaml, openapi.json, schema.graphql, or similar; or a published reference site built from code.

DOC-080 — Changelog in Keep-a-Changelog format

Level: 3 · Scope: repository · Check: deterministic
CHANGELOG.md follows Keep-a-Changelog format with semver-aligned entries.
Rationale: release history gives agents (and humans) a searchable record of what changed when, reducing regression-hunting time.
Evidence expected: file presence; headings match ## [X.Y.Z] - YYYY-MM-DD.

The 8 pillars — sibling pillars in v1.0.
Criteria catalog — all criteria, one page.
Maturity levels — how criteria combine into a level.

Criteria in this pillar

Level: 1 · Scope: repository · Check: deterministic

A README.md (or README variant) exists at the repository root and is longer than 20 non-blank lines, referencing at minimum the project purpose, setup command, and primary development command.

Rationale: agents spawned into a repository read the README first to build a mental model; without one, every task begins with ambiguity and costly discovery.

Evidence expected: file exists at repo root; word count, section headings detected.

Level: 2 · Scope: repository · Check: ai-assisted

The README contains a clear, one-paragraph description of what the project does and for whom.

Rationale: agents that understand intent make better local decisions — they refactor with goals in mind rather than preserving incidental structure.

Evidence expected: section heading detected plus AI-assisted judgment of whether the paragraph answers "what does this do and why."

Level: 2 · Scope: repository · Check: deterministic

A canonical agent-context file (AGENTS.md, CLAUDE.md, or .cursor/rules) is present at the repo root and references stack, conventions, and common commands.

Rationale: agents behave better when given explicit rules than when inferring conventions from scattered files. This is the single highest-leverage artifact for agent readiness.

Evidence expected: file exists; contains sections matching ^##?\s*(Stack|Conventions|Commands|Setup).

Level: 2 · Scope: application · Check: deterministic

Every environment variable the application requires is documented in docs/env.md, README.md, or an equivalent table, and a committed .env.example exists.

Rationale: agents cannot guess undocumented secrets or URLs; missing env documentation blocks every subsequent task.

Evidence expected: .env.example presence; ratio of env.* references in code to documented entries.

Level: 3 · Scope: repository · Check: deterministic

An docs/adr/ (or docs/decisions/) folder exists with at least a template and one recorded decision.

Rationale: ADRs encode why — agents use them to avoid re-litigating settled questions and to respect hard constraints with non-obvious rationale.

Evidence expected: directory present; at least one NNNN-*.md ADR file.

Level: 3 · Scope: application · Check: ai-assisted

A docs/runbook.md (or equivalent) describes on-call procedures, common failure modes, dashboards, and rollback steps.

Rationale: agents that can read runbooks can assist during incidents; those that cannot are dead weight at the worst moments.

Evidence expected: file presence; AI-assisted judgment on content coverage.

Level: 4 · Scope: application · Check: deterministic

API (REST, gRPC, GraphQL, or Server Actions) has a machine-readable specification or hand-maintained reference that is up-to-date with the code.

Rationale: agents consuming or extending an API benefit from a typed, machine-readable contract; without it, every change risks silent contract breakage.

Evidence expected: openapi.yaml, openapi.json, schema.graphql, or similar; or a published reference site built from code.

Level: 3 · Scope: repository · Check: deterministic

CHANGELOG.md follows Keep-a-Changelog format with semver-aligned entries.

Rationale: release history gives agents (and humans) a searchable record of what changed when, reducing regression-hunting time.

Evidence expected: file presence; headings match ## [X.Y.Z] - YYYY-MM-DD.