Audit Agent Docs
Audit whether existing project docs give an agent enough facts to start work without guessing.
Do not edit by default. Report gaps first.
Inspect
Look for:
- root agent instructions:
AGENTS.md, CLAUDE.md, or equivalent
- domain language:
CONTEXT.md or CONTEXT-MAP.md
- durable decisions:
docs/adr/
- agent docs:
docs/agents/ or project equivalent
- build, test, owner, security, and tool policy facts
- package scripts, CI config, test config, and obvious entrypoints
If files are absent, inspect the repo directly before calling it a gap.
Audit Questions
The docs should let an agent answer:
- Where should I start reading?
- How do I install, build, run, lint, typecheck, and test?
- Which modules are likely in scope?
- Which paths or actions need approval?
- Who owns decisions or review?
- Which known risks should not be "fixed" accidentally?
- Which tools, connectors, skills, hooks, and side effects are allowed?
For a deeper checklist, use readiness-questions.md.
Output
Return:
ready, ready_with_gaps, or not_ready- highest-risk gaps first
- evidence: file path or command result
- concrete fix for each gap
- docs that are redundant or should become skills
Do not demand placeholder docs. If a fact is not needed for safe work, say so.
1---2name: audit-agent-docs3description: Audits a repository's agent-readable docs for whether an agent can safely start work. Use when user asks if a repo is ready for coding agents, wants readiness gaps, or asks to review AGENTS.md, CONTEXT.md, docs/agents, build, test, owner, or tool policy docs.4---56# Audit Agent Docs78Audit whether existing project docs give an agent enough facts to start work without guessing.910Do not edit by default. Report gaps first.1112## Inspect1314Look for:1516- root agent instructions: `AGENTS.md`, `CLAUDE.md`, or equivalent17- domain language: `CONTEXT.md` or `CONTEXT-MAP.md`18- durable decisions: `docs/adr/`19- agent docs: `docs/agents/` or project equivalent20- build, test, owner, security, and tool policy facts21- package scripts, CI config, test config, and obvious entrypoints2223If files are absent, inspect the repo directly before calling it a gap.2425## Audit Questions2627The docs should let an agent answer:2829- Where should I start reading?30- How do I install, build, run, lint, typecheck, and test?31- Which modules are likely in scope?32- Which paths or actions need approval?33- Who owns decisions or review?34- Which known risks should not be "fixed" accidentally?35- Which tools, connectors, skills, hooks, and side effects are allowed?3637For a deeper checklist, use [readiness-questions.md](references/readiness-questions.md).3839## Output4041Return:4243- `ready`, `ready_with_gaps`, or `not_ready`44- highest-risk gaps first45- evidence: file path or command result46- concrete fix for each gap47- docs that are redundant or should become skills4849Do not demand placeholder docs. If a fact is not needed for safe work, say so.50
mergemat