Worktree Isolation
Adds harness-aware git worktree setup for isolated branches and refs.
Ensure the current work happens in an isolated workspace without disturbing the main checkout. Most harnesses create a worktree by default at session start, so the common case is that isolation already exists. Detect that first and do not create a redundant one.
Order: detect existing isolation → prefer a native worktree tool → fall back to plain git. Never create a worktree the harness cannot see.
Modes
- New work (default). No specific ref named; create a fresh branch from the base branch.
- Isolate an existing ref. Caller names a ref to work on in isolation: a PR head, branch, or commit. Attach the worktree to that ref instead of creating a new branch.
Hard rule for isolate-an-existing-ref: a branch can be checked out in only one worktree at a time. If the named ref is already checked out elsewhere, report the path and let the caller act (work there in place; or, only if a clean separate tree is essential, create a detached worktree at the same commit). Never put one branch in two worktrees.
Step 0: Detect existing isolation
Before creating anything, check whether the current directory is already a linked worktree. Compare the resolved absolute git dir against the resolved absolute common git dir:
git rev-parse --absolute-git-dir
(cd "$(git rev-parse --git-common-dir)" && pwd -P)
If equal, this is a normal checkout; continue to Step 1.
If they differ, you are in a linked worktree or a submodule. Distinguish:
git rev-parse --show-superproject-working-tree
- Non-empty output → submodule; treat as normal checkout and continue to Step 1.
- Empty output → already in an isolated worktree. Report the worktree path (
git rev-parse --show-toplevel) and current branch. Do not create another worktree. In new-work mode, continue here. In isolate-an-existing-ref mode, check that ref out here unless it is already the current branch.
Step 1: Prefer the harness's native worktree tool
If the harness provides a native worktree primitive (for example Claude Code's EnterWorktree, a /worktree command, or a --worktree flag), use it and stop. Native tools place, track, and clean up the worktree so the harness can manage it. A behind-the-back git worktree add creates phantom state the harness cannot see, navigate to, or clean up.
Step 2: Git fallback
Manual git-worktree mechanics — the numbered creation steps, the
.worktrees/<branch> convention, and the list/remove commands — live in
references/git-fallback.md. Read it only when Step 1 finds no native
harness worktree tool and Step 0 found no existing isolation.
When to create a worktree
Create one only when not already isolated and a separate workspace is needed:
- Reviewing a PR while keeping the current checkout free.
- Running multiple features in parallel without branch-switching overhead.
Do not create a worktree for single-task work that can happen on a branch in the current checkout, and never when Step 0 shows you are already in one.
Integration
/work and /review offer this skill as an option. When the user selects "worktree" in those flows, run Step 0 first: if already isolated, proceed in place; otherwise create one (native tool preferred) with a meaningful branch name derived from the work description.
Troubleshooting
Recovery commands for "Worktree already exists" and "Cannot remove worktree:
it is the current worktree" live in references/git-fallback.md, alongside
the git-fallback creation steps they pair with.