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 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

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

Agents Validation

Overview

OrchestKit includes 30 specialized agents validated against CC 2.1.69 frontmatter format.

Agent Structure

src/agents/
├── backend-system-architect.md
├── code-quality-reviewer.md
├── frontend-ui-developer.md
└── ... (38 total)

Validation Checks

1. Frontmatter Fields

Required fields:

• name - Agent identifier (used in Task subagent_type)
• description - Purpose and auto-mode keywords
• model - opus, sonnet, or haiku
• tools - Array of allowed CC tools
• skills - Array of skill names to auto-inject

Optional fields:

• context - fork or inherit
• color - Display color
• hooks - Agent-specific hooks

2. Model Validation

Only valid models:

# Check model values
grep "^model:" src/agents/*.md | sort | uniq -c

Expected: opus, sonnet, haiku

3. Skills References

All skills in agent frontmatter must exist:

# Check skill references
for agent in src/agents/*.md; do
  grep -A100 "^skills:" "$agent" | grep "^  - " | \
    sed 's/.*- //' | while read skill; do
      [ -d "src/skills/$skill" ] || echo "Missing: $agent -> $skill"
    done
done

4. Tools Validation

Valid CC tools:

• Bash, Read, Write, Edit, MultiEdit
• Grep, Glob
• Task, Skill
• WebFetch, WebSearch
• NotebookEdit
• AskUserQuestion
• TaskCreate, TaskUpdate, TaskGet, TaskList

Quick Validation

# Run full agent validation
npm run test:agents

# Or directly
./tests/agents/test-agent-frontmatter.sh

Common Issues

Invalid model

model: sonnet  # Valid: opus, sonnet, haiku

Missing skill reference

Ensure skill exists in src/skills/ directory.

Invalid tool name

Check tool spelling matches CC tool names exactly.

Agent Registration Check (CC 2.1.50+)

Run claude agents to list all registered agents and compare against the expected count from manifests.

Gate: Only run if CC >= 2.1.50 (feature: claude_agents_cli). Skip with a note if version is older.

# Check registered agent count matches expected
expected_count=$(grep -c '"agents/' manifests/ork.json 2>/dev/null || echo 0)
registered_count=$(claude agents 2>/dev/null | wc -l | tr -d ' ')

if [ "$registered_count" -ne "$expected_count" ]; then
  echo "WARN: Agent count mismatch — expected $expected_count, got $registered_count"
  # List missing agents for investigation
  claude agents 2>/dev/null | sort > /tmp/ork-registered.txt
  ls src/agents/*.md 2>/dev/null | xargs -I{} basename {} .md | sort > /tmp/ork-expected.txt
  echo "Missing agents:"
  comm -23 /tmp/ork-expected.txt /tmp/ork-registered.txt
fi

Check: claude agents | wc -l should match expected agent count (38).

Model Routing

See docs/model-routing.md for per-agent model assignment rationale and version history.

Fail action: List missing agents for manual investigation. Common causes:

• Plugin not installed or not rebuilt after adding agents
• Agent frontmatter parse error preventing registration
• CC version too old (< 2.1.50) to support claude agents CLI

Health Check Output Examples

Reference output examples for each /ork:doctor check category.

Channel Detection

Stable:

Channel: stable (v7.0.0)

Beta:

Channel: beta (v7.0.0-beta.3)
⚠ You are on the beta channel. Report issues at github.com/yonatangross/orchestkit/issues

Alpha:

Channel: alpha (v7.0.0-alpha.1)
⚠ You are on the alpha channel. Expect breaking changes. Report issues at github.com/yonatangross/orchestkit/issues

Detection logic: 1. Read version from .claude-plugin/plugin.json (version field) or version.txt 2. If version contains -alpha → alpha channel 3. If version contains -beta → beta channel 4. Otherwise → stable channel

Installed Plugins

Installed Plugins: 1
- ork: 111 skills, 37 agents, 173 hook entries

Skills Validation

Skills: 79/79 valid
- User-invocable: 18 commands
- Reference skills: 61

Agents Validation

Agents: 38/38 valid
- Models: 12 sonnet, 15 haiku, 8 opus
- All skill references valid

Hook Health

Hooks: 95/95 entries valid (12 bundles)
- Global: 34, Agent-scoped: 54, Skill-scoped: 7
- Async hooks: 9 (native async)
- Error Rate: 0.3%

Memory System

Memory System: healthy
- Graph Memory: 42 decisions, 0 corrupt, queue depth 3

Build System

Build System: in sync
- Skills: 69 src/ = 69 plugins/
- Agents: 38 src/ = 38 plugins/
- Last build: 2 minutes ago

Permission Rules

Permission Rules: 12/12 reachable

Schema Compliance

Schemas: 15/15 compliant

Coordination System

Coordination: healthy
- Active instances: 1
- Stale locks: 0

Context Budget

Context Budget: 1850/2200 tokens (84%)

Claude Code Version

OK:

Claude Code: 2.1.47 (OK)
- Minimum required: 2.1.47
- All 15 features available

Degraded:

Claude Code: 2.1.44 (DEGRADED)
- Minimum required: 2.1.47
- Missing: last_assistant_message, added_dirs, Windows hooks, worktree discovery
- Upgrade: npm install -g @anthropic-ai/claude-code@latest

External Dependencies

Installed (agent-browser ≥ 0.26 — structured doctor):

External Dependencies:
agent-browser: OK (chrome=128.0.6613.137, net=✓)

Installed but degraded:

External Dependencies:
agent-browser: DEGRADED (chrome=128.0.6613.137, net=✗)
  ↳ HIGH: daemon not reachable on port 9222 — try `agent-browser daemon restart`

Installed (agent-browser < 0.26 — legacy fuzzy probe):

External Dependencies:
agent-browser: installed (legacy probe — upgrade to 0.26+ for structured doctor)

Not installed:

External Dependencies:
agent-browser: NOT INSTALLED (optional — install via vercel-labs/agent-browser ≥ 0.26)

Plugin Validate

Pass (CC >= 2.1.77):

Plugin Validate: PASSED
- claude plugin validate: 0 errors, 0 warnings

Fail (CC >= 2.1.77):

Plugin Validate: FAILED
- claude plugin validate: 2 errors
  - src/skills/broken/SKILL.md: missing required field "description"
  - src/hooks/hooks.json: invalid matcher pattern at hooks[3]
- Fix errors and re-run: npm run build && claude plugin validate

Skipped (CC < 2.1.77):

Plugin Validate: SKIPPED (requires CC >= 2.1.77)
- Falling back to OrchestKit custom validation only

Managed Settings Policy (CC >= 2.1.92)

OK — forceRemoteSettingsRefresh with endpoint:

Managed Settings: OK
- forceRemoteSettingsRefresh: enabled
- Remote endpoint configured

Warning — forceRemoteSettingsRefresh without endpoint:

Managed Settings: WARNING
- forceRemoteSettingsRefresh: enabled but no remote settings endpoint detected
- This will block startup if network is unavailable
- Configure a remote endpoint or remove forceRemoteSettingsRefresh

Info — not set:

Managed Settings: OK (default)
- forceRemoteSettingsRefresh: not set (falls back to cached settings)

MCP connector conflict (CC >= 2.1.92 fix):

MCP Servers: WARNING
- Plugin MCP server "{name}" duplicates a claude.ai connector
- Prior to CC 2.1.92 this caused stuck "connecting" state
- Consider setting ENABLE_CLAUDEAI_MCP_SERVERS=false or renaming the plugin server

Hook Validation

Overview

OrchestKit uses 143 global hook entries across 27 event types, compiled into 11 bundles. This reference explains how to validate and troubleshoot hooks.

Hook Architecture

hooks.json (63 global + 22 agent-scoped + 1 skill-scoped entries)
    ↓
12 TypeScript bundles (dist/*.mjs)
    ↓
9 async hooks use fire-and-forget pattern

Platform Support

Windows support history:

• Before CC 2.1.47: All hooks silently failed on Windows (cmd.exe incompatible)
• CC 2.1.47: Fixed by executing hooks via Git Bash instead of cmd.exe
• PR #645: OrchestKit added Windows-safe spawning (no console flashing, no ENAMETOOLONG)

Cross-platform safety measures in OrchestKit hooks:

• paths.ts provides cross-platform path handling (os.homedir(), os.tmpdir(), path.join())
• CRLF normalization (\r\n → \n) in subagent-validator, decision-history, common.ts
• Windows backslash path normalization in structure-location-validator
• Windows-specific test cases for paths, CRLF, and permission handling

Hook Categories

Bundle Structure

Validation Checks

1. hooks.json Schema

# Validate hooks.json structure
cat src/hooks/hooks.json | jq '.hooks | keys'

2. Bundle Existence

# Check all bundles exist
ls -la src/hooks/dist/*.mjs

3. Async Hook Pattern

Async hooks use fire-and-forget scripts:

# 9 fire-and-forget scripts required (updated CC 2.1.47)
ls src/hooks/bin/*-fire-and-forget.mjs

4. Matcher Syntax

Valid matcher patterns:

{
  "matcher": "Bash",           // Exact tool name
  "matcher": "Write|Edit",     // Multiple tools
  "matcher": "*",              // All tools
  "matcher": "mcp__*"          // Wildcard prefix
}

Debug Mode (Issue #243)

Silent hooks run in detached background processes. Enable debug mode to monitor them.

Enable Debug Logging

Create .claude/hooks/debug.json:

{
  "enabled": true,
  "verbose": false,
  "includeInput": false,
  "hookFilters": []
}

View Debug Logs

# Recent background hook activity
tail -f .claude/logs/background-hooks.log

# Filter by hook name
grep "unified-dispatcher" .claude/logs/background-hooks.log

Hook Metrics

Execution metrics tracked in .claude/hooks/metrics.json:

{
  "hooks": {
    "posttool/unified-dispatcher": {
      "totalRuns": 42,
      "successCount": 41,
      "errorCount": 1,
      "avgDurationMs": 150
    }
  }
}

PID Tracking

# Check for orphaned processes
for f in .claude/hooks/pids/*.pid; do
  pid=$(jq -r '.pid' "$f" 2>/dev/null)
  if [ -n "$pid" ] && ! kill -0 "$pid" 2>/dev/null; then
    echo "Orphaned: $f"
    rm "$f"
  fi
done

Troubleshooting

Hook not firing

1. Check matcher pattern matches tool name 2. Verify bundle exists in dist/ 3. Check hooks.json registration

Hook timing out

Default timeout: 120s (bash), 600s (CC 2.1.3+)

Exit Codes

MCP Pinning Check (Category 12 sub-check)

Warns when .mcp.json resolves HIGH-tier MCP servers to @latest. HIGH-tier upstream packages are pre-1.0 or beta-surface — a breaking change can land on any npx -y fetch with no signal.

Closes: #1462. Split from #1446 (MCP audit).

Tier Source-of-Truth

src/skills/mcp-patterns/references/mcp-version-matrix.md

Detection

The check parses .mcp.json and for each non-disabled entry extracts the npm package + version specifier from args (handles both npx -y pkg@x and sh -c "... npx -y pkg@x" shapes). Local servers (e.g., node ./server.mjs) are skipped.

For each enabled remote server:

Output

HIGH-tier @latest detected:

MCP pinning: 2 HIGH-tier server(s) resolve to @latest
    ⚠ 21st-dev-magic (@21st-dev/magic)
    ⚠ agentation (agentation-mcp)
    → Consider pinning to concrete versions in .mcp.json
    → See src/skills/mcp-patterns/references/mcp-version-matrix.md

MEDIUM-tier only:

MCP pinning: 3 MEDIUM-tier server(s) at @latest (informational)
    ℹ context7 (@upstash/context7-mcp)
    ℹ tavily (tavily-mcp)
    ℹ fal (fal-ai-mcp)

OK:

MCP pinning: OK (no HIGH-tier @latest entries)

Script

src/skills/doctor/scripts/check-mcp-pinning.sh — invokable standalone or via /ork:doctor Category 12.

# Standalone
src/skills/doctor/scripts/check-mcp-pinning.sh

# JSON for CI
src/skills/doctor/scripts/check-mcp-pinning.sh --json

# Test fixture
src/skills/doctor/scripts/check-mcp-pinning.sh --mcp-json /tmp/test.json

Exit codes: 0 = OK or absent, 1 = HIGH-tier @latest found, 2 = usage error.

Tests

tests/skills/test-mcp-pinning-check.sh — 18 assertions across 7 fixtures covering HIGH/MEDIUM/LOW tier classification, disabled entries, local servers, JSON output shape, and missing-file handling.

Memory Health

Overview

OrchestKit uses graph memory for knowledge persistence. Doctor validates it with automated checks.

Automated Health Check

The memory-health.ts library provides checkMemoryHealth() which returns a MemoryHealthReport:

interface MemoryHealthReport {
  overall: 'healthy' | 'degraded' | 'unavailable';
  timestamp: string;
  graph: {
    status: TierStatus;
    memoryDir: boolean;        // .claude/memory/ exists
    decisions: FileHealth;     // decisions.jsonl analysis
    graphQueue: FileHealth;    // graph-queue.jsonl depth
  };
}

Each FileHealth includes: exists, lineCount, corruptLines, sizeBytes, lastModified.

Status Meanings

Graph Memory

Local knowledge graph stored in .claude/memory/.

Validation Commands

# Check directory exists
ls -la .claude/memory/

# Count decisions
wc -l .claude/memory/decisions.jsonl

# Check graph queue depth
wc -l .claude/memory/graph-queue.jsonl 2>/dev/null

# Validate JSONL integrity (each line must be valid JSON)
while IFS= read -r line; do
  echo "$line" | python3 -m json.tool > /dev/null 2>&1 || echo "CORRUPT: $line"
done < .claude/memory/decisions.jsonl

Health Indicators

• Directory exists: .claude/memory/
• decisions.jsonl: Valid JSONL, no corrupt lines
• graph-queue.jsonl: Queue depth < 50 (high depth = sync backlog)
• No corruption: every line parses as valid JSON

Degraded Conditions

• Corrupt lines: One or more JSONL lines fail to parse
• High queue depth: >50 pending graph operations (sync backlog)
• Missing directory: Graph memory never initialized

Troubleshooting

Graph memory missing

# Initialize graph
mkdir -p .claude/memory

The first /ork:remember call will create decisions.jsonl.

Corrupt JSONL lines

# Find corrupt lines
python3 -c "
import json, sys
with open('.claude/memory/decisions.jsonl') as f:
    for i, line in enumerate(f, 1):
        try: json.loads(line)
        except: print(f'Line {i}: {line.strip()[:80]}')
"

High queue depth

Queue items accumulate if the stop dispatcher doesn't run (e.g., session crash). The queue-recovery hook processes orphaned queues on the next session start.

Permission Rules Analysis

Overview

CC 2.1.3 added detection for unreachable permission rules. This reference explains how to diagnose and fix permission issues.

Common Issues

1. Unreachable Rules

A rule is unreachable when a more general rule already matches:

// PROBLEM: Second rule never matches
{
  "permissions": [
    { "path": "**/*.md", "action": "allow" },
    { "path": "README.md", "action": "deny" }  // Unreachable!
  ]
}

Fix: Order rules from specific to general:

{
  "permissions": [
    { "path": "README.md", "action": "deny" },
    { "path": "**/*.md", "action": "allow" }
  ]
}

2. Shadowed Rules

When two rules match the same pattern with different actions:

// PROBLEM: Both match, but first wins
{
  "permissions": [
    { "matcher": "Bash", "action": "allow" },
    { "matcher": "Bash", "commands": ["rm"], "action": "deny" }
  ]
}

Fix: Use more specific matchers:

{
  "permissions": [
    { "matcher": "Bash", "commands": ["rm", "rm -rf"], "action": "deny" },
    { "matcher": "Bash", "action": "allow" }
  ]
}

3. Invalid Patterns

Glob patterns that will never match:

// PROBLEM: Typo in pattern
{
  "permissions": [
    { "path": "**.md", "action": "allow" }  // Should be **/*.md
  ]
}

Validation Commands

# Check for unreachable rules
jq '.permissions // [] | to_entries | map(select(.value.action == "allow"))' \
  .claude/settings.json

# List all permission matchers
jq '.permissions // [] | map(.matcher) | unique' .claude/settings.json

Best Practices

1. Order rules from most specific to least specific 2. Use explicit deny rules before catch-all allow rules 3. Test rules with actual tool invocations 4. Review rules after plugin updates

Remediation Guide

Quick remediation steps for common /ork:doctor findings.

Interpreting Results

Troubleshooting

"Skills validation failed"

# Run skill structure tests
npm run test:skills
./tests/skills/structure/test-skill-md.sh

"Build out of sync"

# Rebuild plugins from source
npm run build

"Memory unavailable"

# Check graph memory
ls -la .claude/memory/

"Plugin validate failed"

# Run CC's official validator (requires CC >= 2.1.77)
claude plugin validate

# Fix reported errors, then rebuild and re-validate
npm run build
claude plugin validate

"Stale plugin paths in PATH"

CC ≤ 2.1.127 occasionally left installed_plugins.json entries pointing at deleted cache directories, polluting PATH for subprocesses. CC 2.1.128+ scrubs those automatically — no maintenance needed at our floor (2.1.168). If you see plugin commands failing with command not found after uninstalling a plugin on CC < 2.1.128, upgrade.

"Auto mode unable to evaluate"

CC 2.1.128+ adds a hint to the auto-mode classifier failure path. When you see:

Auto mode could not evaluate this action.
  hint: retry, use /compact, or run with --debug

Pick whichever applies — /compact if context is full, --debug to see the classifier's reasoning, retry if it was transient.

"Logged out after laptop wake"

If multiple CC sessions all logged themselves out at the same moment after the laptop woke from sleep, that is the pre-2.1.129 OAuth refresh race — concurrent wake-time refreshes invalidated the active token across every running session.

Fix: upgrade to CC ≥ 2.1.129 (our floor is 2.1.170, so anyone on the supported window is already fixed). Recover the session with:

claude /login

Then claude --resume the affected session(s). Checkpoint state in .claude/pipeline-state.json survives — see checkpoint-resume skill for resume semantics.

If logouts after wake persist on CC ≥ 2.1.129, the cause is no longer the race — investigate the refresh token (expired, keychain ACL changed, 1Password locked) instead.

"All concurrent sessions 401 simultaneously"

If you had multiple CC sessions open (worktree-isolated agents, parallel /ork:implement chains, multi-tab work) and every one of them dead-ended at 401 Unauthorized at the same instant — that is the pre-2.1.133 parallel-session refresh-token race. A refresh-token rotation fired in one session, the other sessions raced against it, and they all wound up holding the now-invalidated old token.

Fix: upgrade to CC ≥ 2.1.133 (our floor is 2.1.170, so the supported window is already past this). Recover the stuck sessions with:

claude /login

Then claude --resume the affected sessions. Worktree state in each agent's branch is unaffected.

If "all sessions 401 at once" still reproduces on CC ≥ 2.1.133, the cause is no longer this race — check the refresh token itself (expired, revoked by the IdP, keychain ACL changed, 1Password locked). See also the "Logged out after laptop wake" entry above for the related 2.1.129 wake-from-sleep race.

"EnterWorktree drops my unpushed commits"

If a worktree spawned via EnterWorktree, --worktree, or an agent run with isolation: "worktree" is missing commits you made locally but never pushed — and git log in the new worktree starts from origin/<default-branch> instead of your current HEAD — that is CC 2.1.133's new worktree.baseRef default at work. CC 2.1.133 added the setting with default "fresh", which branches new worktrees from origin/<default> rather than local HEAD (the 2.1.128–2.1.132 behavior).

Fix: set worktree.baseRef: "head" in .claude/settings.json (project) or ~/.claude/settings.json (user):

{
  "worktree": {
    "baseRef": "head"
  }
}

After adding the setting, spawn a fresh worktree — the new one will branch from local HEAD and include your unpushed commits. Existing worktrees that were created without the setting need to be recreated; you can recover their work by cherry-picking commits from the original branch first.

See ${CLAUDE_SKILL_DIR}/../chain-patterns/references/worktree-agent-pattern.md for the full agent-isolation context, and ${CLAUDE_SKILL_DIR}/../configure/references/cc-version-settings.md (CC 2.1.133 section) for the upstream change description.

Doctor Report Format

ASCII Report

Full ork plugin:

+===================================================================+
|                    OrchestKit Health Report                        |
+===================================================================+
| Version: {version}  |  CC: {cc_version}  |  Plugins: ork          |
+===================================================================+
| Skills           | 67/67 valid                                    |
| Agents           | 37/37 valid                                    |
| Hooks            | 87/87 entries (12 bundles)                     |
| Memory           | Graph memory healthy                           |
| MCP              | context7 ✓  memory ✓  tavily ○  agentation ○  |
| Permissions      | 12/12 reachable                                |
| Schemas          | 15/15 compliant                                |
| Context          | 1850/2200 tokens (84%)                         |
| Coordination     | 0 stale locks                                  |
| CC Version       | {cc_version} (OK)                              |
| Plugin Validate  | PASSED (0 errors)                                |
+===================================================================+
| Status: HEALTHY (11/11 checks passed)                             |
+===================================================================+

Note: {version} is read from package.json at runtime. {cc_version} is detected from Claude Code. Counts reflect installed plugin — dynamic, not hardcoded.

JSON Output (CI Integration)

/ork:doctor --json

{
  "version": "{version}",
  "claudeCode": "{cc_version}",
  "status": "healthy",
  "plugins": {
    "installed": ["ork"],
    "count": 1
  },
  "checks": {
    "skills": {"passed": true, "count": 67, "perPlugin": {"ork": 67}},
    "agents": {"passed": true, "count": 37, "perPlugin": {"ork": 37}},
    "hooks": {"passed": true, "entries": 87, "bundles": 12, "source": "ork"},
    "memory": {"passed": true, "available": ["graph"]},
    "mcp": {"passed": true, "servers": {"context7": "enabled", "memory": "enabled", "sequential-thinking": "disabled", "tavily": "disabled", "agentation": "disabled"}},
    "permissions": {"passed": true, "count": 12},
    "schemas": {"passed": true, "count": 15},
    "context": {"passed": true, "usage": 0.84},
    "coordination": {"passed": true, "staleLocks": 0},
    "ccVersion": {"passed": true, "version": "2.1.47"},
    "pluginValidate": {"passed": true, "errors": 0, "warnings": 0, "skipped": false}
  },
  "exitCode": 0
}

Exit Codes

Schema Validation

Overview

OrchestKit uses JSON schemas to validate configuration files. This reference explains how to validate and fix schema issues.

Schemas

Located in .claude/schemas/:

Validation Commands

Validate All

./tests/schemas/validate-all.sh

Validate Specific File

# Using ajv
npx ajv validate \
  -s .claude/schemas/skill files \
  -d .claude/skills/doctor/SKILL.md

# Using jq for basic structure check
jq empty .claude/skills/doctor/SKILL.md

Common Schema Errors

Missing Required Field

// ERROR: Missing "description"
{
  "name": "my-skill",
  "version": "1.0.0"
}

Fix: Add all required fields:

{
  "$schema": "../../schemas/skill files",
  "name": "my-skill",
  "version": "1.0.0",
  "description": "Description of the skill",
  "capabilities": ["capability-1"]
}

Invalid Type

// ERROR: capabilities must be array
{
  "capabilities": "single-capability"
}

Fix: Use correct type:

{
  "capabilities": ["single-capability"]
}

Pattern Mismatch

// ERROR: version must match semver
{
  "version": "1.0"
}

Fix: Use proper semver:

{
  "version": "1.0.0"
}

Batch Validation

# Validate all SKILL.md files
for category in skills/*/.claude/skills; do for f in "$category"/*/SKILL.md; do
  npx ajv validate \
    -s .claude/schemas/skill files \
    -d "$f" || echo "INVALID: $f"
done

Creating Valid Files

Use schema as a template:

# View required fields
jq '.required' .claude/schemas/skill files

# View property types
jq '.properties | to_entries | map({key: .key, type: .value.type})' \
  .claude/schemas/skill files

Skills Validation

Overview

OrchestKit includes 111 skills validated against frontmatter requirements and content standards.

Skill Types

Validation Checks

1. Frontmatter Fields

Required fields:

• name - Skill identifier
• description - Brief description with triggers
• user-invocable - Boolean for command availability

Optional fields:

• context - fork (recommended), inherit
• agent - Associated agent name
• tags - Keywords for discovery
• version - Semver version
• allowedTools - Tool whitelist

2. Token Budget

Skills must stay within token limits:

• Minimum: 300 tokens
• Maximum: 5000 tokens

# Check skill size
wc -c src/skills/*/SKILL.md | sort -n

3. Reference Links

All internal links must resolve:

# Check for broken references
for skill in src/skills/*/SKILL.md; do
  grep -o 'references/[^)]*' "$skill" | while read ref; do
    dir=$(dirname "$skill")
    [ -f "$dir/$ref" ] || echo "Broken: $skill -> $ref"
  done
done

4. Related Skills

All skills in "Related Skills" section must exist:

# Validate related skill references
grep -h "^- " src/skills/*/SKILL.md | grep -v "http" | \
  sed 's/.*`\([^`]*\)`.*/\1/' | sort -u

Quick Validation

# Run full skill validation
npm run test:skills

# Or directly
./tests/skills/structure/test-skill-md.sh

Common Issues

Missing frontmatter

---
name: my-skill
description: Does something useful
user-invocable: false
---

Token budget exceeded

Split into SKILL.md + references/ directory.

Broken reference link

Ensure file exists at references/filename.md.

Doctor Rules Index

Rules for OrchestKit health diagnostics checks.

Diagnostic Check Procedures

Detailed procedures for each health check category in /ork:doctor.

---

Incorrect:

✓ Plugins OK    (no actual validation — just assumed healthy)

Correct:

✓ Skills: 69/69 valid (frontmatter, token budget, links)
✗ Hooks: dist/memory-writer.mjs missing — run: cd src/hooks && npm run build
✓ Agents: 38/38 CC 2.1.6 compliant

0. Installed Plugins Detection

Auto-detects which OrchestKit plugins are installed:

# Detection logic:
# - Scans for .claude-plugin/plugin.json in plugin paths
# - Identifies ork plugin
# - Counts skills/agents per installed plugin

---

1. Skills Validation

Validates skills in installed plugins (count varies by installation):

# Checks performed:
# - SKILL.md frontmatter (name, description, user-invocable)
# - context: fork field (required for CC 2.1.0+)
# - Token budget compliance (300-5000 tokens)
# - Internal link validation (references/ paths)
# - Related Skills references exist

---

2. Agents Validation

Validates agents in installed plugins:

# Checks performed:
# - Frontmatter fields (name, description, model, tools, skills)
# - Model validation (opus, sonnet, haiku only)
# - Skills references exist in src/skills/
# - Tools are valid CC tools

---

3. Hook Health

Verifies hooks are properly configured:

# Checks performed:
# - hooks.json schema valid
# - Bundle files exist (12 .mjs bundles)
# - Async hooks use fire-and-forget pattern (9 async)
# - Background hook metrics health (Issue #243)
# - Windows-safe spawning (PR #645)

---

4. Memory System

Validates graph memory with file-level integrity checks:

# Automated checks:
# - Graph: .claude/memory/ exists, decisions.jsonl valid JSONL, queue depth

# Run these commands to gather memory health data:
wc -l .claude/memory/decisions.jsonl 2>/dev/null || echo "No decisions yet"
wc -l .claude/memory/graph-queue.jsonl 2>/dev/null || echo "No graph queue"
ls -la .claude/memory/ 2>/dev/null || echo "Memory directory missing"

Read .claude/memory/decisions.jsonl directly to validate JSONL integrity (each line must parse as valid JSON). Count total lines, corrupt lines, and report per-category breakdown.

See Memory Health for details.

---

5. Build System

Verifies plugins/ sync with src/:

# Checks performed:
# - plugins/ generated from src/
# - Manifest counts match actual files
# - No orphaned skills/agents

---

6. Permission Rules

Leverages CC 2.1.3's unreachable permission rules detection.

---

7. Schema Compliance

Validates JSON files against schemas.

---

8. Coordination System

Checks multi-worktree coordination health (active instances, stale locks).

---

9. Context Budget

Monitors token usage against budget.

---

10. Claude Code Version

Validates runtime version against the Version Compatibility Matrix.

---

11. External Dependencies

Checks optional tool availability:

# agent-browser (vercel-labs/agent-browser)
# Prefer the structured `agent-browser doctor --json` from 0.26.0+ (CC 2.1.121+).
# Falls back to the fuzzy "is the binary on PATH + symlink present?" probe on older versions.
if command -v agent-browser >/dev/null 2>&1; then
  if agent-browser doctor --json >/tmp/ab-doctor.json 2>/dev/null; then
    # Structured snapshot: surface only high-severity issues + a one-line health summary.
    jq -r '
      "agent-browser: " +
      (if (.daemon.status // "unknown") == "running" then "OK" else "DEGRADED" end) +
      " (chrome=" + (.chrome.version // "?") +
      ", net=" + (if .network.reachable then "✓" else "✗" end) + ")"
    ' /tmp/ab-doctor.json
    # Promote any high-severity issue into doctor's findings stream.
    jq -r '.issues[]? | select(.severity == "high") | "  ↳ HIGH: " + .message' /tmp/ab-doctor.json
  else
    # Fallback for agent-browser < 0.26 (no `doctor` subcommand)
    test -L "$HOME/.claude/skills/agent-browser" \
      && echo "agent-browser: installed (legacy probe — upgrade to 0.26+ for structured doctor)" \
      || echo "agent-browser: SYMLINK MISSING at ~/.claude/skills/agent-browser"
  fi
else
  echo "agent-browser: NOT INSTALLED (optional — install via vercel-labs/agent-browser ≥ 0.26)"
fi

# portless: stable named localhost URLs for local dev
#   which portless 2>/dev/null && portless list 2>/dev/null
#   If missing: RECOMMEND "npm i -g portless" for stable local dev URLs
#   If installed but not running: WARN "portless is installed but no services registered"

# tailscale (M127 #1561): only relevant if user has used /ork:dev --share / --funnel / --live.
# Detected by inspecting .claude/state/dev-stack.json for share != null.
#   if [[ -f .claude/state/dev-stack.json ]] && jq -e '.share != null' .claude/state/dev-stack.json >/dev/null 2>&1; then
#     command -v tailscale >/dev/null 2>&1 \
#       && echo "tailscale: OK (share mode in use: $(jq -r '.share.mode' .claude/state/dev-stack.json))" \
#       || echo "tailscale: SHARE MODE ACTIVE BUT TAILSCALE CLI MISSING (Install: brew install tailscale)"
#   fi

# Live demos older than 24h (M127 #1565): warns about sprawl from /ork:dev --live.
#   live_log=".claude/state/live-demos.jsonl"
#   if [[ -f "$live_log" ]]; then
#     now_ts=$(date -u +%s)
#     while IFS= read -r line; do
#       expires=$(printf '%s' "$line" | jq -r '.expiresAt // empty')
#       [[ -z "$expires" ]] && continue
#       expires_ts=$(date -j -u -f '%Y-%m-%dT%H:%M:%SZ' "$expires" +%s 2>/dev/null \
#                  || date -u -d "$expires" +%s 2>/dev/null)
#       if [[ -n "$expires_ts" && "$expires_ts" -lt "$now_ts" ]]; then
#         age_h=$(( (now_ts - expires_ts) / 3600 ))
#         echo "live demo: EXPIRED ${age_h}h ago — branch=$(printf '%s' "$line" | jq -r '.branch')"
#       fi
#     done < "$live_log"
#   fi

Why structured doctor: agent-browser 0.26.0 added doctor --json returning a snapshot of chrome, daemon, network, config, security, and providers. Wiring it in turns the previous "agent-browser broken" failure into actionable per-subsystem findings (Chrome version, daemon status, network reachability, high-severity issues), unblocking debug sessions where the user can't tell us what's wrong.

---

13. Plugin Validate (CC >= 2.1.77)

Runs claude plugin validate for official CC validation of frontmatter and hooks.json. This complements OrchestKit's custom checks (categories 1-3) with CC's built-in validator.

# Check CC version supports plugin validate (>= 2.1.77)
# If CC < 2.1.77, skip with: "Plugin validate: SKIPPED (requires CC >= 2.1.77)"

# Run official validation from plugin root
claude plugin validate

# Checks performed by CC:
# - SKILL.md frontmatter schema (required fields, types, allowed values)
# - hooks.json schema (event types, matchers, command paths)
# - Agent frontmatter schema (model, tools, skills fields)
# - File path resolution (command paths in hooks exist)

Relationship to OrchestKit checks: claude plugin validate performs structural/schema validation at the CC level. OrchestKit's categories 1-3 perform deeper semantic checks (token budgets, cross-references, async patterns) that CC does not cover. Both should pass for a fully healthy plugin.

---

14. Stale Project State (CC >= 2.1.126, #1582, fixed in #1587)

CC 2.1.126 added claude project purge [path] — deletes all CC state (transcripts, tasks, file history, config entry) for a project. Surface this as an info-severity diagnostic when canonical project paths no longer exist on disk.

# Check CC version supports project purge (>= 2.1.126)
# If CC < 2.1.126, skip silently (suggestion would be unactionable)

# Detect stale project state via the authoritative source.
# Use `claude project purge --dry-run --all` because the directory-name encoding
# under ~/.claude/projects/ is lossy (both `/` and `.` collapse to `-`, so the
# original path cannot be reconstructed deterministically — `my-project` is
# indistinguishable from `my.project` or `my/project`). The CLI's dry-run
# output emits canonical paths from ~/.claude.json which IS lossless.
#
#   claude project purge --dry-run --all 2>/dev/null \
#     | grep -oE 'projects\["[^"]+"\]' \
#     | sed -E 's/^projects\["//; s/"\]$//' \
#     | while IFS= read -r p; do
#         [ -n "$p" ] && [ ! -d "$p" ] && echo "$p"
#       done
#
# Example output (info severity, never blocking):
# ℹ Stale project state: 3 canonical paths reference directories that no longer exist on disk.
#    Suggested cleanup (always preview first):
#      claude project purge --dry-run --all
#      claude project purge --interactive    # confirm each project

Why info, never warn or fail: the user may have moved a project rather than deleted it; aggressive removal would lose transcript history. Always recommend --dry-run first. Mirrors the pattern from claude plugin prune (Category 13b).

Why not parse `~/.claude/projects/` directly: the directory naming is a lossy collapse of the original path (/ and . both become -). A naive sed 's|-|/|g' decode produces ambiguous results — ~/.claude/projects/Users-me-my-project could be /Users/me/my-project, /Users/me/my/project, /Users/me/my.project, or other combinations. The dry-run output above is the canonical source.

MCP Status Checks

Validates .mcp.json entries for enabled/disabled state and required credentials.

Check Procedure

# Checks performed:
# - Parse .mcp.json, list each server with enabled/disabled state
# - For tavily: check TAVILY_API_KEY env var OR op CLI availability
# - For memory: check MEMORY_FILE path is writable
# - For agentation: check agentation-mcp package is installed (npx --yes dry-run)
# - Flag any enabled MCP whose process would likely fail at startup
# - HIGH-tier @latest pinning: see references/mcp-pinning-check.md
#   (script: scripts/check-mcp-pinning.sh — exit 1 on HIGH-tier @latest)
# - alwaysLoad audit (CC 2.1.121+, #1541): warn when memory, context7, or
#   sequential-thinking lack `"alwaysLoad": true` — these are universally
#   used and per-skill ToolSearch probes are wasted work without it.
#   Skip the warning on CC < 2.1.121 (key would be silently ignored).
# - claude plugin orphans (CC 2.1.121+, #1544): suggest `claude plugin prune`
#   when `claude plugin list --json` shows orphaned auto-installed deps.

Incorrect:

MCP Servers: all OK

Correct:

MCP Servers:
- context7:  enabled  ✓
- tavily:    enabled  ✗  TAVILY_API_KEY not set — will fail at startup

Output Examples

Healthy:

MCP Servers:
- context7:           enabled  ✓
- memory:             enabled  ✓
- sequential-thinking: disabled ○
- tavily:             disabled ○  (enable: set TAVILY_API_KEY, see /ork:configure)
- agentation:         disabled ○

Misconfigured (Tavily enabled but no key):

MCP Servers:
- context7:           enabled  ✓
- memory:             enabled  ✓
- tavily:             enabled  ✗  TAVILY_API_KEY not set — MCP will fail at startup
                                  Fix: set TAVILY_API_KEY or set "disabled": true in .mcp.json

Misconfigured (agentation enabled but not installed):

MCP Servers:
- agentation:         enabled  ✗  agentation-mcp package not found
                                  Fix: npm install -D agentation-mcp  or  set "disabled": true