From 433c10d78fa86a06d42ef3947d901b319b14628a Mon Sep 17 00:00:00 2001 From: bchanot Date: Mon, 26 Oct 2026 17:47:53 +0100 Subject: [PATCH] refactor(claude-md): four sections become .claude/rules path rules (phase 0) --- .claude/rules/graphify-vendored.md | 32 ++++++++++ .claude/rules/mods.md | 25 ++++++++ .claude/rules/rules-maintenance.md | 27 ++++++++ .claude/rules/transient-artifacts.md | 19 ++++++ CLAUDE.md | 94 ++-------------------------- lib/tests/project-rules.test.sh | 8 +++ 6 files changed, 116 insertions(+), 89 deletions(-) create mode 100644 .claude/rules/graphify-vendored.md create mode 100644 .claude/rules/mods.md create mode 100644 .claude/rules/rules-maintenance.md create mode 100644 .claude/rules/transient-artifacts.md diff --git a/.claude/rules/graphify-vendored.md b/.claude/rules/graphify-vendored.md new file mode 100644 index 0000000..7a92cff --- /dev/null +++ b/.claude/rules/graphify-vendored.md @@ -0,0 +1,32 @@ +--- +paths: ["skills/graphify/**", "install-plugins.sh"] +--- + +# Machine-owned: the vendored graphify skill + +`skills/graphify/SKILL.md`, `skills/graphify/references/` and +`.graphify_version` are written by `graphify claude install` +(`install-plugins.sh` STEP graphify), which lands in the repo because +`~/.claude/skills` is a symlink to `skills/`. They are gitignored: a +`pipx upgrade graphifyy` used to dirty the tree and cost a +`chore(graphify): sync vendored skill X -> Y` commit each time. + +Two graphify commands, easy to confuse, and only one restores the skill: +- `graphify install --platform claude` copies SKILL.md + `references/` + + `.graphify_version` into `skills/graphify/`. Touches nothing else. + This is the recovery command. +- `graphify claude install` writes the CLAUDE.md graphify section and the + `.claude/settings.json` PreToolUse hooks. It **rewrites both guarded + configs** (EVAL-020, verified again 2026-09-15), so revert them after. It does NOT copy + the skill. + +`make plugin` runs both (`install-plugins.sh` STEP graphify) behind the +guarded-config EXIT trap, so a fresh clone is covered. + +Trade-off accepted: an upstream release can now change the skill's prompt +with no diff to review. `skills/graphify/test-prompts.json` is hand-written +for darwin and stays tracked. + +Gotcha, learned the hard way: `git rm --cached` keeps the working file, +but if the branch you merge into still tracks it, the merge deletes it +from disk. Untrack and merge, then restore with the command above. diff --git a/.claude/rules/mods.md b/.claude/rules/mods.md new file mode 100644 index 0000000..5b27c75 --- /dev/null +++ b/.claude/rules/mods.md @@ -0,0 +1,25 @@ +--- +paths: ["mods/**", "skills/model-router/**", "lib/tests/mods.test.sh"] +--- + +# mods/ — function-hooks plugins (Claude Code mods) + +A mod lives in `mods//` (`.claude-plugin/plugin.json` + hooks). It +loads through the tracked relative symlink `skills/` -> `../mods/` +(`~/.claude/skills` links to `skills/`) as `@skills-dir`, in place, +live at the next session or `/reload-plugins`. New mod: `ln -s ../mods/ +skills/` from the repo root (guard with `[ -L ]`, a re-run nests a link). +Not `CLAUDE_CODE_PLUGIN_DIRS` (absolute path, settings `env` has no `$HOME` +expansion, settings.json is tracked), nor a local marketplace (`add` writes +an absolute path into settings.json). +- The engine lays `mods//tsconfig.json` and `.claude-plugin/types/`; + both are gitignored. +- Optional user config: `~/.claude/.json`. Its `"enabled": false` is the + per-machine off switch (untracked). `"@skills-dir": false` in + `enabledPlugins` also works but lands in the TRACKED settings.json and + dirties every machine's tree. +- A dev copy of the same name (`--plugin-dir`, hot-reload link in + `~/.claude/dev-mods//`) shadows the skills-dir copy for that + session: remove it before reading `/reload-plugins` as a test of the link. +- Tests: `make test suite=lib/tests/mods.test.sh` (manifest, link, + `claude plugin validate`, `claude plugin test`). `doctor.sh` has a Mods section. diff --git a/.claude/rules/rules-maintenance.md b/.claude/rules/rules-maintenance.md new file mode 100644 index 0000000..9089601 --- /dev/null +++ b/.claude/rules/rules-maintenance.md @@ -0,0 +1,27 @@ +--- +paths: ["rules/**", "CLAUDE.global.md"] +--- + +# rules/ maintenance + +Modular instruction files loaded by Claude Code alongside the global memory. +`rules/` is symlinked to `~/.claude/rules` by `link.sh` (user scope, ALL +projects). One rule = one file = one concern. + +A rule WITH `paths:` YAML frontmatter (glob list) loads lazily — only when +Claude reads a file matching a glob; a rule WITHOUT it loads at session +start, same cost as the global memory. Extract from CLAUDE.global.md only +what can be path-scoped (the token win) or what is generated; always-on +doctrine stays in CLAUDE.global.md. Exception: a standalone user-authored +rule set that would bust the 320-line density budget may live here WITHOUT +`paths:` (always-on load) — writing-style.md (BDR-085), default-language.md +(BDR-118), secure-by-default.md (BDR-120). `paths:` globs match against the +CURRENT project's tree — a broad glob (e.g. `rules/**`) can fire in foreign +projects; keep rule bodies tiny. +Docs: https://code.claude.com/docs/en/memory.md#path-specific-rules + +Machine-owned: `rules/context7.md` is DELETED BY DESIGN (BDR-053, +2026-07-06) — `ctx7 setup --claude --cli` still writes it, but +install-plugins.sh STEP ctx7 purges it right after; the find-docs skill is +the single ctx7 surface. If it reappears (manual `ctx7 setup`), delete it +or re-run `make plugin`. diff --git a/.claude/rules/transient-artifacts.md b/.claude/rules/transient-artifacts.md new file mode 100644 index 0000000..2fd1f26 --- /dev/null +++ b/.claude/rules/transient-artifacts.md @@ -0,0 +1,19 @@ +--- +paths: ["docs/superpowers/**", ".audit/**"] +# static-check: skip +--- + +# Transient planning artifacts + +`docs/superpowers/specs/**` and `docs/superpowers/plans/**` are run-time +artifacts of a feature pipeline (subagent briefs, reviewer references). +They are committed DURING the run (the SDD worktree + reviewers read them +from disk — NOT gitignored), then AUTO-PURGED by `gitflow finish` on a +`feature`/`bugfix` branch, before the merge, so develop's tip stays clean +(BDR-065, `lib/gitflow.sh` `_gitflow_purge_transient`). The feature commits +stay reachable from develop, so `git show :docs/…` is still the archive. +Opt out with `GITFLOW_PURGE_TRANSIENT=0`. NOT in scope: `.claude/tasks/{contracts,plans}` +(durable, versioned, referenced by decisions.md). Durable knowledge goes to +`.claude/memory/` registries, never to these files. Derived scan/audit +outputs (`.audit/**`) are gitignored and never committed, even redacted +(LRN-124). diff --git a/CLAUDE.md b/CLAUDE.md index 25adfcd..0637c63 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -7,92 +7,8 @@ ## Health Stack - shell: `shellcheck *.sh hooks/*.sh lib/*.sh` -## rules/ maintenance - -Modular instruction files loaded by Claude Code alongside the global memory. -`rules/` is symlinked to `~/.claude/rules` by `link.sh` (user scope, ALL -projects). One rule = one file = one concern. - -A rule WITH `paths:` YAML frontmatter (glob list) loads lazily — only when -Claude reads a file matching a glob; a rule WITHOUT it loads at session -start, same cost as the global memory. Extract from CLAUDE.global.md only -what can be path-scoped (the token win) or what is generated; always-on -doctrine stays in CLAUDE.global.md. Exception: a standalone user-authored -rule set that would bust the 320-line density budget may live here WITHOUT -`paths:` (always-on load) — writing-style.md (BDR-085), default-language.md -(BDR-118), secure-by-default.md (BDR-120). `paths:` globs match against the -CURRENT project's tree — a broad glob (e.g. `rules/**`) can fire in foreign -projects; keep rule bodies tiny. -Docs: https://code.claude.com/docs/en/memory.md#path-specific-rules - -Machine-owned: `rules/context7.md` is DELETED BY DESIGN (BDR-053, -2026-07-06) — `ctx7 setup --claude --cli` still writes it, but -install-plugins.sh STEP ctx7 purges it right after; the find-docs skill is -the single ctx7 surface. If it reappears (manual `ctx7 setup`), delete it -or re-run `make plugin`. - -## Machine-owned: the vendored graphify skill - -`skills/graphify/SKILL.md`, `skills/graphify/references/` and -`.graphify_version` are written by `graphify claude install` -(`install-plugins.sh` STEP graphify), which lands in the repo because -`~/.claude/skills` is a symlink to `skills/`. They are gitignored: a -`pipx upgrade graphifyy` used to dirty the tree and cost a -`chore(graphify): sync vendored skill X -> Y` commit each time. - -Two graphify commands, easy to confuse, and only one restores the skill: -- `graphify install --platform claude` copies SKILL.md + `references/` + - `.graphify_version` into `skills/graphify/`. Touches nothing else. - This is the recovery command. -- `graphify claude install` writes the CLAUDE.md graphify section and the - `.claude/settings.json` PreToolUse hooks. It **rewrites both guarded - configs** (EVAL-020, verified again 2026-09-15), so revert them after. It does NOT copy - the skill. - -`make plugin` runs both (`install-plugins.sh` STEP graphify) behind the -guarded-config EXIT trap, so a fresh clone is covered. - -Trade-off accepted: an upstream release can now change the skill's prompt -with no diff to review. `skills/graphify/test-prompts.json` is hand-written -for darwin and stays tracked. - -Gotcha, learned the hard way: `git rm --cached` keeps the working file, -but if the branch you merge into still tracks it, the merge deletes it -from disk. Untrack and merge, then restore with the command above. - -## mods/ — function-hooks plugins (Claude Code mods) - -A mod lives in `mods//` (`.claude-plugin/plugin.json` + hooks). It -loads through the tracked relative symlink `skills/` -> `../mods/` -(`~/.claude/skills` links to `skills/`) as `@skills-dir`, in place, -live at the next session or `/reload-plugins`. New mod: `ln -s ../mods/ -skills/` from the repo root (guard with `[ -L ]`, a re-run nests a link). -Not `CLAUDE_CODE_PLUGIN_DIRS` (absolute path, settings `env` has no `$HOME` -expansion, settings.json is tracked), nor a local marketplace (`add` writes -an absolute path into settings.json). -- The engine lays `mods//tsconfig.json` and `.claude-plugin/types/`; - both are gitignored. -- Optional user config: `~/.claude/.json`. Its `"enabled": false` is the - per-machine off switch (untracked). `"@skills-dir": false` in - `enabledPlugins` also works but lands in the TRACKED settings.json and - dirties every machine's tree. -- A dev copy of the same name (`--plugin-dir`, hot-reload link in - `~/.claude/dev-mods//`) shadows the skills-dir copy for that - session: remove it before reading `/reload-plugins` as a test of the link. -- Tests: `make test suite=lib/tests/mods.test.sh` (manifest, link, - `claude plugin validate`, `claude plugin test`). `doctor.sh` has a Mods section. - -## Transient planning artifacts - -`docs/superpowers/specs/**` and `docs/superpowers/plans/**` are run-time -artifacts of a feature pipeline (subagent briefs, reviewer references). -They are committed DURING the run (the SDD worktree + reviewers read them -from disk — NOT gitignored), then AUTO-PURGED by `gitflow finish` on a -`feature`/`bugfix` branch, before the merge, so develop's tip stays clean -(BDR-065, `lib/gitflow.sh` `_gitflow_purge_transient`). The feature commits -stay reachable from develop, so `git show :docs/…` is still the archive. -Opt out with `GITFLOW_PURGE_TRANSIENT=0`. NOT in scope: `.claude/tasks/{contracts,plans}` -(durable, versioned, referenced by decisions.md). Durable knowledge goes to -`.claude/memory/` registries, never to these files. Derived scan/audit -outputs (`.audit/**`) are gitignored and never committed, even redacted -(LRN-124). +## Path-scoped rules +Project rules live in `.claude/rules/.md` and load on Read of a file +matching their `paths:` (never at session start): rules-maintenance, +graphify-vendored, mods, transient-artifacts. Check: `bash +lib/project-rules.sh check` (runs in `make test`). diff --git a/lib/tests/project-rules.test.sh b/lib/tests/project-rules.test.sh index 2b636b9..91d2eb1 100644 --- a/lib/tests/project-rules.test.sh +++ b/lib/tests/project-rules.test.sh @@ -174,5 +174,13 @@ printf '%s' "$IN" | CLAUDE_INSTRUCTIONS_LOG="$LOG" bash "$HOOK" check T10k-rotated "$([ -e "$LOG.1" ] && echo yes || echo no)" yes check T10l-fresh-log-one-line "$(wc -l < "$LOG" | tr -d ' ')" 1 +# T11 the real rules of this repo pass the check (4 rules, 1 skip-marked) +out=$(bash "$PR" -C "$ROOT" check); rc=$? +[ "$rc" -eq 0 ] || printf '%s\n' "$out" +check T11-repo-rules-pass "$rc" 0 +check T11b-four-rules "$(printf '%s\n' "$out" | grep -c '4 rule(s) ok')" 1 +check T11c-transient-skipped \ + "$(printf '%s\n' "$out" | grep -c 'transient-artifacts.md: SKIP docs/superpowers/\*\*')" 1 + echo "PASS=$pass FAIL=$fail" [ "$fail" -eq 0 ]