joshsymonds/using-worktrees

Using Git Worktrees

Overview

Git worktrees create isolated workspaces sharing the same repository. No switching branches, no stashing, no conflicts with in-progress work.

Core principle: Discover location → verify safety → create → setup environment → verify baseline → report.

Iron Law: NO skipping baseline verification. Tests must pass in the new worktree BEFORE reporting ready. No exceptions.

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

Rigidity Level

LOW FREEDOM - Follow the 8-step process exactly. No skipping steps. STOP points halt execution until resolved.

Quick Reference

| Step | Action | STOP If | |------|--------|---------| | 1 | Check existing directories | - | | 2 | Check CLAUDE.md preference | - | | 3 | Ask user for preference | No answer received | | 4 | Verify directory is gitignored | Cannot add to .gitignore | | 5 | Create worktree | Git command fails | | 6 | Run environment setup | Setup fails | | 7 | Verify clean baseline | Tests fail AND user says investigate | | 8 | Report ready | - |

Directory priority: Existing dir > CLAUDE.md preference > Ask user

When to Use

• Starting feature work that needs isolation from main workspace
• Before executing implementation plans
• Working on multiple features simultaneously
• Experimenting without affecting main workspace

Don't use for: quick fixes, single-file changes, when user explicitly wants current directory

The Process

Step 1: Check Existing Directories

ls -d .worktrees 2>/dev/null     # Check first (preferred, hidden)
ls -d worktrees 2>/dev/null      # Check second (alternative)

• .worktrees/ exists → Use it, skip to Step 4
• worktrees/ exists (no .worktrees) → Use it, skip to Step 4
• Both exist → Use .worktrees/, skip to Step 4
• Neither exists → Step 2

---

Step 2: Check CLAUDE.md Preference

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

• Specifies location → Use it, go to Step 4
• No preference or no CLAUDE.md → Step 3

---

Step 3: Ask User for Preference

REQUIRED: Use AskUserQuestion tool.

AskUserQuestion
  questions:
    - question: "No worktree directory found. Where should I create worktrees?"
      header: "Location"
      options:
        - label: ".worktrees/ (Recommended)"
          description: "Project-local, hidden directory"
        - label: "worktrees/"
          description: "Project-local, visible directory"
        - label: "~/.worktrees/<project>/"
          description: "Global location outside project"
      multiSelect: false

STOP: Wait for user response before proceeding.

---

Step 4: Verify Directory is Gitignored

Project-local directories only (.worktrees or worktrees). Skip for global (~/.worktrees/).

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

• Exit 0 (ignored) → Step 5
• Exit 1 (not ignored) → Fix immediately:

echo ".worktrees/" >> .gitignore
git add .gitignore && git commit -m "chore: add worktree directory to gitignore"

STOP if commit fails. Do not create worktree with unignored directory.

---

Step 5: Create Worktree

Determine branch name from user request (e.g., "auth feature" → feature/auth).

# Set path based on location choice
path=".worktrees/$BRANCH_NAME"           # project-local
path="$HOME/.worktrees/$project/$BRANCH_NAME"  # global

git worktree add "$path" -b "$BRANCH_NAME"

STOP if git command fails. Report error and ask user.

Verify:

cd "$path" && git status  # Clean working tree on new branch

---

Step 6: Run Environment Setup

Detect project type and run FIRST match:

| Priority | Detection | Setup Command | |----------|-----------|---------------| | 1 | devenv.nix or .envrc | See devenv workflow below | | 2 | package.json | npm install / yarn install / pnpm install (match lockfile) | | 3 | Cargo.toml | cargo build | | 4 | pyproject.toml with tool.poetry | poetry install | | 5 | requirements.txt | pip install -r requirements.txt | | 6 | go.mod | go mod download | | None | No match | Report "No recognized project type. Skipping setup." |

Devenv Database Handling

If devenv detected, check for database usage:

grep -l "DATABASE_URL\|postgres\|mysql" devenv.nix .envrc 2>/dev/null

If database found, REQUIRED: Ask about strategy:

AskUserQuestion
  questions:
    - question: "This project uses devenv with a database. How should the worktree handle it?"
      header: "Database"
      options:
        - label: "Share database (Recommended)"
          description: "Use same $DATABASE_URL as main. Faster setup, shared data."
        - label: "Isolated database"
          description: "Create new database. Clean slate, but requires migration."
      multiSelect: false

STOP: Wait for response.

• Shared: direnv allow 2>/dev/null || devenv shell
• Isolated: Create database, write .env.local, allow direnv, run migrations

---

Step 7: Verify Clean Baseline

REQUIRED: Run tests to establish baseline.

| Project Type | Test Command | |--------------|--------------| | Node.js | npm test | | Rust | cargo test | | Python | pytest | | Go | go test ./... | | Devenv | Check Makefile for test target |

• All pass → Step 8
• Tests fail → Present options to user:

Tests failing (N failures) in fresh worktree.
[Show first 3-5 failures]

These failures exist in the base branch. Options:
1. Proceed anyway (failures are known/expected)
2. Investigate before proceeding
3. Cancel worktree creation

• Investigate → STOP until resolved
• Cancel → git worktree remove "$path", STOP
• Proceed → Continue to Step 8, noting known failures

---

Step 8: Report and Chain Forward

Worktree ready at <full-absolute-path>
Branch: <branch-name>
Tests: <N> passing, <M> failures (if any)
Environment: <devenv/npm/cargo/pip/go/none>

Always use full absolute path. User needs it for navigation.

Then chain to the next skill automatically. If tasks exist (invoked from a brainstorming handoff), invoke executing-plans directly:

Skill skill="gambit:executing-plans"

If no tasks exist yet (invoked standalone), ask the user:

AskUserQuestion
  questions:
    - question: "Worktree ready. What's next?"
      header: "Next step"
      options:
        - label: "Plan the work"
          description: "Design and create tasks with gambit:brainstorming"
        - label: "Start executing"
          description: "Execute existing tasks with gambit:executing-plans"
      multiSelect: false

Then invoke the chosen skill directly using the Skill tool.

---

Critical Rules

Rules That Have No Exceptions

1. Never create project-local worktree without verifying gitignore → Risk of committing worktree contents
2. Never skip baseline test verification → Can't distinguish new bugs from inherited ones
3. Never proceed with failing tests without explicit permission → User must acknowledge known failures
4. Never assume directory location → Follow priority: existing > CLAUDE.md > ask
5. Always ask about database strategy for devenv projects → Database isolation is a critical choice
6. Always report full absolute path → User needs exact location for navigation

Common Excuses

All mean: STOP. Follow the process.

| Excuse | Reality | |--------|---------| | "Directory is probably ignored" | RUN git check-ignore to verify | | "Tests probably pass" | RUN tests to verify | | "Same as last time, don't need to ask" | ASK — user preferences can change | | "Small feature, don't need isolation" | User requested worktree — create it | | "Can fix gitignore later" | FIX NOW — prevents accidents |

---

Verification Checklist

Before reporting ready:

• [ ] Checked existing directories (.worktrees, worktrees)
• [ ] Checked CLAUDE.md for preference
• [ ] Asked user if no existing preference (using AskUserQuestion)
• [ ] Verified directory is gitignored (project-local only)
• [ ] Created worktree with branch
• [ ] Detected environment type and ran setup
• [ ] Asked about database strategy (devenv with database only)
• [ ] Ran tests to verify baseline
• [ ] Got permission if tests failed
• [ ] Reported full absolute path, branch, test status, environment

---

Examples

See REFERENCE.md for detailed good/bad examples including:

• Complete workflow with devenv database handling
• Skipping gitignore verification (and consequences)
• Proceeding with failing tests silently (and consequences)

---

Integration

Called by:

• gambit:brainstorming (optional, user chooses at handoff)
• User via /gambit:using-worktrees

Calls:

• gambit:executing-plans (invoked directly after worktree setup, if tasks exist)
• gambit:brainstorming (if invoked standalone with no tasks)

Pairs with:

• gambit:finishing-branch — handles worktree cleanup after work complete

Workflow:

gambit:brainstorming → gambit:using-worktrees → gambit:executing-plans
                                                          ↓
                                                 gambit:review
                                                          ↓
                                                 gambit:finishing-branch