Agent Readiness Audit

A tiny CLI that scores whether a codebase is ready for coding agents like Cursor, Codex, Claude Code, or Hermes subagents.

Inspired by Lee Robinson's agent-legible codebase guidance: agents need source-of-truth clarity, verification loops, concise AGENTS.md, and automation hooks.

What it checks

• AGENTS.md / agent instruction file
• fast verification commands: tests, lint, typecheck
• docs and source-of-truth clarity
• dependency manifests and project structure
• CI/background automation
• MCP/CLI/API integration hints

Quickstart

python -m venv .venv
. .venv/bin/activate
pip install -e .
agent-readiness-audit /path/to/repo
agent-readiness-audit /path/to/repo --json

Example output

Agent readiness: 72/100 (B)

Strengths:
- Agent instructions found: AGENTS.md
- Test command likely available: pytest

Fix next:
- Add a concise AGENTS.md with setup, test, lint, and PR rules.
- Add CI so agents can verify changes without local guesswork.

Why this exists

Coding agents are only as good as the environment they can understand and verify. This CLI gives a repo owner a quick score and a concrete remediation plan.

Roadmap

• --fix-plan markdown export
• framework-specific checks for JS, Python, Rails, Salesforce
• GitHub Action that comments readiness score on PRs
• AGENTS.md generator from detected repo shape

Contributing

Open issues with repo types this should learn to score better.