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.
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)
The /ork:doctor command performs comprehensive health checks on your OrchestKit installation. It auto-detects installed plugins and validates 14 categories:
xhigh effort, /ultrareview, stream-json plugin_errorsclaude plugin validate for official CC frontmatter + hooks.json validation (CC >= 2.1.77)xhigh effort is requested without Opus 4.7 (silent fallback otherwise)npm run buildTip (CC 2.1.69+): After fixing issues found by doctor, run
/reload-pluginsto activate plugin changes without restarting your session.
/ork:doctor # Standard health check
/ork:doctor -v # Verbose output
/ork:doctor --json # Machine-readable for CI
| Flag | Description |
|---|---|
-v, --verbose | Detailed output per check |
--json | JSON output for CI integration |
--category=X | Run only specific category |
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.
| Category | What It Checks | Reference |
|---|---|---|
| 0. Installed Plugins | Auto-detects ork plugin, counts skills/agents | load ${CLAUDE_SKILL_DIR}/rules/diagnostic-checks.md |
| 1. Skills | Frontmatter, context field, token budget, links | load ${CLAUDE_SKILL_DIR}/references/skills-validation.md |
| 2. Agents | Frontmatter, model, skill refs, tool refs | load ${CLAUDE_SKILL_DIR}/references/agents-validation.md |
| 3. Hooks | hooks.json schema, bundles, async patterns | load ${CLAUDE_SKILL_DIR}/references/hook-validation.md |
| Category | What It Checks | Reference |
|---|---|---|
| 4. Memory | .claude/memory/ exists, decisions.jsonl integrity, queue depth | load ${CLAUDE_SKILL_DIR}/references/memory-health.md |
| 5. Build | plugins/ sync with src/, manifest counts, orphans | load ${CLAUDE_SKILL_DIR}/rules/diagnostic-checks.md |
| Category | What It Checks |
|---|---|
| 6. Permission Rules | Unreachable rules detection |
| 7. Schema Compliance | JSON files against schemas |
| 8. Coordination | Multi-worktree lock health, stale locks, sparse paths config |
| 9. Context Budget | Token usage against budget |
| Category | What It Checks | Reference |
|---|---|---|
| 10. CC Version & Channel | Runtime version against minimum required, release channel (stable/beta/alpha) | load ${CLAUDE_SKILL_DIR}/references/version-compatibility.md |
| 11. External Deps | Optional tools (agent-browser, portless) | load ${CLAUDE_SKILL_DIR}/rules/diagnostic-checks.md |
| 12. MCP Status | Enabled/disabled state, credential checks | load ${CLAUDE_SKILL_DIR}/rules/mcp-status-checks.md |
| 13. Plugin Validate | Official CC frontmatter + hooks.json validation (CC >= 2.1.77) | load ${CLAUDE_SKILL_DIR}/rules/diagnostic-checks.md |
| 14. Effort/Model | Detects xhigh effort configured without Opus 4.7 — see below | inline |
CC 2.1.111 added xhigh effort (Opus 4.7 only). Using it with any other model silently falls back to high — producing no error but losing the extra deepening pass documented in the affected skills.
Detection:
/effort is set to xhigh:
.claude/settings.json → effort field$ORCHESTKIT_EFFORT env var (populated by the effort-detector hook).claude/chain/*.json that explicitly set effort: xhigh with a non-4.7 model in scopeWarning format:
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`.
Exit code: Non-zero in --json mode; soft warning in interactive mode.
Load
Read("${CLAUDE_SKILL_DIR}/references/report-format.md")for ASCII report templates, JSON CI output schema, and exit codes.
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).
ork:configure - Configure plugin settingsork:quality-gates - CI/CD integrationsecurity-scanning - Comprehensive auditsLoad on demand with Read("${CLAUDE_SKILL_DIR}/references/<file>") or Read("${CLAUDE_SKILL_DIR}/rules/<file>"):
| File | Content |
|---|---|
rules/diagnostic-checks.md | Bash commands and validation logic per category |
rules/mcp-status-checks.md | Credential validation and misconfiguration detection |
references/remediation-guide.md | Results interpretation and troubleshooting steps |
references/health-check-outputs.md | Sample output per category |
references/skills-validation.md | Skills frontmatter and structure checks |
references/agents-validation.md | Agents frontmatter and tool ref checks |
references/hook-validation.md | Hook registration and bundle checks |
references/memory-health.md | Memory system integrity checks |
references/permission-rules.md | Permission rule detection |
references/schema-validation.md | JSON schema compliance |
references/report-format.md | ASCII report templates and JSON CI output |
references/version-compatibility.md | CC version and channel validation |