---
name: claude-md-guardian
model: sonnet
description: Produces a CLAUDE.md health report listing conflicts, redundancies, and stale rules across the global, project, and subdirectory hierarchy — and optionally installs a PreToolUse hook to block unauthorized modifications going forward (the enforcement mechanism the audit-only `dojo-craft:community-claude-md-guardian` variant lacks). Use when: "agent behavior is inconsistent", "just merged branches that touched CLAUDE.md", "onboarding a new agent", "after applying learnings", "weekly maintenance".
license: proprietary
category: repo-docs-health

inputs:
  - name: context
    type: string
    description: Trigger context — branch merge, onboarding, weekly maintenance, or behavior inconsistency
    required: false
outputs:
  - name: health_report
    type: string
    description: CLAUDE.md health report listing conflicts, redundancies, and stale rules across global, project, and subdirectory hierarchy
---

# CLAUDE.md Guardian

## I. Philosophy

CLAUDE.md is the agent's behavioral contract. When rules drift, conflict, or
accumulate without review, agent behavior becomes unpredictable. The guardian
skill treats CLAUDE.md as a living document that requires the same rigor as
source code: validation, consistency checks, and protection against unreviewed
modification.

Three failure modes threaten CLAUDE.md health:
1. **Drift** -- Rules added to one CLAUDE.md but not propagated to related files.
2. **Conflict** -- Contradictory rules across global, project, and subdirectory files.
3. **Bloat** -- Accumulated rules that are no longer relevant or are redundant.

Mechanical enforcement (hooks) prevents unauthorized modification. Periodic
audits catch semantic drift that mechanics cannot detect.

## II. When to Use

- After applying learnings from `reflect-and-learn` to verify no conflicts were introduced.
- During periodic maintenance (weekly or sprint boundaries).
- When agent behavior deviates unexpectedly (first suspect: CLAUDE.md conflict).
- Before onboarding a new team member or agent to a project.
- After merging branches that may have modified CLAUDE.md independently.

Do not use this skill for writing new CLAUDE.md rules (use `reflect-and-learn`
for correction-based rules, or edit directly). Do not use it for auditing
documentation broadly (use `documentation-audit`).

## III. Workflow

**Step 1 -- Inventory all CLAUDE.md files.**

Locate every behavioral configuration file:
- `~/.claude/CLAUDE.md` (global)
- `./CLAUDE.md` (project root)
- `./subdirectory/CLAUDE.md` (subdirectory overrides)
- `./AGENTS.md` (cross-tool compatibility)

**Step 2 -- Extract and normalize rules.**

Parse each file into discrete behavioral rules. Normalize phrasing to detect
semantic duplicates and contradictions. Flag:
- Duplicate rules across files (redundancy)
- Contradictory rules (conflict)
- Rules that reference deprecated tools, paths, or patterns (staleness)

**Step 3 -- Check inheritance hierarchy.**

CLAUDE.md files form a cascade: global < project < subdirectory. Verify:
- Subdirectory rules do not contradict project rules unintentionally
- Project rules do not repeat global rules unnecessarily
- Override intent is explicit, not accidental

**Step 4 -- Configure mechanical protection (optional).**

Set up a PreToolUse hook that intercepts Write/Edit operations targeting
CLAUDE.md files. The hook can:
- Log all modification attempts for audit trail
- Block modifications from sub-agents (only primary agent may modify)
- Require a specific confirmation pattern before allowing changes

**Step 5 -- Report findings.**

Produce a health report listing:
- Total rule count per file
- Conflicts found (with file locations and rule text)
- Redundancies identified
- Staleness candidates
- Recommended actions (merge, delete, promote, demote)

## IV. Best Practices

- Run the guardian after every `reflect-and-learn` session.
- Keep global CLAUDE.md under 50 rules. Overflow to project-level files.
- Use explicit override markers when subdirectory rules intentionally contradict
  project rules ("OVERRIDE: ...").
- Version CLAUDE.md in git to track rule evolution over time.
- Cross-reference CLAUDE.md rules with AGENTS.md for cross-tool consistency.

## V. Quality Checklist

- [ ] All CLAUDE.md files inventoried (global, project, subdirectory)
- [ ] No unintentional contradictions between hierarchy levels
- [ ] Redundant rules identified and consolidated
- [ ] Stale rules flagged for removal
- [ ] Mechanical protection hook installed (if appropriate)
- [ ] Health report generated with actionable recommendations

## VI. Common Pitfalls

- **Treating all contradictions as bugs.** Some subdirectory overrides are intentional.
- **Over-guarding.** Blocking all CLAUDE.md modifications prevents legitimate learning.
- **Ignoring AGENTS.md.** Cross-tool files can contradict CLAUDE.md silently.
- **Manual-only audits.** Without hooks, modifications between audits go undetected.
- **Rule count as quality metric.** More rules does not mean better behavior.

## VII. Related Skills

- `reflect-and-learn` -- Applies learnings that this skill then validates
- `documentation-audit` -- Broader documentation health (not CLAUDE.md-specific)
- `hooks-reference` -- Configure the mechanical protection hooks
- `health-audit` -- Repository-wide health check (includes CLAUDE.md as one dimension)

## Output
- Health report: total rule count per file, list of conflicts with file locations and rule text, redundancies identified, staleness candidates, and recommended actions (merge, delete, promote, demote).
- Optional: a PreToolUse hook script and settings.json registration blocking unauthorized CLAUDE.md edits from sub-agents.

## Examples
**Scenario 1:** "Agent started ignoring my no-emoji rule after a merge" → Guardian inventories all CLAUDE.md files, finds a subdirectory rule that overrides the project-level rule unintentionally, and recommends adding an explicit OVERRIDE marker or removing the duplicate.
**Scenario 2:** "Weekly CLAUDE.md maintenance" → Identifies 3 rules referencing a deprecated tool path, 2 redundant rules between global and project files, and recommends consolidation. No conflicts found. Hook already installed from prior run.

## Edge Cases
- Intentional subdirectory overrides that genuinely contradict project rules are not bugs — confirm intent before flagging as conflicts. Check for explicit "OVERRIDE:" markers.
- AGENTS.md files can contradict CLAUDE.md silently; always include them in the inventory even if the user only mentions CLAUDE.md.

## Anti-Patterns
- Treating rule count as a quality metric — more rules does not mean better agent behavior; favor fewer, precise rules.
- Blocking all CLAUDE.md modifications via hook without a human override path — prevents legitimate learning and creates operational friction.