/agent-readiness
Assess how well this codebase supports autonomous AI coding agents.
Then fix the highest-impact gaps.
Target: $ARGUMENTS
Core Insight
The agent is not broken. The environment is. A codebase with fast feedback
loops and clear instructions makes any agent dramatically more effective.
A codebase with poor feedback loops defeats any agent you throw at it.
Workflow
Phase 1: Assess
Dispatch parallel subagents — one per pillar — to evaluate the codebase.
Each subagent runs the checks from references/pillar-checks.md for its
assigned pillar and returns a structured verdict.
Launch all pillar assessments simultaneously:
| Subagent |
Pillar |
What it checks |
| 1 |
Style & Validation |
Linters, formatters, type checkers, pre-commit hooks |
| 2 |
Build & CI |
Build commands, dependency pinning, CI config, feedback speed |
| 3 |
Testing |
Coverage, speed, local execution, unit/integration/E2E layers |
| 4 |
Documentation |
CLAUDE.md/AGENTS.md, README, setup guide, architecture docs, ADRs |
| 5 |
Dev Environment |
Reproducibility, env templates, devcontainers, isolated workspaces |
| 6 |
Code Quality |
Modularity, complexity, file organization, coupling, dead code |
| 7 |
Observability |
Structured logging, error handling, metrics, tracing |
| 8 |
Security & Governance |
Branch protection, CODEOWNERS, secret scanning, dependency audit |
Each subagent uses Explore agent type and reads references/pillar-checks.md
for its pillar's specific pass/fail criteria. Output format per subagent:
## [Pillar Name]
Score: X/Y checks passed
Maturity: L1-L5
### Passing
- [check]: [evidence]
### Failing
- [check]: [what's missing] → [recommended fix]
### Highest-Impact Fix
[The single change that would most improve this pillar]
Phase 2: Report
Synthesize subagent results into a single readiness report:
# Agent Readiness Report: [project-name]
## Overall: Level X — [Maturity Name] (XX%)
| Pillar | Score | Level | Top Fix |
|--------|-------|-------|---------|
| Style & Validation | 4/6 | L3 | Add pre-commit hooks |
| Testing | 2/7 | L1 | Add unit test runner |
| ... | ... | ... | ... |
## Maturity Levels
- L1 Functional: Code runs, but agents need hand-holding
- L2 Documented: Processes written down, some automation
- L3 Standardized: Enforced automation, agents handle routine work
- L4 Optimized: Fast feedback, data-driven improvement
- L5 Autonomous: Self-improving, sophisticated orchestration
## Top 5 Recommendations (by impact)
1. [highest impact fix across all pillars]
2. ...
## Detailed Findings
[per-pillar sections from subagents]
Maturity level is gated: must pass 80% of criteria at current level
and all previous levels before advancing. This prevents cherry-picking.
Phase 3: Clarify
Present the report and top 5 recommendations to the user. Ask:
- Which recommendations should we execute now?
- Any pillars to skip or deprioritize?
- Any constraints (don't change CI provider, keep current test framework, etc.)?
One question at a time. Don't dump all three at once.
Phase 4: Fix
For each approved recommendation, spawn a builder subagent (or use
worktrees for parallel fixes on disjoint files). Each fix follows the
project's existing patterns — don't introduce new tools the team hasn't
chosen.
Typical fix categories:
| Fix type |
Example |
Subagent approach |
| Config addition |
Add .editorconfig, pre-commit hooks |
Single builder, quick |
| Documentation |
Create/update CLAUDE.md, AGENTS.md |
Single builder |
| Test infrastructure |
Add test runner, coverage config |
Builder + TDD cycle |
| CI enhancement |
Add lint/typecheck/test to CI |
Single builder, verify locally |
| Architecture doc |
Create ADR, architecture overview |
Builder reads codebase first |
| Security hardening |
Add CODEOWNERS, branch protection |
Builder + gh CLI |
After fixes: re-run the failing checks to verify improvement. Report
the before/after delta.
Phase 5: Re-assess (optional)
If --fix was used, re-run the full assessment to show the improved score.
Present the before/after comparison.
Routing
| Argument |
Behavior |
| (none) |
Full assess → report → clarify → fix cycle |
--assess-only |
Assess and report only, no fixes |
--fix |
Skip clarification, fix all top 5 recommendations |
--pillar <name> |
Assess only the named pillar |
Pillar Check Reference
All specific checks are in references/pillar-checks.md. Each check is:
- Binary: pass or fail (no subjective scoring)
- Evidence-based: the subagent must cite the file/config/output that proves pass/fail
- Actionable: every failing check has a concrete remediation
See references/agent-readiness-principles.md for the deeper "why" behind
each pillar — useful when explaining recommendations to the user.
Gotchas
- Scoring without fixing is theater. The report is only useful if it
leads to action. Always push toward Phase 4.
- Don't introduce tools the team hasn't chosen. If they use Jest, don't
suggest Vitest. If they use ESLint, don't add Biome. Work within existing
choices.
- Pre-commit hooks are the highest-leverage single fix for most codebases.
They give agents instant feedback instead of waiting for CI.
- CLAUDE.md/AGENTS.md is the highest-leverage documentation fix. It's the
file agents actually read. A perfect README that agents ignore is worth less
than a scrappy CLAUDE.md they always load.
- Don't conflate coverage percentage with test quality. 80% coverage with
shallow tests is worse than 50% coverage with behavior-focused tests.
Check for assertion density, not just line coverage.
- Monorepos need per-app assessment. A monorepo score is the floor of
its worst app, not the average.
- Speed matters as much as existence. A test suite that takes 20 minutes
is nearly as bad as no tests for agent workflows. Measure execution time.
- The codebase is the product, not the agent. Every fix here improves
the experience for ALL agents and ALL developers, not just one tool.
1---2name: agent-readiness3description: Assess and improve codebase readiness for AI coding agents. Dispatches parallel subagents to evaluate style, testing, docs, architecture, CI, observability, security, and dev environment. Produces a scored report with prioritized remediation. Then executes the highest-impact fixes. Use when: "agent readiness", "is this codebase agent-ready", "readiness report", "make this codebase agent-friendly", "agent-ready assessment", "readiness audit", "prepare for agents". Trigger: /agent-readiness, /readiness.4---56# /agent-readiness78Assess how well this codebase supports autonomous AI coding agents.9Then fix the highest-impact gaps.1011**Target:** $ARGUMENTS1213## Core Insight1415The agent is not broken. The environment is. A codebase with fast feedback16loops and clear instructions makes any agent dramatically more effective.17A codebase with poor feedback loops defeats any agent you throw at it.1819## Workflow2021### Phase 1: Assess2223Dispatch **parallel subagents** — one per pillar — to evaluate the codebase.24Each subagent runs the checks from `references/pillar-checks.md` for its25assigned pillar and returns a structured verdict.2627Launch all pillar assessments simultaneously:2829| Subagent | Pillar | What it checks |30|----------|--------|---------------|31| 1 | Style & Validation | Linters, formatters, type checkers, pre-commit hooks |32| 2 | Build & CI | Build commands, dependency pinning, CI config, feedback speed |33| 3 | Testing | Coverage, speed, local execution, unit/integration/E2E layers |34| 4 | Documentation | CLAUDE.md/AGENTS.md, README, setup guide, architecture docs, ADRs |35| 5 | Dev Environment | Reproducibility, env templates, devcontainers, isolated workspaces |36| 6 | Code Quality | Modularity, complexity, file organization, coupling, dead code |37| 7 | Observability | Structured logging, error handling, metrics, tracing |38| 8 | Security & Governance | Branch protection, CODEOWNERS, secret scanning, dependency audit |3940Each subagent uses **Explore** agent type and reads `references/pillar-checks.md`41for its pillar's specific pass/fail criteria. Output format per subagent:4243```markdown44## [Pillar Name]45Score: X/Y checks passed46Maturity: L1-L54748### Passing49- [check]: [evidence]5051### Failing52- [check]: [what's missing] → [recommended fix]5354### Highest-Impact Fix55[The single change that would most improve this pillar]56```5758### Phase 2: Report5960Synthesize subagent results into a single readiness report:6162```markdown63# Agent Readiness Report: [project-name]6465## Overall: Level X — [Maturity Name] (XX%)6667| Pillar | Score | Level | Top Fix |68|--------|-------|-------|---------|69| Style & Validation | 4/6 | L3 | Add pre-commit hooks |70| Testing | 2/7 | L1 | Add unit test runner |71| ... | ... | ... | ... |7273## Maturity Levels74- L1 Functional: Code runs, but agents need hand-holding75- L2 Documented: Processes written down, some automation76- L3 Standardized: Enforced automation, agents handle routine work77- L4 Optimized: Fast feedback, data-driven improvement78- L5 Autonomous: Self-improving, sophisticated orchestration7980## Top 5 Recommendations (by impact)811. [highest impact fix across all pillars]822. ...8384## Detailed Findings85[per-pillar sections from subagents]86```8788**Maturity level is gated:** must pass 80% of criteria at current level89and all previous levels before advancing. This prevents cherry-picking.9091### Phase 3: Clarify9293Present the report and top 5 recommendations to the user. Ask:94951. Which recommendations should we execute now?962. Any pillars to skip or deprioritize?973. Any constraints (don't change CI provider, keep current test framework, etc.)?9899**One question at a time.** Don't dump all three at once.100101### Phase 4: Fix102103For each approved recommendation, spawn a **builder** subagent (or use104worktrees for parallel fixes on disjoint files). Each fix follows the105project's existing patterns — don't introduce new tools the team hasn't106chosen.107108Typical fix categories:109110| Fix type | Example | Subagent approach |111|----------|---------|-------------------|112| Config addition | Add `.editorconfig`, pre-commit hooks | Single builder, quick |113| Documentation | Create/update CLAUDE.md, AGENTS.md | Single builder |114| Test infrastructure | Add test runner, coverage config | Builder + TDD cycle |115| CI enhancement | Add lint/typecheck/test to CI | Single builder, verify locally |116| Architecture doc | Create ADR, architecture overview | Builder reads codebase first |117| Security hardening | Add CODEOWNERS, branch protection | Builder + gh CLI |118119After fixes: re-run the failing checks to verify improvement. Report120the before/after delta.121122### Phase 5: Re-assess (optional)123124If `--fix` was used, re-run the full assessment to show the improved score.125Present the before/after comparison.126127## Routing128129| Argument | Behavior |130|----------|----------|131| (none) | Full assess → report → clarify → fix cycle |132| `--assess-only` | Assess and report only, no fixes |133| `--fix` | Skip clarification, fix all top 5 recommendations |134| `--pillar <name>` | Assess only the named pillar |135136## Pillar Check Reference137138All specific checks are in `references/pillar-checks.md`. Each check is:139- **Binary**: pass or fail (no subjective scoring)140- **Evidence-based**: the subagent must cite the file/config/output that proves pass/fail141- **Actionable**: every failing check has a concrete remediation142143See `references/agent-readiness-principles.md` for the deeper "why" behind144each pillar — useful when explaining recommendations to the user.145146## Gotchas147148- **Scoring without fixing is theater.** The report is only useful if it149 leads to action. Always push toward Phase 4.150- **Don't introduce tools the team hasn't chosen.** If they use Jest, don't151 suggest Vitest. If they use ESLint, don't add Biome. Work within existing152 choices.153- **Pre-commit hooks are the highest-leverage single fix** for most codebases.154 They give agents instant feedback instead of waiting for CI.155- **CLAUDE.md/AGENTS.md is the highest-leverage documentation fix.** It's the156 file agents actually read. A perfect README that agents ignore is worth less157 than a scrappy CLAUDE.md they always load.158- **Don't conflate coverage percentage with test quality.** 80% coverage with159 shallow tests is worse than 50% coverage with behavior-focused tests.160 Check for assertion density, not just line coverage.161- **Monorepos need per-app assessment.** A monorepo score is the floor of162 its worst app, not the average.163- **Speed matters as much as existence.** A test suite that takes 20 minutes164 is nearly as bad as no tests for agent workflows. Measure execution time.165- **The codebase is the product, not the agent.** Every fix here improves166 the experience for ALL agents and ALL developers, not just one tool.
VRIL-LABS