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
$ARGUMENTS is 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
.git exists)
- 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.
1---2name: readiness3description: Evaluate repository readiness for AI agents. Analyzes 81 criteria across 8 pillars, assigns maturity level 1-5, generates visual report.4---56# Repository Readiness Assessment78Audit any repository to determine readiness for autonomous AI agent workflows. Produces a structured report scoring 81 distinct criteria.910**Target:** Use `$ARGUMENTS` if a GitHub URL is provided, otherwise analyze the current working directory.1112## Workflow13141. **Clone if needed** — When `$ARGUMENTS` is a GitHub URL, clone to `/tmp`152. **Discover context** — Detect languages, locate source/test/config directories163. **Identify apps** — Count deployable units (monorepo services, libraries, etc.)174. **Evaluate criteria** — Score all 81 criteria from [CRITERIA.md](CRITERIA.md)185. **Calculate level** — Determine maturity level 1-5 based on thresholds196. **Generate report** — Output visual ASCII report per [OUTPUT_FORMAT.md](OUTPUT_FORMAT.md)207. **Ask about HTML export** — ALWAYS ask the user if they want the D3.js dashboard after the ASCII report; do not proceed until they answer2122## Boundary Rules2324- Stay within git repository root (where `.git` exists)25- Skip `.git`, `node_modules`, `dist`, `build`, `__pycache__`26- Never access paths outside the repository2728## Language Detection2930| Language | Indicators |31|----------|-----------|32| JS/TS | `package.json`, `tsconfig.json`, `.ts`/`.tsx`/`.js`/`.jsx` |33| Python | `pyproject.toml`, `setup.py`, `requirements.txt`, `.py` |34| Rust | `Cargo.toml`, `.rs` |35| Go | `go.mod`, `.go` |36| Java | `pom.xml`, `build.gradle`, `.java` |37| Ruby | `Gemfile`, `.gemspec`, `.rb` |3839## Application Discovery4041An **application** is a standalone deployable unit:42- Independent build/deploy lifecycle43- Serves users or systems directly44- Could function as its own repository4546**Patterns:**47- Simple repos → 1 app (root)48- Monorepos → count each deployable service49- Libraries → 1 app (the library itself)5051## Scoring Rules5253**Repository Scope (43 criteria):**54- Evaluated once for entire repo55- numerator: 1 (pass), 0 (fail), null (skipped)56- denominator: always 15758**Application Scope (38 criteria):**59- Evaluated per-app60- numerator: count of passing apps61- denominator: total apps (N)6263## Maturity Levels6465| Level | Name | Requirement |66|-------|------|-------------|67| L1 | Functional | Baseline (all repos start here) |68| L2 | Documented | ≥80% of L1 criteria pass |69| L3 | Standardized | L2 + ≥80% of L2 criteria pass |70| L4 | Optimized | L3 + ≥80% of L3 criteria pass |71| L5 | Autonomous | L4 + ≥80% of L4 criteria pass |7273## Evaluation Principles7475- **Deterministic**: Same repo → same output76- **Existence-based**: Prefer file/config existence over semantic analysis77- **Conservative**: Ambiguous evidence = fail78- **Concise rationales**: Max 500 characters each7980## Additional Resources8182- **[CRITERIA.md](CRITERIA.md)** — Full list of 81 criteria with descriptions83- **[OUTPUT_FORMAT.md](OUTPUT_FORMAT.md)** — ASCII visual report format with ANSI colors84- **[templates/report.html](templates/report.html)** — D3.js HTML dashboard template85- **[examples/sample-output.md](examples/sample-output.md)** — Example report output8687## HTML Report Generation (MANDATORY)8889**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.**9091Ask user:92```93Would you like to generate an interactive HTML report with D3.js charts? [yes/no]94```9596Wait for user response. If yes, use template from [templates/report.html](templates/report.html) and save as `readiness-report.html`. After generation, always offer to open the report.
viktor-silakov