name: using-git-worktrees
description: Use when starting new feature work to create isolated git worktrees with smart directory selection and safety verification. Keeps main branch clean while developing.

Using Git Worktrees

Core Principle

Isolate feature work. Keep main clean.

Git worktrees let you work on multiple branches simultaneously in separate directories.

When to Use

• Starting a new feature
• Working on a bugfix while main development continues
• Need to context-switch without stashing
• Want clean separation between work streams

Setup Process

Step 1: Check for Existing Worktree Directory

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

If found: Use that directory.
If both exist: .worktrees wins.

Step 2: Check CLAUDE.md for Preferences

grep -i "worktree.*director" CLAUDE.md 2>/dev/null

If preference specified: Use it without asking.

Step 3: If No Directory Exists

Ask the user:

No worktree directory found. Where should I create worktrees?
1. .worktrees/ (project-local, hidden)
2. worktrees/ (project-local, visible)
3. ~/.config/superpowers/worktrees/<project-name>/ (global location)

Which would you prefer?

Step 4: Verify .gitignore

# Check if directory pattern in .gitignore
grep -q "^\.worktrees/$" .gitignore || grep -q "^worktrees/$" .gitignore

If not present, add it:

echo ".worktrees/" >> .gitignore
# or
echo "worktrees/" >> .gitignore

Creating a Worktree

Standard Creation

# Determine branch name from feature
BRANCH_NAME="feature/descriptive-name"

# Create worktree with new branch
git worktree add ".worktrees/$BRANCH_NAME" -b "$BRANCH_NAME"

# Navigate to worktree
cd ".worktrees/$BRANCH_NAME"

From Existing Branch

git worktree add ".worktrees/$BRANCH_NAME" "$BRANCH_NAME"

Post-Creation Setup

Install Dependencies

# 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

Run Initial Tests

# Run test suite
npm test  # or appropriate command

# Report status

If tests fail: Report failures, ask whether to proceed or investigate.
If tests pass: Report ready.

Worktree Management

List Worktrees

git worktree list

Remove Worktree

# After merging feature branch
git worktree remove ".worktrees/feature/branch-name"

# Force remove (if needed)
git worktree remove --force ".worktrees/feature/branch-name"

Prune Stale Worktrees

git worktree prune

Best Practices

Naming Convention

• feature/descriptive-name for features
• bugfix/issue-number-description for bugs
• hotfix/critical-issue for urgent fixes

Keep Worktrees Focused

• One feature per worktree
• Merge and remove when done
• Don't let worktrees accumulate

Sync Regularly

# In worktree, get latest from main
git fetch origin
git rebase origin/main

Completion Checklist

When feature is complete:
1. [ ] All tests pass
2. [ ] Code reviewed
3. [ ] Merged to main
4. [ ] Worktree removed
5. [ ] Branch deleted (if desired)

# Full cleanup
git checkout main
git pull
git worktree remove ".worktrees/feature/name"
git branch -d feature/name

Announcement Template

At start of worktree creation:

"I'm using the using-git-worktrees skill to set up an isolated workspace for [feature name]."

On completion:

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