Using Git Worktrees

Overview

Ensure work happens in an isolated workspace. Prioritize your platform's native worktree tools. Only fall back to manual git worktree when no native tools are 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 am using the using-git-worktrees skill to set up an isolated workspace."

Step 0: Detect Existing Isolation

Before creating anything, check if you're already in an isolated workspace.

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

is also true inside a git submodule. Before determining "already in worktree", confirm you're not in a submodule:

bash

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

If
GIT_DIR != GIT_COMMON
(and not in a submodule): You're already inside a linked worktree. Skip to Step 3 (Project Setup). Do NOT create another worktree.

Report based on branch status:

On a branch: "Already in isolated workspace
```
<path>
```
, branch
```
<name>
```
."
Detached HEAD: "Already in isolated workspace
```
<path>
```
(detached HEAD, managed externally). Need to create a branch when done."

If
GIT_DIR == GIT_COMMON
(or in a submodule): You're in a normal repo checkout.

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

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

If the user has stated a preference, follow it directly without asking. If the user declines consent, work in place and skip to Step 3.

Step 1: Create Isolated Workspace

You have two mechanisms. Try in this order.

1a. Native Worktree Tools (Preferred)

The user has requested an isolated workspace (consented in Step 0). Do you already have a method to create worktrees? It could be tools named

EnterWorktree

WorktreeCreate

/worktree

command, or

--worktree

flag. If yes, use it, then skip to Step 3.

Native tools automatically handle directory placement, branch creation, and cleanup. Using

git worktree add

when you have native tools will create "phantom state" that your harness can't see or manage.

Only proceed to Step 1b if no native worktree tools are available.

1b. Git Worktree Fallback

Only use when Step 1a is not applicable — you have no native worktree tools available. Manually create a worktree with git.

Directory Selection

Follow these priorities. Explicit user preferences always take precedence over observed filesystem state.

Check if a worktree directory preference is declared in your instructions. If specified by the user, use it without asking.

Check for project-local worktree directories:

bash

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

Use if found. If both exist,

.worktrees

takes priority.

Check for global directory:

bash

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

Use if found (compatible with old global paths).

If no other references exist, default to
```
.worktrees/
```
in the project root.

Security Validation (Project-Local Directories Only)

Must verify the directory is ignored before creating worktree:

bash

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

If not ignored: Add to .gitignore, commit the change, then proceed.

Why it's critical: Prevent worktree content from being accidentally committed to the repo.

Global directories (

~/.config/superpowers/worktrees/

) don't need validation.

Create Worktree

bash

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

# Determine path based on selected location
# Project-local: path="$LOCATION/$BRANCH_NAME"
# 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 permission errors (sandbox denial), inform the user that the sandbox prevented worktree creation, and you will work in the current directory. Then run setup and baseline tests in place.

Step 3: Project Setup

Automatically detect and run the corresponding setup commands:

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

Step 4: Verify Clean Baseline

Run tests to ensure the initial workspace state is clean:

bash

# Use project-specific commands
npm test / cargo test / pytest / go test ./...

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

If tests pass: Report readiness.

Report

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

Quick Reference

Scenario	Action
Already in linked worktree	Skip creation (Step 0)
Inside a submodule	Treat as normal repo (Step 0 guard)
Native worktree tools available	Use them (Step 1a)
No native tools	Use git worktree fallback (Step 1b)
`.worktrees/` exists	Use it (verify ignored)
`worktrees/` exists	Use it (verify ignored)
Both exist	Use `.worktrees/`
Neither exists	Check instructions file, then default to `.worktrees/`
Global path exists	Use it (backward compatibility)
Directory not ignored	Add to .gitignore + commit
Permission error during creation	Sandbox fallback, work in place
Baseline tests fail	Report failure + ask
No package.json/Cargo.toml	Skip dependency installation

Common Errors

Fighting the Harness

Problem: Using
```
git worktree add
```
when the platform already provides isolation
Fix: Detect existing isolation in Step 0. Defer to native tools in Step 1a.

Skipping Detection

Problem: Nested creation of another worktree inside an existing one
Fix: Always run Step 0 before creating anything

Skipping Ignore Validation

Problem: Worktree content is tracked, polluting git status
Fix: Always use
```
git check-ignore
```
before creating project-local worktrees

Assuming Directory Location

Problem: Causes inconsistency, violates project conventions
Fix: Follow priorities: existing directories > global historical paths > instructions file > default

Continuing with Failed Tests

Problem: Can't distinguish new bugs from pre-existing issues
Fix: Report failure and get explicit permission before continuing

Red Lines

Never:

Create a worktree when Step 0 detects existing isolation
Use
```
git worktree add
```
when native worktree tools (like
```
EnterWorktree
```
) are available. This is the #1 mistake — use what's available.
Skip Step 1a and jump directly to git commands in Step 1b
Create project-local worktrees without verifying they're ignored
Skip baseline test validation
Continue with failed tests without asking

Always:

Run Step 0 detection first
Prioritize native tools, then git fallback
Follow directory priorities: existing directories > global historical paths > instructions file > default
Verify project-local directories are ignored
Automatically detect and run project setup
Verify clean test baseline

Integration

Called by these skills:

brainstorming (Phase 4) - Required when design is approved and implementation is needed
subagent-driven-development - Required before executing any tasks
executing-plans - Required before executing any tasks
Any skill that requires an isolated workspace

Used with:

finishing-a-development-branch - Required for cleanup when work is completed

using-git-worktrees

NPX Install

Tags

SKILL.md Content (Chinese)

Using Git Worktrees

Overview

Step 0: Detect Existing Isolation

Step 1: Create Isolated Workspace

1a. Native Worktree Tools (Preferred)

1b. Git Worktree Fallback

Directory Selection

Security Validation (Project-Local Directories Only)

Create Worktree

Step 3: Project Setup

Step 4: Verify Clean Baseline

Report

Quick Reference

Common Errors

Fighting the Harness

Skipping Detection

Skipping Ignore Validation

Assuming Directory Location

Continuing with Failed Tests

Red Lines

Integration