Doctor

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 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 >= 2.1.220 (supported floor). 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)
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

/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("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. /ork: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 ${CLAUDE_PLUGIN_ROOT}/skills/configure/references/operator-scope-settings.md.

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

CC 2.1.111 added the xhigh effort tier. The only reason this category exists is the silence: a model that does not implement xhigh degrades the request to high with no error, no warning, and no log line, so the extra deepening pass the affected skills document is lost without any visible signal. If CC ever surfaces the downgrade itself, delete this category.

The check is capability-shaped, not model-name-shaped. Never hardcode "the current frontier model" here: that guarantees a false failure the day the next one ships, and it prescribes a downgrade to a superseded model.

Do not route this through src/hooks/src/lib/models.vocab.json. That file is the model-id/pricing vocabulary and carries no effort or capability fields at all, so keying off it would leave the check permanently, accidentally dead rather than deliberately quiet.

Detection (warn only on positive proof):

1. Resolve the configured effort, in order: .claude/settings.json → effort, then $ORCHESTKIT_EFFORT (populated by the effort-detector hook), then any .claude/chain/*.json entry that explicitly set effort: xhigh. No xhigh anywhere means pass, no output.
2. Resolve the active model id.
3. Warn only when that model id matches a prefix in doctor's local XHIGH_UNSUPPORTED_PREFIXES table below. Every other outcome (model absent from the table, model id unresolvable, settings file missing) is a pass. A check that cannot prove a problem stays quiet.

# Doctor-local capability table. Deliberately a DENY-list, not an allow-list:
# a model absent from this table is assumed to support xhigh and emits nothing.
# Add an entry only from an OBSERVED silent degrade, citing the CC version it was
# seen on. Never add one by inferring from a model being new, old, or cheap.
XHIGH_UNSUPPORTED_PREFIXES = [
    # prefix        evidence
    "claude-3-",  # the whole Claude 3 line predates CC 2.1.111, which introduced the tier
]

An empty or short table is the correct resting state. Silence here means "doctor has no proof of a problem", which is a true statement, whereas a name-matched failure against an unrecognized model is a false one.

Warning format (no model name is hardcoded, both sides are read at runtime):

WARNING: effort is set to `xhigh`, but <model-id> matches XHIGH_UNSUPPORTED_PREFIXES.
  Configured effort: xhigh (source: <settings.json | $ORCHESTKIT_EFFORT | chain>)
  Impact: the run degrades to `high` with no error and no log line, so the extra
          deepening pass is lost with nothing to notice it by.
  Fix: run this on a model that implements `xhigh`, or set effort to `high` so the
       config matches what actually executes.

Exit code: Non-zero in --json mode only when the warning actually fires; soft warning in interactive mode. A silent pass is exit 0.

Report Format

Every category reports an explicit pass / warn / fail status, and every warn or fail comes with specific fix steps for that failure type (the exact command to run, file to edit, or config to change) — doctor diagnoses AND prescribes, it never just lists problems.

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

Interpreting Results & Troubleshooting

Load Read("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("references/<file>") or Read("rules/<file>"):