| name | harness-doctor |
| description | Use when evaluating a repository's Claude Code harness setup — CLAUDE.md, skills, guides/sensors, hooks, memory — to surface good practices, gaps, and prioritized fixes. Triggers when the user asks to audit their agent setup, "is my harness any good", "review my CLAUDE.md / skills", grade a repo's Claude Code config, or onboard a project to agents well. |
| license | MIT |
| metadata | {"author":"jubscodes","version":"1.0"} |
Harness Doctor
Audit a repository's agent harness — everything wrapped around the model (the contract, skills, guides, sensors, hooks, memory) — and report what's good, what's missing, and what to fix first.
Framing: Agent = Model + Harness. Guides steer before the agent acts (feedforward); sensors check after (feedback). You need both. (Böckeler, Harness Engineering, martinfowler.com.)
Process
1. Scan (read, don't guess)
Run scripts/scan.sh [repo-dir] first — a fast, deterministic inventory (contract · skills · sensors · hooks · memory). Then read what it can't judge — skill descriptions, CLAUDE.md content. Look for:
CLAUDE.md (also AGENTS.md, .cursor/rules) — the always-on contract.claude/skills/*/SKILL.md — expertise.claude/commands/, .claude/agents/, .claude/hooks/, .claude/settings*.json, .mcp.json, rules/- Sensors: test setup, linter/formatter config, type-checker, CI (
.github/workflows/); is it computational (cheap/deterministic) or only inferential?
- Memory & state:
MEMORY.md, decision/progress logs, ADRs, a STATE.md/plan for long tasks
- Improvement loop: skill evals, a learnings log, drift scans — does the harness get better when it fails?
For a large repo, spawn an Explore subagent to map it so you don't bloat your context.
2. Evaluate
Read references/checklist.md (the criteria) and references/principles.md (the why + sources) now, and score each dimension against them. Mark every finding ✓ good · ⚠ weak · ✗ missing, and tag each fix [cheap] (deterministic, do first) or [deeper].
3. Report (scannable, in the terminal)
- Scorecard — one line per dimension: Contract · Skills · Guides · Sensors · Enforcement · Memory & State · Improvement loop
- ✓ Strengths — what's already good (keep doing)
- ⚠ / ✗ Gaps — each with a one-line concrete fix, ordered cheapest-deterministic first ("start cheap")
- Top 3 next moves
4. Offer to fix
After the report, ask which fixes to apply — don't edit unprompted. When approved, make the change and show a diff. Typical fixes: scaffold a CLAUDE.md contract, rewrite a skill description to WHEN-not-WHAT, split a bloated CLAUDE.md into .claude/rules/, add a pre-commit secret/lint hook, wire a test/lint command in.
Never weaken a check to make something pass.
Principles to judge against
- Guides + sensors, before + after — flag feedforward-only (rules, never verified) and feedback-only (checks, no guidance).
- A rule is only hard if a hook blocks it — prose is a request, a
PreToolUse hook is enforcement.
- Keep CLAUDE.md lean (< ~200 lines) — how-to belongs in skills/rules, not the contract.
- Right tool for the job — flag misplacements (the skill/command/subagent/hook/MCP map is in
references/checklist.md).
- Start cheap — prefer fast deterministic controls (lint, tests, type-check) before slow/inferential ones (LLM-as-judge).
