diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json index c33b700..b1a2bf7 100644 --- a/.claude-plugin/plugin.json +++ b/.claude-plugin/plugin.json @@ -20,7 +20,10 @@ ], "skills": [ "./skill", - "./skill/karpathy-guidelines" + "./skill/karpathy-guidelines", + "./skill/claude-md-drift-audit", + "./skill/claude-md-link-check", + "./skill/claude-md-dependency-rescan" ], "commands": [ "./command/enhance-claude-md.md", diff --git a/CHANGELOG.md b/CHANGELOG.md index aae65a1..55e9a1d 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -9,6 +9,16 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ## [Unreleased] +### Added (wave 4 — forked task-style audit skills) + +Three new task-style skills under `skill/`, each using Anthropic's `context: fork` + `agent: Explore` so they run in an isolated subagent context (no caller chat history, ≤500-token summary back to the main session): + +- **`claude-md-drift-audit`** (`skill/claude-md-drift-audit/SKILL.md`, 51 lines): walks the last N days of git history (default 7), cross-references every CLAUDE.md and `.claude/rules/*.md` against deleted paths / renamed paths / removed deps from that window, returns a punch list. Read-only. +- **`claude-md-link-check`** (`skill/claude-md-link-check/SKILL.md`, 51 lines): verifies every `@path` chain import and every relative markdown link inside every CLAUDE.md resolves to an existing file. Returns broken links with file:line refs. Read-only. +- **`claude-md-dependency-rescan`** (`skill/claude-md-dependency-rescan/SKILL.md`, 54 lines): re-detects the project's tech stack from `package.json` / `requirements.txt` / `pyproject.toml` / `go.mod` / `Cargo.toml`, diffs against every CLAUDE.md's Tech Stack section, returns added / removed / renamed lists per file. Read-only. + +All three are standalone-invocable (`/claude-md-drift-audit`, etc.) and orchestrated by **`/sync-claude-md --weekly`**, which now opens with a Phase 0 that issues the three skills in parallel via the Skill tool before doing the normal sync work. Plugin manifest registers all five skills (the two existing + three new). + ### Added (wave 3 — adoption hardening) - **Command discovery metadata** (`command/enhance-claude-md.md`, `command/sync-claude-md.md`): both commands now declare `allowed-tools`, `disallowedTools` (blocks `WebFetch`/`WebSearch`), `argument-hint`, and `when_to_use` so Claude Code can auto-suggest and zero-prompt them. diff --git a/command/sync-claude-md.md b/command/sync-claude-md.md index a2206ed..44c879e 100644 --- a/command/sync-claude-md.md +++ b/command/sync-claude-md.md @@ -1,9 +1,11 @@ --- description: Walk every CLAUDE.md in the project, prune stale references (removed deps, deleted paths, broken modular links), enforce the 150-line cap by splitting into sub-files, and repair the root ↔ subdirectory chain (markdown links + @path imports). -argument-hint: "[--dry-run | --paths-only | ]" +argument-hint: "[--weekly | --dry-run | --paths-only | ]" when_to_use: | Run after refactors, dependency changes, deleted directories, or when any single - CLAUDE.md is near the 150-line cap. Also run before cutting a release so the + CLAUDE.md is near the 150-line cap. Use --weekly for a periodic audit pass that + parallel-invokes the drift-audit, link-check, and dependency-rescan forked skills + before doing the normal sync work. Also run before cutting a release so the documentation tag-snapshot is truthful. allowed-tools: - Read @@ -47,6 +49,20 @@ This command keeps every CLAUDE.md in the project current, lean, and chained. Ap --- +## Phase 0: Weekly Audit (only when `--weekly` is passed) + +When the user invokes `/sync-claude-md --weekly`, run the three audit skills in parallel via the **Skill tool** before touching any file. Each is forked (`context: fork`, `agent: Explore`) so its work happens in an isolated context and only the summary returns: + +1. `Skill(claude-md-drift-audit)` — references against last 7 days of git history. +2. `Skill(claude-md-link-check)` — `@path` imports and markdown links resolve. +3. `Skill(claude-md-dependency-rescan)` — Tech Stack sections vs. manifest files. + +Issue all three in a single message so they execute concurrently. Wait for all three to return, then aggregate their findings into one report at the top of this run — `## Weekly Audit Summary` with one subsection per skill. If any audit returns findings, proceed to Phase 1 with those findings in mind so the sync work resolves them. If all three are clean, skip to Phase 4 (chain repair) — no edits required. + +When `--weekly` is not passed, skip this phase entirely and start at Phase 1. + +--- + ## Phase 1: Inventory Discover every CLAUDE.md in the project (skipping vendor directories) and report sizes. diff --git a/skill/claude-md-dependency-rescan/SKILL.md b/skill/claude-md-dependency-rescan/SKILL.md new file mode 100644 index 0000000..361465a --- /dev/null +++ b/skill/claude-md-dependency-rescan/SKILL.md @@ -0,0 +1,54 @@ +--- +name: claude-md-dependency-rescan +description: Re-detect this project's tech stack from package.json / requirements.txt / pyproject.toml / go.mod / Cargo.toml and diff it against the Tech Stack section of every CLAUDE.md. Read-only — returns added / removed / renamed dependencies, never edits. +when_to_use: | + Use when the user asks "is my Tech Stack section up to date?", "what deps changed?", + "rescan my dependencies", after dependency upgrades, or as part of /sync-claude-md --weekly. +argument-hint: "[manifest-path]" +context: fork +agent: Explore +allowed-tools: + - Read + - Glob + - Grep + - "Bash(find:*)" + - "Bash(cat:*)" +disable-model-invocation: false +--- + +# CLAUDE.md Dependency Rescan (forked, read-only) + +Optional explicit manifest: `$ARGUMENTS` (default: auto-detect all five manifest types). + +Run these steps in order. Do not modify any file. + +1. **Detect manifests.** Look for `package.json`, `requirements.txt`, `pyproject.toml`, `go.mod`, `Cargo.toml` at the repo root and one level deep (workspaces/monorepos). +2. **Extract declared dependencies** from each: + - `package.json` → keys of `dependencies` and `devDependencies` (skip versions). + - `requirements.txt` → first token of each non-comment line. + - `pyproject.toml` → `[project.dependencies]` / `[tool.poetry.dependencies]` keys. + - `go.mod` → module paths under `require (...)`. + - `Cargo.toml` → keys under `[dependencies]` / `[dev-dependencies]`. +3. **Inventory documented deps** in every `CLAUDE.md` (and `.claude/rules/*.md`): grep for the Tech Stack / Dependencies sections and the lists under them. +4. **Compute three sets per file:** + - `added`: in manifest but absent from this CLAUDE.md. + - `removed`: documented in this CLAUDE.md but absent from manifest. + - `renamed`: documented and present in manifest but spelled differently (`react-router` vs `react-router-dom`, `pg` vs `psycopg2`). +5. **Return** in this exact shape: + +``` +## Dependency Rescan + +Manifests detected: +Total declared deps: + +### Per file +#### +- Added (in manifest, not documented): +- Removed (documented, not in manifest): +- Renamed / aliased: +``` + +6. If every documented set matches its manifest, return exactly `## Dependency Rescan\n\nAll documented deps match manifests. files inspected.`. Do not pad. + +**Hard rule**: do not propose specific edits — just surface the diffs. `/sync-claude-md` decides whether to write them. diff --git a/skill/claude-md-drift-audit/SKILL.md b/skill/claude-md-drift-audit/SKILL.md new file mode 100644 index 0000000..0bb0c57 --- /dev/null +++ b/skill/claude-md-drift-audit/SKILL.md @@ -0,0 +1,51 @@ +--- +name: claude-md-drift-audit +description: Audit every CLAUDE.md in this project for drift against the last week of git history. Flags sections that reference deleted files, renamed paths, or removed dependencies. Read-only — returns a punch list, never edits. +when_to_use: | + Use when the user asks "is my CLAUDE.md still accurate?", "audit my docs for staleness", + "what changed in the last week?", or as part of /sync-claude-md --weekly. +argument-hint: "[days=7]" +context: fork +agent: Explore +allowed-tools: + - Read + - Glob + - Grep + - "Bash(git log:*)" + - "Bash(git diff:*)" + - "Bash(git status:*)" + - "Bash(find:*)" +disable-model-invocation: false +--- + +# CLAUDE.md Drift Audit (forked, read-only) + +Days window: `$ARGUMENTS` (default `7` if empty). + +Perform these steps in order, then return a single punch-list summary. Do not modify any file. + +1. **Inventory** every `CLAUDE.md` and `*.claude/rules/*.md` in the tree using `find . -name "CLAUDE.md" -type f -not -path "*/.git/*" -not -path "*/node_modules/*"`. List paths and line counts. +2. **Collect change signal** for the window: + - `git log --since="$ARGUMENTS days ago" --name-status --no-merges --diff-filter=DR` → deleted and renamed paths. + - `git diff "@{$ARGUMENTS days ago}" --name-status -- package.json requirements.txt pyproject.toml go.mod Cargo.toml 2>/dev/null` → manifest deltas (removed/added deps). +3. **Cross-reference** each CLAUDE.md against those signals using `grep` / `Read`: + - Mark any line that names a deleted or renamed path. + - Mark any line in a Tech Stack / Dependencies section that names a removed dep. + - Mark any `@path/...` chain import or markdown link whose target was deleted. +4. **Return** the punch list in this exact shape (markdown), nothing else: + +``` +## Drift Audit (window: days) + +Total CLAUDE.md inspected: +Signals examined: , , + +### Findings +- : — — suggested action +- ... (one bullet per drift; omit section if empty) + +### Clean +- (lines unchanged, references valid) +``` + +5. If no drift is found, return exactly `## Drift Audit\n\nNo drift in -day window. files inspected.`. Do not pad the output. diff --git a/skill/claude-md-link-check/SKILL.md b/skill/claude-md-link-check/SKILL.md new file mode 100644 index 0000000..f43d326 --- /dev/null +++ b/skill/claude-md-link-check/SKILL.md @@ -0,0 +1,51 @@ +--- +name: claude-md-link-check +description: Verify every @path chain import and every markdown link inside every CLAUDE.md in this project resolves to an existing file. Read-only — returns broken links with file:line refs, never edits. +when_to_use: | + Use when the user asks "check my CLAUDE.md links", "are the @-imports still valid?", + "find broken cross-references", or as part of /sync-claude-md --weekly. +argument-hint: "[path-glob]" +context: fork +agent: Explore +allowed-tools: + - Read + - Glob + - Grep + - "Bash(find:*)" + - "Bash(test:*)" + - "Bash(ls:*)" +disable-model-invocation: false +--- + +# CLAUDE.md Link Check (forked, read-only) + +Optional path-glob: `$ARGUMENTS` (default `.` — entire tree). + +Run these steps in order. Do not modify any file. + +1. **Inventory.** `find -name "CLAUDE.md" -type f -not -path "*/.git/*" -not -path "*/node_modules/*"`. Also include `.claude/rules/*.md`. Record paths. +2. **Extract candidates** from each file: + - **Chain imports** — lines matching `^@\S+`. The literal after `@` is a relative path. + - **Markdown links** — `[text](target)` where `target` is not an HTTP(S) URL, not `mailto:`, not a bare anchor `#section`. +3. **Resolve each candidate** relative to the file containing it (use `Read` on the parent file to confirm position, then `test -e ` or `Glob`). + - For `@../CLAUDE.md` inside `skill/CLAUDE.md`, resolved path is `CLAUDE.md`. + - For `[Backend](backend/CLAUDE.md)` inside the root, resolved path is `backend/CLAUDE.md`. +4. **Return** the report in this exact shape: + +``` +## Link Check + +Files inspected: +References checked: @-imports, markdown links + +### Broken +- : — `` → does not resolve (expected ``) +- ... (omit section if empty) + +### Clean + references resolved. +``` + +5. If everything resolves, return exactly `## Link Check\n\nAll references resolved across files.`. Do not pad. + +**Hard rule**: never invent a fix. Report the broken target verbatim. Repair is the user's call (or `/sync-claude-md`'s).