ktg-plugin-marketplace/plugins/config-audit/commands/config-audit.md

---
name: config-audit
description: Claude Code Configuration Intelligence - audit, analyze, and optimize your configuration
argument-hint: "[posture|feature-gap|fix|rollback|plan|implement|help|discover|analyze|interview|drift|plugin-health|whats-active|status|cleanup]"
allowed-tools: Read, Write, Glob, Grep, Bash, Agent, AskUserQuestion
model: opus
---

# Config-Audit: Claude Code Configuration Intelligence

Analyze, report on, and optimize your Claude Code configuration.

## Router Logic

If a subcommand is provided, route to it:
- `posture` → `/config-audit:posture`
- `feature-gap` → `/config-audit:feature-gap`
- `fix` → `/config-audit:fix`
- `rollback` → `/config-audit:rollback`
- `plan` → `/config-audit:plan`
- `implement` → `/config-audit:implement`
- `help` → `/config-audit:help`
- `discover` → `/config-audit:discover`
- `analyze` → `/config-audit:analyze`
- `interview` → `/config-audit:interview`
- `drift` → `/config-audit:drift`
- `plugin-health` → `/config-audit:plugin-health`
- `whats-active` → `/config-audit:whats-active`
- `status` → `/config-audit:status`
- `cleanup` → `/config-audit:cleanup`

If a scope override is provided (`current`, `repo`, `home`, `full`), use it as the scope type (see Scope Resolution below).

If no subcommand and no scope override: **run the default audit** (see below).

## UX Rules (MANDATORY — apply to every step)

1. **Narrate before acting.** Before each step, tell the user what you're about to do and why, in plain language.
2. **Never show raw output.** All scanner Bash commands MUST use `--output-file <path>` AND `2>/dev/null`. The user should NEVER see JSON, stderr progress lines, or exit codes.
3. **Handle exit codes silently.** Append `; echo $?` to scanner commands. Exit codes 0/1/2 are all expected (PASS/WARNING/FAIL). Only exit code 3 is a real error — tell user: "Scanner encountered an unexpected error. Try `/config-audit posture` for a quick check instead."
4. **Explain, don't dump.** When presenting findings, add plain-language context. "Grade B" alone means nothing — say "Grade B — your CLAUDE.md files are well-structured with minor improvements possible."
5. **Separate signal from noise.** If findings exist in `tests/fixtures/` or `examples/` directories, count them separately and exclude from the main count: "Found 37 findings (66 additional in test fixtures, excluded)."
6. **Context-sensitive next steps.** Don't just list commands — explain what each does and why the user might want it based on their specific results.

## Default Audit (no arguments)

### Step 1: Auto-detect scope and greet the user

If the user provided a scope override (`/config-audit full`, `/config-audit repo`, etc.), use that.

Otherwise, auto-detect:
1. Run `git rev-parse --show-toplevel 2>/dev/null` via Bash
2. If it succeeds and pwd is inside the repo → **repo** scope (use the git root path)
3. If pwd is `$HOME` → **home** scope
4. Otherwise → **current** directory scope

Show the user what's happening:

```
## Config-Audit

Analyzing your Claude Code configuration...

**Scope:** {Repository|Home directory|Current directory} — `{path}`
**What this checks:** CLAUDE.md quality, settings validation, hook safety, rules correctness, MCP server config, import chains, conflicts, and feature coverage.
```

### Step 2: Initialize session

1. Generate session ID: `YYYYMMDD_HHmmss` format
2. Create session directory and findings subdirectory:

```bash
mkdir -p ~/.claude/config-audit/sessions/{session-id}/findings
```

This is a silent infrastructure step — do NOT show output to the user.

### Step 3: Run scanners and posture assessment

Tell the user: **"Running 8 configuration scanners..."**

Run both scanners and posture in a single Bash command:

```bash
node ${CLAUDE_PLUGIN_ROOT}/scanners/scan-orchestrator.mjs <target-path> --output-file ~/.claude/config-audit/sessions/{session-id}/findings/scan-results.json [--full-machine] [--global] 2>/dev/null; node ${CLAUDE_PLUGIN_ROOT}/scanners/posture.mjs <target-path> --json --output-file ~/.claude/config-audit/sessions/{session-id}/posture.json [--full-machine] [--global] 2>/dev/null; echo $?
```

Use `--full-machine` for `full` scope, `--global` for `home` scope. For `repo` and `current`, pass the resolved path directly.

Check the echoed exit code:
- `0`, `1`, or `2` → continue normally
- `3` → tell user: "Scanner encountered an unexpected error. Try `/config-audit posture` for a quick check instead." and stop.

### Step 4: Analyze results

Tell the user: **"Scanners complete. Preparing your results..."**

Read BOTH output files using the Read tool:
- `~/.claude/config-audit/sessions/{session-id}/findings/scan-results.json`
- `~/.claude/config-audit/sessions/{session-id}/posture.json`

Extract these metrics from the JSON:

**From posture.json:**
- `overallGrade` — the health grade (A-F)
- `opportunityCount` — number of unused features detected
- `areas[]` — per-area grades and finding counts (use only quality areas, exclude Feature Coverage)

**From scan-results.json:**
- `aggregate.total_findings` — total findings (test fixture findings are already excluded automatically)
- `fixture_findings` array (if present) — count of findings excluded from test/example directories
- Count findings by severity from `aggregate.counts` (critical, high, medium, low, info)
- Count findings where `autoFixable: true`
- Note total `files_scanned` across scanners

### Step 5: Update state

Write session state (silent — no user output):

```yaml
session_id: "{session-id}"
current_phase: "analyze"
completed_phases: ["discover", "analyze"]
next_phase: "plan"
updated_at: "{ISO timestamp}"
scope_type: "{repo|home|current|full}"
target_path: "{resolved path}"
```

Write to: `~/.claude/config-audit/sessions/{session-id}/state.yaml`

### Step 6: Display results

Present results using this template. Replace all placeholders with actual values. **Adapt the summary sentence based on grade.**

```markdown
### Results

**Health: {overallGrade}** | {qualityAreaCount} areas scanned

{grade-based summary — pick ONE:}
- Grade A: "Excellent — your configuration is correct and well-maintained."
- Grade B: "Strong — your configuration is solid with minor improvements available."
- Grade C: "Decent — your configuration works but has some issues worth addressing."
- Grade D: "Needs work — several configuration issues could affect your Claude Code experience."
- Grade F: "Significant issues found — addressing these will meaningfully improve your workflow."

Scanned {files_scanned} files | {real_finding_count} findings ({severity_breakdown})
{If test_fixture_count > 0: "({test_fixture_count} additional findings in test fixtures were excluded.)"}
{If fixable_count > 0: "{fixable_count} of these can be auto-fixed."}

### Area Breakdown

| Area | Grade | Findings | |
|------|-------|----------|-|
| CLAUDE.md | {grade} | {count} | {one-phrase status} |
| Settings | {grade} | {count} | {status} |
| Hooks | {grade} | {count} | {status} |
| Rules | {grade} | {count} | {status} |
| MCP Servers | {grade} | {count} | {status} |
| Imports | {grade} | {count} | {status} |
| Conflicts | {grade} | {count} | {status} |

{For the status column, use plain language like: "Well structured", "2 minor issues", "Missing trust levels", "No issues", etc.}

{If opportunityCount > 0:}
{opportunityCount} feature opportunities available — run `/config-audit feature-gap` for context-aware recommendations.

### What you can do next

{Include only relevant options based on findings. Explain each one:}

{If fixable_count > 0:}
- **`/config-audit fix`** — Automatically fix {fixable_count} issues. Creates a backup first so you can roll back with one command.

{If real findings > fixable_count:}
- **`/config-audit plan`** — Get a prioritized action plan for the {remaining} issues that need manual attention.

{If grade is C or better:}
- **`/config-audit feature-gap`** — See which features could help your project, and implement the ones you want on the spot.

{If grade is D or F:}
- **`/config-audit fix`** should be your first step — it handles the most impactful issues automatically.

Session saved to: `~/.claude/config-audit/sessions/{session-id}/`
```

## Scope Resolution

| Scope | What gets scanned |
|-------|-------------------|
| `current` | Current directory + parent CLAUDE.md files up to root + `~/.claude/` |
| `repo` | Git repository root + `~/.claude/` |
| `home` | `~/.claude/` global configuration only |
| `full` | Everything: `~/.claude/`, managed paths, all dev dirs under $HOME |

## Error Handling

- If scanner fails (exit 3), tell the user in plain language and suggest `/config-audit posture` as fallback
- If path doesn't exist, tell the user: "That path doesn't exist. Run `/config-audit` without arguments to auto-detect."
- If git command fails for auto-detect, silently fall back to `current` scope
- If no CLAUDE.md found anywhere, explain: "No CLAUDE.md found. This is the main configuration file for Claude Code — creating one is the single highest-impact thing you can do. Run `/config-audit feature-gap` to see what's recommended."