pi-skills/superpowers/using-git-worktrees/SKILL.md

name, description

name	description
using-git-worktrees	Use when starting feature work that needs isolation from current workspace or before executing implementation plans - creates isolated git worktrees with safety verification

Using Git Worktrees

Overview

Git worktrees create isolated workspaces sharing the same repository, allowing work on multiple branches simultaneously without switching.

Core principle: Use repo-root .worktree/ + safety verification for reliable isolation.

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

Directory Rule

Use repo-root .worktree/ by default.

Do not suggest:

• .worktrees/
• worktrees/
• ~/.config/superpowers/worktrees/...

Only deviate if the user explicitly asks for a different location.

Safety Verification

MUST verify .worktree/ is ignored before creating a worktree:

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

If NOT ignored:

Per Jesse's rule "Fix broken things immediately":

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

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

Creation Steps

1. Detect Project Name

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

2. Create Worktree

path=".worktree/$BRANCH_NAME"
git worktree add "$path" -b "$BRANCH_NAME"
cd "$path"

3. Run Project Setup

Auto-detect and run 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

4. Verify Clean Baseline

Run tests to ensure worktree starts clean:

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

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

Quick Reference

Situation	Action
Starting feature work	Use .worktree/<branch-name>
.worktree/ not ignored	Add .worktree/ to .gitignore, commit, continue
Tests fail during baseline	Report failures and ask
No package manager/build file	Skip dependency install
User explicitly wants another location	Follow the user's instruction

Common Mistakes

Skipping ignore verification

• Problem: Worktree contents get tracked and pollute git status
• Fix: Always verify .worktree/ is ignored first

Using the wrong directory

• Problem: Inconsistent worktree layout across repositories
• Fix: Use repo-root .worktree/ unless the user explicitly overrides it

Proceeding with failing tests

• Problem: Can't distinguish new bugs from pre-existing issues
• Fix: Report failures and 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.

[Verify .worktree/ is ignored]
[Create worktree: git worktree add .worktree/auth -b feature/auth]
[Run npm install]
[Run npm test - 47 passing]

Worktree ready at /Users/jesse/myproject/.worktree/auth
Tests passing (47 tests, 0 failures)
Ready to implement auth feature

Red Flags

Never:

• Create a worktree without verifying .worktree/ is ignored
• Skip baseline test verification
• Proceed with failing tests without asking
• Suggest .worktrees/, worktrees/, or ~/.config/superpowers/worktrees/... by default

Always:

• Use repo-root .worktree/ by default
• Verify .worktree/ is ignored
• Auto-detect and run project setup
• Verify a 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