anntnzrb Agent Readiness Report
Evaluate how well a repository supports autonomous AI development by analyzing it across eight technical pillars and five maturity levels.
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
Required follow-up reads
| Need | Read | When |
|---|---|---|
| Complete criterion definitions | references/criteria.md |
Explaining a criterion or auditing scorer behavior |
| Level thresholds and interpretation | references/maturity-levels.md |
Explaining maturity or prioritizing gaps |
| Analyzer implementation | scripts/analyze_repo.py |
Debugging signal detection |
| Report formatting | scripts/generate_report.py |
Debugging rendered output |
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.