/update-claudemd

name: update-claudemd
description: This skill should be used when the user says "update CLAUDE.md", "refresh CLAUDE.md", "sync CLAUDE.md with the codebase", "reorganize CLAUDE.md", "optimize project instructions", or when CLAUDE.md is stale, verbose, or out of sync.
allowed-tools:
  - Read
  - Glob
  - Grep
  - Edit
  - Write
  - Bash(wc:*)
  - Bash(git:*)
  - Bash(mkdir:*)
  - Bash(cp:*)
  - Task
  - AskUserQuestion

Update and Optimize CLAUDE.md

Reconcile project CLAUDE.md and its topic files against codebase reality and git history since each file's last commit. Enforce progressive disclosure: CLAUDE.md is a top-level index of project identity, universal invariants, and pointers to topic files at `.claude/rules/*.md`. Files in `.claude/rules/` auto-load at SessionStart unless scoped with `paths:` frontmatter — every topic file this skill writes must carry that frontmatter so it loads only when its subsystem's files are touched, not on every session.

Reconciliation scope includes every file in `.claude/rules/`. Topic files are first-class content — they share the same staleness, accuracy, and duplication risks as CLAUDE.md itself and must be audited, reconciled, and (when warranted) edited during every run. They are not appendices.

Scope boundary: project CLAUDE.md (L1) and its topic files only. User-global `~/.claude/CLAUDE.md` (L0) is out of scope unless the user explicitly asks.

Governing Principle

Content in CLAUDE.md is justified only if it changes how Claude acts in the next session AND is needed across most tasks — not subsystem-specific. Subsystem-scoped content still matters but belongs in a topic file, loaded on demand.

Content in a topic file is justified only if it changes how Claude acts within its subsystem AND is accurate against current codebase reality. Stale topic files are worse than missing ones because Claude trusts them.

Phase 3 operationalizes this principle with a seven-action set that lets content flow both downward (demote from CLAUDE.md to a topic file) and upward (promote from a topic file back to CLAUDE.md when a detail becomes universal). The goal is a living progressive-disclosure hierarchy, not a one-way archive.

Budget

CLAUDE.md: soft target ~120 lines, soft ceiling 150 lines. Over-budget files are flagged, not forced — hand-maintained CLAUDE.md is respected. Line counts measured with `wc -l`.

Topic files: informational soft ceiling ~300 lines each. Topic files legitimately grow as their subsystem grows; past ~300 lines, flag the overage in Phase 7 and suggest splitting by sub-topic. Never block. The CLAUDE.md budget is the only hard constraint.

Fan-out Rule

Codebase research scales with project size and churn. Compute once in Phase 1, apply in Phase 2.

Signals:

• `churn` — commits since last CLAUDE.md touch: `git log --since="<date>" --oneline --no-merges | wc -l`
• `files` — tracked files: `git ls-files | wc -l`

N (codebase-scan shards):

| churn | files | N | |------------|---------------|---| | < 20 | < 100 | 1 | | 20 – 59 | 100 – 499 | 2 | | 60 – 149 | 500 – 1999 | 3 | | ≥ 150 | ≥ 2000 | 4 |

Compute N for each column independently. Take the max. Cap at 4. When N > 1, partition by top-level directory clusters (e.g. `plugins/` → shard 1; `scripts/ + tests/` → shard 2).

Phase 1 — Orient and Compute Fan-out

Glob for `CLAUDE.md` at the project root. If missing, inform the user that creation is out of scope for this skill and stop.

Record current `CLAUDE.md` line count with `wc -l`. List `.claude/rules/*.md` if the directory exists and record each topic file's line count AND last-commit date via `git log -1 --format="%ai" -- <path>`. The per-file dates are required in Phase 2 so Agent B can anchor each file's staleness window independently — using CLAUDE.md's date for every file produces wrong windows when cadences differ.

Run cheap git probes in two steps.

First, resolve the last CLAUDE.md commit date (sequential — downstream probe depends on it):

• `git log -1 --format="%ai" -- CLAUDE.md` → record as `<last_claudemd_date>`. If CLAUDE.md has no history, fall back to `git log --reverse --format="%ai" | head -1`.

Then run the remaining probes as parallel Bash calls:

• `git log --since="<last_claudemd_date>" --oneline --no-merges | wc -l` — churn
• `git ls-files | wc -l` — tracked files
• `git ls-files | awk -F/ 'NF>1{print $1}' | sort -u | wc -l` — top-level directory count

Compute N using the fan-out rule. Decide the shard plan: which top-level directories each Codebase Scan agent will cover.

Exit condition: CLAUDE.md exists, baseline line counts recorded, per-topic-file line counts and last-commit dates recorded, N computed, shard plan decided.

Phase 2 — Parallel Research

Launch `3 + N` Explore agents in a single message. All use `subagent_type: Explore`.

**Agent A — CLAUDE.md and Topic Files Audit** (`subagent_type: Explore`)

Read the project's CLAUDE.md and every file in `.claude/rules/` if present. Apply the same H1/H2/H3 classification pass to CLAUDE.md AND to every topic file — topic files are first-class content, not inventory.

For each H1/H2/H3 section in either source, record: `source` (CLAUDE.md path or topic file path), `name`, `line_count`, and `classification_hint` (project identity, universal invariant, subsystem-scoped detail, conditional guidance, or derivable from file inspection). For topic-file sections, also flag any that have become universal invariants — content that now changes how Claude acts across almost every task in the project, not just within one subsystem — these are promote-back candidates.

Flag stale content (version numbers, paths, commands, features that look wrong). Flag cross-file duplication — topic-file content that duplicates CLAUDE.md, or topic files that overlap each other.

Also scan for index drift between CLAUDE.md and the topic files directory:

• `dangling_references` — topic files pointed at from CLAUDE