From a18c0974e81795f585c1e55a88c1d92149acd358 Mon Sep 17 00:00:00 2001 From: Brummel Date: Tue, 30 Jun 2026 13:35:05 +0200 Subject: [PATCH] docs: add repo CLAUDE.md forbidding worktree development The plugin installs via symlinks pinned at the absolute path of the primary clone, so skill/agent/workflow edits made in a git worktree of this repo are not what the live session runs (silent no-op or, on re-install, a split-brain). Record a no-worktree rule for this repo in a repo-local CLAUDE.md, with the dominant symlink-pinning rationale plus the secondary cwd-slug memory/transcript re-keying caveat. closes #15 --- CLAUDE.md | 31 +++++++++++++++++++++++++++++++ 1 file changed, 31 insertions(+) create mode 100644 CLAUDE.md diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..d187e58 --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,31 @@ +# Skills plugin — repo-local rules + +This is the skills plugin's own repository. It does not consume its own +pipeline: there is no `## Skills plugin: project facts` section and no +per-cycle skill dispatch here. Changes are made directly and committed to +`main`. + +## Do not develop this repo from a git worktree + +Never work on this repository from a git worktree — neither a manual +`git worktree add` nor the harness `EnterWorktree` tool. Always edit the +primary clone at `~/dev/skills`, on `main`. + +Reason (dominant): `install.sh` installs the plugin by symlinking +`~/.claude/{skills,agents,workflows}` to the absolute path of the clone it +was first run from — the primary clone. A running session loads every +skill, agent, and workflow definition through those symlinks regardless of +cwd, so it always executes the primary clone's bodies. Edits made in a +worktree of this repo are therefore not what the live session runs: +dispatching an edited skill silently runs the old primary-clone body, and +re-running `install.sh` from a worktree skips the existing symlinks and +only adds links for new skills (a split-brain across two checkouts). +Worktree development of the plugin is silently ineffective. + +Secondary: a worktree session also re-keys the cwd-derived project slug, +so the accumulated auto-memory and the session transcript land under a +different namespace than the primary clone. + +This constraint is specific to editing the plugin itself. Consumer +projects are unaffected: they resolve the same global symlinks and read +their own checked-in `CLAUDE.md`, so they may use worktrees freely.