doctor

name: doctor license: MIT compatibility: "Claude Code 2.1.183+ 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 15 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 15 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.183 (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

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

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

Categories 6-9: Infrastructure

Categories 10-15: Environment

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>"):