Files

T

Bastien Chanot d7662abc1e chore(graphify): correct the recovery note, capitalize LRN-154

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.

2026-09-15 19:57:07 +02:00

3.8 KiB

Raw Blame History

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).