worktree

Installation
SKILL.md

Worktree Isolation

Choose the branch first. Workspace setup uses the current role and direct tools within the caller's isolation authority. It needs no model worker or route resolution. Any later worker dispatch follows shared/references/model-preview.md and consumes the caller's approved snapshot without re-resolution or extra workers.

Ensure the current work happens in an isolated workspace without disturbing the user's main checkout. Most coding harnesses now create a worktree by default at session start, so first detect whether isolation already exists.

The common caller is a user asking for isolation. An implementation workflow may request it after its plan identifies independent tracks. Creating a reversible worktree is within an implementation request. Commit-based integration remains separately authorized. implement-and-review otherwise uses one sequential working-tree track.

Order of operations: detect existing isolation -> prefer the harness-native worktree tool -> fall back to plain git. Never create a worktree the harness cannot see.

Two modes, set by the caller's need:

  • New work (default). No specific ref named — create a fresh branch from a base (trunk).
  • Isolate an existing ref. The caller names a ref to work on in isolation — a PR head, an existing branch, or a commit. Attach the worktree to that ref instead of creating a new branch. One hard git rule governs this mode: a branch can be checked out in only one worktree at a time. If the named ref is already checked out somewhere (most commonly because it is the current branch in the primary checkout), do not create a second worktree for it — report that it is already checked out at <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.

The steps below (detect -> native tool -> git fallback) apply to both modes; the mode only changes what gets checked out and is reported back to the caller.

Installs
49
GitHub Stars
2
First Seen
Jul 28, 2026