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

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

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:

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):

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.

### 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."