Harness Doctor

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

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: jubscodes
• Source: jubscodes/harness-doctor
• License: MIT

Install and usage instructions live in the source repository linked above.