Using Git Worktrees

Set up isolated workspaces for feature development with automatic safety verification

Create isolated git worktrees for working on multiple branches simultaneously without switching contexts. This skill handles directory selection, safety verification, and project setup automatically.

When to Use

Use this skill when:

• Starting feature work that needs isolation from your current workspace
• Before executing implementation plans
• Working on multiple features that need to coexist
• Wanting to preserve your current workspace state while experimenting

Always announce at start: “I’m using the using-git-worktrees skill to set up an isolated workspace.”

Core Principle

Systematic directory selection + safety verification = reliable isolation

Git worktrees share the same repository while providing separate working directories. This allows concurrent work on different branches without the overhead of cloning.

Directory Selection Process

The skill follows a strict priority order to determine where to create worktrees:

1. Check for existing directories

   First checks if a worktree directory already exists:

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

   If found, uses that directory. If both exist, .worktrees wins.

2. Check CLAUDE.md for preferences

   If no directory exists, checks for a preference in CLAUDE.md:

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

   If a preference is specified, uses it without asking.

3. Ask the user

   If no directory exists and no CLAUDE.md preference, presents two options:

   1. .worktrees/ - Project-local, hidden directory
   2. ~/.config/superpowers/worktrees/<project-name>/ - Global location

Safety Verification

For project-local directories (.worktrees or worktrees), the skill must verify the directory is ignored before creating a worktree.

Project-Local Directories

Before creating a worktree:

# Check if directory is ignored
git check-ignore -q .worktrees 2>/dev/null || git check-ignore -q worktrees 2>/dev/null

If NOT ignored:

Following the rule “Fix broken things immediately”:

1. Add appropriate line to .gitignore
2. Commit the change
3. Proceed with worktree creation

Why this is critical: Prevents accidentally committing worktree contents to the repository.

Global Directory

For ~/.config/superpowers/worktrees, no .gitignore verification is needed - it’s outside the project entirely.

Creation Workflow

1. Detect project name

   project=$(basename "$(git rev-parse --show-toplevel)")
   
2. Create worktree

   # Determine full path based on location
   case $LOCATION in
     .worktrees|worktrees)
       path="$LOCATION/$BRANCH_NAME"
       ;;
     ~/.config/superpowers/worktrees/*)
       path="~/.config/superpowers/worktrees/$project/$BRANCH_NAME"
       ;;
   esac
   
   # Create worktree with new branch
   git worktree add "$path" -b "$BRANCH_NAME"
   cd "$path"
   
3. Run project setup

   Auto-detects and runs appropriate setup commands:

   # 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

   Runs tests to ensure the worktree starts clean:

   npm test
   cargo test
   pytest
   go test ./...
   

   If tests fail: Reports failures and asks whether to proceed or investigate.

   If tests pass: Reports ready.

5. Report location

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

Quick Reference

Situation	Action
.worktrees/ exists	Use it (verify ignored)
worktrees/ exists	Use it (verify ignored)
Both exist	Use .worktrees/
Neither exists	Check CLAUDE.md → Ask user
Directory not ignored	Add to .gitignore + commit
Tests fail during baseline	Report failures + ask
No package.json/Cargo.toml	Skip dependency install

Common Pitfalls

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

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, Cargo.toml, 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 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
• Verify directory is ignored for project-local
• Auto-detect and run project setup
• Verify clean test baseline

Integration with Other Skills

Called by

• brainstorming (Phase 4) - Required when design is approved
• subagent-driven-development - Required before executing tasks
• executing-plans - Required before executing tasks

Pairs with

• finishing-a-development-branch - Required for cleanup after work complete