aile-git-worktrees

Using Git Worktrees

Overview

Git worktrees create independent workspaces that share the same repository, allowing work on multiple branches simultaneously without switching.

**Core principle:** Systematic directory selection + safety verification = reliable isolation.

Declare at the start:"I am using the aile-git-worktrees skill to set up an isolated workspace."

Directory Selection Process

Follow this priority order:

1. Check existing directories

# 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,.worktreeswins.

2. Check CLAUDE.md

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

If a preference is specified: use it without asking.

3. Ask the user

If no directory exists and there is no CLAUDE.md preference:

No worktree directory found. Where should I create worktrees?

1. .worktrees/ (project-local, hidden)
2. ~/.config/superpowers/worktrees/<project-name>/ (global location)

Which would you prefer?

Safety Verification

For project-local directories (.worktrees or worktrees)

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

# Check if directory is ignored (respects local, global, and system gitignore)
git check-ignore -q .worktrees 2>/dev/null || git check-ignore -q worktrees 2>/dev/null

If not ignored:

According to Jesse's rule "fix broken things immediately":

1. Add the appropriate line to .gitignore
2. Commit the change
3. Continue creating the worktree

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

For global directories (~/.config/superpowers/worktrees)

Skip .gitignore verification - entirely outside the project.

Creation Steps

1. Detect project name

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

2. Create worktree

# Determine full path
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

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

4. Verify a clean baseline

Run tests to ensure the worktree starts clean:

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

If tests fail: report the failure, ask whether to continue 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
.worktrees/exists	Use it (verify ignored)
worktrees/exists	Use it (verify ignored)
Both exist	Use.worktrees/
Neither exists	Check CLAUDE.md → ask the user
Directory is not ignored	Add to .gitignore + commit
Tests fail during baseline	Report failure + ask
Package has no .json/Cargo.toml	Skip dependency installation

Common Mistakes

Skipping ignore verification

• Problem: Worktree contents are tracked, polluting git status
• **Fix:** Always usegit check-ignorebefore creating a project-local worktree

Assuming the directory location

• Problem: Causes inconsistency, violates project conventions
• **Fix:** Follow priority: existing > CLAUDE.md > ask

Continuing with failing tests

• Problem: Cannot distinguish new errors from pre-existing issues
• Fix: report failure, obtain explicit permission to continue

Hardcoded setup commands

• Problem: breaks in projects using different tools
• **Fix:** Auto-detect from project files (package.json, etc.)

Example Workflow

You: I'm using the aile-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 a worktree without verifying it is ignored (project-local)
• Skip baseline test verification
• Proceed on failing tests without asking
• Assume directory location when it is unclear
• Skip CLAUDE.md check

Always:

• Follow directory priority: existing > CLAUDE.md > ask
• Verify project-local directories are ignored
• Auto-detect and run project setup
• Verify a clean test baseline

Integration

Callers:

• Brainstorming(Phase 4) - needed when a design is approved and subsequently implemented
• Subagent-driven development - needed before executing any task
• Execution plan - needed before executing any task
• Any skill requiring an independent workspace

Works with:

• Finishing a development branch - needed for cleanup after work is complete