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-setup --interactive 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. This repo follows the

core/

adapters/<tool>/

→

install.sh

assembly model (Principle 14): root

CLAUDE.md

AGENTS.md

GEMINI.md

are build products — audit them at their source, never as hand-edited files.

CLAUDE.md

(root) — build product; audit its sources:

core/instructions/*

core/methodology/*

adapters/claude-code/claude.sections-*.md

core/output-styles/*.body.md

and

adapters/claude-code/output-styles/*

(output styles).

```
skills/*/SKILL.md
```
— see shape note below.
```
hooks/*
```
and
```
core/hooks/*
```
(read for cross-checks against
```
CLAUDE.md
```
, do NOT audit hook internals).
```
adapters/claude-code/settings.json
```
and
```
settings.local.json
```
(cross-checks only — duplicated rules, hook declarations matching files in
```
hooks/
```
).
```
adapters/<tool>/mcp/*.json
```
(existence only).
```
adapters/claude-code/keybindings.json
```
(existence only).
```
~/.claude/
```
orphan scan (Principle 12 whitelists).

Skill shape (Principle 14) — a

SKILL.md

containing an

ASSEMBLY:BEGIN

marker is spliced: its source of truth is

core/skills/<x>/logic.md

, and the spliced region in

SKILL.md

is a build product — audit findings inside it map to the

core/

source. A

SKILL.md

with no marker is direct-source: audit it in place. Both shapes coexist by design (27/39 spliced — live count enforced by

validate.sh

Check 7; the other 12 are direct-source by nature — governance/setup skills whose logic references Claude-specific paths), so audit tooling MUST handle both.

Do not audit anything else. Out of scope:

docs/

(except guidelines),

memory/

agents/

, test fixtures, README.

Project mode — audit only these targets:

```
CLAUDE.md
```
at CWD root (the project's own).
```
.claude/skills/*/SKILL.md
```
if present (project-local skills).

.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-style source (

core/output-styles/*.body.md

and

adapters/claude-code/output-styles/*

) 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
```
core/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:

markdown

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

config-audit

NPX Install

Tags

SKILL.md Content

config-audit

Process

Step 0 — Detect execution context

Step 1 — Locate guidelines

Step 2 — Enumerate target files

Step 3 — Run check matrix

Token-budget checks (Principle 4)

Separation-of-concerns checks (Principle 2)

Anti-duplication checks (Principle 3)

OS-correctness checks (Principle 5)

Engram-ownership checks (Principle 9)

Force-read-inline table checks (Principle 10)

Skill format checks (Principle 8)

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

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

Cross-reference checks (general)

Step 4 — Write the report

Step 5 — Print summary to chat

Rules