doctor

name	doctor
license	MIT
compatibility	Claude Code 2.1.170+ for xhigh effort warning (Category 14); earlier versions skip that check.
description	OrchestKit doctor for health diagnostics across manifest integrity, hook configuration, skill validation, agent frontmatter, MCP server connectivity, CC version compatibility, and permission rules. Reports issues with severity levels and auto-remediation suggestions. Validates component counts, detects orphaned entries, and checks CC version matrix compliance. Use when diagnosing plugin health, troubleshooting configuration issues, or running pre-release checks.
argument-hint	[--verbose]
context	inherit
version	3.2.0
author	OrchestKit
tags	["health-check","diagnostics","validation","permissions","hooks","skills","agents","memory"]
user-invocable	true
disable-model-invocation	true
allowed-tools	["Bash","Read","Grep","Glob"]
skills	["configure"]
complexity	low
persuasion-type	collaborative
effort	low
model	haiku
hooks	{"PreToolUse":[{"matcher":"Bash","command":"${CLAUDE_PLUGIN_ROOT}/hooks/bin/run-hook.mjs skill/doctor-env-snapshot","once":true}]}
metadata	{"category":"document-asset-creation"}
triggers	{"keywords":["doctor","diagnose","health check","healthy","hooks configured","skills showing","plugin setup","something broken","troubleshoot","installation is"],"examples":["run orchestkit doctor","are my hooks configured correctly","something feels broken with ork"],"anti-triggers":["help","setup","configure","explore","implement"]}

OrchestKit Health Diagnostics

Argument Resolution

FLAGS = "$ARGUMENTS"         # Full argument string, e.g., "--verbose" or "--json"
FLAG = "$ARGUMENTS[0]"       # First token: -v, --verbose, --json, --category=X
# $ARGUMENTS[0], $ARGUMENTS[1] for indexed access (CC 2.1.59)

STEP 0: Choose Scope (AskUserQuestion — M118 #1464)

A full doctor run takes ~20s. Most invocations only need one slice. Ask the user up-front so voice-flow shortcuts ("just the MCPs") map cleanly:

# Skip the prompt when an explicit scope arg or env override is present:
#   /ork:doctor cc      → skip, use cc-only
#   /ork:doctor mcp     → skip, use mcp-only
#   /ork:doctor plugin  → skip, use plugin-only
#   ORK_DOCTOR_SCOPE=all (or any of the above) → skip, use the env value
#
# Otherwise, ask:
AskUserQuestion(questions=[{
  "question": "What should doctor check?",
  "header": "Scope",
  "options": [
    {"label": "Everything (default)", "description": "Full system health — ~20s; runs all 14 categories"},
    {"label": "CC version & features only", "description": "Categories 10 + 13 + 14; ~3s — for 'is my CC up to date?'"},
    {"label": "MCP servers only", "description": "Category 12 (incl. pinning sub-check); ~5s — for 'are MCPs working?'"},
    {"label": "Plugin health only", "description": "Categories 0-3 + 5 (skills, agents, hooks, build); ~8s — for 'after npm run build'"}
  ]
}])

Skip the prompt entirely when the scope is unambiguous from the invocation. The fast scopes (3-8s) are 3-7× faster than the full run — voice users say "just the MCPs" and get a 5s answer.

Overview

The /ork:doctor command performs comprehensive health checks on your OrchestKit installation. It auto-detects installed plugins and validates 14 categories:

1. Installed Plugins - Detects ork plugin
2. Skills Validation - Frontmatter, references, token budget (dynamic count)
3. Agents Validation - Frontmatter, tool refs, skill refs (dynamic count)
4. Hook Health - Registration, bundles, async patterns
5. Permission Rules - Detects unreachable rules
6. Schema Compliance - Validates JSON files against schemas
7. Coordination System - Checks lock health and registry integrity
8. Context Budget - Monitors token usage against budget
9. Memory System - Graph memory health
10. Claude Code Version & Channel - Validates CC >= 2.1.170 (supported floor), detects release channel (stable/beta/alpha), recommends 2.1.154+ for Opus 4.8 / xhigh effort, /ultrareview, stream-json plugin_errors
11. External Dependencies - Checks optional tool availability (agent-browser)
12. MCP Status - Active vs disabled vs misconfigured, API key presence for paid MCPs. CC 2.1.110: detects duplicate definitions across config scopes. Sub-check warns when HIGH-tier servers resolve to @latest in .mcp.json (closes #1462)
13. Plugin Validate - Runs claude plugin validate for official CC frontmatter + hooks.json validation (CC >= 2.1.77)
14. Effort/Model Compatibility - Warns when xhigh effort is requested without Opus 4.8 (silent fallback otherwise)

When to Use

• After installing or updating OrchestKit
• When hooks aren't firing as expected
• Before deploying to a team environment
• When debugging coordination issues
• After running npm run build

Quick Start

/ork:doctor           # Standard health check
/ork:doctor -v        # Verbose output
/ork:doctor --json    # Machine-readable for CI

CLI Options

Flag	Description
-v, --verbose	Detailed output per check
--json	JSON output for CI integration
--category=X	Run only specific category

Health Check Categories

Detailed check procedures: Load Read("${CLAUDE_SKILL_DIR}/rules/diagnostic-checks.md") for bash commands and validation logic per category.

MCP-specific checks: Load Read("${CLAUDE_SKILL_DIR}/rules/mcp-status-checks.md") for credential validation and misconfiguration detection.

Output examples: Load Read("${CLAUDE_SKILL_DIR}/references/health-check-outputs.md") for sample output per category.

Categories 0-3: Core Validation

Category	What It Checks	Reference
0. Installed Plugins	Auto-detects ork plugin, counts skills/agents	load ${CLAUDE_SKILL_DIR}/rules/diagnostic-checks.md
1. Skills	Frontmatter, context field, token budget, links, activation-channel reachability (no orphaned user-invocable skills)	load ${CLAUDE_SKILL_DIR}/references/skills-validation.md
2. Agents	Frontmatter, model, skill refs, tool refs	load ${CLAUDE_SKILL_DIR}/references/agents-validation.md
3. Hooks	hooks.json schema, bundles, async patterns	load ${CLAUDE_SKILL_DIR}/references/hook-validation.md

Activation-channel orphans (repo / pre-release): a user-invocable skill should be reachable by more than a human typing it — via a chain (another skill references /ork:<skill>), a subagent grant (skills: in src/agents/*.md), or a background trigger. A skill with none is an "island" that silently rots. In a repo checkout, run npm run test:manifests:channels (gated in CI via test:manifests). Fix an island by wiring any one channel, or add it to STANDALONE_ALLOWLIST with a justification.

Categories 4-5: System Health

Category	What It Checks	Reference
4. Memory	.claude/memory/ exists, decisions.jsonl integrity, queue depth	load ${CLAUDE_SKILL_DIR}/references/memory-health.md
5. Build	plugins/ sync with src/, manifest counts, orphans	load ${CLAUDE_SKILL_DIR}/rules/diagnostic-checks.md

Categories 6-9: Infrastructure

Category	What It Checks
6. Permission Rules	Unreachable rules detection
7. Schema Compliance	JSON files against schemas
8. Coordination	Multi-worktree lock health, stale locks, sparse paths config
9. Context Budget	Token usage against budget

Categories 10-14: Environment

Category	What It Checks	Reference
10. CC Version & Channel	Runtime version against minimum required, release channel (stable/beta/alpha)	load ${CLAUDE_SKILL_DIR}/references/version-compatibility.md
11. External Deps	Optional tools (agent-browser, portless)	load ${CLAUDE_SKILL_DIR}/rules/diagnostic-checks.md
12. MCP Status	Enabled/disabled state, credential checks, HIGH-tier @latest pinning warn	load ${CLAUDE_SKILL_DIR}/rules/mcp-status-checks.md + ${CLAUDE_SKILL_DIR}/references/mcp-pinning-check.md
13. Plugin Validate	Official CC frontmatter + hooks.json validation (CC >= 2.1.77)	load ${CLAUDE_SKILL_DIR}/rules/diagnostic-checks.md
14. Effort/Model	Detects xhigh effort configured without Opus 4.8 — see below	inline

Category 14: Effort/Model Compatibility (CC 2.1.111+)

CC 2.1.111 added xhigh effort (Opus 4.8; since CC 2.1.154 it defaults to high and takes xhigh for the hardest tasks). Using it with a model that doesn't support it silently falls back to high — producing no error but losing the extra deepening pass documented in the affected skills.

Detection:

• If the active model does NOT support xhigh (i.e. not Opus 4.8), check whether /effort is set to xhigh:
  • Read .claude/settings.json → effort field
  • Read $ORCHESTKIT_EFFORT env var (populated by the effort-detector hook)
• Check for any skill invocation under .claude/chain/*.json that explicitly set effort: xhigh with a non-Opus-4.8 model in scope

Warning format:

WARNING: xhigh effort requires Opus 4.8.
  Current model: <model-id>
  Configured effort: xhigh
  Impact: Skills fall back to high — xhigh's extra deepening pass is lost silently.
  Fix: Either switch to Opus 4.8 (`claude --model opus-4-8`) or lower effort to `high`.

Exit code: Non-zero in --json mode; soft warning in interactive mode.

Report Format

Load Read("${CLAUDE_SKILL_DIR}/references/report-format.md") for ASCII report templates, JSON CI output schema, and exit codes.

Interpreting Results & Troubleshooting

Load Read("${CLAUDE_SKILL_DIR}/references/remediation-guide.md") for the full results interpretation table and troubleshooting steps for common failures (skills validation, build sync, memory).

Bisect with --safe-mode (CC 2.1.169+): when doctor findings don't explain a misbehaving session, restart with claude --safe-mode (or CLAUDE_CODE_SAFE_MODE=1) — it disables ALL customizations (CLAUDE.md, plugins incl. ork, skills, hooks, MCP). If the problem disappears, it's a customization; re-enable halves to isolate. If it persists, it's CC itself — file upstream.

After you fix an issue

CC 2.1.69+: Run /reload-plugins to activate plugin changes in the current session without restarting.

CC 2.1.116+: /reload-plugins and background plugin auto-update now auto-install missing plugin dependencies from marketplaces you've already added. If ork:doctor flagged a plugin-load failure due to a missing dep, /reload-plugins resolves it in place — no manual plugin install step needed.

CC 2.1.152+: For non-plugin skills in a skill directory (~/.claude/skills/ or .claude/skills/), run /reload-skills to re-scan without restarting — the skill analogue of /reload-plugins.

Chain: Deeper Audit

After a clean health report, audit the observability pipeline itself:

/ork:telemetry-inspect

doctor validates structure (manifests, hooks, skills, agents); /ork:telemetry-inspect validates the data plane — every telemetry writer's row count, schema lock, growth trend, and orphaned analytics files that structural checks don't cover.

Related Skills

• ork:configure - Configure plugin settings
• ork:telemetry-inspect - Audit the telemetry/analytics pipeline after a clean structural check
• ork:quality-gates - CI/CD integration
• security-scanning - Comprehensive audits

References

Load on demand with Read("${CLAUDE_SKILL_DIR}/references/<file>") or Read("${CLAUDE_SKILL_DIR}/rules/<file>"):

File	Content
rules/diagnostic-checks.md	Bash commands and validation logic per category
rules/mcp-status-checks.md	Credential validation and misconfiguration detection
references/remediation-guide.md	Results interpretation and troubleshooting steps
references/health-check-outputs.md	Sample output per category
references/skills-validation.md	Skills frontmatter and structure checks
references/agents-validation.md	Agents frontmatter and tool ref checks
references/hook-validation.md	Hook registration and bundle checks
references/memory-health.md	Memory system integrity checks
references/permission-rules.md	Permission rule detection
references/schema-validation.md	JSON schema compliance
references/report-format.md	ASCII report templates and JSON CI output
references/version-compatibility.md	CC version and channel validation
references/mcp-pinning-check.md	HIGH-tier MCP @latest warning logic + tier source-of-truth