Git Worktrees

Worktrees give each parallel task its own filesystem while sharing one repository. Every worktree has a branch; every parallel agent gets its own worktree.

Steps

Pre-flight (mandatory before any worktree creation):

1. Run these two commands and compare output:

   git rev-parse --git-dir
   git rev-parse --git-common-dir

   If the outputs differ, you are inside a worktree. Stop immediately and warn: "You are already inside a worktree. Switch to the main checkout first." Do not proceed.
2. Run:

   git check-ignore -q .worktrees

   If exit code is non-zero, add .worktrees/ to .gitignore before proceeding.

Both checks are mandatory. Never skip them — nested worktrees corrupt repository state.

1. Create the worktree — Run:

   git worktree add .worktrees/<name> -b <branch-name>

   Convention: name the directory after the task, prefix the branch by type:

   git worktree add .worktrees/fix-auth-bug -b fix/auth-bug
   git worktree add .worktrees/redesign-nav -b feature/redesign-nav

   If the branch already exists:

   git worktree add .worktrees/<name> <existing-branch>

2. Work in the worktree — cd .worktrees/<name> and operate normally. Run the project's tests after entering to confirm a clean baseline.
3. List active worktrees — After creating worktrees, always run:

   git worktree list

   This confirms the worktrees are set up correctly and shows the full set of active workspaces.
4. Merge results — When work is complete:
   • Push the branch and create a PR, or
   • From the main checkout: git merge <branch-name>
5. Remove the worktree — After merging, always run both commands:

   git worktree remove .worktrees/<name>
   git branch -d <branch-name>

   Both are required — worktree remove detaches the directory, branch -d deletes the branch. If the directory was deleted manually, run git worktree prune instead.

Parallel Execution Pattern

For batch operations across multiple tasks, see parallel-execution.md.

Conventions

• Store worktrees in .worktrees/ at the project root
• Name directories after the task (not the branch)
• Branch naming: use a type prefix matching your project's convention (e.g., feature/, fix/, release/, experiment/)
• Add .worktrees/ to .gitignore (one-time setup)
• Remove worktrees after merging — they are temporary

Gotchas

• Same branch twice — Git refuses to check out a branch in two worktrees simultaneously. Use a different branch name or detach HEAD.
• Shared refs — All worktrees share .git/refs. A tag or remote update in one is visible in all.
• Shared stash — git stash is global. Name stashes: git stash push -m "worktree: description"
• Hooks — Git hooks are shared (.git/hooks). A pre-commit hook runs in whichever worktree triggers it.
• IDE state — Open each worktree as a separate project window to avoid conflicts.
• Skipping pre-flight — Agents consistently skip pre-flight checks when eager to create worktrees. The guards exist because nested worktrees corrupt state and unignored .worktrees/ pollutes git status.

Boundaries

• DOES create, list, and remove worktrees
• DOES establish branch naming conventions for worktrees
• DOES demonstrate parallel execution patterns
• Does NOT manage PRs or merges (use create-pr skill)
• Does NOT handle CI/CD or deployment
• Does NOT replace branch workflow — extends it with parallelism