readiness

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

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

```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 (check `.git/hooks/pre-commit` OR `.husky/pre-commit` — either location counts) covering linting, formatting, secret scanning
- [ ]