superpowers-using-git-worktrees

Using Git Worktrees

Overview

Work in isolated workspace. Prefer native worktree tools; manual git worktrees only when none.

Core principle: Detect existing isolation first. Then native tools. Then git fallback. Never fight harness.

Announce at start: "I'm using the superpowers-using-git-worktrees skill to set up an isolated workspace."

Step 0: Detect Existing Isolation

Before creating anything, check if already in isolated workspace. Via bash:

GIT_DIR=$(cd "$(git rev-parse --git-dir)" 2>/dev/null && pwd -P)
GIT_COMMON=$(cd "$(git rev-parse --git-common-dir)" 2>/dev/null && pwd -P)
BRANCH=$(git branch --show-current)

Submodule guard: GIT_DIR != GIT_COMMON also true inside submodules. Verify not a submodule before concluding "worktree":

# If this returns a path, you're in a submodule, not a worktree — treat as normal repo
git rev-parse --show-superproject-working-tree 2>/dev/null

If GIT_DIR != GIT_COMMON (and not a submodule): Already in linked worktree. Skip to Step 3, do NOT create another. Report branch state:

• On a branch: "Already in isolated workspace at <path> on branch <name>."
• Detached HEAD: "Already in isolated workspace at <path> (detached HEAD, externally managed). Branch creation needed at finish."

If GIT_DIR == GIT_COMMON (or in a submodule): Normal repo checkout. Preference declared? Honor it, no asking. Else ask consent:

"Would you like me to set up an isolated worktree? It protects your current branch from changes."

Declines: work in place, skip to Step 3 — do NOT start editing feature code on the current branch first.

Step 1: Create Isolated Workspace

1a. Native Worktree Tools (preferred)

Already have a worktree mechanism — a tool named EnterWorktree, WorktreeCreate, a /worktree command, or a --worktree flag? Use it, skip to Step 3.

Native tools handle placement, branch creation, cleanup. Using git worktree add when a native tool exists creates phantom state the harness can't manage. No native tool: proceed to Step 1b.