Worktree

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.