/worktree - Git Worktree Isolation

Create isolated workspaces for parallel development. Each task gets its own directory - no branch switching, no stashing, no conflicts.

Target: $ARGUMENTS

When to Use

Working on multiple features simultaneously
Risky refactoring that might break things
Long-running tasks that shouldn't block other work
Testing a fix while keeping current work intact
Running parallel agents on different tasks
NOT for: simple single-file changes (just use a branch)

Workflow

Step 1: Directory Selection

Choose where to create worktrees:

Priority order:
1. Existing worktrees directory (if configured)
2. .claude/worktrees/ (default for Specialist Agent)
3. ../project-worktrees/ (sibling directory)
4. Ask user

Step 2: Create Worktree

# Create new branch and worktree
git worktree add .claude/worktrees/$ARGUMENTS -b worktree/$ARGUMENTS

# Verify creation
git worktree list

Step 3: Setup Workspace

# Enter worktree
cd .claude/worktrees/$ARGUMENTS

# Install dependencies (auto-detect)
if [ -f "package-lock.json" ]; then npm ci
elif [ -f "yarn.lock" ]; then yarn install --frozen-lockfile
elif [ -f "pnpm-lock.yaml" ]; then pnpm install --frozen-lockfile
elif [ -f "bun.lockb" ]; then bun install
fi

# Verify clean baseline
git status

Step 4: Work in Isolation

The worktree is a full copy of the repo.
- Changes here do NOT affect the main worktree
- You can run tests, builds, anything
- Commits go to the worktree/$ARGUMENTS branch

Step 5: Merge or Discard

When done:

# Option 1: Merge back
cd /path/to/main/repo
git merge worktree/$ARGUMENTS

# Option 2: Create PR from worktree branch
gh pr create --base main --head worktree/$ARGUMENTS

# Option 3: Discard
git worktree remove .claude/worktrees/$ARGUMENTS
git branch -D worktree/$ARGUMENTS

Worktree Management

List Active Worktrees

git worktree list

Remove a Worktree

git worktree remove .claude/worktrees/$NAME
git branch -D worktree/$NAME

Clean All Worktrees

git worktree prune

Integration with @orchestrator

When @orchestrator dispatches parallel agents:

@orchestrator
├── Worktree: feature-a → @builder (component)
├── Worktree: feature-b → @builder (service)
└── Worktree: feature-c → @tester (tests)

Each agent works in its own worktree.
No file conflicts possible.
Merge when all complete.

Verification Protocol

Before claiming worktree is ready:

git worktree list shows the new worktree
Working directory is clean (git status shows no untracked files from setup)
Dependencies are installed (if applicable)
Tests pass in the worktree (baseline)

Anti-Rationalization

Excuse	Reality
"Just stash and switch branches"	Stashing loses context and is error-prone. Worktrees keep everything intact.
"I'll remember what I was working on"	You won't. Worktrees preserve state explicitly.
"Too much disk space"	Worktrees share .git objects. Overhead is minimal.
"Merging will be hard"	Merging is the same as any branch. Worktrees don't add merge complexity.
"I'll just do tasks sequentially"	Sequential is slower. Parallel worktrees = parallel development.

Rules

Always name worktrees descriptively - worktree/auth-refactor not worktree/temp
Install dependencies after creation - Auto-detect package manager
Verify baseline before working - Tests must pass in fresh worktree
Clean up when done - Remove worktrees and branches after merge
Never work in .git/ - Worktrees are directories, not git internals
Gitignore the worktrees directory - Add .claude/worktrees/ to .gitignore

Output

──── /worktree ────
Action: [create | list | remove | merge]
Name: $ARGUMENTS
Path: .claude/worktrees/$ARGUMENTS
Branch: worktree/$ARGUMENTS

Status: Ready
Dependencies: Installed
Baseline tests: Passing

Active worktrees:
  1. /main/repo (main branch)
  2. .claude/worktrees/$ARGUMENTS (worktree/$ARGUMENTS)

worktree