Bastien Chanot
d7662abc1e
The previous note said a fresh clone gets the skill back from `make
plugin` without naming the command, and I picked the wrong one when the
files actually went missing. There are two, and only one restores the
skill:
- `graphify install --platform claude` copies SKILL.md, references/
and .graphify_version. Touches nothing else. This is the recovery
command, verified: the skill came back at 0.9.61 and the four
guarded configs were byte-identical afterwards.
- `graphify claude install` writes the CLAUDE.md section and the
.claude/settings.json PreToolUse hooks, rewrites both of those
guarded configs (EVAL-020, reproduced today), and does NOT copy the
skill.
LRN-154 records why the files vanished in the first place. `git rm
--cached` keeps the working file, but `gitflow finish` checks out the
target branch, where it is still tracked, so git restores it and the
merge then deletes it from disk. .gitignore does not protect it; it only
stops a re-add. The file survives the commit and dies at the merge, which
reads as unrelated.
76 lines
3.8 KiB
Markdown
76 lines
3.8 KiB
Markdown
<!-- PROJECT SCOPE ONLY (claude-config repo). The user-scope GLOBAL memory is
|
|
./CLAUDE.global.md, deployed as ~/.claude/CLAUDE.md by link.sh — edit
|
|
THAT file for cross-project doctrine. -->
|
|
|
|
# claude-config — project instructions
|
|
|
|
## 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). `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.
|
|
|
|
## 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 <sha>: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).
|