git:20260323.d683468 to git:20260325.1cb08b1

---

name: readiness

description: >

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:

```bash

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.

---

## 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

- `$SETUP_SCRIPTS/hooks/pre-push` — what a good pre-push hook runs

- `$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:

```json

{

"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 (linting, formatting, secret scanning)

- [ ] Pre-push hook exists and runs tests

- [ ] Secret scanning configured — a script or tool that blocks commits containing API keys, tokens, or private keys (reference the patterns in `check-secrets.js`)

- [ ] File size limits enforced mechanically — commits blocked if source files exceed a line limit (reference `check-file-sizes.js`)

- [ ] **Smart test caching** — 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

| 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

Write the report with YAML frontmatter for machine-parseable delta tracking on future runs.

```yaml

---

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

| 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:

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