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

1. Clone if needed — When $ARGUMENTS is a GitHub URL, clone to /tmp
2. Discover context — Detect languages, locate source/test/config directories
3. Identify apps — Count deployable units (monorepo services, libraries, etc.)
4. Evaluate criteria — Score all 81 criteria from CRITERIA.md
5. Calculate level — Determine maturity level 1-5 based on thresholds
6. Generate report — Output visual ASCII report per OUTPUT_FORMAT.md
7. 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

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

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.