95 added, 98 removed. Audit A to A.
---
name: using-git-worktrees
- description: Use when starting feature work that needs isolation from current workspace or before executing implementation plans - creates isolated git worktrees with smart directory selection and safety verification
+ description: 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
---
# Using Git Worktrees
## Overview
- Git worktrees create isolated workspaces sharing the same repository, allowing work on multiple branches simultaneously without switching.
+ Ensure 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.
- **Core principle:** Systematic directory selection + safety verification = reliable isolation.
+ **Core principle:** Detect existing isolation first. Then use native tools. Then fall back to git. Never fight the harness.
**Announce at start:** "I'm using the using-git-worktrees skill to set up an isolated workspace."
- ## Directory Selection Process
-
- Follow this priority order:
+ ## Step 0: Detect Existing Isolation
- ### 1. Check Existing Directories
+ **Before creating anything, check if you are already in an isolated workspace.**
```bash
- # Check in priority order
- ls -d .worktrees 2>/dev/null # Preferred (hidden)
- ls -d worktrees 2>/dev/null # Alternative
+ 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)
```
- **If found:** Use that directory. If both exist, `.worktrees` wins.
-
- ### 2. Check CLAUDE.md
+ **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:
```bash
- grep -i "worktree.*director" CLAUDE.md 2>/dev/null
+ # 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 preference specified:** Use it without asking.
+ **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.
- ### 3. Ask User
+ Report with 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 time."
- If no directory exists and no CLAUDE.md preference:
+ **If `GIT_DIR == GIT_COMMON` (or in a submodule):** You are in a normal repo checkout.
- ```
- No worktree directory found. Where should I create worktrees?
+ Has the user already indicated their worktree preference in your instructions? If not, ask for consent before creating a worktree:
- 1. .worktrees/ (project-local, hidden)
- 2. ~/.config/superpowers/worktrees/<project-name>/ (global location)
+ > "Would you like me to set up an isolated worktree? It protects your current branch from changes."
- Which would you prefer?
- ```
+ Honor any existing declared preference without asking. If the user declines consent, work in place and skip to Step 3.
- ## Safety Verification
+ ## Step 1: Create Isolated Workspace
- ### For Project-Local Directories (.worktrees or worktrees)
+ **You have two mechanisms. Try them in this order.**
- **MUST verify directory is ignored before creating worktree:**
+ ### 1a. Native Worktree Tools (preferred)
- ```bash
- # Check if directory is ignored (respects local, global, and system gitignore)
- git check-ignore -q .worktrees 2>/dev/null || git check-ignore -q worktrees 2>/dev/null
- ```
+ The 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.
- **If NOT ignored:**
+ Native 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.
- Per Jesse's rule "Fix broken things immediately":
- 1. Add appropriate line to .gitignore
- 2. Commit the change
- 3. Proceed with worktree creation
+ Only proceed to Step 1b if you have no native worktree tool available.
- **Why critical:** Prevents accidentally committing worktree contents to repository.
+ ### 1b. Git Worktree Fallback
- ### For Global Directory (~/.config/superpowers/worktrees)
+ **Only use this if Step 1a does not apply** — you have no native worktree tool available. Create a worktree manually using git.
- No .gitignore verification needed - outside project entirely.
+ #### Directory Selection
- ## Creation Steps
+ Follow this priority order. Explicit user preference always beats observed filesystem state.
- ### 1. Detect Project Name
+ 1. **Check your instructions for a declared worktree directory preference.** If the user has already specified one, use it without asking.
+ 2. **Check for an existing project-local worktree directory:**
+ ```bash
+ ls -d .worktrees 2>/dev/null # Preferred (hidden)
+ ls -d worktrees 2>/dev/null # Alternative
+ ```
+ If found, use it. If both exist, `.worktrees` wins.
+
+ 3. **Check for an existing global directory:**
+ ```bash
+ project=$(basename "$(git rev-parse --show-toplevel)")
+ ls -d ~/.config/superpowers/worktrees/$project 2>/dev/null
+ ```
+ If found, use it (backward compatibility with legacy global path).
+
+ 4. **If there is no other guidance available**, default to `.worktrees/` at the project root.
+
+ #### Safety Verification (project-local directories only)
+
+ **MUST verify directory is ignored before creating worktree:**
+
```bash
- project=$(basename "$(git rev-parse --show-toplevel)")
+ git check-ignore -q .worktrees 2>/dev/null || git check-ignore -q worktrees 2>/dev/null
```
- ### 2. Create Worktree
+ **If NOT ignored:** Add to .gitignore, commit the change, then proceed.
+ **Why critical:** Prevents accidentally committing worktree contents to repository.
+
+ Global directories (`~/.config/superpowers/worktrees/`) need no verification.
+
+ #### Create the Worktree
+
```bash
- # Determine full path
- case $LOCATION in
- .worktrees|worktrees)
- path="$LOCATION/$BRANCH_NAME"
- ;;
- ~/.config/superpowers/worktrees/*)
- path="~/.config/superpowers/worktrees/$project/$BRANCH_NAME"
- ;;
- esac
+ project=$(basename "$(git rev-parse --show-toplevel)")
- # Create worktree with new branch
+ # Determine path based on chosen location
+ # For project-local: path="$LOCATION/$BRANCH_NAME"
+ # For global: path="~/.config/superpowers/worktrees/$project/$BRANCH_NAME"
+
git worktree add "$path" -b "$BRANCH_NAME"
cd "$path"
```
- ### 3. Run Project Setup
+ **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.
+ ## Step 3: Project Setup
+
Auto-detect and run appropriate setup:
```bash
# Node.js
if [ -f package.json ]; then npm install; fi
# Rust
if [ -f Cargo.toml ]; then cargo build; fi
# Python
if [ -f requirements.txt ]; then pip install -r requirements.txt; fi
if [ -f pyproject.toml ]; then poetry install; fi
# Go
if [ -f go.mod ]; then go mod download; fi
```
- ### 4. Verify Clean Baseline
+ ## Step 4: Verify Clean Baseline
- Run tests to ensure worktree starts clean:
+ Run tests to ensure workspace starts clean:
```bash
- # Examples - use project-appropriate command
- npm test
- cargo test
- pytest
- go test ./...
+ # Use project-appropriate command
+ npm test / cargo test / pytest / go test ./...
```
**If tests fail:** Report failures, ask whether to proceed or investigate.
**If tests pass:** Report ready.
- ### 5. Report Location
+ ### Report
```
Worktree ready at <full-path>
Tests passing (<N> tests, 0 failures)
Ready to implement <feature-name>
```
## Quick Reference
| Situation | Action |
|-----------|--------|
+ | Already in linked worktree | Skip creation (Step 0) |
+ | In a submodule | Treat as normal repo (Step 0 guard) |
+ | Native worktree tool available | Use it (Step 1a) |
+ | No native tool | Git worktree fallback (Step 1b) |
| `.worktrees/` exists | Use it (verify ignored) |
| `worktrees/` exists | Use it (verify ignored) |
| Both exist | Use `.worktrees/` |
- | Neither exists | Check CLAUDE.md → Ask user |
+ | Neither exists | Check instruction file, then default `.worktrees/` |
+ | Global path exists | Use it (backward compat) |
| Directory not ignored | Add to .gitignore + commit |
+ | Permission error on create | Sandbox fallback, work in place |
| Tests fail during baseline | Report failures + ask |
| No package.json/Cargo.toml | Skip dependency install |
## Common Mistakes
+ ### Fighting the harness
+
+ - **Problem:** Using `git worktree add` when the platform already provides isolation
+ - **Fix:** Step 0 detects existing isolation. Step 1a defers to native tools.
+
+ ### Skipping detection
+
+ - **Problem:** Creating a nested worktree inside an existing one
+ - **Fix:** Always run Step 0 before creating anything
+
### Skipping ignore verification
- **Problem:** Worktree contents get tracked, pollute git status
- **Fix:** Always use `git check-ignore` before creating project-local worktree
### Assuming directory location
- **Problem:** Creates inconsistency, violates project conventions
- - **Fix:** Follow priority: existing > CLAUDE.md > ask
+ - **Fix:** Follow priority: existing > global legacy > instruction file > default
### Proceeding with failing tests
- **Problem:** Can't distinguish new bugs from pre-existing issues
- **Fix:** Report failures, get explicit permission to proceed
- ### Hardcoding setup commands
-
- - **Problem:** Breaks on projects using different tools
- - **Fix:** Auto-detect from project files (package.json, etc.)
-
- ## Example Workflow
-
- ```
- You: I'm using the using-git-worktrees skill to set up an isolated workspace.
-
- [Check .worktrees/ - exists]
- [Verify ignored - git check-ignore confirms .worktrees/ is ignored]
- [Create worktree: git worktree add .worktrees/auth -b feature/auth]
- [Run npm install]
- [Run npm test - 47 passing]
-
- Worktree ready at /Users/jesse/myproject/.worktrees/auth
- Tests passing (47 tests, 0 failures)
- Ready to implement auth feature
- ```
-
## Red Flags
**Never:**
+ - Create a worktree when Step 0 detects existing isolation
+ - 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.
+ - Skip Step 1a by jumping straight to Step 1b's git commands
- Create worktree without verifying it's ignored (project-local)
- Skip baseline test verification
- Proceed with failing tests without asking
- - Assume directory location when ambiguous
- - Skip CLAUDE.md check
**Always:**
- - Follow directory priority: existing > CLAUDE.md > ask
+ - Run Step 0 detection first
+ - Prefer native tools over git fallback
+ - Follow directory priority: existing > global legacy > instruction file > default
- Verify directory is ignored for project-local
- Auto-detect and run project setup
- Verify clean test baseline
-
- ## Integration
-
- **Called by:**
- - **brainstorming** (Phase 4) - REQUIRED when design is approved and implementation follows
- - **subagent-driven-development** - REQUIRED before executing any tasks
- - **executing-plans** - REQUIRED before executing any tasks
- - Any skill needing isolated workspace
-
- **Pairs with:**
- - **finishing-a-development-branch** - REQUIRED for cleanup after work complete