Use when the user wants to analyze, audit, or assess their codebase for AI agent readiness. Also use for "readiness report", "how ready is my project", "analyze my codebase", "audit my repo", "check my setup", or "what should I improve".
Installation
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
Use when the user wants to analyze, audit, or assess their codebase for AI agent readiness. Also use for "readiness report", "how ready is my project", "analyze my codebase", "audit my repo", "check my setup", or "what should I improve".
Resource Resolution Preamble
Before any other step, resolve both the readiness skill's directory and the setup skill's resources:
If SKILL_DIR is empty, halt and tell the user: "Could not locate the readiness plugin directory under ~/.claude/plugins. Verify the plugin is installed."
If SETUP_SKILL_DIR is empty, halt and tell the user: "Could not locate the setup plugin directory. The readiness skill requires the setup skill to be installed as part of the same plugin."
The setup skill's files are references only — read them to understand what good enforcement looks like, but never blindly run install scripts on an existing project.
{"pillars":{"pillar-name":{"criteria":[{"name":"Linter configured","pass":true,"evidence":"Found eslint.config.js with 12 rules"},{"name":"Formatter configured","pass":false,"evidence":"No prettier/black/gofmt config found"}]}},"insights":["Tests exist but 4 of 12 test files contain only TODO stubs — technically passing but not testing anything","CLAUDE.md has a Commands section but lists npm scripts that don't exist in package.json"]}
The insights array captures nuanced observations that go beyond pass/fail — things only an intelligent agent would notice.
Phase 3: Pillar Criteria Reference
This section defines what each subagent evaluates. Each criterion is binary pass/fail with evidence — cite the specific file, config, or absence found.
For monorepos: repo-scoped criteria are evaluated once across the whole repo. App-scoped criteria are evaluated per app/package.
Pillar 1: Style & Validation (repo-scoped)
Linter configured with a run command (eslint, ruff, golangci-lint, clang-tidy, clippy, etc.)
Lint-on-commit configured (lint-staged, pre-commit framework, or equivalent)
No default exports rule (JS/TS only — import/no-default-export or equivalent)
Pillar 2: Testing (app-scoped)
Test runner configured with a run command (jest, pytest, go test, cargo test, etc.)
Test files exist alongside or mirroring source files (colocation)
Coverage threshold configured
Tests actually pass (run them)
TDD enforcement — a dedicated TDD rule file exists (e.g., .claude/rules/tdd.md) that enforces test-first development as a process, not just test existence
Pillar 3: Git Hooks & Enforcement (repo-scoped)
Pre-commit hook exists and runs checks (check .git/hooks/pre-commit OR .husky/pre-commit — either location counts) covering linting, formatting, secret scanning
Pre-push hook exists and runs tests (check .git/hooks/pre-push OR .husky/pre-push — either location counts)
Secret scanning configured — a script or tool that blocks commits containing API keys, tokens, or private keys, wired into the pre-commit hook at .git/hooks/pre-commit or .husky/pre-commit (reference the patterns in check-secrets.js)
File size limits enforced mechanically — commits blocked if source files exceed a line limit, wired into the pre-commit hook at .git/hooks/pre-commit or .husky/pre-commit (reference check-file-sizes.js)
Smart test caching — pre-push hook (at .git/hooks/pre-push or .husky/pre-push) uses SHA-based caching to skip test runs when HEAD hasn't changed (.test-passed file or equivalent)
Pillar 4: Documentation (app-scoped)
Compare the project's CLAUDE.md (or AGENTS.md) against $SETUP_TEMPLATES/project-claude.md section-by-section. Use $SETUP_REFERENCES/claude-md-guide.md for quality criteria: dense, high-signal content where every line saves a future session from re-discovery.
CLAUDE.md or AGENTS.md exists
Has Commands section — lists build, test, lint, dev commands (compare against template)
Has Architecture section — describes directory structure, key modules, data flow (compare against template)
Has Critical Gotchas section — captures non-obvious discoveries that prevent re-debugging ("When you hit a non-obvious issue, add it here immediately")
Has Quality gates documented — file size limits, function length limits, complexity red flags
Has Code Review Checklist — or equivalent quality checks
Auto-generated sections — uses <!-- AUTO:name --> markers for sections that should stay in sync with code (or equivalent automation)
No drift — documented structure matches actual codebase (compare what CLAUDE.md says about directories/files vs. what actually exists on disk)
Content quality — sections contain actionable, specific information, not generic boilerplate. Apply claude-md-guide.md criteria: commands that save re-discovery, gotchas that prevent repeat debugging, config quirks that aren't obvious from code
Path-scoped rules exist (.claude/rules/ directory with rule files that use globs: frontmatter for file-pattern matching)
Enforcement hierarchy — mechanical enforcement (hooks) backs up advisory rules, which back up CLAUDE.md prose. Check that things stated in rules are also enforced by hooks where possible (e.g., "300-line limit" appears in both a rule file AND a hook script)
Pillar 6: Code Quality (app-scoped)
No source files over 300 lines (scan src/, lib/, or equivalent directories)
No obvious hardcoded secrets in source (apply patterns from check-secrets.js: sk-or-*, sk-ant-*, AKIA*, ghp_*, -----BEGIN.*PRIVATE KEY-----)
Consistent code style across the codebase (agent judgment — look for mixed conventions, inconsistent naming, etc.)
Pillar 7: Dev Environment (repo-scoped)
.env.example or equivalent environment template exists
Build/dev commands are documented and functional
Dependencies install cleanly (run the install command and check for errors)
Pillar 8: Agentic Workflow (repo-scoped)
Check whether a structured plan-before-build workflow system is installed.
Workflow system present — detect any of these (or similar agentic workflow tools) that include a planning phase before implementation:
BMAD — _bmad/ directory, _bmad-output/, or BMAD skills in .claude/skills/
Superpowers — skills with superpowers: prefix (brainstorm, write-plan, execute-plan)
gStack — .claude/skills/gstack/ directory or ~/.claude/skills/gstack/
Other — any SKILL.md files that provide planning, review, or structured development phases
Session-start validation — some mechanism exists to validate project state at the start of a work session. Examples: validate-docs.js --full instruction in CLAUDE.md, a session-start hook, a SessionStart hook in settings, or a skill that audits state before coding begins
If no agentic workflow system is detected, recommend Superpowers as the default:
After all 3 subagents return, merge their results into a unified scorecard in the main context.
Scoring rules:
Per-pillar score: passing criteria / total criteria
Level unlock: must pass 80% of criteria at that level + 100% of all previous levels
Levels are cumulative — no cherry-picking
Level
Name
Requirements
1
Bare
Has manifest + git. That's it.
2
Basic
Linter + formatter + test runner exist and work.
3
Enforced
Git hooks block bad commits. CLAUDE.md exists with essential sections. Agent settings configured.
4
Automated
Auto-generated docs, drift detection, path-scoped rules, smart test caching. Agentic workflow system installed.
5
Autonomous
Full harness coverage. TDD enforced. Docs in sync. Plan-before-build + session-start validation active. Agent can work for hours without going off the rails.
Monorepo scoring: Show per-app scores for app-scoped pillars (e.g., "Testing: 3/4 apps pass"). Overall level is gated by the weakest app — all apps must meet the level threshold.
Phase 5: Output — Two Parts
Part A: Structured Report (saved to readiness-report.md)
Write the report with YAML frontmatter for machine-parseable delta tracking on future runs.
Use the Unicode block characters for the progress bars:
█ for each passing unit (proportional to total)
░ for each failing unit
Scale each bar to 6 characters wide regardless of the pillar's total criteria count
Part B: Conversational Insights (in the chat, not saved to file)
After writing the structured report, provide prose analysis in the conversation:
What's working well — acknowledge strengths and explain why they matter
Highest-impact gaps — explain the cost of each gap (e.g., "Without a pre-commit hook, every bad commit gets caught in CI instead of locally — wasting 5-10 minutes per cycle")
Nuanced observations — things the checklist can't capture, drawn from the subagents' insights arrays (e.g., "Your tests exist but 4 of 12 are stubs with TODO comments — technically passing but not actually testing anything")
Stack-specific notes — any observations specific to the detected language/framework
Phase 6: Remediation Recommendations
Provide surgical, context-aware recommendations — not "run /setup" but specific actions that respect what already exists.
Surgical vs. Blunt Recommendations
Gap
Blunt (wrong)
Surgical (right)
No Commands section in CLAUDE.md
"Run /setup to generate CLAUDE.md"
"Add a Commands section to your existing CLAUDE.md listing your build/test/lint commands. See $SETUP_TEMPLATES/project-claude.md for the pattern."
No pre-commit hook
"Install husky"
"Your project uses lint-staged but has no hook trigger. Add a pre-commit hook that runs lint-staged + secret scanning. See $SETUP_SCRIPTS/hooks/pre-commit for a reference implementation."
No settings.json
"Run /setup"
"Create .claude/settings.json based on your existing npm scripts. Allow: test, lint, build. Deny: force push, rm -rf. See $SETUP_TEMPLATES/settings.json for the template."
CLAUDE.md exists but no Architecture section
"Regenerate CLAUDE.md"
"Add an Architecture section to your existing CLAUDE.md describing your current directory layout and key modules."
No agentic workflow
"Figure it out"
"Install Superpowers for structured development phases: /plugin install superpowers@claude-plugins-official"
Prioritization
Order recommendations by impact — fixes that unlock the next maturity level come first. Group them:
To reach Level N (next level) — the minimum fixes needed
Quick wins — easy fixes with high payoff (e.g., adding .env.example)
Deeper improvements — things that require more effort but compound over time
Offer to Apply
After presenting recommendations, ask: "Want me to apply any of these fixes?"
