Doctor

OrchestKit Health Diagnostics

Host-neutral workflow. Invoke by skill name (doctor). Claude Code slash routing, YAML hook loaders, and .claude/chain live in references/claude-code.md.

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:
#   doctor cc      → skip, use cc-only
#   doctor mcp     → skip, use mcp-only
#   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 doctor command performs comprehensive health checks on your OrchestKit installation. It auto-detects installed plugins and validates 16 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 - Validates CC >= the supported_floor in shared/cc-support.json (read it; it is the single source). Everything the old "recommends 2.1.154+" note gated (xhigh effort, /ultrareview, stream-json plugin_errors) is floor-guaranteed now, so there is nothing left to recommend
11. External Dependencies - Checks optional tool availability (agent-browser), plus one line per peer skill installed from another marketplace: typesafe@typesafe-ai installed version against the marketplace's, via scripts/check-peer-skill.py (missing marketplace and missing plugin are separate verdicts, the vendor's update commands are the fix text; #4233)
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 only when xhigh effort is configured AND the active model is provably unable to run it. Silent otherwise, because the fallback itself is silent
15. Sandbox Posture - CC Bash-sandbox on/off across all four settings scopes (incl. ~/.claude/settings.json, where real configs usually live), with a /sandbox nudge; sub-check 15b queries the macOS unified log for recent sandbox deny events (fail-closed: a denied log query reports UNOBSERVABLE, never zero)
16. Operator Settings Posture - Detects security controls that a plugin bundle cannot carry (credential-read deny rules, the sandbox block, CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS) and are therefore missing unless the operator wrote them into their own settings

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

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

CLI Options

Health Check Categories

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

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

Output examples: Load Read("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

Analytics writer liveness (System Health): the local analytics pipeline has several independent JSONL writers under ~/.claude/analytics/ (skill-usage, agent-usage, hook-timing). A writer can die silently while its siblings stay hot — observed once for four months (skill-usage.jsonl, 2026-03 to 2026-07). The check is a peer comparison: flag any watched file whose last write is ≥48h old while a sibling wrote within 24h (stat -f '%m %N' ~/.claude/analytics/*.jsonl). The lifecycle/analytics-liveness-check SessionStart hook runs the same comparison continuously.

A flagged writer means the write path was dropped from dispatch, so check both surfaces — src/hooks/hooks.json AND the entries map (src/hooks/src/entries/*.ts). A hook present in one but not the other is registered-looking and silently dead: the #959 failure class. telemetry-inspect gives the per-file deep dive, covering the field-level defects this structural check cannot see: constant fields and phantom rows, the two classes fixed in #3034 and #3035 (both closed 2026-07-20). Cite them as prior art, not as open work.

(Category numbering in this file is inconsistent between the Overview list above and these tables — the Overview numbers 4 as Hook Health, the tables number 4 as Memory. This check belongs to System Health regardless of which numbering a reader follows.)

Categories 6-9: Infrastructure

Categories 10-16: Environment

Why Check 16 exists at all: plugins-reference.md:858 says "Only the agent and subagentStatusLine keys are currently supported" in a plugin's bundled settings.json. Everything else ork used to declare there was inert, so the protection it looked like it shipped was never in force. Check 16 is the replacement: detect the gap in a scope CC really reads, then hand the operator the exact JSON. The ork:configure skill, section Operator-Scope Settings, carries the paste-ready blocks, staged loose-then-strict per #3424; the full JSON is in ../configure/references/operator-scope-settings.md.