Git Worktree

Process

1. Check existing directories: .worktrees/ or worktrees/
2. Verify gitignored: MUST verify before creating
3. Create worktree: git worktree add <path> -b <branch>
4. Run project setup: Auto-detect (npm/pip/go/cargo)
5. Verify baseline tests: Run tests, report status

Directory Selection

Priority	Check
1	Existing .worktrees/
2	Existing worktrees/
3	Project config/docs
4	Ask user

Safety Verification

For project-local directories:

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

If NOT ignored → Add to .gitignore first.

Creation Steps

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

# Run project setup in worktree (use absolute path)
if [ -f ".worktrees/$BRANCH_NAME/package.json" ]; then npm install --prefix ".worktrees/$BRANCH_NAME"; fi
if [ -f ".worktrees/$BRANCH_NAME/requirements.txt" ]; then pip install -r ".worktrees/$BRANCH_NAME/requirements.txt"; fi

# Verify baseline tests
npm test / pytest / go test ./...

Report Format

Worktree ready at <full-path>
Branch: <branch-name>
Tests: <N> passing
Ready to implement <feature-name>

Worktree Management

git worktree list          # List all
git worktree remove <path> # Remove after merge
git worktree prune         # Clean stale

Key Rules

• ALWAYS verify directory is gitignored for project-local
• MUST run baseline tests before reporting ready
• If tests fail → Report failures, ask whether to proceed
• ALWAYS auto-detect and run project setup

Common Mistakes

• ❌ Skip ignore verification → ✅ Always verify gitignored
• ❌ Skip baseline tests → ✅ Verify clean starting point
• ❌ Proceed with failing tests → ✅ Ask user first
• ❌ Leave stale worktrees → ✅ Remove after merge