doctor

name	doctor
description	Diagnose the full harness environment. Reports external tool versions, gh auth status, user-project file presence, `_harness_version` drift, and runtime gitignore state in a single screen. Non-blocking — emits the report only. Usage: /harness:doctor
allowed-tools	["Bash","Read"]

doctor — Environment Diagnostics

Probes every prerequisite the plugin needs to operate and reports results to stdout as a table. Performs no automatic fixes — the user reads the report and decides what to act on.

Step 1 — Path resolution

PROJECT_DIR="${CLAUDE_PROJECT_DIR:-$PWD}"
PLUGIN_ROOT="${CLAUDE_PLUGIN_ROOT:-$PROJECT_DIR/.claude}"
TEMPLATES_DIR="$PLUGIN_ROOT/templates"

Step 2 — External tool probe

For each tool: install status + version (if present) + PATH.

Tool	Command	Impact when missing
jq	jq --version	blocking: every hook depends on jq
git	git --version	blocking: version control unavailable
python3	python3 --version	PRD / ADR / ROADMAP / ARCHITECTURE generators disabled
gh	gh --version	PR / Issue flow disabled
bash	bash --version | head -1	informational

Additionally: if gh is present, run gh auth status and check for Logged in to.

Step 3 — Project file inspection

Item	Check
CLAUDE.md	exists + extract _harness_version marker
.claude/config.json	exists + extract _harness_version key
.claude/runtime/	exists (optional — auto-created on first task)
.gitignore	contains .claude/runtime/ entry
.claude/rules/	code-style / file-conventions / review-finding-format files present

Step 4 — Drift inspection

TMPL_VER=$(jq -r '._harness_version // empty' "$TEMPLATES_DIR/config.json.tmpl" 2>/dev/null)
CFG_VER=$(jq -r '._harness_version // "unknown"' "$PROJECT_DIR/.claude/config.json" 2>/dev/null)
CLM_VER=$(grep -oE '_harness_version: [0-9]+\.[0-9]+\.[0-9]+' "$PROJECT_DIR/CLAUDE.md" 2>/dev/null \
          | head -1 | awk '{print $2}')

Compare TMPL_VER against CFG_VER / CLM_VER — mismatch = drift.

Step 5 — Output format

=== Harness Doctor ===
Plugin:  /Users/x/.claude/plugins/harness@tkstardev   (templates v0.1.0)
Project: /Users/x/myproject

Tools:
  jq       1.7.1      OK
  git      2.43.0     OK
  python3  3.11.7     OK
  gh       2.40.1     OK  (logged in as @username)
  bash     5.2.21     OK

Files:
  CLAUDE.md                               OK  v0.1.0
  .claude/config.json                     OK  v0.1.0
  .claude/runtime/                        OK  (gitignored)
  .claude/rules/code-style.md             OK
  .claude/rules/file-conventions.md       OK
  .claude/rules/review-finding-format.md  OK

Drift:
  config.json  v0.1.0 -> v0.1.0  OK
  CLAUDE.md    v0.1.0 -> v0.1.0  OK

Overall: OK

Step 6 — Remediation guidance

Per-item fix commands:

Missing	Fix
jq	macOS: brew install jq / Debian: apt install jq
python3	macOS: brew install python / Debian: apt install python3
gh	macOS: brew install gh / Debian: official GitHub CLI guide
gh auth	gh auth login
CLAUDE.md	/harness:init
.claude/config.json	session restart (ensure-config.sh auto-runs) or cp .claude/templates/config.json.tmpl .claude/config.json
drift	/harness:update
.claude/runtime/ not gitignored	session restart (ensure-runtime-gitignore.sh auto-runs)

Operational guarantees

• Read-only: every probe is read-only. No files are modified.
• Non-blocking: missing items report and exit 0 — never abort the session.
• Single-screen: full state visible at a glance via tables + status markers.