Repository Readiness Assessment
Audit any repository to determine readiness for autonomous AI agent workflows. Produces a structured report scoring 81 distinct criteria.
Target: Use $ARGUMENTS if a GitHub URL is provided, otherwise analyze the current working directory.
Workflow
- Clone if needed — When
$ARGUMENTSis a GitHub URL, clone to/tmp - Discover context — Detect languages, locate source/test/config directories
- Identify apps — Count deployable units (monorepo services, libraries, etc.)
- Evaluate criteria — Score all 81 criteria from CRITERIA.md
- Calculate level — Determine maturity level 1-5 based on thresholds
- Generate report — Output visual ASCII report per OUTPUT_FORMAT.md
- Ask about HTML export — ALWAYS ask the user if they want the D3.js dashboard after the ASCII report; do not proceed until they answer
Boundary Rules
- Stay within git repository root (where
.gitexists) - Skip
.git,node_modules,dist,build,__pycache__ - Never access paths outside the repository
Language Detection
| Language | Indicators |
|---|---|
| JS/TS | package.json, tsconfig.json, .ts/.tsx/.js/.jsx |
| Python | pyproject.toml, setup.py, requirements.txt, .py |
| Rust | Cargo.toml, .rs |
| Go | go.mod, .go |
| Java | pom.xml, build.gradle, .java |
| Ruby | Gemfile, .gemspec, .rb |
Application Discovery
An application is a standalone deployable unit:
- Independent build/deploy lifecycle
- Serves users or systems directly
- Could function as its own repository
Patterns:
- Simple repos → 1 app (root)
- Monorepos → count each deployable service
- Libraries → 1 app (the library itself)
Scoring Rules
Repository Scope (43 criteria):
- Evaluated once for entire repo
- numerator: 1 (pass), 0 (fail), null (skipped)
- denominator: always 1
Application Scope (38 criteria):
- Evaluated per-app
- numerator: count of passing apps
- denominator: total apps (N)
Maturity Levels
| Level | Name | Requirement |
|---|---|---|
| L1 | Functional | Baseline (all repos start here) |
| L2 | Documented | ≥80% of L1 criteria pass |
| L3 | Standardized | L2 + ≥80% of L2 criteria pass |
| L4 | Optimized | L3 + ≥80% of L3 criteria pass |
| L5 | Autonomous | L4 + ≥80% of L4 criteria pass |
Evaluation Principles
- Deterministic: Same repo → same output
- Existence-based: Prefer file/config existence over semantic analysis
- Conservative: Ambiguous evidence = fail
- Concise rationales: Max 500 characters each
Additional Resources
- CRITERIA.md — Full list of 81 criteria with descriptions
- OUTPUT_FORMAT.md — ASCII visual report format with ANSI colors
- templates/report.html — D3.js HTML dashboard template
- examples/sample-output.md — Example report output
HTML Report Generation (MANDATORY)
IMPORTANT: You MUST ask the user this question every single time after displaying the ASCII report. Do not skip this step and do not proceed until the user responds.
Ask user:
Would you like to generate an interactive HTML report with D3.js charts? [yes/no]
Wait for user response. If yes, use template from templates/report.html and save as readiness-report.html. After generation, always offer to open the report.