Config Audit

config-audit

Audits the repo's Claude configuration against docs/config-guidelines.md. Read-only.

Produces audit-report.md consumed by config-refactor.

Triggers: /config-audit, audit config, audit claude config, review configuration, configuration health check

---

Process

Step 0 — Detect execution context

Determine which mode to run in (per Principle 13):

• Global mode — CWD is the claude-config repo. Detected when ALL of:
• install.sh exists at CWD root.
• skills/_shared/ exists at CWD root.
• OR basename of CWD matches claude-config or agent-config.
• Project mode — CWD is any other directory containing a CLAUDE.md at root.
• No-config mode — CWD has no CLAUDE.md. Stop and print:

No CLAUDE.md found in this directory. Run project-claude-init (future) or create one manually before auditing.

Record the detected mode and proceed. The mode controls Step 1 (guidelines source) and Step 2 (target file enumeration).

Step 1 — Locate guidelines

Global mode — read docs/config-guidelines.md from CWD. This file is the spec.

Project mode — read ~/.claude/docs/config-guidelines.md (the deployed global spec) as the read-only baseline. The project's own CLAUDE.md is the audit target, not a spec source.

If the guidelines file does not exist in either mode:

• Emit CRITICAL "Guidelines file missing — cannot audit. In global mode, create

docs/config-guidelines.md. In project mode, run install.sh from the claude-config repo on this machine."

• Stop. Do not produce a partial report.

Step 2 — Enumerate target files

Global mode — audit only these targets, in this order:

1. CLAUDE.md (root) 2. output-styles/*.md 3. skills/*/SKILL.md 4. hooks/* (read for cross-checks against CLAUDE.md, do NOT audit hook internals) 5. settings.json and settings.local.json (cross-checks only — duplicated rules, hook declarations matching files in hooks/) 6. mcp/*.json (existence only) 7. keybindings.json (existence only) 8. ~/.claude/ orphan scan (Principle 12 whitelists).

Do not audit anything else. Out of scope: docs/ (except guidelines), memory/, agents/, test fixtures, README.

Project mode — audit only these targets:

1. CLAUDE.md at CWD root (the project's own). 2. .claude/skills/*/SKILL.md if present (project-local skills). 3. .claude/settings.json and .claude/settings.local.json if present.

Out of scope in project mode: ~/.claude/ runtime directories, the global CLAUDE.md, anything outside the project root. The global layer is read-only reference for duplication checks (Principle 13 anti-duplication rule).

Step 3 — Run check matrix

Apply every check below. For each finding, record:

• severity: CRITICAL | WARNING | SUGGESTION
• file: absolute path
• line (if applicable)
• rule: the principle name from guidelines (e.g. "Principle 4 — Token budget")
• finding: one-sentence description
• fix_hint: one-sentence suggested action

Token-budget checks (Principle 4)

For each target file:

• Count lines.
• Compare against the file's soft and hard limit from the guidelines table.
• Over hard limit → CRITICAL.
• Over soft limit → WARNING.

Separation-of-concerns checks (Principle 2)

Scan CLAUDE.md for:

• Sections that match orchestrator/agent-specific scope (e.g. "Bind this to … agent or

rule only", explicit sub-agent contracts, SDD model assignments). If found and no agents/<name>.md exists, raise WARNING "Move scoped section to agents/".

• A manual skill catalog (table listing 5+ skills with descriptions). If found, raise

WARNING "Remove manual skill catalog — harness auto-discovers skills (Principle 2)".

Scan each output-styles/*.md for:

• Bullets that begin with verbs like "Verify", "Never agree", "Propose alternatives",

"Explain why with evidence". These restate CLAUDE.md behavior rules → WARNING.

• Prescriptive technical opinions ("X over Y", "always use X", "concepts > code"). Raise

WARNING with rule "Principle 7 — Output styles are tone, not behavior".

Anti-duplication checks (Principle 3)

Build a normalized fingerprint of each rule line in CLAUDE.md and each rule line in output styles and skills. A "rule line" is a top-level bullet inside a ## Rules-like section.

For each pair that exceeds 70% token overlap:

• If one of the two files is a hook and the other is CLAUDE.md → CRITICAL "Rule

duplicated between hook and CLAUDE.md (Principle 3.1)".

• If CLAUDE.md and an output-style → WARNING "Rule duplicated (Principle 3.2)".
• If two skills → SUGGESTION "Extract shared rule into skills/_shared/".

OS-correctness checks (Principle 5)

Scan CLAUDE.md for these substrings (case-insensitive): brew, apt-get, cat , find , sed , grep (as Bash command, not the Grep tool), ls .

For each hit:

• If the line is not prefixed by an OS-specific marker ("On Linux/macOS only:", "WSL:", etc.)

→ WARNING "OS-specific tooling assumed without declaration (Principle 5)".

Engram-ownership checks (Principle 9)

Scan CLAUDE.md for headings or bullets that look like the engram protocol payload:

• "PROACTIVE SAVE TRIGGERS"
• "SESSION START PROTOCOL"
• "SESSION CLOSE PROTOCOL"
• "AFTER COMPACTION"
• mem_save format template (a multi-bullet block describing title, type, content)

If found AND the same content is also injected by a SessionStart hook → CRITICAL "Engram protocol duplicated between hook and CLAUDE.md (Principle 9)".

If found AND no hook injects it → WARNING "Engram protocol in CLAUDE.md but no hook injects it; verify ownership".

Force-read-inline table checks (Principle 10)

Find the "Skills — Force-read inline" table (or any table at root of CLAUDE.md listing skills with paths). Check:

• More than 4 entries → WARNING "Force-read table exceeds 4 entries".
• Title is "Skills catalog", "Auto-load skills", or any wording that implies full catalog

→ WARNING "Rename to 'Skills — Force-read inline'".

• Any path that does not exist on disk → CRITICAL "Force-read entry points to missing

file".

Skill format checks (Principle 8)

For each skills/*/SKILL.md:

• Missing YAML frontmatter → CRITICAL.
• Missing name, description, or format in frontmatter → CRITICAL.
• format value not in {procedural, reference, anti-pattern} → CRITICAL.
• Missing **Triggers**: line in body → WARNING.
• Section contract for declared format not met (see docs/format-types.md) → WARNING.

Two-layer duplication checks (Principle 13, project mode only)

For each rule line in the project CLAUDE.md:

• Normalize and fingerprint as in the anti-duplication check.
• Compare against rules in the global ~/.claude/CLAUDE.md.
• Token overlap > 70% AND no ## Overrides global block declares the rule →

CRITICAL "Project CLAUDE.md restates global rule without override declaration (Principle 13)".

• If a project rule contradicts a global rule (semantic opposite) and no override

block is declared → CRITICAL "Project CLAUDE.md contradicts global without override (Principle 13)".

In global mode this check is skipped (only one layer present).

Orphan checks in ~/.claude/ (Principle 12, global mode only)

List the entries directly under ~/.claude/. For each entry:

• If the name is in the known-runtime whitelist (Principle 12) → ignore.
• If the name is in the known-deployed whitelist → ignore.
• Otherwise → WARNING "Orphan in ~/.claude/: <name>. Investigate origin or remove."

Do not recurse into runtime directories. The check is one level deep.

Cross-reference checks (general)

• For every absolute path mentioned in CLAUDE.md (e.g. ~/.claude/skills/foo/SKILL.md),

verify the corresponding repo path exists. If not → SUGGESTION "Dead reference".

• For every skill name referenced inside another SKILL.md body, verify it exists in

skills/. If not → SUGGESTION "Reference to missing skill".

Step 4 — Write the report

Write the result to audit-report.md at the repo root with this exact structure:

# Configuration Audit Report

Generated: YYYY-MM-DD HH:MM
Guidelines version: <git short hash of docs/config-guidelines.md if available, else "untracked">

## Summary

- CRITICAL: <count>
- WARNING:  <count>
- SUGGESTION: <count>

## Findings

### CRITICAL

#### [CRIT-1] <one-line title>
- File: `<path>` (line <n> if applicable)
- Rule: <principle name>
- Finding: <one sentence>
- Fix hint: <one sentence>

(repeat for each CRITICAL)

### WARNING

(same shape)

### SUGGESTION

(same shape)

## No-issues sections

List target files that produced zero findings. One per line.

## Next step

Run `/config-refactor` to apply fixes. The refactor skill reads this file as its spec.

Use stable IDs (CRIT-1, WARN-1, SUGG-1 …) so config-refactor can reference them exactly.

Step 5 — Print summary to chat

After writing the report, print a compact summary to the user:

• The three counts.
• The top 3 CRITICAL findings (title + file only).
• The path to the full report.
• One closing line: "Run /config-refactor to apply, or open the report to triage first."

Do NOT propose fixes inline. The refactor skill owns that.

---

Rules

• Read-only. This skill never edits any file other than audit-report.md.
• Never invent rules. Every finding cites a principle from docs/config-guidelines.md.
• If a check would produce more than 20 findings of the same severity for the same file,

collapse them into one finding ("File has 23 lines exceeding token budget by …") to keep the report readable.

• Deterministic ordering: CRITICAL before WARNING before SUGGESTION; inside each, ordered

by file path then line number.

• The report MUST be self-contained — config-refactor reads only audit-report.md and

docs/config-guidelines.md, never the original conversation.

• Audit only the files listed in Step 2. Do not expand scope mid-run.