using-git-worktrees

Use Git Worktrees

Overview

Ensure work happens in an isolated workspace. Prefer your platform's native worktree tools. Only fall back to manual git worktrees when no native tool is available.

Core principle: Detect existing isolation first. Then use native tools. Then fall back to git. Never fight the harness.

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

Step 0: Detect existing isolation

Before creating anything, check whether you are already in an isolated workspace.

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 This is also true inside git submodules. Before concluding "already in a worktree", first verify you are not in a submodule:

# 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): You are already in a linked worktree. Skip to Step 3 (Project Setup). Do not create another worktree.

Report branch status:

On 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 GIT_DIR == GIT_COMMON(or in a submodule): You are in a normal repo checkout.

Has the user already indicated their worktree preference in your instructions? If not, get consent before creating a worktree:

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

Follow any existing explicit preference and do not ask again. If the user declines consent, work in place and skip to Step 3.

Step 1: Create isolated Workspace

You have two mechanisms. Try them in this order.

1a. Native Worktree tools (preferred)

The user has already asked to use an isolated workspace (Step 0 consent). Do you already have a way to create a worktree? It might be a tool named EnterWorktree、WorktreeCreate , a/worktree command, or a --worktree flag. If so, use it and skip to Step 3.

Native tools automatically handle directory location, branch creation, and cleanup. Using git worktree addwhen you have a native tool creates phantom state that the harness cannot see or manage.

Only continue to Step 1b when no native worktree tool is available.

1b. Git Worktree Fallback

Only use this when Step 1a does not apply — you have no native worktree tool available. Create a worktree manually with git.

Directory selection

Follow this priority order. An explicit user preference always takes precedence over observed filesystem state.

Check whether a worktree directory preference is declared in your instructions. If the user has already specified one, use it without asking.

Check whether a project-local worktree directory exists:

ls -d .worktrees 2>/dev/null     # Preferred (hidden)
ls -d worktrees 2>/dev/null      # Alternative

If found, use it. If both exist,.worktrees takes precedence.

Check whether a global directory exists:

project=$(basename "$(git rev-parse --show-toplevel)")
ls -d ~/.config/superpowers/worktrees/$project 2>/dev/null

If found, use it (maintain backward compatibility with the legacy global path).

If no other guidance is available, default to .worktrees/。

Safety verification (project-local directories only)

Before creating a worktree you must verify the directory is ignored:

git check-ignore -q .worktrees 2>/dev/null || git check-ignore -q worktrees 2>/dev/null

If it is not ignored: Add to .gitignore, commit that change, then continue.

Why it matters: Prevent accidentally committing worktree contents to the repository.

Global directory (~/.config/superpowers/worktrees/) requires no verification.

Create Worktree

project=$(basename "$(git rev-parse --show-toplevel)")

# 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"

Sandbox fallback： If git worktree add fails due to a permission error (sandbox denial), tell the user the sandbox blocked worktree creation and that you will work in the current directory instead. Then run setup and baseline tests in place.

Step 3: Project Setup

Automatically detect and run the appropriate setup:

# 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

Step 4: Verify Clean Baseline

Run the tests to ensure the workspace starts in a clean state:

# Use project-appropriate command
npm test / cargo test / pytest / go test ./...

If tests fail: Report the failure and ask whether to continue or investigate.

If tests pass: Report ready.

Report

Worktree ready at <full-path>
Tests passing (<N> tests, 0 failures)
Ready to implement <feature-name>

Quick Reference

Situation	Action
Already in a linked worktree	Skip creation (Step 0)
In a submodule	Treat as a 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 the instruction file, then default to `.worktrees/`
Global path exists	Use it (backward compat)
Directory not ignored	Add to .gitignore + commit
Permission error during creation	Sandbox fallback, work in place
Tests fail during baseline	Report failure + ask
No package.json/Cargo.toml	Skip dependency install

Common Mistakes

Anti-patterns as harness

Problem: Using git worktree add
Fix: Step 0 detects existing isolation. Step 1a hands off to the native tool.

Skipping detection

Problem: Creating a nested worktree inside an existing worktree
Fix: Always run Step 0 before creating anything

Skipping ignore verification

Problem: Worktree contents are tracked, polluting git status
Fix: Always use git check-ignore

Assuming the directory location

Problem: Creates inconsistency, violating project conventions
Fix: Follow the priority: existing > global legacy > instruction file > default

Continuing when tests fail

Problem: Cannot distinguish new bugs from pre-existing issues
Fix: Report the failure and obtain explicit permission before continuing

Red Flags

Never:

Create a worktree when Step 0 detects existing isolation
When you have a native worktree tool (e.g. EnterWorktree) use git worktree add. This is the #1 mistake — if you have it, use it.
Skip Step 1a and jump directly to the git commands in Step 1b
Create a worktree without verifying it is ignored (project-local)
Skip baseline test verification
Continue when tests fail without asking

Always:

Run Step 0 detection first
Prefer native tools over the git fallback
Follow directory priority: existing > global legacy > instruction file > default
Verify the directory is ignored for project-local directories
Auto-detect and run project setup
Verify a clean test baseline