Scores a repository against the agentic-quality doctrine (the cross-repo standard in rules/agentic-quality.md for code, comments, docs and structure a cold agent session can navigate), and owns the AGENTS.md protocol: creating, auditing, upgrading and org-surveying a repo's entry doc.
Read-only by default. The scorer, the scan, the audit and the survey never write. The
only writing step is agents-md.py scaffold --write, which creates an AGENTS.md and
refuses to overwrite one (there is deliberately no --force).
AGENTS.md: create, audit, upgrade, survey
The protocol (what goes in, what stays out, the 150/200-line and 12,000/16,000-character
budget and how to split, CLAUDE.md shadowing, staleness in commits) is
references/agents-md-protocol.md. Read it before
writing or judging an entry doc. The load-bearing fact: Claude Code reads AGENTS.md
only when no CLAUDE.md, .claude/CLAUDE.md or CLAUDE.local.md sits in the working
directory or above it, unless that CLAUDE.md imports @AGENTS.md.
# 1. Deep scan: deterministic facts JSON; every fact cites file:line or a command,
# plus landmine CANDIDATES from git history (always questions, never facts)
python scripts/repo-scan.py --repo path/to/repo --json > facts.json
# 2. Create: draft from the facts (commands only from declared scripts, tagged [untested])
python scripts/agents-md.py scaffold --repo path/to/repo --facts facts.json > AGENTS.draft.md
python scripts/agents-md.py scaffold --repo path/to/repo --write # creates; never overwrites
# 3. Audit, then upgrade with a reviewable patch
python scripts/agents-md.py audit --repo path/to/repo # exit 10 on warn/crit
python scripts/agents-md.py audit --repo path/to/repo --diff > agents-md.patch
git -C path/to/repo apply "$PWD/agents-md.patch"
# 4. Survey a GitHub org: read-only gh api, no clones, writes nothing
python scripts/agents-md.py survey --org my-org --json | jq '.meta'
Workflow rules:
- Scan before drafting. The scaffold's archetype templates
(assets/agents-md/: PHP CMS + DDEV + bundler, Node/TS app,
Python service, static site, generic) hold slots, not claims. Everything the scan can't
verify becomes a
TODO(owner):question. - The owner finishes the draft. Answer or delete every
TODO(owner), run each command once and drop its[untested]tag, delete the DRAFT comment. The audit flags all three until done. Optional synthesis (one read-only Explore subagent per custom code area, at most four, fed the facts JSON) is in the protocol's section 8. - The patch never removes landmines.
--diffadds missing-section stubs, an@AGENTS.mdimport for a shadowing CLAUDE.md, annotations on dead commands, and moves for oversized sections (setup prose to README, subsystem detail to a nested AGENTS.md, the rest todocs/agents/). It leaves the overview, Commands, Landmines and Deploy where they are. The audit also lists scan candidates whose files the doc never names: each is a landmine to write or rule out. - Pair with Claude Code's own checks.
/doctor prompt-auditdoes the semantic pass (outdated or contradictory instructions); this tooling is the deterministic, CI-able one (protocol section 7).
Never run repo tooling to "verify" a command: Composer plugins, justfile backticks and
make $(shell ...) execute repo code even when listing. The scan reads tracked files and
git metadata only, never opens secret files, and keeps variable names (not values) from
.env.example.
Repo scorer
python scripts/repo-doctor.py # audit cwd, human panel
python scripts/repo-doctor.py --repo path/to/repo # audit another repo
python scripts/repo-doctor.py --json | jq .data.grade # machine-readable
python scripts/repo-doctor.py --strict # CI gate: exit 10 below B
Six dimensions, 0-5 each, weighted into a letter grade:
| Dimension | Measures | Weight |
|---|---|---|
entry_docs |
AGENTS.md/CLAUDE.md present · Landmines section · 200-line / 16,000-character budget · freshness in commits-since-touched · a CLAUDE.md that shadows AGENTS.md | 2.0 |
docs_health |
README · docs/ index when >6 files · ghost links in the index | 1.5 |
comments |
contract blocks on the largest source files · section markers in files >400 lines | 2.0 |
structure |
monster files (>800 warn, >1500 crit; generated exempt) · repo-root junk | 2.0 |
enforcement |
tests · CI · single check entry point · invariant gate scripts |
1.5 |
doc_pairing |
fraction of recent feat/fix commits touching a *.md in the same commit |
1.0 |
Full rubric (each check, threshold and fix): references/scoring-rubric.md.
Audit workflow
- Run the scorer. On cp1252/plain terminals it degrades to ASCII; nothing is written.
- Read findings top-down (crit, then warn, then info). Facts (monster-file list,
pairing ratio, entry-doc age) ride in
--jsonunder.data.facts. - Verify before acting. The scorer is heuristic: a flagged 900-line file may be a justified single-writer module (then it needs the guard comment, section map and gate, not a split); a "stale" AGENTS.md may describe code that genuinely didn't change.
- Remediate via the owning skill (below). Batch fixes into small commits: entry doc first (highest leverage), then indexes, guard comments, splits.
- Re-run to confirm the grade moved. For fleets, loop
--jsonover repo roots, or useagents-md.py survey --orgfor the entry-doc column without cloning.
Remediation map: who owns each fix
| Finding | Owner |
|---|---|
| Missing/weak/oversized AGENTS.md, shadowing CLAUDE.md | agents-md.py scaffold / audit --diff (above); hand skeleton: assets/AGENTS-template.md |
| Multi-platform doc mess (CLAUDE.md + COPILOT.md + CURSOR.md ...) | doc-scanner (consolidate), then audit the result here |
| Missing docs index | Write from assets/docs-index-template.md |
| Monster file needs splitting | refactor-ops (extract-module patterns, circular-dep cautions) |
| Monster file is justified | Guard comment + section map + a scripts/check-* invariant gate (references/comment-doctrine.md) |
| Missing/weak comments | references/comment-doctrine.md: contract blocks, WHY-only, guard comments, citations |
| Decisions undocumented | adr-ops |
| Stale PLAN/roadmap | project-planner |
| Code-level debt (duplication, dead code, security) | techdebt: deliberately NOT scored here |
| New repo from scratch | scaffold + the templates in assets/ |
Boundary: repo-doctor audits repo-level conventions; techdebt scans code-level
debt; review/code-review judge diffs. Don't blur the three.
Nested entry docs and monorepos
Nest an AGENTS.md only where a subsystem has its own contract (invariant law, audience
or gate); the root links every nested doc, and a CLAUDE.md beside a nested AGENTS.md
shadows it (protocol section 6). For large multi-subsystem repos the root entry doc is
judged as a router (invariants + ownership table), each contracted package needs its
own entry doc and check, and cross-package invariants need mechanical gates:
references/monorepo-structure.md. Run the scorer
per package as well as at root.
Resources
| Resource | What it owns |
|---|---|
| scripts/repo-doctor.py | The scorer: six dimensions, findings, grade; --json envelope claude-mods.repo-doctor/v1; --strict CI gate |
| scripts/repo-scan.py | Deep scan: manifests, DDEV, deploy hooks and the scripts they call, CI, tests, generated output, code areas, size outliers, docs, env names, git-history landmine candidates; --json (repo-scan/v1), --only |
| scripts/agents-md.py | scaffold (--write creates only), audit (--diff patch), survey --org / --remote (GET-only); exit 10 on findings |
| scripts/check-memory-docs.py | Tripwire for the Claude Code facts the protocol encodes: --offline in PR CI, --live in the scheduled freshness workflow |
| references/agents-md-protocol.md | The AGENTS.md protocol: contents, exclusions, size and split, CLAUDE.md shadowing, staleness, how the tools fit beside /doctor |
| references/scoring-rubric.md | Every scorer check: what it measures, threshold, why, and the fix |
| references/comment-doctrine.md | Contract blocks, WHY-only inline, guard comments, section markers, format-at-site, citations |
| references/monorepo-structure.md | Structuring very large monorepos for agentic development |
| assets/agents-md/ | Archetype templates the scaffold fills (usable by hand: the slots are documented in each file's header) |
| assets/AGENTS-template.md | Hand-fill entry-doc skeleton with the mandatory Landmines section |
| assets/docs-index-template.md | docs/00_INDEX.md skeleton with the two anti-rot rules baked in |