Git Worktrees

Git Worktrees

Adapted from obra/superpowers — MIT. Provides a formal worktree workflow that extends the existing /minion isolation model.

Purpose

Isolate feature development from main using git worktree. Each feature gets its own working directory with clean dependencies and a verified test baseline — preventing feature branches from corrupting each other.

When to Use

• Starting any non-trivial feature (especially multi-session work)
• Parallel feature development (2+ features in flight simultaneously)
• Risky refactors that may break other work in progress
• When the /minion command is used with the --isolate flag
• Any time you need a clean environment to verify tests pass

Don't use when:

• Hotfix on main (patch directly)
• Single-file trivial change
• Throwaway prototype / spike

Worktree Setup Workflow

Step 1: Determine Worktree Directory

Check in this priority order:

1. Existing .worktrees/ directory at project root → use it
2. Existing worktrees/ directory at project root → use it
3. CLAUDE.md preference — check for stated worktree location preference
4. Default: Create .worktrees/ at project root, add to .gitignore

# Check what exists
ls -la | grep worktrees
grep -i "worktree" CLAUDE.md

Step 2: Safety — Verify .gitignore

MANDATORY before creating any worktree in a project-local directory.

Project-local worktrees MUST be in .gitignore to prevent accidentally committing worktree contents.

# Check if .worktrees/ is already ignored
grep -e "\.worktrees" -e "worktrees/" .gitignore

# If not present, add it
echo ".worktrees/" >> .gitignore
git add .gitignore
git commit -m "chore: add .worktrees/ to .gitignore"

Step 3: Create the Worktree

# Create worktree on a new branch
git worktree add .worktrees/<feature-name> -b feature/<feature-name>

# Example
git worktree add .worktrees/auth-refresh -b feature/auth-refresh

# Verify
git worktree list

Step 4: Auto-Detect and Install Dependencies

Navigate to the new worktree and install based on detected project type:

cd .worktrees/<feature-name>

# NodeJS-Starter-V1 is a monorepo — always:
pnpm install

# Backend Python dependencies
cd apps/backend && uv sync && cd ../..

Detection logic (in order):

Step 5: Baseline Test Verification

MANDATORY. Never skip. Run baseline tests before writing any feature code.

# Full test suite — must be green before starting feature work
pnpm turbo run test

# If baseline is red, STOP. Fix the baseline before starting feature work.
# Do not begin feature development on a broken test suite.

Report the baseline result:

• ✅ Baseline green: N tests passing → proceed to feature development
• ❌ Baseline red: Stop. Fix failing tests on main before creating worktree.

Step 6: Report and Begin Work

Worktree created: .worktrees/<feature-name>
Branch: feature/<feature-name>
Dependencies: installed (pnpm + uv sync)
Baseline: ✅ N tests passing

Ready to begin: <feature-name>

Working in the Worktree

# Navigate to worktree
cd .worktrees/<feature-name>

# All standard commands work as expected
pnpm dev
pnpm test --filter=web
cd apps/backend && uv run pytest -v
pnpm turbo run type-check

The worktree is a full git checkout — commit, branch, push as normal.

Cleanup

After Merging / PR Approved

# Return to root
cd "D:\Node JS Starter V1"

# Remove the worktree
git worktree remove .worktrees/<feature-name>

# Delete the branch (if merged)
git branch -d feature/<feature-name>

# Verify
git worktree list

Stale Worktrees

# List all worktrees with status
git worktree list

# Prune worktrees whose branches no longer exist
git worktree prune

# Force remove a locked/stale worktree
git worktree remove --force .worktrees/<stale-name>

NodeJS-Starter-V1 Specifics

Note on Docker: PostgreSQL and Redis run as shared Docker services. They are not per-worktree — all worktrees share the same database instance. Use separate databases or reset between tests if isolation is critical.

Integration with /minion

The /minion command uses --isolate to request worktree isolation. This skill provides the formal protocol that backs that flag:

# /minion with isolation
/minion --isolate "implement auth refresh token rotation"
# → creates .worktrees/auth-refresh-token-rotation/
# → installs deps, runs baseline
# → executes blueprint in isolation
# → creates PR when done
# → removes worktree after PR created

Safety Checklist

Before creating a worktree:

• .worktrees/ is in .gitignore
• Base branch (main) is clean: git status
• All current changes committed or stashed

After creating a worktree:

• Dependencies installed: pnpm install && cd apps/backend && uv sync
• Baseline tests passing: pnpm turbo run test
• Worktree listed correctly: git worktree list

Before removing a worktree:

• All work committed and pushed
• PR created (if applicable)
• Branch merged or intentionally preserved