jrenaldi79/harness-engineering/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)