[Docs] Question: doctor /skill:doctor SKILL.md sections 6/7/10 hard-code Claude Code plugin layout — false-FAIL on Pi (and other non-StopHook harnesses)

[nhvvin]

Documentation Question

The /skill:doctor SKILL.md (and its sibling commands/doctor.md) is shipped byte-for-byte identical across every harness plugin (babysitter-codex, babysitter-cursor, babysitter-github, babysitter-omp, babysitter-opencode, babysitter-pi), but its hook-related sections are written exclusively for the Claude Code plugin layout. On the Pi harness (npm:@a5c-ai/babysitter-pi) those code paths can never succeed, so the doctor reports false FAILs on a perfectly healthy run.

Specifically:

• Section 6 — Session State tells the agent to glob plugins/babysitter/skills/babysit/state/*.md. On Pi the package is installed under ~/.pi/agent/npm/node_modules/@a5c-ai/babysitter-pi/skills/babysit/state/*.md; that glob is wrong by design.
• Section 7 — Log Analysis reads $CLAUDE_PLUGIN_ROOT/.a5c/logs/babysitter-stop-hook.log, …/babysitter-session-start-hook.log, etc. CLAUDE_PLUGIN_ROOT does not exist in a Pi session, so every one of those reads degrades to "Not found".
• Section 10 — Hook Execution Health is the most striking: it walks plugins/babysitter/hooks/hooks.json, hooks/babysitter-stop-hook.sh, hooks/babysitter-session-start-hook.sh, and finally ~/.claude/settings.json / ~/.claude/plugins/installed_plugins.json. Pi has none of those files; the SDK's own packages/sdk/src/harness/pi.ts declares supportsHookType() returns false and emits the message "Pi does not use babysitter hook:run for ... Use the Pi package skills and extension bridge instead." — but the doctor SKILL is unaware of this and marks Section 10 as FAIL.
• The /babysitter:contrib postscript at the bottom of commands/doctor.md even instructs users to call Claude Code's /debug slash command, which doesn't exist in Pi.

Net effect on Pi: a healthy run shows up as CRITICAL in the final report on the strength of false negatives in 6/7/10, even though sections 1–5, 8, 9 pass cleanly.

The SDK already encodes the right answer; the SKILL just doesn't ask. What's the canonical fix the project wants here?

Topic Area

plugins/<harness>/skills/doctor/SKILL.md and plugins/<harness>/commands/doctor.md — harness-aware skill content. Expected doc type: harness-aware skill source / per-harness branching guidance (or, if the project prefers, a single Pi-specific equivalent for sections 6/7/10).

What I've Searched

• CLAUDE.md, AGENTS.md, CONTRIBUTING.md, CHANGELOG.md, README.md (root)
• All six plugins/*/skills/doctor/SKILL.md — all md5 ccc1a16f8f267a08cc4b429d6340e08f, 427 lines, byte-for-byte identical.
• All six plugins/*/commands/doctor.md — same Claude-Code-shaped content.
• plugins/babysitter-pi/extensions/index.ts — confirms Pi exposes slash commands via pi.registerCommand (babysit, babysitter, assimilate, call, cleanup, contrib, doctor, forever, help, observe, plan, plugins, project-install, resume, retrospect, user-install, yolo, plus babysitter:<name> aliases). No Stop / SessionStart hook scripts are registered.
• packages/sdk/src/harness/{discovery,pi,types,registry}.ts and the harness adapter siblings — see "Existing machinery" below.
• docs/assimilation/harness/{claude-code-integration,generic-harness-guide}.md.
• library/specializations/meta/harnesses/pi/.
• GitHub issue search across this repo on the following queries (all combined open + closed): doctor SKILL.md harness, doctor Pi flavor, doctor stop hook claude, skill harness aware, doctor hook execution health, doctor claude plugin layout, doctor false fail pi. No existing issue covers this.

The closest open issue, #876, is a different bug (Pi resource-path crash inside pi-coding-agent's package-manager). The cluster of closed Claude-Code stop-hook bugs (#69, #107, #130, #133, #138, #139, #160, #166, #170) all assume the same Claude-Code layout that doctor SKILL.md hard-codes — they reinforce the question rather than answer it.

Expected Documentation

I think this is really a code question masquerading as a docs question — the doctor SKILL.md is the documentation-as-skill. So the resolution is most likely either:

Option (a) — Recommended: harness-aware doctor that consults KNOWN_HARNESSES / capability bits. The SDK already exposes everything you need:

• KNOWN_HARNESSES in packages/sdk/src/harness/discovery.ts lists every harness with its capability set:
  • claude-code → [SessionBinding, StopHook, Mcp, HeadlessPrompt]
  • pi → [Programmatic, SessionBinding, HeadlessPrompt] (no StopHook)
  • cursor → […, StopHook, …], opencode → [HeadlessPrompt], etc.
• detectCallerHarness() in the same file resolves the active harness from env vars (CLAUDE_ENV_FILE → claude-code, PI_SESSION_ID/PI_PLUGIN_ROOT → pi, …).
• pi.ts#supportsHookType() returns false; getUnsupportedHookMessage() produces a ready-made "use the Pi extension bridge instead" string.

The doctor SKILL could open with a "Phase 0: Detect harness" step that calls detectCallerHarness() and asks the SDK whether the active adapter has Cap.StopHook. If it doesn't, sections 6/7/10 emit a single N/A — harness <name> does not register stop / session-start hooks (KNOWN_HARNESSES capability set: …) line and skip cleanly. The verdict logic should treat N/A as neither pass nor fail.

Option (b) — replacement Pi-specific 6/7/10. If the project prefers explicit per-harness skill bodies, the Pi versions of those sections should validate:

• 6 (Session State): glob ~/.pi/agent/npm/node_modules/@a5c-ai/babysitter-pi/skills/babysit/state/*.md plus .a5c/state/* (already covered).
• 7 (Log Analysis): drop $CLAUDE_PLUGIN_ROOT/.a5c/logs/* (no analogue on Pi) and either (i) skip log analysis entirely or (ii) point at whatever the Pi extension chooses to log.
• 10 (Hook Execution Health): replace with "Pi extension registration health" — verify ~/.pi/agent/settings.json lists npm:@a5c-ai/babysitter-pi, that ~/.pi/agent/npm/node_modules/@a5c-ai/babysitter-pi/extensions/index.ts resolves, and that pi.registerCommand registers the expected slash commands.

I'd recommend (a) because it scales to all harnesses (cursor and codex have similar mismatches in opposite directions) and reuses authoritative SDK detection rather than duplicating the truth across six SKILL.md copies.

Related Documentation

• packages/sdk/src/harness/discovery.ts — KNOWN_HARNESSES, detectCallerHarness(), discoverHarnesses().
• packages/sdk/src/harness/types.ts — HarnessCapability enum (Programmatic, SessionBinding, StopHook, Mcp, HeadlessPrompt).
• packages/sdk/src/harness/pi.ts — createPiAdapter, supportsHookType(), getUnsupportedHookMessage().
• docs/assimilation/harness/claude-code-integration.md and docs/assimilation/harness/generic-harness-guide.md — per-harness integration docs (do not cover doctor portability).
• CHANGELOG.md — entries "Doctor command enhanced with hook execution health diagnostics" and "Auto-detection of harness environment when binding sessions" both shipped, but the harness-detection work didn't propagate into the doctor SKILL.

Reproduction

Reproduced against a fresh clean run on the Pi harness:

• Run: 01KT5T02R3G3ZTS7X2THYWE8FP (process cradle/project-install, completed HEALTHY at the journal level).
• Env: babysitter-sdk 0.0.187, Pi extension npm:@a5c-ai/babysitter-pi registered via ~/.pi/agent/settings.json.
• Steps:
  1. From a Pi session in the repo root: /skill:doctor (or /babysitter:doctor).
  2. Sections 1–5, 8, 9: PASS. Section 6: WARN (no Claude-shaped session state files). Sections 7 + 10: FAIL (CLAUDE_PLUGIN_ROOT empty; no plugins/babysitter/hooks/*.sh; no ~/.claude/...).
  3. Final verdict: CRITICAL even though every functionally meaningful check passed.

The byte-identical SKILL.md is verifiable with:

md5sum plugins/*/skills/doctor/SKILL.md
# all six → ccc1a16f8f267a08cc4b429d6340e08f

Happy to send a PR for option (a) if the maintainers agree on the direction.

[a5c-ai]

Triage: confirmed valid, root cause identified

I confirmed this is a real issue, not a duplicate. I found no associated open PR for #877 and issue search for the same doctor/Pi/harness-aware failure only returns this issue.

What is still broken

The legacy doctor skill is exactly as reported:

• plugins/babysitter/skills/doctor/SKILL.md section 6 searches the legacy Claude-shaped plugins/babysitter/skills/babysit/state/*.md path.
• Section 7 reads $CLAUDE_PLUGIN_ROOT/.a5c/logs/* hook logs.
• Section 10 requires Claude-style hook registration and scripts (plugins/babysitter/hooks/hooks.json, hooks/babysitter-stop-hook.sh, hooks/babysitter-session-start-hook.sh) and marks missing registration/scripts as FAIL.
• The final report maps any FAIL to CRITICAL, so an unsupported hook surface becomes a critical runtime diagnosis instead of N/A.

The current generated/unified doctor source has partially improved, but does not fully fix this:

• plugins/babysitter-unified/commands/doctor.md and the generated SDK template at packages/sdk/src/prompts/templates/commands/doctor.md now use .a5c/state/* for section 6 and ${BABYSITTER_LOG_DIR:-$HOME/.a5c/logs} for section 7.
• However, section 10 still says to check CLAUDE_PLUGIN_ROOT, find a babysitter hooks.json, require Stop/SessionStart entries, require babysitter-stop-hook.sh and babysitter-session-start-hook.sh, and diagnose missing hooks through Claude settings (~/.claude/settings.json, ~/.claude/plugins/installed_plugins.json). That remains wrong for Pi and other non-StopHook harnesses.
• The later session-provenance sections in the unified doctor also still use Claude-specific wording for otherwise generic session checks, so this should be cleaned up at the same time.

Why Pi is a false failure

The SDK already knows Pi is not a stop-hook harness:

• packages/sdk/src/harness/adapters/pi.ts declares Pi capabilities as Programmatic, SessionBinding, and HeadlessPrompt; it does not include StopHook. It also sets hookDriven: false and noHookSupport: true.
• BaseHarnessAdapter.supportsHookType() returns false when noHookSupport is set, and babysitter hook:run reports UNSUPPORTED_HOOK_TYPE before dispatching unsupported hook types.
• The Pi plugin surface in plugins/babysitter-unified/per-harness/pi/extensions-index.ts exposes commands through pi.registerCommand(...) and a best-effort proxied session_start; it does not install a Claude-style hooks.json stop-hook surface.

So section 10 is currently asserting a requirement that the authoritative harness adapter explicitly says Pi does not have. On Pi, the correct result for stop-hook execution health is not FAIL; it is N/A or a Pi-specific extension/command registration check.

Recommended fix

I recommend fixing the canonical source first, then regenerating all derived copies:

1. Update plugins/babysitter-unified/commands/doctor.md as the source of truth, then sync packages/sdk/src/prompts/templates/commands/doctor.md and any generated per-harness command/skill copies.
2. Add an initial harness detection step in doctor. The detection should use SDK-owned truth, not duplicated prose. Acceptable sources include detectCallerHarness() / detectAdapter() / getCapabilities() or a CLI wrapper that exposes the same adapter capability set.
3. Gate hook-specific checks on HarnessCapability.StopHook (or adapter supportsHookType("stop")). If the active harness lacks stop-hook support, section 10 should be N/A with an explicit note like: N/A - harness pi does not advertise StopHook; Pi uses command-backed skills and extension events instead.
4. Treat N/A as neutral in the final verdict. It must not count as WARN or FAIL.
5. For Pi, either stop at N/A for section 10 or replace it with a Pi-specific extension health check: verify PI_PLUGIN_ROOT when available, the package command surface, and the expected pi.registerCommand aliases (doctor, babysitter:doctor, etc.).
6. Replace Claude-specific wording in generic session sections with harness-neutral language, with Claude-specific remediation shown only when the detected harness is claude-code.
7. Add a regression test or static verification that the doctor command does not require Claude hook files when the detected harness lacks StopHook.

Suggested classification

• Type: bug + documentation (the skill/command docs are executable operational guidance)
• Components: plugins, plugin-pi, sdk
• Priority: priority:medium because it produces a false CRITICAL diagnosis for healthy Pi runs, but does not break orchestration itself
• Effort: effort:medium because the fix should touch canonical doctor prompt content, generated copies, and tests/sync verification
• Ready for dev: yes

[a5c-ai]

Triage outcome

This is a valid bug in the doctor skill/command content, not just a docs question. The canonical fix should be harness-aware doctor behavior driven by the existing SDK/catalog harness capability source of truth.

Root cause

The doctor instructions still assume a Claude Code-style hook/plugin layout in hook-related diagnostics. In current staging:

• plugins/babysitter/skills/doctor/SKILL.md section 7 still reads $CLAUDE_PLUGIN_ROOT/.a5c/logs/..., and section 10 checks CLAUDE_PLUGIN_ROOT, plugins/babysitter/hooks/hooks.json, hooks/babysitter-stop-hook.sh, hooks/babysitter-session-start-hook.sh, and ~/.claude/... enablement files.
• plugins/babysitter-unified/commands/doctor.md and the generated template packages/sdk/src/prompts/templates/commands/doctor.md have already improved section 6 to .a5c/state and section 7 to ${BABYSITTER_LOG_DIR:-$HOME/.a5c/logs}, but section 10 still assumes Claude-style hook registration/scripts and ~/.claude settings.
• packages/sdk/src/harness/adapters/pi.ts derives the Pi adapter with Programmatic, SessionBinding, and HeadlessPrompt capabilities, hookDriven: false, and noHookSupport: true.
• packages/sdk/src/harness/BaseAdapter.ts already makes supportsHookType() return false when noHookSupport is set.
• plugins/babysitter-unified/per-harness/pi/extensions-index.ts registers /doctor and /babysitter:doctor through pi.registerCommand, sets PI_PLUGIN_ROOT / PI_SESSION_ID, and does not use the Claude hooks.json / ~/.claude enablement model.

So on Pi, the doctor is treating an unsupported hook surface as a required failing check. That turns a healthy run into a false FAIL/CRITICAL instead of reporting hook execution as N/A for this harness.

One staging nuance: I only see two local doctor sources in this checkout (plugins/babysitter/skills/doctor/SKILL.md and plugins/babysitter-unified/commands/doctor.md), not six checked-in harness-specific copies. The reported six-copy behavior likely comes from generated/published harness packages or an older tree. The underlying bug still exists in the shared source/template path.

Recommended fix

Implement a Phase 0 harness-detection step in the shared doctor source/template, then branch the hook-related diagnostics from the detected capabilities:

1. Detect the active harness using the SDK/catalog source of truth (detectCallerHarness() / registry-derived KNOWN_HARNESSES / adapter capabilities, whichever is the intended internal API for command templates).
2. If the active harness does not support StopHook, section 10 should emit N/A - harness <name> does not support StopHook with the detected capability set, skip Claude hook registration/script/~/.claude checks, and ensure N/A does not count as FAIL in the final verdict.
3. Keep the current hook registration/script/log checks for StopHook-capable harnesses.
4. Make section 7 consistently use ${BABYSITTER_LOG_DIR:-$HOME/.a5c/logs} in the legacy skill copy as well, or retire/sync that copy from the unified command source.
5. Remove/qualify Claude-only remediation such as /debug when the detected harness is not Claude Code.

I would not recommend a Pi-only replacement body as the primary fix. It would solve this report but duplicate capability rules that already exist in the SDK/catalog and would likely rot for OpenClaw/OpenCode/other non-StopHook targets.

Verification plan

• Add a non-StopHook harness fixture (Pi is the obvious one) proving doctor section 10 reports N/A, not FAIL, and the final verdict does not become CRITICAL solely because stop hooks are unsupported.
• Add or keep a StopHook-capable harness fixture proving Claude/Cursor/Codex-style hook registration checks still run where appropriate.
• Run the command-template sync checks so plugins/babysitter-unified/commands/doctor.md and packages/sdk/src/prompts/templates/commands/doctor.md stay aligned.
• If CI builds generated harness packages, inspect or test the generated Pi doctor content to ensure it no longer points users to ~/.claude or Claude /debug for Pi-only failures.

Priority / risk / effort

• Priority: medium. It produces false CRITICAL health reports for supported harnesses, but does not corrupt run state.
• Risk: medium. Verdict scoring and hook diagnostics are cross-harness, so the fix needs positive coverage for both StopHook and non-StopHook harnesses.
• Effort: medium. The core change is mostly command/skill content plus tests/template sync, but it crosses generated plugin surfaces.

Ready for development. Suggested labels: bug, documentation, plugins, harness, effort:medium, risk:medium, ready-for-dev.

[a5c-ai]

Created draft planning PR: https://github.com/a5c-ai/babysitter/pull/935\n\nPlan summary:\n- Add a runnable Babysitter process at .a5c/processes/issue-877-harness-aware-doctor.mjs#process with matching inputs.\n- Start with issue-context reading and Phase 0 reuse audit, including the absence of .a5c/process-library/ in this checkout and the available library/methodologies references.\n- Trace the canonical doctor source, generated SDK template, generated plugin surfaces, and SDK-owned harness capability APIs.\n- Design and implement the fix by gating doctor section 10 on HarnessCapability.StopHook / supportsHookType("stop"), making non-StopHook section 10 results neutral N/A, and keeping Claude-specific remediation conditional.\n- Add focused regression coverage so Pi/non-StopHook harnesses cannot be marked CRITICAL solely because Claude hook files are absent.\n\nQuality gates:\n- N/A must not count as WARN/FAIL/CRITICAL.\n- Pi must not require CLAUDE_PLUGIN_ROOT, hooks.json, hook shell scripts, or ~/.claude settings for a healthy doctor run.\n- StopHook harnesses must retain actionable hook diagnostics.\n- Unified doctor source, SDK template, and generated copies must stay synchronized.\n- Verification includes npm run check:sdk-command-templates, npm run generate:plugins, npm run build:sdk, npm run test:sdk, npm run verify:metadata, and git diff --check.