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)
Overview
The /ork:doctor command performs comprehensive health checks on your OrchestKit installation. It auto-detects installed plugins and validates 13 categories:
- Installed Plugins - Detects ork plugin
- Skills Validation - Frontmatter, references, token budget (dynamic count)
- Agents Validation - Frontmatter, tool refs, skill refs (dynamic count)
- Hook Health - Registration, bundles, async patterns
- Permission Rules - Detects unreachable rules
- Schema Compliance - Validates JSON files against schemas
- Coordination System - Checks lock health and registry integrity
- Context Budget - Monitors token usage against budget
- Memory System - Graph memory health
- Claude Code Version & Channel - Validates CC >= 2.1.86, detects release channel (stable/beta/alpha)
- External Dependencies - Checks optional tool availability (agent-browser)
- MCP Status - Active vs disabled vs misconfigured, API key presence for paid MCPs
- Plugin Validate - Runs
claude plugin validate for official CC frontmatter + hooks.json validation (CC >= 2.1.77)
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
Tip (CC 2.1.69+): After fixing issues found by doctor, run /reload-plugins to activate plugin changes without restarting your session.
Quick Start
/ork:doctor # Standard health check
/ork:doctor -v # Verbose output
/ork:doctor --json # Machine-readable for CI
CLI Options
| Flag |
Description |
-v, --verbose |
Detailed output per check |
--json |
JSON output for CI integration |
--category=X |
Run only specific category |
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
| 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 |
Categories 4-5: System Health
| 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 |
Categories 6-9: Infrastructure
| 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 |
Categories 10-13: Environment
| 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 |
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).
Related Skills
ork:configure - Configure plugin settingsork:quality-gates - CI/CD integrationsecurity-scanning - Comprehensive audits
References
Load 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 |
Converted and distributed by TomeVault — claim your Tome and manage your conversions.
1---2name: doctor-33description: OrchestKit doctor for health diagnostics. Use when running checks on plugin health, diagnosing problems, or troubleshooting issues. Use when this capability is needed.4---56# OrchestKit Health Diagnostics78## Argument Resolution910```python11FLAGS = "$ARGUMENTS" # Full argument string, e.g., "--verbose" or "--json"12FLAG = "$ARGUMENTS[0]" # First token: -v, --verbose, --json, --category=X13# $ARGUMENTS[0], $ARGUMENTS[1] for indexed access (CC 2.1.59)14```1516## Overview1718The `/ork:doctor` command performs comprehensive health checks on your OrchestKit installation. It auto-detects installed plugins and validates 13 categories:19201. **Installed Plugins** - Detects ork plugin212. **Skills Validation** - Frontmatter, references, token budget (dynamic count)223. **Agents Validation** - Frontmatter, tool refs, skill refs (dynamic count)234. **Hook Health** - Registration, bundles, async patterns245. **Permission Rules** - Detects unreachable rules256. **Schema Compliance** - Validates JSON files against schemas267. **Coordination System** - Checks lock health and registry integrity278. **Context Budget** - Monitors token usage against budget289. **Memory System** - Graph memory health2910. **Claude Code Version & Channel** - Validates CC >= 2.1.86, detects release channel (stable/beta/alpha)3011. **External Dependencies** - Checks optional tool availability (agent-browser)3112. **MCP Status** - Active vs disabled vs misconfigured, API key presence for paid MCPs3213. **Plugin Validate** - Runs `claude plugin validate` for official CC frontmatter + hooks.json validation (CC >= 2.1.77)3334## When to Use3536- After installing or updating OrchestKit37- When hooks aren't firing as expected38- Before deploying to a team environment39- When debugging coordination issues40- After running `npm run build`4142> **Tip (CC 2.1.69+):** After fixing issues found by doctor, run `/reload-plugins` to activate plugin changes without restarting your session.4344## Quick Start4546```bash47/ork:doctor # Standard health check48/ork:doctor -v # Verbose output49/ork:doctor --json # Machine-readable for CI50```5152## CLI Options5354| Flag | Description |55|------|-------------|56| `-v`, `--verbose` | Detailed output per check |57| `--json` | JSON output for CI integration |58| `--category=X` | Run only specific category |5960## Health Check Categories6162> **Detailed check procedures**: Load `Read("${CLAUDE_SKILL_DIR}/rules/diagnostic-checks.md")` for bash commands and validation logic per category.63>64> **MCP-specific checks**: Load `Read("${CLAUDE_SKILL_DIR}/rules/mcp-status-checks.md")` for credential validation and misconfiguration detection.65>66> **Output examples**: Load `Read("${CLAUDE_SKILL_DIR}/references/health-check-outputs.md")` for sample output per category.6768### Categories 0-3: Core Validation6970| Category | What It Checks | Reference |71|----------|---------------|-----------|72| **0. Installed Plugins** | Auto-detects ork plugin, counts skills/agents | load `${CLAUDE_SKILL_DIR}/rules/diagnostic-checks.md` |73| **1. Skills** | Frontmatter, context field, token budget, links | load `${CLAUDE_SKILL_DIR}/references/skills-validation.md` |74| **2. Agents** | Frontmatter, model, skill refs, tool refs | load `${CLAUDE_SKILL_DIR}/references/agents-validation.md` |75| **3. Hooks** | hooks.json schema, bundles, async patterns | load `${CLAUDE_SKILL_DIR}/references/hook-validation.md` |7677### Categories 4-5: System Health7879| Category | What It Checks | Reference |80|----------|---------------|-----------|81| **4. Memory** | .claude/memory/ exists, decisions.jsonl integrity, queue depth | load `${CLAUDE_SKILL_DIR}/references/memory-health.md` |82| **5. Build** | plugins/ sync with src/, manifest counts, orphans | load `${CLAUDE_SKILL_DIR}/rules/diagnostic-checks.md` |8384### Categories 6-9: Infrastructure8586| Category | What It Checks |87|----------|---------------|88| **6. Permission Rules** | Unreachable rules detection |89| **7. Schema Compliance** | JSON files against schemas |90| **8. Coordination** | Multi-worktree lock health, stale locks, sparse paths config |91| **9. Context Budget** | Token usage against budget |9293### Categories 10-13: Environment9495| Category | What It Checks | Reference |96|----------|---------------|-----------|97| **10. CC Version & Channel** | Runtime version against minimum required, release channel (stable/beta/alpha) | load `${CLAUDE_SKILL_DIR}/references/version-compatibility.md` |98| **11. External Deps** | Optional tools (agent-browser, portless) | load `${CLAUDE_SKILL_DIR}/rules/diagnostic-checks.md` |99| **12. MCP Status** | Enabled/disabled state, credential checks | load `${CLAUDE_SKILL_DIR}/rules/mcp-status-checks.md` |100| **13. Plugin Validate** | Official CC frontmatter + hooks.json validation (CC >= 2.1.77) | load `${CLAUDE_SKILL_DIR}/rules/diagnostic-checks.md` |101102## Report Format103104> Load `Read("${CLAUDE_SKILL_DIR}/references/report-format.md")` for ASCII report templates, JSON CI output schema, and exit codes.105106## Interpreting Results & Troubleshooting107108> 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).109110## Related Skills111112- `ork:configure` - Configure plugin settings113- `ork:quality-gates` - CI/CD integration114- `security-scanning` - Comprehensive audits115116## References117118Load on demand with `Read("${CLAUDE_SKILL_DIR}/references/<file>")` or `Read("${CLAUDE_SKILL_DIR}/rules/<file>")`:119| File | Content |120|------|---------|121| `rules/diagnostic-checks.md` | Bash commands and validation logic per category |122| `rules/mcp-status-checks.md` | Credential validation and misconfiguration detection |123| `references/remediation-guide.md` | Results interpretation and troubleshooting steps |124| `references/health-check-outputs.md` | Sample output per category |125| `references/skills-validation.md` | Skills frontmatter and structure checks |126| `references/agents-validation.md` | Agents frontmatter and tool ref checks |127| `references/hook-validation.md` | Hook registration and bundle checks |128| `references/memory-health.md` | Memory system integrity checks |129| `references/permission-rules.md` | Permission rule detection |130| `references/schema-validation.md` | JSON schema compliance |131| `references/report-format.md` | ASCII report templates and JSON CI output |132| `references/version-compatibility.md` | CC version and channel validation |133134---135> Converted and distributed by [TomeVault](https://tomevault.io/claim/yonatangross) — claim your Tome and manage your conversions.136<!-- tomevault:4.0:skill_md:2026-04-11 -->
tomevault-io