worktree-isolation

What this skill does

# Worktree isolation

## The rule

**The primary clone is a coordination point, not a workspace.** Every distinct line of work — a feature, a fix, a "quick change," an agent's task — runs in its **own git worktree on its own branch**. Two lines of work never share one checked-out tree.

This is non-negotiable when *any* parallel work is live: an autopilot running, another Claude session open, a long task mid-flight. The moment two actors touch one tree on different branches, you get clobbered uncommitted changes, "branch already checked out" errors, and "wait, what branch am I even on" — the classic shared-tree collision.

## Why

**The failure mode:** Feature B has an uncommitted implementation in the working tree, and then Feature C's branch gets checked out in the *same* tree on top of it. You get overlaid changes, "branch already checked out" errors when something else tries to use B's branch, and confusion about which branch is even live. The autopilot already isolates its own subagents (see `feature-workflow`), so the exposure is everything *else* that can reach the same checkout — a change made directly in the primary clone, or a second Claude session opened against the repo, while parallel work is live. Nothing structural stops any of those from landing on top of in-flight work.

The fix is structural, not willpower: make isolation the easy path, so "just make the change" lands in a worktree instead of the shared tree.

## How to apply (this is guidance for *you*, the agent)

When the user asks for a change and there is — or might be — parallel work live, **don't edit the primary clone.** Isolate first:

1. **Check where you are.** If the repo has linked worktrees (`git worktree list` shows more than one) and you're in the primary clone, you're on the shared tree. (In a tmux setup the status bar flags this as `⚠ primary`.)
2. **Isolate the work** by the cheapest sufficient means:
   - **Dispatch an `isolation: "worktree"` subagent** (the Agent tool) to do the change — the harness gives it a clean worktree. Best for a self-contained task.
   - **Or create a worktree and work there** at the **target repo's** `.worktrees/<branch>`, resolved from that repo's root (not your cwd) and as a **real path** (`pwd -P`):
     ```bash
     ROOT="$(cd "$TARGET" && git rev-parse --show-toplevel)"; ROOT="$(cd "$ROOT" && pwd -P)"
     git -C "$ROOT" worktree add "$ROOT/.worktrees/<branch>" -b <branch> origin/dev
     ```
     `$TARGET` is the repo this line of work targets (base off `dev` if it exists). Then operate inside it. Best when you'll iterate interactively.
   - Use **worktree-relative paths**; never reconstruct primary-clone absolute paths inside a worktree (that's how agents drift back out and re-collide).
3. **Only edit the primary clone directly** when nothing else is live and the change is on the clone's own checked-out branch (e.g. a `dev` doc tweak you're about to commit immediately).

## Where worktrees go (the location rule)

Always `<target-repo-root>/.worktrees/<branch>` — resolved from the **repo the work targets**, not your current directory, and as a **real path** (`pwd -P`). Two reasons this exact form matters:

- **Multi-repo workspaces.** When several repos sit under one coordination root and you may be launched from the root *or* from a member, deriving the path from the target repo's root (`git -C "$TARGET" rev-parse --show-toplevel`) makes it identical either way. Don't build cwd-relative or primary-clone-absolute paths.
- **Never `/tmp`.** On macOS `/tmp` is a symlink to `/private/tmp`; worktrees under it break tooling that resolves modules in worker threads — vite-node/vitest dies with `Cannot find package …` *before a single test runs*, so suites silently never run and regressions only surface in CI. A worktree under the repo root is already a real path; `pwd -P` is the backstop.

## Starting parallel work

To open a *new* parallel line of work, start it isolated from the beginning:

- **Native:** `claude -w <name>` launches Claude in its own worktree (`.claude/worktrees/<name>`). This is the built-in primitive — reach for it instead of opening a second session in the same tree.
- **Worktree-aware launcher (optional accelerator):** a launcher like the `proj` function in the operator's dotfiles makes "pick a branch → land in its worktree" one step — the default branch routes to the home-base/primary clone (read & coordinate), any other branch transparently gets a worktree. If such a launcher exists, prefer it.
- **`.worktreeinclude`** (gitignore syntax) lists gitignored files (e.g. `.env`) to copy into each new worktree; add `.claude/worktrees/` and `.worktrees/` to ignore rules.

## Knowing where you are

A worktree's git-dir path contains `/worktrees/`; the primary clone's does not — that's the reliable "am I isolated?" check. In a tmux status bar, surface the branch per pane and a `⚠ primary` marker when a pane sits in the primary clone with worktrees live, so the shared tree is visually obvious.

## Escalation — when isolation must be a hard guarantee

Worktrees + this discipline are a *soft* boundary: an agent can still drift back into the primary clone via absolute paths, and enforcement hooks have documented bypass paths. If you're running unattended fleets or `--dangerously-skip-permissions` and escape *must* be impossible, the real boundary is a **per-agent devcontainer** (filesystem-isolated, default-deny egress), not a hook. Reach for that only when the stakes require it — for interactive day-to-day parallel work, worktree-per-line-of-work is the right level.

## Related

- `feature-workflow` autopilot — already dispatches every write/git subagent with `isolation: "worktree"` (no opt-out). This skill covers the *other* paths (your ad-hoc changes, parallel sessions) that autopilot can't.
- `branch-promotion-model` — feature branches (the things you isolate) flow `feat → dev → main`.