1---
2name: using-git-worktrees
3description: Use when starting feature work that needs isolation from current workspace or before executing implementation plans - ensures an isolated workspace exists via native tools or git worktree fallback
4---
5 
6# Using Git Worktrees
7 
8## Overview
9 
10Ensure work happens in an isolated workspace. Prefer your platform's native worktree tools. Fall back to manual git worktrees only when no native tool is available.
11 
12**Core principle:** Detect existing isolation first. Then use native tools. Then fall back to git. Never fight the harness.
13 
14**Announce at start:** "I'm using the using-git-worktrees skill to set up an isolated workspace."
15 
16## Step 0: Detect Existing Isolation
17 
18**Before creating anything, check if you are already in an isolated workspace.**
19 
20```bash
21GIT_DIR=$(cd "$(git rev-parse --git-dir)" 2>/dev/null && pwd -P)
22GIT_COMMON=$(cd "$(git rev-parse --git-common-dir)" 2>/dev/null && pwd -P)
23BRANCH=$(git branch --show-current)
24```
25 
26**Submodule guard:** `GIT_DIR != GIT_COMMON` is also true inside git submodules. Before concluding "already in a worktree," verify you are not in a submodule:
27 
28```bash
29# If this returns a path, you're in a submodule, not a worktree — treat as normal repo
30git rev-parse --show-superproject-working-tree 2>/dev/null
31```
32 
33**If `GIT_DIR != GIT_COMMON` (and not a submodule):** You are already in a linked worktree. Skip to Step 3 (Project Setup). Do NOT create another worktree.
34 
35Report with branch state:
36- On a branch: "Already in isolated workspace at `<path>` on branch `<name>`."
37- Detached HEAD: "Already in isolated workspace at `<path>` (detached HEAD, externally managed). Branch creation needed at finish time."
38 
39**If `GIT_DIR == GIT_COMMON` (or in a submodule):** You are in a normal repo checkout.
40 
41Has the user already indicated their worktree preference in your instructions? If not, ask for consent before creating a worktree:
42 
43> "Would you like me to set up an isolated worktree? It protects your current branch from changes."
44 
45Honor any existing declared preference without asking. If the user declines consent, work in place and skip to Step 3.
46 
47## Step 1: Create Isolated Workspace
48 
49**You have two mechanisms. Try them in this order.**
50 
51### 1a. Native Worktree Tools (preferred)
52 
53The user has asked for an isolated workspace (Step 0 consent). Do you already have a way to create a worktree? It might be a tool with a name like `EnterWorktree`, `WorktreeCreate`, a `/worktree` command, or a `--worktree` flag. If you do, use it and skip to Step 3.
54 
55Native tools handle directory placement, branch creation, and cleanup automatically. Using `git worktree add` when you have a native tool creates phantom state your harness can't see or manage.
56 
57Only proceed to Step 1b if you have no native worktree tool available.
58 
59### 1b. Git Worktree Fallback
60 
61**Only use this if Step 1a does not apply** — you have no native worktree tool available. Create a worktree manually using git.
62 
63#### Directory Selection
64 
65Follow this priority order. Explicit user preference always beats observed filesystem state.
66 
671. **Check your instructions for a declared worktree directory preference.** If the user has already specified one, use it without asking.
68 
692. **Check for an existing project-local worktree directory:**
70   ```bash
71   ls -d .worktrees 2>/dev/null     # Preferred (hidden)
72   ls -d worktrees 2>/dev/null      # Alternative
73   ```
74   If found, use it. If both exist, `.worktrees` wins.
75 
763. **Check for an existing global directory:**
77   ```bash
78   project=$(basename "$(git rev-parse --show-toplevel)")
79   ls -d ~/.config/superpowers/worktrees/$project 2>/dev/null
80   ```
81   If found, use it (backward compatibility with legacy global path).
82 
834. **If there is no other guidance available**, default to `.worktrees/` at the project root.
84 
85#### Safety Verification (project-local directories only)
86 
87**MUST verify directory is ignored before creating worktree:**
88 
89```bash
90git check-ignore -q .worktrees 2>/dev/null || git check-ignore -q worktrees 2>/dev/null
91```
92 
93**If NOT ignored:** Add to .gitignore, commit the change, then proceed.
94 
95**Why critical:** Prevents accidentally committing worktree contents to repository.
96 
97Global directories (`~/.config/superpowers/worktrees/`) need no verification.
98 
99#### Create the Worktree
100 
101```bash
102project=$(basename "$(git rev-parse --show-toplevel)")
103 
104# Determine path based on chosen location
105# For project-local: path="$LOCATION/$BRANCH_NAME"
106# For global: path="~/.config/superpowers/worktrees/$project/$BRANCH_NAME"
107 
108git worktree add "$path" -b "$BRANCH_NAME"
109cd "$path"
110```
111 
112**Sandbox fallback:** If `git worktree add` fails with a permission error (sandbox denial), tell the user the sandbox blocked worktree creation and you're working in the current directory instead. Then run setup and baseline tests in place.
113 
114## Step 3: Project Setup
115 
116Auto-detect and run appropriate setup:
117 
118```bash
119# Node.js
120if [ -f package.json ]; then npm install; fi
121 
122# Rust
123if [ -f Cargo.toml ]; then cargo build; fi
124 
125# Python
126if [ -f requirements.txt ]; then pip install -r requirements.txt; fi
127if [ -f pyproject.toml ]; then poetry install; fi
128 
129# Go
130if [ -f go.mod ]; then go mod download; fi
131```
132 
133## Step 4: Verify Clean Baseline
134 
135Run tests to ensure workspace starts clean:
136 
137```bash
138# Use project-appropriate command
139npm test / cargo test / pytest / go test ./...
140```
141 
142**If tests fail:** Report failures, ask whether to proceed or investigate.
143 
144**If tests pass:** Report ready.
145 
146### Report
147 
148```
149Worktree ready at <full-path>
150Tests passing (<N> tests, 0 failures)
151Ready to implement <feature-name>
152```
153 
154## Quick Reference
155 
156| Situation | Action |
157|-----------|--------|
158| Already in linked worktree | Skip creation (Step 0) |
159| In a submodule | Treat as normal repo (Step 0 guard) |
160| Native worktree tool available | Use it (Step 1a) |
161| No native tool | Git worktree fallback (Step 1b) |
162| `.worktrees/` exists | Use it (verify ignored) |
163| `worktrees/` exists | Use it (verify ignored) |
164| Both exist | Use `.worktrees/` |
165| Neither exists | Check instruction file, then default `.worktrees/` |
166| Global path exists | Use it (backward compat) |
167| Directory not ignored | Add to .gitignore + commit |
168| Permission error on create | Sandbox fallback, work in place |
169| Tests fail during baseline | Report failures + ask |
170| No package.json/Cargo.toml | Skip dependency install |
171 
172## Common Mistakes
173 
174### Fighting the harness
175 
176- **Problem:** Using `git worktree add` when the platform already provides isolation
177- **Fix:** Step 0 detects existing isolation. Step 1a defers to native tools.
178 
179### Skipping detection
180 
181- **Problem:** Creating a nested worktree inside an existing one
182- **Fix:** Always run Step 0 before creating anything
183 
184### Skipping ignore verification
185 
186- **Problem:** Worktree contents get tracked, pollute git status
187- **Fix:** Always use `git check-ignore` before creating project-local worktree
188 
189### Assuming directory location
190 
191- **Problem:** Creates inconsistency, violates project conventions
192- **Fix:** Follow priority: existing > global legacy > instruction file > default
193 
194### Proceeding with failing tests
195 
196- **Problem:** Can't distinguish new bugs from pre-existing issues
197- **Fix:** Report failures, get explicit permission to proceed
198 
199## Red Flags
200 
201**Never:**
202- Create a worktree when Step 0 detects existing isolation
203- Use `git worktree add` when you have a native worktree tool (e.g., `EnterWorktree`). This is the #1 mistake — if you have it, use it.
204- Skip Step 1a by jumping straight to Step 1b's git commands
205- Create worktree without verifying it's ignored (project-local)
206- Skip baseline test verification
207- Proceed with failing tests without asking
208 
209**Always:**
210- Run Step 0 detection first
211- Prefer native tools over git fallback
212- Follow directory priority: existing > global legacy > instruction file > default
213- Verify directory is ignored for project-local
214- Auto-detect and run project setup
215- Verify clean test baseline
216