Git Worktree Management

Iron Law

NEVER MODIFY FILES IN A WORKTREE YOU DID NOT CREATE

Operations

1. Create

git worktree add <path> -b <branch-name>

• Always use a descriptive branch name matching the worktree purpose
• Place worktrees in a consistent location (e.g.,

  /tmp/<repo>-worktrees/<name>

  )
• Verify the worktree was created successfully before proceeding
• Initialize any required workspace files (progress.txt, CLAUDE.md, prd.json)

2. List

git worktree list

• Check for stale or orphaned worktrees
• Verify each worktree points to a valid path
• Note which branches are checked out where

3. Switch

• Always verify your current working directory before making changes
• Use absolute paths to avoid confusion
• Check

  git status

  in the target worktree before starting work
• Never assume you are in the correct worktree — verify with

  pwd

  and

  git branch

4. Sync

# From within the worktree:
git fetch origin
git rebase origin/main  # or merge, depending on strategy

• Resolve conflicts in the worktree where they occur
• Do not sync during active implementation — finish the current story first
• After syncing, re-run quality checks to catch integration issues

5. Cleanup

git worktree remove <path>
git worktree prune

• Verify all changes are committed and pushed before removing
• Never force-remove a worktree with uncommitted changes
• Prune stale references after removal
• Delete the associated branch only after confirming the merge

Red Flags — If You Catch Yourself Thinking:

Rules

• Always verify your working directory before making any changes
• Never force-remove a worktree without checking for uncommitted changes
• Prune stale worktree references after every removal
• Use absolute paths for all worktree operations
• One branch per worktree — never checkout a branch that is active in another worktree