Worktree Isolation

Git worktrees give each agent its own complete copy of the codebase. This enables true parallel development — multiple agents can modify the same files without conflicts.

How Worktrees Work

A Git worktree is a linked copy of your repository at a different path, sharing the same .git directory. Each worktree can be on a different branch, enabling isolated development.

When an AI coding agent creates a worktree-isolated sub-agent:

1. A new worktree is created with a fresh branch
2. The agent runs in the worktree directory
3. Changes are committed to the worktree’s branch
4. If no changes were made, the worktree is auto-cleaned
5. If changes exist, the worktree path and branch are returned

Setting Up Worktree Agents

In Agent Definitions

Store in your agent’s agents/ folder (see Tool Configuration Reference for exact paths):

agents/feature-builder.md

---
name: feature-builder
description: Implements features in an isolated worktree
tools: Read, Write, Edit, Bash, Grep, Glob
isolation: worktree
---

Implement the specified feature following TDD.
Commit all changes with descriptive messages.

Ad-Hoc Worktree Usage

Use an agent with worktree isolation to implement
the user profile API endpoints from .sdlc/plans/user-profiles.md.

Parallel Worktree Patterns

Independent Feature Development

When features don’t overlap:

Main Branch
├── Worktree A: Implement user profiles API
├── Worktree B: Implement notification system
└── Worktree C: Implement analytics dashboard
    └── All merge independently to main

Competitive Implementation

Have multiple agents implement the same feature differently, then choose the best:

Main Branch
├── Worktree A: Implement rate limiter (sliding window)
├── Worktree B: Implement rate limiter (token bucket)
└── Review both → pick the winner → merge

Batch Migration

Use batch commands (where supported by your agent tool) to process files in parallel worktrees:

Migrate all React class components in src/components/
to functional components with hooks. Process each file
in parallel worktrees.

Best Practices

Practice	Details
Limit active worktrees	3-4 max — more causes management overhead
Add to .gitignore	Add agent worktree directories to prevent showing as untracked
Define interfaces first	Agree on contracts before parallel implementation
Test in isolation	Each worktree should pass tests independently
Merge incrementally	Don’t let branches diverge too far

Caution

Worktrees share the same .git directory. Operations like git stash or git bisect can affect other worktrees. Stick to branch-isolated operations within worktrees.

Conflict Resolution

When worktrees modify overlapping code:

1. Merge the first branch to main
2. Rebase the second branch onto updated main
3. Resolve conflicts (agent can help)
4. Repeat for additional branches

For truly parallel work on the same files, consider whether the task can be decomposed differently to avoid overlap.

When NOT to Use Worktrees

• Sequential tasks — where each step depends on the previous
• Tightly coupled changes — where files in one worktree depend on changes in another
• Simple tasks — overhead isn’t worth it for small changes
• Research/exploration — use regular sub-agents instead (no code changes needed)