/ork:doctor

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)

# 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'"}
  ]
}])

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

WARNING: xhigh effort requires Opus 4.7.
  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.7 (`claude --model opus-4.7`) or lower effort to `high`.

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

✓ 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

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

# 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

# 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

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

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

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

# 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

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

# 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

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

MCP Servers: all OK

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

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

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

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

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

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

# 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

# Run full agent validation
npm run test:agents

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

model: sonnet  # Valid: opus, sonnet, haiku

# 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

Channel: stable (v7.0.0)

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

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

Installed Plugins: 1
- ork: 103 skills, 36 agents, 173 hook entries

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

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

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: healthy
- Graph Memory: 42 decisions, 0 corrupt, queue depth 3

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

Permission Rules: 12/12 reachable

Schemas: 15/15 compliant

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

Context Budget: 1850/2200 tokens (84%)

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

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:
agent-browser: OK (chrome=128.0.6613.137, net=✓)

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

# 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

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

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

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

# 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

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

# 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

# Initialize graph
mkdir -p .claude/memory

# 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]}')
"

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

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

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

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

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

# 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

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

# Rebuild plugins from source
npm run build

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

# 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

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

claude /login

claude /login

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

+===================================================================+
|                    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)                             |
+===================================================================+

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

./tests/schemas/validate-all.sh

# 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

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

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

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

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

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

{
  "version": "1.0.0"
}

# 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

# 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

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

# 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

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

# Run full skill validation
npm run test:skills

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

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

export ENABLE_PROMPT_CACHING_1H=1

# CC reports version via environment or CLI
claude --version  # Returns e.g. "2.1.47"

Claude Code: 2.1.47 (OK)
- Minimum required: 2.1.47

Claude Code: 2.1.44 (DEGRADED)
- Minimum required: 2.1.47
- Missing features:
  - last_assistant_message (Stop/SubagentStop context)
  - added_dirs (multi-directory support)
  - Windows hook execution
  - Worktree discovery
  - Deferred SessionStart
- Upgrade: npm install -g @anthropic-ai/claude-code@latest

Claude Code: 2.1.4x (MEMORY LEAK RISK)
- 8 memory leaks fixed in 2.1.50 affect long-running sessions
- Symptoms: increasing memory usage, slower responses over time
- Upgrade: npm install -g @anthropic-ai/claude-code@latest

Claude Code: 2.1.56 (OK)
- Minimum required: 2.1.56
- OrchestKit channel: beta (v7.0.0-beta.3)
  ⚠ Pre-release version — some features may be unstable. Report issues at github.com/yonatangross/orchestkit/issues

Claude Code: 2.1.56 (OK)
- Minimum required: 2.1.56
- OrchestKit channel: stable (v7.0.0)