config-audit

Files (2)

• README.md
• SKILL.md

SKILL.md (first lines)

# Config Stack Audit

A comprehensive, prompt-driven audit of the entire Claude Code configuration at `~/.claude/` and all project-level `.claude/` directories. Produces a scored report with delta tracking across runs and a self-improving heuristics loop.

## 1. Modes

Parse the arguments passed to `/config-audit`:

| Flag | Behavior |
|------|----------|
| (no flag) or `--full` | Run all 7 dimensions. Default mode. |
| `--quick` | Run dimensions 1-3 only (Duplication, Security, Staleness). |
| `--dimension N` | Run only dimension N (1-7). Still requires inventory phase. |
| `--fix` | After report generation, enter auto-remediation flow for automatable findings. Can combine with any mode above. |

**First-run handling:** Before starting, check if `~/.claude/config-audit-reports/` contains any previous reports. If not, this is a baseline audit — skip delta comparison in Section 5 and note "Baseline audit — no prior data for comparison" in the Delta section of the report.

## 2. Inventory Phase

**Runs for ALL modes.** Build the complete config inventory before any analysis.

Execute these tool calls (parallelize where independent):

**Batch 1 — Global config (all parallel):**
1. `Glob("~/.claude/rules/*.md")` — list all global rules
2. `Glob("~/.claude/agents/*.md")` — list all global agents
3. `Glob("~/.claude/skills/*/")` — list all global skill directories
4. `Glob("~/.claude/commands/*.md")` — list all global commands
5. `Read("~/.claude/settings.json")` — extract hooks, permissions, MCP config
6. `Read("~/.claude/mcp.json")` — extract MCP server registrations

**Batch 2 — Project-level config (all parallel):**
7. `Glob("~/projects/**/.claude/settings.json")` — all project settings
8. `Glob("~/projects/**/.claude/rules/*.md")` — all project rules
9. `Glob("~/projects/**/.claude/agents/*.md")` — all project agents
10. `Glob("~/projects/**/.claude/skills/*/")` — all project skills
11. `Glob("~/projects/**/.claude/commands/*.md")` — all project commands
12. `Glob("~/projects/**/CLAUDE.md")` — all CLAUDE.md files

> Adjust the `~/projects/**` glob root to wherever you keep your repositories if it differs.

Store the file lists and counts. These are the inputs for all dimension analyses.

**Token discipline:**
- Use Glob/Grep for discovery — never `find` or `ls` via Bash
- Only Read file contents when comparison requires it (e.g., duplication checks)
- Read first 100 lines max per file during comparison
- Use parallel Agent calls (model: haiku) for independent dimensions to keep main context clean
- Budget: `--quick` ~20-30K tokens, `--full` ~40-60K tokens

## 2a. Project Scope Policy

Not every repo earns full config scrutiny. Scoping prevents coverage dimensions (GAP/SEC) from inflating with every throwaway experiment — a recurring false signal (see heuristic H-003). Apply these tiers:

| Tier | What | Expectation | Audit treatment |
|------|------|-------------|-----------------|
| **Client / secret-handling** | Active deliverables that handle secrets or sensitive data | MUST have `CLAUDE.md` + `.primeignore` + `.claude/settings.json` with `.env*`/credentials/secrets deny rules | Full scope; missing config = GAP/SEC finding |
| **Internal tools (shipped)** | Used but lower-risk | SHOULD have `CLAUDE.md`; deny rules if secrets present | Full scope; severity scaled down |
| **Experiment / scratch / superseded** | scratch dirs, empty repos, superseded versions | None required | **EXEMPT** from GAP/SEC |

**Exemption mechanism:** A project is out of scope for the dimensions listed in its marker if EITHER:
- it contains an `.audit-ignore` file at its root (format: `exempt_dimensions: GAP, SEC` — comma-separated dimension codes, or `ALL`), OR
- it lives under a scratch/experiments root (e.g. `~/projects/experiments/`).

During the inventory phase, record exempt projects separately and list them under "Suppressed Findings" in the report (e.g., "3 projects exempt by `.audit-ignore`"). Do not generate GAP/SEC findings for exempt projects. New projects start compliant if your project scaffolding sets up the deny-ruled `settings.json` by default.

## 3. The 7 Audit Dimensions

Each dimension produces: (a) findings with severity and deterministic IDs, (b) a score 1-10.

### Dimension Dependency Graph

```
Inventory Phase (must complete first)
     │
     ├──► Dim 1: Duplication  ─┐
     ├──► Dim 2: Security     ─┤  Batch A — launch as parallel Agents (haiku)
     ├──► Dim 3: Staleness    ─┤
     └──► Dim 4: Consistency  ─┘
                                │
                                ▼  (wait for Batch A results)
     ├──► Dim 5: Coverage Gaps ─┐
     ├──► Dim 6: Optimization  ─┤  Batch B — launch as parallel Agents (haiku)
     └──► Dim 7: Innovation    ─┘
```

- **`--quick`**: Run dims 1-3 from Batch A only. Skip dim 4 and all of Batch B.
- **`--dimension N`**: Run only that dimension (still requires inventory).

---

### Dimension 1: Duplication

**What to check:** Identical or diverged copies of rules, agents, skills, and commands across the global ↔ project layers.

**How to check:**
1. For each file type (rules, agents, commands), extract filenames from the global inventory and each project inventory.
2. Find same-named files across layers.
3. For each match, Read first 100 lines of both files.
4. Classify as:
   - **IDENTICAL** — content matches → recommend consolidating to global
   - **DIVERGED** — same name, different content → recommend syncing or documenting the fork
   - **INTENTIONAL FORK** — file contains `# audit:ignore` or `# audit:ignore:DUP` → suppress

**Scoring rubric:**
| Score | Criteria |
|-------|----------|
| 10 | Zero untracked duplicates across all layers |
| 7 | Duplicates exist but all are marked intentional via `audit:ignore` |
| 4 | Multiple untracked diverged copies in active projects |
| 1 | Widespread unmanaged duplication with security-critical divergences (e.g., security rules missing sections) |

**Finding ID format:** `DUP-{project-slug}-{dir}-{filename}`
Example: `DUP-devenv-rules-security-md`

---

### Dimension 2: Security

From PatriotAgenticLLC/better_claude_skillz, MIT.

More from PatriotAgenticLLC/better_claude_skillz