Claudit

---
name: claudit
description: Full multi-phase audit of Claude Code configuration (dispatches research + audit subagents, edits files, may open a PR). Run only when the user explicitly asks to audit or optimize their Claude Code setup.
argument-hint: "[focus-area]"
allowed-tools: Task, Read, Glob, Grep, Bash, Write, Edit, AskUserQuestion
---

# Claudit: Claude Code Configuration Audit

You are the Claudit orchestrator. When the user runs `/claudit` or `/claudit <focus-area>`, execute this 6-phase audit workflow (Phases 0–5). Follow each phase in order. Do not skip phases.

## Phase 0: Environment Detection & Configuration Map

### Step 1: Environment Detection

1. **PROJECT_ROOT**: Run `git rev-parse --show-toplevel 2>/dev/null` via Bash. If this fails (not in a git repo), set PROJECT_ROOT to empty.
2. **HOME_DIR**: Run `echo $HOME` via Bash.

### Step 1.5: Parse Focus Argument

Extract the focus area from `$ARGUMENTS`.

- If `$ARGUMENTS` is empty or missing → set **FOCUS_MODE = false**. Proceed with a full audit (default behavior).
- If `$ARGUMENTS` is provided → set **FOCUS_MODE = true**. Set **FOCUS_AREA** to the user's input.

Map `$ARGUMENTS` to a focus area using the **Focus-Area Mapping** table in `${CLAUDE_PLUGIN_ROOT}/skills/claudit/references/report-templates.md`. Store **FOCUS_AREA** (the interpreted label) and **FOCUS_CATEGORIES** (the relevant scoring categories) for use in later phases. Plugin-name matching is deferred to Step 3.5 (it requires reading `installed_plugins.json`); apply only keyword matching here.

### Step 2: Scope Detection

- If `PROJECT_ROOT` is found → **comprehensive** (global + project)
- If `PROJECT_ROOT` is empty → **global only**

### Step 3: Comprehensive Configuration Scan

Run parallel Glob calls to discover every Claude-related file. Cap at 50 total files — if a project has more, report the cap and proceed with the 50 most recently modified.

**Project-level (if comprehensive):**

| Category | Glob Pattern | Notes |
|----------|-------------|-------|
| Instructions | `{PROJECT_ROOT}/**/CLAUDE.md` | Exclude node_modules, .git, vendor, dist, build via pattern |
| Local instructions | `{PROJECT_ROOT}/CLAUDE.local.md` | Personal/gitignored |
| Rules | `{PROJECT_ROOT}/.claude/rules/**/*.md` | Modular rules with optional path frontmatter |
| Settings (shared) | `{PROJECT_ROOT}/.claude/settings.json` | Team settings |
| Settings (local) | `{PROJECT_ROOT}/.claude/settings.local.json` | Personal project settings |
| Skills | `{PROJECT_ROOT}/.claude/skills/*/SKILL.md` | Project skills |
| Agents | `{PROJECT_ROOT}/.claude/agents/*.md` | Project subagents |
| Memory | `{PROJECT_ROOT}/.claude/MEMORY.md` | Project memory |
| MCP | `{PROJECT_ROOT}/.mcp.json` | Project MCP servers |
| Plugin hooks | `{PROJECT_ROOT}/.claude/plugins/*/hooks/hooks.json` | Plugin-level hooks |

For the Instructions glob, exclude common vendor directories. Use Glob with pattern `**/CLAUDE.md` rooted at PROJECT_ROOT, then filter out paths containing `node_modules`, `.git`, `vendor`, `dist`, or `build`.

**Global-level (always):**

| Category | Path | Notes |
|----------|------|-------|
| Settings | `~/.claude/settings.json` | Global settings |
| Instructions | `~/.claude/CLAUDE.md` | Global instructions (check `~/CLAUDE.md` too as legacy) |
| Rules | `~/.claude/rules/**/*.md` | Personal modular rules |
| Memory | `~/.claude/MEMORY.md` | Global memory |
| MCP | `~/.claude/.mcp.json` | Global MCP servers |
| Plugins | `~/.claude/plugins/installed_plugins.json` | Installed plugins |
| Marketplaces | `~/.claude/plugins/known_marketplaces.json` | Registered marketplaces |
| Managed policy (macOS) | `/Library/Application Support/ClaudeCode/CLAUDE.md` | macOS managed policy |
| Managed policy (Linux) | `/etc/claude-code/CLAUDE.md` | Linux/WSL managed policy |

For each file found, get its line count via `wc -l` (batch multiple files in a single Bash call for efficiency). Quote paths containing spaces (e.g., `/Library/Application Support/...`) in any Bash commands.

### Step 3.5: Resolve Plugin Name Focus

If **FOCUS_MODE is true** and **FOCUS_AREA** is still "Free-form": check whether `$ARGUMENTS` matches an installed plugin name. Read `installed_plugins.json` (if it was found in the config scan) and check whether `$ARGUMENTS` is an exact match or substring of any plugin name. If so, reclassify: set **FOCUS_AREA** to "Specific Plugin: {name}" and **FOCUS_CATEGORIES** to Plugin Health.

### Step 4: Build and Present the Configuration Map

Build a structured manifest grouping files by category with line counts, then present it (and, if **FOCUS_MODE is true**, the focus summary) following the **Configuration Map** template in `${CLAUDE_PLUGIN_ROOT}/skills/claudit/references/report-templates.md`. That template also defines the instruction-file token estimate to display.

### Step 5: Load Decision Memory

Load past audit decisions so they can be injected into audit agents and annotated in the report. Follow the read procedure in `${CLAUDE_PLUGIN_ROOT}/references/decision-memory-protocol.md`.

1. Determine the decisions file path:
   - **Comprehensive scope**: `{PROJECT_ROOT}/.claude/claudit-decisions.json`
   - **Global only**: `~/.cache/claudit/decisions.json`
2. Read the file via Bash: `cat {path} 2>/dev/null`
3. If it exists and parses as valid JSON with `schema_version: 1` → store `decisions` array as **DECISION_HISTORY**
4. If it doesn't exist → set **DECISION_HISTORY** to empty array (first run)
5. Add to the config map display: `Decision Memory: N past decisions` (or `Decision Memory: none (first run)`)

Also run `git config user.name 2>/dev/null` and store as **GIT_USER** for use in Phase 4.

Then tell the user:

```
Phase 1: Building expert context from official Anthropic documentation...
```

---

## Phase 1: Build Expert Context

### Step 1: Load Expert Context

Invoke `/claudit:knowledge all` to retrieve all three knowledge domains (core-config, ecosystem, optimization). The knowledge skill checks cache freshness and auto-refreshes stale domains.

Use the output as **Expert Context** for Phase 2.

Tell the user:
```
Phase 2: Analyzing your configuration against expert knowledge...
```

---

## Phase 2: Expert-Informed Audit

Dispatch audit subagents using the Task tool. Each agent receives the **Expert Context** from Phase 1 plus **only its relevant slice** of the configuration map.

### Build Agent Dispatch Prompts

**For `audit-global`**, include:
- Full Expert Context
- Global slice of config map: global instructions, global rules, global settings, global memory, global MCP, plugins, managed policy paths
- If comprehensive: also include the **content of the project's root CLAUDE.md** (read it and paste the first 200 lines) so the agent can detect cross-scope redundancy. Cap at 200 lines to avoid bloating the agent prompt for very large files.

**For `audit-project`** (comprehensive only), include:
- Full Expert Context
- Project slice of config map: all project instructions (with full paths), rules, settings, skills, agents, memory

**For `audit-ecosystem`**, include:
- Full Expert Context
- Ecosystem slice: all MCP config paths (global + project as applicable), plugins path, plugin hooks paths, paths to all settings files (agent reads them to check for hooks)

### Decision History Injection

If **DECISION_HISTORY** is non-empty, append a `=== DECISION HISTORY ===` block to each audit agent's dispatch prompt (after the Expert Context, before any Focus Directive). Route decisions to agents by **category slug** (not file_stem, which is ambiguous across scopes):

- **audit-global**: decisions where `category_slug` is `security` or `context-efficiency`
- **audit-project**: decisions where `category_slug` is `over-engineering`, `claudemd-quality`, `security`, or `context-efficiency`
- **audit-ecosystem**: decisions where `category_slug` is `mcp-config`, `plugin-health`, or `over-engineering` (for hook/MCP sprawl)

Note: `security` and `context-efficiency` route to multiple agents because both global and project agents contribute to those categories. `over-engineering` routes to both project (CLAUDE.md analysis) and ecosystem (hook/MCP sprawl). This is intentional — agents simply note matching decisions without changing behavior.

Format each decision concisely:

```
=== DECISION HISTORY ===
- [rejected] over-engineering:restated-builtin:CLAUDE.md — "Team onboarding — keeping for junior devs" (acostanzo, 2026-02-15)
- [accepted] security:broad-bash-allow:settings.json — applied fix (acostanzo, 2026-02-15)
=== END DECISION HISTORY ===
```

Agents are instructed to note matching decisions in their findings but never suppress issues.

### Focus Directive Injection

If **FOCUS_MODE is true**, prepend the following block to **each** audit agent's dispatch prompt (before the Expert Context):

```
=== FOCUS DIRECTIVE ===
The user has requested a focused audit on: {FOCUS_AREA}

Instructions:
1. Still perform your full audit scope (all checks in your playbook)
2. For findings RELATED to {FOCUS_AREA}: go deeper — read more files, check more edge cases, provide more detailed analysis with specific line numbers and concrete fix suggestions
3. For findings UNRELATED to {FOCUS_AREA}: perform standard-depth checks but keep findings concise
4. In your output, clearly separate focus-area findings into a "FOCUS FINDINGS" section at the top of your report, followed by "OTHER FINDINGS" for everything else
5. For focus findings, include specific file paths, line numbers, quoted content, and actionable recommendations
=== END FOCUS DIRECTIVE ===
```

The dispatch logic (which agents to send based on scope) does NOT change — always dispatch the same agents as the non-focused path. The Focus Directive is additive context, not a routing change.

### Dispatch Based on Scope

**Global only** → dispatch `audit-global` + `audit-ecosystem` in parallel (2 agents)
**Comprehensive** → dispatch all three in parallel (3 agents)

Use these agent types:
- `subagent_type`: "claudit:audit-global"
- `subagent_type`: "claudit:audit-project"
- `subagent_type`: "claudit:audit-ecosystem"

---

## Phase 3: Scoring & Synthesis

Once all audit agents return, read the scoring rubric:
- Read `${CLAUDE_PLUGIN_ROOT}/skills/claudit/references/scoring-rubric.md`

### Score Each Category

Apply the rubric to the audit findings. For each of the 6 categories:

1. Start at base score of **100**
2. Apply matching **deductions** from the rubric based on audit findings
3. Apply matching **bonuses** from the rubric based on audit findings
4. Clamp to 0-100 range

**Categories and their weights:**

| Category | Weight | Primary Audit Source |
|----------|--------|---------------------|
| Over-Engineering Detection | 20% | audit-project (CLAUDE.md analysis) + audit-ecosystem (hook/MCP sprawl) |
| CLAUDE.md Quality | 20% | audit-project (structure, sections, references, multi-file) |
| Security Posture | 15% | audit-project (permissions) + audit-global (settings) |
| MCP Configuration | 15% | audit-ecosystem (server health, sprawl) |
| Plugin Health | 15% | audit-ecosystem (plugin structure) + audit-global (installed plugins) |
| Context Efficiency | 15% | All audits (token cost estimates, aggregate instruction size) |

**Scope-aware scoring:**
- **Global only**: Exclude CLAUDE.md Quality from scoring (no project to evaluate). Renormalize the remaining 5 category weights proportionally: Over-Engineering = 20/80 = 25%, Security = 15/80 = 18.75%, MCP = 18.75%, Plugin = 18.75%, Context = 18.75%. Note "CLAUDE.md Quality: skipped (no project detected)" in the report.
- **Comprehensive**: Score all 6 categories normally.

### Compute Overall Score

```
overall = sum(category_score * category_weight for all categories)
```

Look up the letter grade from the rubric's grade threshold table.

### Build Recommendations

Compile a ranked list of recommendations from all audit findings using the **Recommendation Ranking** tiers (Critical / High / Medium / Low by point impact) in the scoring rubric loaded above. Include both **issues to fix** (problems in the current config) and **features to adopt** (capabilities from Expert Context the user isn't using).

### Annotate with Decision Memory

If **DECISION_HISTORY** is non-empty, annotate each recommendation with past decision context. Follow the fingerprinting and matching algorithm in `${CLAUDE_PLUGIN_ROOT}/references/decision-memory-protocol.md`.

For each recommendation:

1. **Compute fingerprint**: `{category_slug}:{issue_type}:{file_stem}` using the Issue Type Slugs table in the scoring rubric
2. **Match against DECISION_HISTORY**: same fingerprint → a past decision applies; no match → new
3. **Check staleness** for matched decisions (any of: score impact delta >= 5, Claude Code version changed, age > 90 days, deferred > 30 days)
4. **Annotate** with status and any staleness reason (see Decision Annotation Format in scoring rubric)

**Ordering adjustment**: Present recommendations in this order:
1. New recommendations (no past decision)
2. Stale decisions (past decision exists but flagged for re-evaluation)
3. Previously accepted that recurred (regressions — most urgent, something was fixed but came back)
4. Previously rejected (with annotation showing reason and who decided)

**Never suppress recommendations** based on past decisions. All recommendations appear in the report regardless of decision history.

### Present the Health Report

Render the health report card following the **Health Report Card** template in `${CLAUDE_PLUGIN_ROOT}/skills/claudit/references/report-templates.md`, filling in scope, file counts, decision-memory counts (N past / M stale / K new), the overall score and grade, and the per-category score bars.

### Focus Mode Report Adjustments

If **FOCUS_MODE is true**, apply the **Focus Mode Report Adjustments** in `${CLAUDE_PLUGIN_ROOT}/skills/claudit/references/report-templates.md` (a `Focus:` header line, `◆` markers on focus categories, a Focus Deep Dive section, and focus-first findings order).

After the score card, present:

1. **Focus Deep Dive** (focus mode only) — consolidated focus-area findings from all agents
2. **Critical Issues** — anything scoring below 50 in a category
3. **Top Recommendations** — ranked list with estimated point impact (focus-relevant recommendations first when in focus mode)
4. **New Features to Adopt** — capabilities from Expert Context not currently used
5. **See Also** — operational suggestions based on findings:
   - If the knowledge cache was stale or missing (Phase 1 Step 1 fell through to Step 2): suggest `Run /claudit:refresh periodically to speed up future audits`

---

## Phase 4: Interactive Enhancement

After presenting the report, offer to implement improvements.

### Present Recommendations for Selection

Use AskUserQuestion with `multiSelect: true` to let the user choose which recommendations to apply. Group by priority (Critical, High, Medium, Low). Include the estimated score impact for each.

Format each option as:
- Label: Short description (e.g., "Trim CLAUDE.md redundancy")
- Description: What will change and estimated point impact (e.g., "Remove 5 restated built-in instructions. ~200 token savings. +15 pts Over-Engineering")

Include a "Skip — no changes" option.

### Implement Selected Fixes

For each selected recommendation:

1. Read the target file
2. Apply the fix using Write or Edit tools
3. Briefly explain what changed

Common fix types:
- **CLAUDE.md trimming**: Remove redundant/restated instructions, consolidate duplicates
- **Permission simplification**: Replace granular rules with appropriate permission mode
- **Hook cleanup**: Remove hooks that duplicate built-in behavior, add missing timeouts
- **MCP cleanup**: Remove servers with missing binaries or duplicate functionality
- **Config additions**: Add missing recommended settings or sections
- **Modularization**: Move instructions from monolithic CLAUDE.md to `.claude/rules/` or subdirectory files
- **Cross-scope cleanup**: Remove project-specific instructions from personal config (apply directly, never via PR)
- **@import fixes**: Remove broken imports, fix circular references

**Scope safety for fixes:**
- Project-scoped files (CLAUDE.md, .claude/settings.json, .claude/rules/): eligible for direct edit and PR
- `CLAUDE.local.md`: edit directly, never include in PR (it's gitignored/personal)
- `.claude/settings.local.json`: edit directly, never include in PR (it's personal/local)
- `~/.claude/` files: edit directly, never include in PR (they're personal)

### Capture Decisions

After implementing selected fixes (or if user selected "Skip — no changes"), record decisions to memory. Follow the write procedure in `${CLAUDE_PLUGIN_ROOT}/references/decision-memory-protocol.md`.

**If the user selected specific recommendations (not "Skip"):**

1. Record each **selected** recommendation as `action: "accepted"` with its computed fingerprint
2. For **unselected** recommendations (items the user did not select), present a single follow-up AskUserQuestion:

   ```
   Some recommendations were not selected. How should claudit treat them in future audits?
   ```

   Use `multiSelect: true` with options for each unselected recommendation:
   - `"<recommendation>" — Rejected (intentional / false positive)`
   - `"<recommendation>" — Deferred (will address later)`

   Include a `"Don't record — treat as new next time"` option.

   - If 3 or fewer items are marked as rejected, ask a follow-up for optional reasons (single AskUserQuestion with text per item)
   - Record rejected/deferred items with their respective actions

3. For each decision, populate:
   - `fingerprint`: computed in the annotation step
   - `decided_by`: **GIT_USER** from Phase 0
   - `timestamp`: current ISO 8601 timestamp
   - `context`: current claudit version, Claude Code version, score impact

4. Merge new decisions with existing DECISION_HISTORY (upsert by fingerprint) and write to the decisions file path determined in Phase 0

**If the user selected "Skip — no changes":** Still offer the follow-up AskUserQuestion for categorizing recommendations — the user may want to record rejections ("I don't want to see these again") even without applying any fixes. If the user selects "Don't record" or dismisses the prompt, no decisions are recorded.

### Re-Score and Show Delta

After implementing fixes:

1. Re-score only the affected categories
2. Show before/after:

```
Score Delta:
  Over-Engineering     65 → 85  (+20)
  CLAUDE.md Quality    70 → 88  (+18)
  Overall              72 → 84  (+12)  Grade: C → B
```

---

## Phase 5: PR Delivery

Read `${CLAUDE_PLUGIN_ROOT}/skills/claudit/references/pr-delivery.md` and follow the PR delivery instructions.

---

## Error Handling

- If a research agent fails to fetch docs, continue with available knowledge and note the gap
- If an audit agent can't read a config file (doesn't exist), that's valid data — report it as "not configured"
- If the project has no `.claude/` directory at all, focus the audit on global config and recommend project-level setup
- If no issues are found (score 90+), congratulate the user and suggest any new features to explore
- If Glob returns too many files (>50), cap and note the truncation

## Important Notes

- **Never auto-apply changes** — always present recommendations and let the user choose
- **Quote specific lines** when showing what would change in instruction files
- **Be opinionated** about over-engineering — this is the plugin's core value proposition
- **Show token savings** whenever removing content from instruction files or other config
- **The Expert Context makes this audit unique** — always highlight features the user isn't using yet
- **Respect scope boundaries** — project config is the team contract; personal config is personal
- **Only project-scoped files go in PRs** — CLAUDE.local.md and ~/.claude/ changes are always local-only