claude-mods/rules/worktree-boundaries.md

Worktree Boundaries

Never touch .claude/worktrees/ in any repo. Never touch git worktrees, submodules, gitlinks, or agent-spawned ephemeral dirs in repos outside your current working scope.

The rule

Worktrees belong to the project that owns them. If private-project housekeeping touches file X in repo Y, that does NOT extend to .claude/worktrees/ in repo Y. Worktrees are the private state of whichever agent, session, or human spawned them. They may look orphaned and aren't.

What counts as "don't touch"

• Do not rm -rf .claude/worktrees/ in any repo
• Do not git rm or git rm --cached worktree entries
• Do not stage deletions of worktree dirs via git add -A (this is the subtle one — -A sweeps up changes you didn't intend)
• Do not commit changes that reference .claude/worktrees/ paths
• Do not reason about whether a worktree is "orphaned" unless the owning project explicitly asks

Why

• Worktree names like agent-<hash> look like ephemeral agent artifacts but may be active sessions
• A gitlink/submodule pointing at a worktree is not garbage — it's a reference with meaning to the owning session
• Agent-spawned worktrees may contain uncommitted work the user wants to inspect
• Cross-project cleanup assumes context you don't have; when a project wants cleanup it will ask its own session

The specific failure this came from (2026-04-19)

During a private-project ecosystem-wide "commit + push all tool repos" pass, git add -A in flarecrawl staged gitlinks to 9 agent worktrees (from background agents running inside flarecrawl). Those gitlinks were committed and pushed as part of "chore: sync tool state". Then a subsequent rm -rf .claude/worktrees/ deleted the filesystem dirs, creating a dirty state. The user correctly pushed back — private-project housekeeping has no business touching another project's agent state.

Applied corrections when running bulk commits across repos

• Use explicit file paths to git add, not -A or ., when the repo contains any .claude/ directory
• Inspect git status --short before any bulk commit loop; if .claude/worktrees/ appears, STOP and ask
• Never include worktrees in commit messages, scripts, or cleanup routines
• If a repo's .claude/ state looks "dirty" during cross-project work, that's the repo's problem, not yours

Scope this rule covers

All projects. Never make exceptions "just for this session". If a worktree ever looks like it needs cleanup, ask the user explicitly before touching it.