readiness

Resource Resolution Preamble

Before any other step, resolve both the readiness skill's directory and the setup skill's resources:

SKILL_DIR=$(find ~/.claude/plugins -path "*/readiness/SKILL.md" -print -quit | xargs dirname)
SETUP_SKILL_DIR=$(find ~/.claude/plugins -path "*/setup/SKILL.md" -print -quit | xargs dirname)
SETUP_SCRIPTS=$SETUP_SKILL_DIR/scripts
SETUP_TEMPLATES=$SETUP_SKILL_DIR/templates
SETUP_REFERENCES=$SETUP_SKILL_DIR/references

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.

Phase 1: Detect Environment & Load Previous Report

Check the working directory for:

Manifest files: package.json, pyproject.toml, go.mod, Cargo.toml, CMakeLists.txt, Makefile

Git: .git/ exists

Existing agent config: CLAUDE.md, AGENTS.md, .claude/, .cursor/

Stack detection: Infer language, framework, and package manager from manifest contents.

Monorepo detection: Check for:

• package.json → workspaces field
• pnpm-workspace.yaml
• Cargo.toml → [workspace]
• Go workspace (go.work)
• Lerna (lerna.json), Nx (nx.json), Turborepo (turbo.json)

If monorepo: identify each app/package as a separate scoring unit.

Previous report: Check for readiness-report.md. If present, read the YAML frontmatter to enable delta comparison at the end.

Phase 2: Parallel Subagent Evaluation

Use subagents to keep the main context clean. Each subagent receives:

1. The specific reference file paths it needs (resolved from the preamble)
2. The project path to evaluate
3. The stack info detected in Phase 1
4. Its pillar criteria to evaluate (from Phase 3 below)
5. Whether this is a monorepo and if so, the list of app/package paths

Launch 3 subagents in parallel, each covering related pillars:

Subagent 1: Style, Testing & Code Quality

Reference files to read first:

• $SETUP_REFERENCES/enforcement-scripts.md — secret scanning patterns, file size rules
• $SETUP_SCRIPTS/lib/check-file-sizes.js — 300-line limit implementation
• $SETUP_SCRIPTS/lib/check-secrets.js — secret patterns to scan for
• $SETUP_SCRIPTS/lib/check-test-colocation.js — test colocation rules

Evaluates: Pillar 1 (Style & Validation), Pillar 2 (Testing), Pillar 6 (Code Quality)

Subagent 2: Hooks, Config, Environment & Workflow

Reference files to read first:

• $SETUP_SCRIPTS/hooks/pre-commit — what a good pre-commit hook runs (project hooks may live in .git/hooks/ or .husky/)
• $SETUP_SCRIPTS/hooks/pre-push — what a good pre-push hook runs (project hooks may live in .git/hooks/ or .husky/)
• $SETUP_TEMPLATES/settings.json — what a good settings file looks like
• $SETUP_TEMPLATES/rules/*.md — what path-scoped rules look like

Evaluates: Pillar 3 (Git Hooks & Enforcement), Pillar 5 (Agent Configuration), Pillar 7 (Dev Environment), Pillar 8 (Agentic Workflow)

Subagent 3: Documentation

Reference files to read first:

• $SETUP_TEMPLATES/project-claude.md — what a well-structured CLAUDE.md contains
• $SETUP_TEMPLATES/global-claude.md — what global guidance contains
• $SETUP_REFERENCES/claude-md-guide.md — quality criteria for CLAUDE.md content
• $SETUP_SCRIPTS/lib/validate-docs.js — drift detection logic
• $SETUP_SCRIPTS/lib/generate-docs.js — auto-generation patterns

Evaluates: Pillar 4 (Documentation)

Subagent Return Format

Each subagent returns a structured JSON result:

{
  "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.)
• Formatter configured (prettier, black, gofmt, clang-format, rustfmt, 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

Pillar 5: Agent Configuration (repo-scoped)

• .claude/settings.json (or equivalent agent config) exists
• Allow list covers standard dev commands (test, lint, build, git operations)
• Deny list blocks destructive operations (rm -rf /, git push --force, git reset --hard, etc.)
• 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:

• Install: /plugin install superpowers@claude-plugins-official
• Provides: brainstorming, planning, TDD enforcement, code review, debugging, testing, shipping phases
• GitHub: github.com/obra/superpowers

Phase 4: Score & Level

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

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.

---
generated: YYYY-MM-DD
level: 2
level_name: Basic
score: 12
total: 37
stack: node-typescript
monorepo: false
pillars:
  style-validation: { pass: 3, total: 4 }
  testing: { pass: 2, total: 5 }
  git-hooks: { pass: 0, total: 5 }
  documentation: { pass: 2, total: 9 }
  agent-config: { pass: 1, total: 5 }
  code-quality: { pass: 3, total: 3 }
  dev-environment: { pass: 1, total: 3 }
  agentic-workflow: { pass: 0, total: 2 }
---

# Harness Readiness Report

**Project:** <name> (<stack>)
**Level:** X / 5 (<level-name>)
**Score:** X / 36 criteria passing
**Delta:** +N since last report (was Level X)     ← only if previous report exists

## Pillar Scores

Style & Validation    ████░░ X/4
Testing               ███░░░ X/5
Git Hooks             ░░░░░░ X/5
Documentation         ██░░░░ X/9
Agent Configuration   █░░░░░ X/5
Code Quality          ██████ X/3
Dev Environment       ██░░░░ X/3
Agentic Workflow      ░░░░░░ X/2

## Monorepo Breakdown                    ← only if monorepo
| Package | Level | Score |
|---|---|---|
| packages/api | 3 | 25/37 |
| packages/web | 2 | 18/37 |

## Passing
- ✓ <criterion> (<evidence>)
- ...

## Failing
- ✗ <criterion> — <what's missing>
- ...

## Changes Since Last Report              ← only if previous report exists
- ↑ Now passing: <criteria that improved>
- ↓ Regressed: <criteria that went from pass to fail, or "none">

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:

1. What's working well — acknowledge strengths and explain why they matter
2. 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")
3. 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")
4. 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

Prioritization

Order recommendations by impact — fixes that unlock the next maturity level come first. Group them:

1. To reach Level N (next level) — the minimum fixes needed
2. Quick wins — easy fixes with high payoff (e.g., adding .env.example)
3. 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?"

If yes, apply them surgically:

• Edit existing files (add missing sections, don't overwrite existing content)
• Create new files only where nothing exists
• Use the setup skill's templates and scripts as references for what to create
• Never overwrite existing CLAUDE.md content, settings, or rules — augment them
• After applying, suggest re-running /readiness to verify improvement