harness-doctor
Skill20 starsChanged 3 months agoMITView on GitHub
Report-first, idempotent instance health check for a harness-managed project. Verifies python3/git presence, the hook set and its executability, .claude/settings.json wiring, .gitignore rules, .harness/ file validity, version drift against the current plugin, whether a passing/in-progress feature's test_file actually exists, and the mld non-injection guarantee. Offers a --fix upgrade mode, but never writes without explicit approval. Use when a smoke test fails unexpectedly, after a manual edit to .claude/ or .harness/, or when upgrading a project initialized under an older harness version.
5 other projects use a version of this.
Adopted by
Most recently taken up by
- Mark-Life/agent-skillstheir own version, first seen Nov 10, 2026
- PromptPartner/agentsmiththeir own version, first seen Oct 26, 2026
- thefiredev-cloud/meshvault-harnesstheir own version, first seen Oct 13, 2026
- MrBogomips/agentic-harnesstheir own version, first seen Jun 13, 2026
- jubscodes/harness-doctortheir own version, first seen Jun 2, 2026
Other versions5 projects use a version of this.
Word for word · 0
None found.
Edited · 0
None found.
Wrote their own version · 5
- PromptPartner/agentsmith★ 173same name
- jubscodes/harness-doctor★ 9same name
- Mark-Life/agent-skills★ 4same name
- MrBogomips/agentic-harness★ 1same name
- thefiredev-cloud/meshvault-harness★ 0same name
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
In this repository10 other files it gives its agents.
- AGENTS.mdAGENTS.md
- skills/AGENTS.mdAGENTS.md
- test/AGENTS.mdAGENTS.md
- CLAUDE.mdCLAUDE.md
- templates/CLAUDE.mdCLAUDE.md
- harness-continueSkill
- harness-improveSkill
- harness-initSkill
- harness-issue-debugSkill
- harness-issue-prepSkill
The file
We split this skill into the rules it gives an agent
5 rules. 0 are common, 1 is distinctive, and 4 are very specific to this project.
0
Common
Most of the 5 edited versions we read keep these.
1
Distinctive
This author's own choices. Worth a look.
4
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 65
.gitignore: does not exclude .claude/ without the !.claude/hooks/ and !.claude/settings.json exceptions, and does include … - Very specific: line 97
mld non-injection: if .harness/mld/ exists, the currently running plugin's hooks/session-start.sh must not reference it anywhere — that …
- Very specific: line 157
Before recommending a fix for .claude/settings.json or .gitignore findings, the doctor diffs the artifact against git history to note …
- Very specific: line 205
After manually editing anything under .claude/ or .harness/.
- Distinctive: line 206
Before or after upgrading a project that was initialized under an older harness version — this replaces the six manual steps INSTALL.md …
“Common” is measured: kept by at least 6 in 10 of the 5 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Harness Doctor
Structural, idempotent health check for a single harness project. It is report-first:
running it never changes anything on disk. It only writes when re-run with --fix,
and --fix applies exactly the six mechanical steps in INSTALL.md's "Upgrading an
existing harness project" section — nothing broader, and never without you having
first seen the report and asked for the fix.
Running it
python3 "${CLAUDE_PLUGIN_ROOT}/skills/harness-doctor/doctor.py" .A clean project prints a single line:
healthyA project with problems prints one FINDING:/fix: pair per problem and exits
non-zero:
FINDING: hook 'enforce-scope.sh' is not executable
fix: chmod +x .claude/hooks/enforce-scope.shA directory with no .harness/ at all is not a harness project — the doctor exits 2
and points to /harness-init instead of running any checks.
What it checks
- Dependencies:
python3andgitresolve onPATH— every hook depends onpython3, and nothing else in this project checks for it. - Hook set, each entry classified so a missing artifact is reported at the right
severity:
- Hard-required (missing or non-executable = error):
verify-task-quality.sh,enforce-scope.sh,verify-git-identity.sh,statusline.sh. - Optional-v5 (missing = "upgrade available", not an error):
harness_state.py(post-OVI-50) —verify-task-quality.shworks identically with or without it, so its absence is a suggestion, not a defect. - Stale Agent Teams artifacts (present = flagged for removal, not an error): a
leftover
check-remaining-tasks.shhook or.claude/teammate-scope.txtfile from a project initialized before the v6 Agent Teams retirement. Nothing invokes them anymore; the doctor flags them and--fixremoves them. - Not-yet-applicable: a commit-content gate (post-S4/OVI-64). The doctor only checks for this once the running plugin version actually ships a commit-gate template; until then, a missing per-project copy produces no finding of any kind.
- Hard-required (missing or non-executable = error):
.claude/settings.json: parses; carriesstatusLine, a non-emptypermissions.allow, and hook wiring forPreToolUse(enforce-scope.sh, verify-git-identity.sh, commit-gate.sh) andTaskCompleted(verify-task-quality.sh). The check is structural — it accepts either the"$CLAUDE_PROJECT_DIR"/...form or a simpler relative path, since both are functionally equivalent; it does not enforce one string form over the other. Stale blocks are flagged for removal: aPostCompacthook block (superseded by the plugin's SessionStartcompacthandling), aTeammateIdlehook block, and theCLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMSenv var (both dead since the v6 Agent Teams retirement)..gitignore: does not exclude.claude/without the!.claude/hooks/and!.claude/settings.jsonexceptions, and does include.harness/SESSION_INCOMPLETE..harness/state:harness.jsonandfeatures.jsonparse;features.jsonadditionally validates againstscripts/validate-features.pywhen the running plugin ships one;context_summary.mdcarries the section headings that always appear per its canonical template (rules/context-summary.md):## Active Context,## Cross-Cutting Concerns, at least one## Domain:section, and## Meta-Patterns. Repeatable dated## Meta-Session [DATE]entries and the optional## Closed Work Streamssection are not checked for bare presence — a project's first session legitimately has neither yet.- v5 upgrade staleness: a stale
PostCompactblock (see check 3) and missing v5 artifacts (statusline.sh, the settings wiring, the.gitignoreentry,harness_state.py) are the staleness surface for a per-project doctor. The global v3.6-era stale-file manifest inCHANGELOG.mdis explicitly scoped to~/.claude/only and does not apply here. - Feature test_file existence (F066): every feature with status
passingorin-progressand a non-nulltest_filemust have that path actually resolve in the working tree —features.jsonrecording a test file is a claim, not a fact, and nothing else in the harness validates it.pendingfeatures and features with notest_fileset are not checked (nothing to verify yet). - Plugin version drift (F068):
.harness/harness.json'splugin_versionfield is compared against the currently running plugin's own.claude-plugin/plugin.jsonversion.scripts/stamp.shwrites it at project creation (mechanical, not decision-shaped, so the stamp emits it directly rather than deferring it to a/harness-initfollow-up step likegit_identity/worker). A mismatch is reported (not an error) — hooks and skills may have legitimately changed between the two versions, and the reader decides whether that matters here. A project with noplugin_versionrecorded at all — one stamped before F068 shipped, most likely — gets an "upgrade available" finding, same class as the missing-harness_state.pycase (check 2): fixable, not a hard error, and--fixbootstraps it. This is the only path by which such a project can ever acquire the field, so unlike theworkerblock, absence here is not silently valid. - mld non-injection: if
.harness/mld/exists, the currently running plugin'shooks/session-start.shmust not reference it anywhere — that directory is telemetry, never something read into the model's context. This checks the plugin's own copy rather than anything under the project's.claude/hooks/, sincesession-start.shis invoked directly fromCLAUDE_PLUGIN_ROOTand is never copied per-project. If.harness/mld/doesn't exist, or the plugin root can't be determined, there is nothing to guard and no finding is produced. - focused_test skip contract (F108):
.harness/init.shis a per-project copy made at init time, so v5.5.0's focused_test exit-code contract (F106 — exit 3 reserved for a skip, a runner's own exit 3 remapped to 1, a missing test file skipped rather than faked green) never reaches a project that adoptedfocused_testbefore F106 shipped. Ifinit.shmentionsfocused_testoutside a comment (the same support-detection heuristicverify-task-quality.shuses) but is missing theskipped (exit 3)marker on a non-comment line — or still carries a pre-F106treating as passfake-green arm, which catches a partially hand-applied repair — the doctor reports it as upgrade-available. Therun_focusedexit-3 remap is not required: a stack with no per-file runner legitimately skips every invocation with the marker and defines norun_focusedat all (the trade-off — a runner-invokinginit.shmissing only the remap goes undetected — was accepted in OVI-147's field validation over false-positiving on every always-skip project). All of these are checked against non-comment lines only, so a comment quoting the markers (a TODO note, or the finding text pasted as a reminder) neither satisfies nor triggers the check. Aninit.shwith nofocused_testsupport at all, or none present, produces no finding — there is nothing to check yet. - Agent Teams migration (OVI-144): Agent Teams was retired in v6, after
v5.7.0 made worktree-isolated workflows the primary parallel path. A project
initialized under v5.x still
carries four artifacts of it, each reported as a migration step with a fixer:
a
TeammateIdleroute tocheck-remaining-tasks.sh, theCLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMSenv var, the orphaned.claude/hooks/check-remaining-tasks.shitself, and a leftover.claude/teammate-scope.txt. The last one is the only remnant that still has an effect — while it exists,enforce-scope.shgates edits against a scope no running teammate owns.
Workflow-support notices
Workflow mode needs the claude CLI at 2.1.154 or newer and the Workflow tool
enabled. Neither is a health defect: without them the single-session fallback applies
and the project is fine. So these are printed as notice lines beside the report and
never change its exit code:
WARN: claude CLI 2.1.100 < 2.1.154 -- workflow mode unavailable, single-session fallback applies
WARN: Workflow tool disabled in settings -- workflow mode unavailable
INFO: claude CLI version undetectable -- skipping workflow-support checkThe version probe is defensive in the same way harness-continue's worker-epoch check
is: an absent CLI, a non-zero exit, or output this can't parse all produce the INFO
line and skip the check rather than failing anything. "Disabled in settings" means the
settings explicitly turn the tool off — a permissions.deny entry naming Workflow,
or the org-level disableWorkflows switch. Anything subtler than those two literal
forms is left to the skill, which detects unavailability at runtime by the tool simply
being absent. Without them /harness-continue falls back to plain worktree-isolated
subagents, which is a working configuration, not a broken one.
Finding classification
Before recommending a fix for .claude/settings.json or .gitignore findings, the
doctor diffs the artifact against git history to note whether the problem is
committed drift or a local, uncommitted edit — the two call for different follow-up
(fix it here vs. fix it upstream). If the artifact is untracked, or the repository has
no commit history for it at all, the doctor defaults to "uncommitted local edit" and
says so explicitly. It never assumes committed drift without a diffable baseline.
--fix
python3 "${CLAUDE_PLUGIN_ROOT}/skills/harness-doctor/doctor.py" --fix .This applies only the mechanical actions from INSTALL.md's upgrade section: remove a
stale PostCompact block; copy statusline.sh from the plugin; add the missing
statusLine/permissions/hook wiring to .claude/settings.json; append
.harness/SESSION_INCOMPLETE to .gitignore; copy harness_state.py.template (and
re-copy verify-task-quality.sh, since older per-project copies may carry pre-OVI-50
inline logic); write or update .harness/harness.json's plugin_version to the
currently installed plugin's version (F068) — this is how a project that predates
F068, or has simply drifted, ever acquires or refreshes the field; nothing else does.
It also applies the Agent Teams migration (check 11): it deletes the orphaned
check-remaining-tasks.sh and the stale teammate-scope.txt, and strips both
settings.json remnants under a single .claude/settings.json.bak written immediately
before the edit (overwriting any older .bak, so the backup always describes the
state this run is about to change). Only the harness's own hook entry leaves the
TeammateIdle array — a user-authored hook sitting alongside it is preserved, and the
event key itself is removed only when nothing is left to run.
Anything it cannot mechanically resolve —
missing python3/git, a hard-required hook that was deleted outright, a JSON parse
error, a features.json validation failure, a context_summary.md missing a required
section, a stale focused_test skip contract in .harness/init.sh (check 10) — is
reported unchanged after the fix pass, because that is a judgment call, not a copy
step. init.sh in particular is never rewritten by --fix at all: it is the one
genuinely decision-shaped per-project file (it mixes in project-specific stack logic),
so its finding always carries a hand-apply repair instead of a fix.
Report-first is the whole point: the doctor never writes anything without explicit
approval. Run it plain first, read the findings, and only re-run with --fix once
you've decided you want those specific mechanical fixes applied. It is idempotent —
running it (with or without --fix) twice in a row produces the same result the
second time.
When to reach for it
harness-continue's Step 2.5 smoke test fails unexpectedly.- After manually editing anything under
.claude/or.harness/. - Before or after upgrading a project that was initialized under an older harness version — this replaces the six manual steps INSTALL.md used to require.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

