Agent Readiness

Agent Readiness Assessment

Evaluate whether a repository gives an autonomous coding agent enough structure to take a task from spec to implementation to local verification without human hand-holding.

Automated analysis (default)

This skill ships with analysis scripts in the scripts/ directory. If Python 3 is available, use the combined runner for the full assessment including session-log pattern analysis:

# Full assessment (with session log analysis)
python3 scripts/run_readiness_check.py \
  --sessions-dir ~/.claude/projects/PROJECT-NAME \
  --repo .

# Static audit only (no session logs needed — fastest)
python3 scripts/run_readiness_check.py \
  --repo . \
  --skip-sessions \
  --output /tmp/agent-readiness-report.html

The output is an HTML report at /tmp/agent-readiness-report.html with maturity level, dimension scores, failure patterns, critical gaps, and a prioritized action plan.

Session log analysis

When session logs are available (.jsonl files from Claude Code, Codex, Cursor, etc. in ~/.claude/projects/), the analyzer detects:

• Classification distribution (research-only, validation-only, blocked, task-finisher, etc.)
• Top failed tools and commands
• Recurring failure patterns (browser auth, test failures, MCP schema issues, etc.)
• Post-edit validation rate
• Compact qualitative summaries of selected sessions

Pass --max-sessions N for a smaller sample while iterating. The analyzer caches parsed results by file hash so re-runs are near-instant.

Scoring checklist

When scoring manually (or to validate the automated output), use this rubric:

| Dim | Subject | Check | Impact if missing | |-----|---------|-------|-------------------| | 1 | Spec clarity | Structured templates with AC, edge cases, non-goals | No template → cap at 3 | | 2 | Agent instructions | Root AGENTS.md with stack, paths, commands | None → cap at 2 | | 2 | Agent instructions | High-risk invariants documented (migrations, secrets, etc.) | Missing → −1 | | 3 | Code clarity | Strict TypeScript or equivalent static types | None → cap at 2 | | 3 | Code clarity | Business logic separated from framework glue | Mixed → −1 | | 4 | Searchability | Feature flows discoverable by name/route | Hidden → −1 | | 4 | Searchability | Generated/vendored code clearly marked | Mixed → −0.5 | | 5 | Local env | Dependency lockfile committed | No lockfile → cap at 2 | | 5 | Local env | One-command setup script | Manual → −1 | | 6 | Tests | Unit + integration + E2E tests exist | None → cap at 1 | | 6 | Tests | Focused test commands per surface | Only blanket → −0.5 | | 7 | Static validation | Linter configured and documented | None → cap at 2 | | 7 | Static validation | Pre-commit or CI hook enforces lint | Missing → −0.5 | | 8 | Build feedback | Package-scoped build commands exist | Only root → −0.5 | | 8 | Build feedback | Dev mode with HMR documented | Missing → −1 | | 9 | Debuggability | Tests produce diagnostic artifacts (screenshots, traces) | None → −1 | | 9 | Debuggability | Structured error types | Silent errors → −1 | | 10 | Safety | Destructive migration workflow explicit | Implicit → cap at 3 | | 10 | Safety | Secret/env files in .gitignore | Not ignored → cap at 2 | | 11 | Browser automation | Auth bypass avoids login page | Manual login → cap at 2 | | 11 | Browser automation | Stable selectors (data-testid or a11y roles) | CSS classes → −1 |

Start each dimension at 3, adjust up/down per the checklist, max 5, min 1.

What it assesses

| # | Dimension | |---|-----------| | 1 | Code Comprehensibility — strong types, clear names, predictable structure | | 2 | Context & Documentation — AGENTS.md, README, ADRs, inline WHY | | 3 | Verifiability & Testing — test pyramid, type checker, linter, CI gates | | 4 | Dev Environment Reproducibility — one-command setup, locked deps, containerized services | | 5 | Style & Validation Tooling — strict linter, formatter, pre-commit hooks | | 6 | Build System — deterministic builds, fast feedback, HMR | | 7 | Observability & Debuggability — structured logs, health checks, actionable errors | | 8 | Security & Governance — branch protection, secret scanning, CODEOWNERS | | 9 | Task Discovery & Scoping — issue templates, acceptance criteria, definition of done | | 10 | Spec & Planning Quality — structured PRDs, API contracts, measurable success criteria | | 11 | CI/CD & Deployment Pipeline — automated gates, staging, rollback docs |

Maturity levels

| Level | Score | What agents can do | |-------|-------|-------------------| | Fragile | <2.0 | Explore only; heavy supervision needed | | Documented | 2.0–2.9 | Small changes with close review | | Standardized | 3.0–3.9 | Well-scoped tasks with local verification | | Optimized | 4.0–4.4 | Complex multi-file tasks with light review | | Autonomous | 4.5+ | Spec to tested implementation with strategic oversight |

Manual mode (no Python)

When Python 3 is not available, score each dimension 1–5 manually using the checklist above. Produce a report with: overall level, dimension table, critical gaps, action plan, and coverage table. See the automated report for output format reference.

Report delivery

Persist the report as an HTML document artifact when team artifact/document tools are available. Otherwise display the summary in chat and note the full HTML path at /tmp/agent-readiness-report.html.

Updates

This skill ships from the supatest-ai/supa-skills marketplace. The source of truth for the scripts is the supatest-ai/aiden repo under .agents/skills/agent-readiness/scripts/.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: supatest-ai
• Source: supatest-ai/supa-skills
• License: MIT

Install and usage instructions live in the source repository linked above.