Git Worktrees Skill | Agent Skills

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:

Existing .worktrees/ directory at project root → use it
Existing worktrees/ directory at project root → use it
CLAUDE.md preference — check for stated worktree location preference
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): | Indicator File | Command | |---------------|---------| | pnpm-lock.yaml | pnpm install | | package-lock.json | npm ci | | yarn.lock | yarn install | | pyproject.toml | uv sync | | requirements.txt | pip install -r requirements.txt |

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

| Item | Detail | |------|--------| | Worktree location | .worktrees/<feature-name>/ | | .gitignore entry | .worktrees/ | | Monorepo deps | pnpm install (root) | | Backend Python deps | cd apps/backend && uv sync | | Test baseline | pnpm turbo run test | | Docker services | Start separately: pnpm run docker:up (shared, not per-worktree) |

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

Agent Skills: Git Worktrees

Install this agent skill to your local

Skill Files