/claude-health

name: claude-health
description: "Claude Code config health check + plugin sync. Use when: auditing .claude/ structure, checking naming, verifying hook setup, detecting plugin version drift, syncing installed assets. Not for: skill quality (use skill-health-check), code review (use codex-code-review). Output: health report + fix recommendations."
allowed-tools: Read, Grep, Glob, Bash(ls:*), Bash(find:*), Bash(wc:*), Bash(du:*), Bash(rm:*), Bash(git:*), Bash(/bin/bash:*), Bash(node:*)
context: fork

Claude Health Check

Trigger

• Keywords: health check, .claude check, config audit, lint .claude, claude health, plugin sync, version drift, upgrade check, doctor

When NOT to Use

• Code review (use `/codex-review-fast`)
• Doc review (use `/codex-review-doc`)
• Security review (use `/codex-security`)

Scope

| Argument | Description | |----------|-------------| | `--scope hygiene` | Only run C1-C7 hygiene checks | | `--scope sync` | Only run S1-S3 sync checks and the S4 plugin-copies inventory | | `--scope budget` | Only run the Instruction Budget Module (B1-B3) | | `--scope all` | Run every module — hygiene, sync and budget (**default**) |

Workflow

[--scope] → Select modules → Scan → Classify → Report → Fix suggestions
               │                                  │
       ┌───────┴───────┐                     P0/P1/P2
       ▼               ▼                    + fix commands
  Hygiene (C1-C7)  Sync (S1-S3)

Hygiene Module — Checks (7 items)

| # | Check | Method | Criteria | |---|-------|--------|----------| | 1 | Junk files | `find .claude/ -name ".DS_Store" -o -name "*.zip" -o -name ".tmp*"` | Any exists → P1 | | 2 | .gitignore exists | `ls .claude/.gitignore` | Missing → P1 | | 3 | .gitignore completeness | Read `.claude/.gitignore`, compare required items | Missing required → P2 | | 4 | Naming consistency | Scan all `skills/*/` for `reference` vs `references` | Inconsistent → P2 | | 5 | README count sync | Count actual vs README description | Mismatch → P2 | | 6 | Command-Skill pairing | Each core skill should have corresponding command | Missing → P1 | | 7 | Cache size | `du -sh .claude/cache/` | > 50M → P2 |

Check 1: Junk Files

find .claude/ -name ".DS_Store" -o -name "*.zip" -o -name ".tmp*" 2>/dev/null

• Has results → **P1**: List files, suggest deletion
• No results → ✅

Check 2-3: .gitignore

ls .claude/.gitignore 2>/dev/null || echo "MISSING"

Missing → **P1**. If exists, read content and compare required items:

| Required Item | Reason | |---------------|--------| | `.DS_Store` | macOS generates continuously | | `settings.local.json` | Personal config | | `cache/` | Runtime cache | | `.tmp*` | Temp files | | `*.tmp` | Temp files (suffix variant) | | `*.zip` | Backup archives |

Missing any → **P2**

Check 4: Naming Consistency

# Scan all skill subdirectories
for dir in .claude/skills/*/; do
  if [ -d "${dir}reference" ]; then echo "INCONSISTENT: ${dir}reference"; fi
done

Has `reference/` (singular) → **P2**, suggest renaming to `references/`

Check 5: README Count Sync

# Count actual items
ls .claude/commands/ 2>/dev/null | wc -l
ls .claude/skills/ 2>/dev/null | wc -l
ls .claude/agents/ 2>/dev/null | wc -l
ls .claude/rules/ 2>/dev/null | wc -l
ls .claude/hooks/*.sh 2>/dev/null | wc -l

Extract counts from README.md, compare. Mismatch → **P2**

Check 6: Command-Skill Pairing

Scan all `skills/*/SKILL.md`, exclude these types, then check for corresponding command:

| Exclude Type | Examples | Reason | |--------------|----------|--------| | Domain KB | `portfolio`, `aum` | Referenced by other skills, no standalone entry | | External | `agent-browser` | Not maintained by this project |

Remaining skills without command → **P1**

Check 7: Cache Size

du -sh .claude/cache/ 2>/dev/null

• \> 50M → **P2**, suggest cleanup
• ≤ 50M → ✅

Sync Module — Checks (S1-S3)

> Only runs when `--scope sync` or `--scope all` (default).

S1: Version Check

| # | Check | Method | Criteria | |---|-------|--------|----------| | S1.1 | Manifest exists | Read `.sd0x/install-state.json` | Missing → P1 | | S1.2 | Manifest parseable | JSON.parse | Parse error → P1 | | S1.3 | `schema_version` current | `== 1` | Mismatch → P2 | | S1.4 | `plugin_version` matches | manifest vs `.claude-plugin/plugin.json` or `package.json` | Mismatch → P1 | | S1.5 | Manifest completeness | Has `rules` + `hook_scripts` + `scripts` keys | Missing key → P2 (`MANIFEST_GAP`) |

**Plugin version resolution** (priority order):

.claude-plugin/plugin.json → package.json → "unknown"

**Plugin source location** (same as `/install-rules` Phase 1):

Glob: ~/.claude/plugins/**/sd0x-dev-flow/rules/auto-loop.md
Glob: ${REPO_ROOT}/node_modules/sd0x-dev-flow/rules/auto-loop.md
Fallback: @rules/auto-loop.md (plugin-relative)

S2: Component Classification

For each managed component (rules, hooks, scripts), compute 3 hashes and classify:

manifest_hash  = manifest[category][filename].hash    # null if missing
local_hash     = git hash-object --no-filters <local-path>  # null if file missing
plugin_hash    = git hash-object --no-filters <plugin-path>  # source of truth

**Classification table** (read-only diagnostic; maps to install-rules states for delegation):

| Doctor State | Condition | Severity | install-rules Equivalent | |-------|-----------|----------|--------------------------| | `OK` | local == manifest == plugin | ✅ | `SKIP` | | `MISSING` | local_hash is null, plugin exists | P1 | `FRESH_INSTALL` | | `OUTDATED` | local == manifest, plugin != manifest | P1 | `AUTO_UPDATE` | | `LOCAL_MODIFIED` | local != manifest, plugin == manifest | ✅ | `KEEP_LOCAL` | | `CONFLICT` | local != manifest, plugin != manifest | P2 | `CONFLICT` | | `LEGACY` | manifest_hash is null, local exists | P2 | `LEGACY` | | `MANIFEST_GAP` | manifest category key missing | P2 | N/A | | `TOMBSTONED`