By name: readiness-report
description: Evaluate how well a codebase supports autonomous AI development. Analyzes repositories across eight technical pillars (Style & Validation, Build System, Testing, Documentation, Dev Environment, Debugging & Observability, Security, Task Discovery) and five maturity levels. Use when users request /readiness-report or want to assess agent readiness, codebase maturity, or identify gaps preventing effective AI-assisted development.
license: GPL-3.0-or-later
metadata:
author: anntnzrb
allowed-tools: ""
Agent Readiness Report
Evaluate how well a repository supports autonomous AI development by analyzing it across eight technical pillars and five maturity levels.
Overview
Agent Readiness measures how prepared a codebase is for AI-assisted development. Poor feedback loops, missing documentation, or lack of tooling cause agents to waste cycles on preventable errors. This skill identifies those gaps and prioritizes fixes.
Quick Start
Run /readiness-report to evaluate the current repository. The analysis:
- Scans repository structure, CI configs, and tooling
- Evaluates 81 criteria across 9 technical pillars
- Determines maturity level (L1-L5) based on 80% threshold per level
- Provides prioritized recommendations
Entry point
Cross-platform:
uv run --script <skill-dir>/scripts/cli.py ...
Set <skill-dir> to this skill directory. Do not rely on shell sourcing, executable bits, or shebang dispatch.
Workflow
Step 1: Run Repository Analysis
Execute the analysis script to gather signals from the repository:
uv run --script <skill-dir>/scripts/cli.py analyze --repo-path .
Or analyze and print a report in one pass:
uv run --script <skill-dir>/scripts/cli.py run --repo-path . --format markdown
This script checks for:
- Configuration files (.eslintrc, pyproject.toml, etc.)
- CI/CD workflows (.github/workflows/, .gitlab-ci.yml)
- Documentation (README, AGENTS.md, CONTRIBUTING.md)
- Test infrastructure (test directories, coverage configs)
- Security configurations (CODEOWNERS, .gitignore, secrets management)
Step 2: Generate Report
After analysis, generate the formatted report:
uv run --script <skill-dir>/scripts/cli.py report --analysis-file <temp-dir>/readiness_analysis.json
Step 3: Present Results
The report includes:
- Overall Score: Pass rate percentage and maturity level achieved
- Level Progress: Bar showing L1-L5 completion percentages
- Strengths: Top-performing pillars with passing criteria
- Opportunities: Prioritized list of improvements to implement
- Detailed Criteria: Full breakdown by pillar showing each criterion status
Nine Technical Pillars
Each pillar addresses specific failure modes in AI-assisted development:
| Pillar | Purpose | Key Signals |
|---|---|---|
| Style & Validation | Catch bugs instantly | Linters, formatters, type checkers |
| Build System | Fast, reliable builds | Build docs, CI speed, automation |
| Testing | Verify correctness | Unit/integration tests, coverage |
| Documentation | Guide the agent | AGENTS.md, README, architecture docs |
| Dev Environment | Reproducible setup | Devcontainer, env templates |
| Debugging & Observability | Diagnose issues | Logging, tracing, metrics |
| Security | Protect the codebase | CODEOWNERS, secrets management |
| Task Discovery | Find work to do | Issue templates, PR templates |
| Product & Analytics | Error-to-insight loop | Error tracking, product analytics |
See references/criteria.md for the complete list of 81 criteria per pillar.
Five Maturity Levels
| Level | Name | Description | Agent Capability |
|---|---|---|---|
| L1 | Initial | Basic version control | Manual assistance only |
| L2 | Managed | Basic CI/CD and testing | Simple, well-defined tasks |
| L3 | Standardized | Production-ready for agents | Routine maintenance |
| L4 | Measured | Comprehensive automation | Complex features |
| L5 | Optimized | Full autonomous capability | End-to-end development |
Level Progression: To unlock a level, pass ≥80% of criteria at that level AND all previous levels.
See references/maturity-levels.md for detailed level requirements.
Interpreting Results
Pass vs Fail vs Skip
- ✓ Pass: Criterion met (contributes to score)
- ✗ Fail: Criterion not met (opportunity for improvement)
- — Skip: Not applicable to this repository type (excluded from score)
Priority Order
Fix gaps in this order:
- L1-L2 failures: Foundation issues blocking basic agent operation
- L3 failures: Production readiness gaps
- High-impact L4+ failures: Optimization opportunities
Common Quick Wins
- Add AGENTS.md: Document commands, architecture, and workflows for AI agents
- Configure pre-commit hooks: Catch style issues before CI
- Add PR/issue templates: Structure task discovery
- Document single-command setup: Enable fast environment provisioning
Resources
scripts/cli.py- Public dispatcher (analyze,report,run)scripts/analyze_repo.py- Internal repository analysis scriptscripts/generate_report.py- Internal report generation and formattingreferences/criteria.md- Complete criteria definitions by pillarreferences/maturity-levels.md- Detailed level requirements
Automated Remediation
After reviewing the report, common fixes can be automated:
- Generate AGENTS.md from repository structure
- Add missing issue/PR templates
- Configure standard linters and formatters
- Set up pre-commit hooks
Ask to "fix readiness gaps" to begin automated remediation of failing criteria.