Use when starting isolated feature work or before executing implementation plans. Manages full worktree lifecycle from creation through cleanup with safety checks and error recovery.
Use when starting isolated feature work or before executing implementation plans. Manages full worktree lifecycle from creation through cleanup with safety checks and error recovery.
Creating worktree without checking if branch already exists
Creating worktree without checking if directory path is available
Forgetting to add worktree directory to .gitignore
Manually deleting worktree with rm -rf (use git worktree remove)
Removing worktree with uncommitted changes without user confirmation
Using same branch in multiple worktrees simultaneously
Working in worktree after returning to main directory (stale CWD)
Not storing original CWD before entering worktree
Skipping dependency installation in new worktree
Not running baseline tests before starting work
6-Phase Lifecycle
Phase 1: Pre-flight Checks
Purpose: Verify all prerequisites before creating anything.
Required checks (all must pass):
# 1. Verify git repository
git rev-parse --git-dir &>/dev/null
if [ $? -ne 0 ]; then
ERROR: "Not a git repository"
RECOVERY: Abort with clear error message
fi# 2. Detect detached HEAD stateif ! git symbolic-ref HEAD &>/dev/null; then
WARNING: "Currently in detached HEAD state"
RECOVERY: Ask user if they want to create branch from current commit
fi# 3. Check if branch already in a worktreeif git worktree list | grep -q "$BRANCH"; then
ERROR: "Branch $BRANCH already checked out in a worktree"
RECOVERY: Ask user - reuse existing, rename branch, or cancel
fi# 4. Check if branch exists (but not in worktree)if git branch --list "$BRANCH" | grep -q .; then
WARNING: "Branch $BRANCH already exists"
RECOVERY: Ask user - use existing branch or create new with different name
fi# 5. Check if target path is available# IMPORTANT: Create directory first before checking (git check-ignore needs path to exist)mkdir -p "$WORKTREE_DIR"if [ -d "$WORKTREE_PATH" ]; then
ERROR: "Directory $WORKTREE_PATH already exists"
RECOVERY: Ask user - choose different path or remove existing
fi
Error Recovery Table:
Error
Detection
Recovery
Not a git repo
git rev-parse --git-dir fails
Abort with clear error
Detached HEAD
git symbolic-ref HEAD fails
Ask: create branch from commit?
Branch in worktree
git worktree list | grep $BRANCH succeeds
Ask: reuse, rename, or cancel
Branch exists
git branch --list $BRANCH returns result
Ask: use existing or rename
Path exists
Directory already present
Ask: choose different path or remove
Parent not writable
Cannot create parent directory
Abort with permission error
Phase 2: Directory Selection
Priority order (cascading, first match wins):
Check for existing .worktrees/ directory → use it (no prompt)
Check for existing worktrees/ directory → use it (no prompt)
Check CLAUDE.md for worktree preference → follow it (no prompt)
Ask user (only if no default found)
For orchestrator integration: Pass WORKTREE_DIR=".worktrees" to skip this phase entirely.
Example detection:
if [ -d ".worktrees" ]; then
WORKTREE_DIR=".worktrees"elif [ -d "worktrees" ]; then
WORKTREE_DIR="worktrees"elif grep -q "worktree.*directory" CLAUDE.md 2>/dev/null; then
WORKTREE_DIR=$(grep "worktree.*directory" CLAUDE.md | extract_path)
else# Ask user via AskUserQuestion# Options: .worktrees/, worktrees/, customfi
Error handling: If git worktree add fails, clean up any partial state and report the error to user.
Phase 4: Setup
Multi-stack detection:
# Detect all present stacks
STACKS=()
[ -f package.json ] && STACKS+=("nodejs")
[ -f Cargo.toml ] && STACKS+=("rust")
[ -f go.mod ] && STACKS+=("golang")
[ -f pyproject.toml ] || [ -f requirements.txt ] && STACKS+=("python")
[ -f Gemfile ] && STACKS+=("ruby")
# Run setup for each detected stackfor stack in"${STACKS[@]}"; doecho"Setting up $stack..."case"$stack"in
nodejs)
if [ -f bun.lockb ]; then
bun install
elif [ -f pnpm-lock.yaml ]; then
pnpm install
elif [ -f yarn.lock ]; then
yarn install
else
npm install
fi
;;
rust)
cargo build
;;
golang)
go mod download
;;
python)
if [ -f pyproject.toml ]; then
pip install -e .
else
pip install -r requirements.txt
fi
;;
ruby)
bundle install
;;
esacdone
Baseline test verification:
# Run tests and capture output (allow pre-existing failures)for stack in"${STACKS[@]}"; docase"$stack"in
nodejs)
if [ -f bun.lockb ]; then
bun test 2>&1 | tee test-output.log
else
npm test 2>&1 | tee test-output.log
fi
;;
rust)
cargo test 2>&1 | tee test-output.log
;;
golang)
go test ./... 2>&1 | tee test-output.log
;;
python)
pytest 2>&1 | tee test-output.log
;;
esac# Parse test results (do NOT block on pre-existing failures)
PASSING=$(grep -o '[0-9]* passing' test-output.log | cut -d' ' -f1)
FAILING=$(grep -o '[0-9]* failing' test-output.log | cut -d' ' -f1)
echo"Baseline tests: $PASSING passing, $FAILING failing"if [ "${FAILING:-0}" -gt 0 ]; thenecho"WARNING: Pre-existing test failures detected. Proceed with caution."fidone
SESSION_PATH: ${SESSION_PATH}
WORKTREE_PATH: ${WORKTREE_PATH}
BRANCH_NAME: ${BRANCH_NAME}
ORIGINAL_CWD: ${ORIGINAL_CWD}
IMPORTANT: You are working in an isolated worktree.
- cd to WORKTREE_PATH before writing any code
- Session artifacts stay in SESSION_PATH (main worktree)
- When complete, return control to orchestrator for cleanup
Phase 6: Cleanup
Trigger conditions:
Orchestrator completion phase
Explicit user request via /dev:worktree cleanup
Error recovery (abort implementation)
Steps (with safety checks):
# 1. Verify worktree metadata existsif [ ! -f "${SESSION_PATH}/worktree-metadata.json" ]; then
ERROR: "No worktree metadata found"
RECOVERY: Ask user for worktree path manually
fi# Read metadata
WORKTREE_PATH=$(jq -r .worktreePath "${SESSION_PATH}/worktree-metadata.json")
ORIGINAL_CWD=$(jq -r .originalCwd "${SESSION_PATH}/worktree-metadata.json")
BRANCH=$(jq -r .branchName "${SESSION_PATH}/worktree-metadata.json")
# 2. Return to original CWD if currently in worktree
CURRENT_CWD=$(pwd)
if [[ "$CURRENT_CWD" == *"$WORKTREE_PATH"* ]]; thencd"$ORIGINAL_CWD"fi# 3. Check for uncommitted changescd"$WORKTREE_PATH"if [ -n "$(git status --porcelain)" ]; then# Use AskUserQuestion to resolveecho"WARNING: Uncommitted changes detected in worktree"# Options: commit now, stash, discard, abort cleanup# DO NOT proceed until resolvedfi# 4. Return to original CWDcd"$ORIGINAL_CWD"# 5. Remove worktree (NEVER use rm -rf)
git worktree remove "$WORKTREE_PATH"# 6. Optionally delete branch (only if merged or user confirms)if git branch --merged | grep -q "$BRANCH"; then
git branch -d "$BRANCH"# Safe delete (only if merged)else# Ask user: keep branch or force delete?# git branch -D "$BRANCH" # Force delete (only with confirmation)fi# 7. Update metadata status
jq '.status = "removed" | .removedAt = "'$(date -u +%Y-%m-%dT%H:%M:%SZ)'"' \
"${SESSION_PATH}/worktree-metadata.json" > "${SESSION_PATH}/worktree-metadata.json.tmp"mv"${SESSION_PATH}/worktree-metadata.json.tmp""${SESSION_PATH}/worktree-metadata.json"# 8. Remove statusline worktree markerif [ -n "$SESSION_ID" ]; thenrm -f "$HOME/.claude/.statusline-worktree-${SESSION_ID}"fi
Error handling during cleanup:
Error
Detection
Recovery
Currently in worktree
CWD matches worktree path
Auto-return to original CWD
Uncommitted changes
git status --porcelain not empty
Ask user: commit/stash/discard
Worktree in use
git worktree remove fails
Ask: force removal with --force?
Branch not merged
git branch -d fails
Ask: keep branch or force delete?
Stale marker file
Marker exists but worktree removed
Auto-cleaned by statusline (marker ignored if worktree gone)
Error Recovery
Critical errors (abort workflow):
Not a git repository
Permission denied creating directory
Git worktree creation fails without clear reason
Recoverable errors (ask user):
Branch already exists → Use existing or rename
Path already exists → Choose different path or remove
Uncommitted changes during cleanup → Commit/stash/discard
Tests fail during baseline → Proceed or abort
Quick Reference Card
Before starting isolated work:
✅ Run Pre-flight Checks (Phase 1)
Git repo valid
Branch available
Path available
✅ Select or detect worktree directory (Phase 2)
✅ Create worktree + verify .gitignore (Phase 3)
✅ Install dependencies for all stacks (Phase 4)
✅ Run baseline tests (Phase 4)
✅ Store metadata and hand off to agent (Phase 5)
After completing work:
✅ Return to original CWD if in worktree
✅ Check for uncommitted changes → resolve
✅ Remove worktree with git worktree remove
✅ Optionally delete branch (only if merged or confirmed)
Remember: Always use git worktree remove, never rm -rf.
Orchestrator Integration
/dev:feature Integration
Phase 0 (after session init):
Add AskUserQuestion: "Create isolated worktree?"
If yes: Run Phases 1-5, pass WORKTREE_PATH to all agents
If no: Continue as normal
Phase 8 (completion):
If worktree created: Ask cleanup options (PR, merge, keep, discard)
Execute Phase 6 with chosen option
/dev:implement Integration
Phase 1 (lightweight version):
Add AskUserQuestion: "Use isolated worktree?"
If yes: Run Phases 1-5 with defaults (no directory selection)
Use .worktrees/ automatically, skip multi-stack detection
Phase 6 (finalization):
If worktree created: Ask "Merge and clean up?"
Execute Phase 6 with merge or keep option
Subagent Context Template
When delegating to agents in worktrees, always include:
SESSION_PATH: ${SESSION_PATH}
WORKTREE_PATH: ${WORKTREE_PATH}
BRANCH_NAME: ${BRANCH_NAME}
IMPORTANT: You are working in an isolated worktree.
- cd to WORKTREE_PATH before writing any code
- Read from ${SESSION_PATH} for architecture/requirements
- Write code to WORKTREE_PATH (current branch: ${BRANCH_NAME})
- Session artifacts stay in ${SESSION_PATH} (main worktree)
