Parallel Development¶
Beyond Background Tasks¶
Lift 1 introduced parallel execution: background tasks and sub-agents let you run multiple workstreams simultaneously. The constraint was context — each conversation has its own context window, so you needed context engineering to keep each workstream focused.
But background execution has a limitation: all the work happens in the same working directory. When Agent A modifies the analysis engine while Agent B rewrites the alert generator, and both touch shared utility files, you get conflicts. The agents step on each other.
Worktrees solve this by giving each workstream its own copy of the codebase.
What a Worktree Is¶
A git worktree creates a second (or third, or fourth) working directory linked to the same repository. Each worktree has its own branch, its own files on disk, and its own state — but they share the same git history. Changes made in one worktree don't affect another until you explicitly merge.
For parallel AI development, this means: each agent gets its own isolated environment. Agent A rewrites the escalation logic on branch fix-escalation. Agent B adds the Skyline zone on branch add-skyline. Agent C improves alert templates on branch better-alerts. All three work simultaneously, and none can break each other's work.
Claude Code has built-in worktree support. Launch with claude --worktree fix-escalation to create an isolated worktree with its own branch. Each worktree session gets its own conversation and context. When you're done, Claude prompts you to keep or remove the worktree.
Create worktrees manually with git worktree add ../fix-escalation -b fix-escalation, then run a separate Codex instance in that directory.
Create worktrees manually with git worktree add, then launch a separate pi instance in each worktree directory.
Your Role Shifts¶
With worktrees, the division of labor changes. You're no longer the person doing the work — you're the person defining what work gets done and how it's structured.
| Before Worktrees | With Worktrees |
|---|---|
| You work on one task at a time | Multiple agents work on different tasks simultaneously |
| You write the code (or closely supervise it) | You write the specs and acceptance criteria |
| You context-switch between tasks | You design the task boundaries so work is independent |
| You review by reading code | You review by checking eval results and running tests |
The critical design decision is task independence. Before launching parallel worktrees, you need to answer: can these workstreams complete without stepping on each other? The delegation-ready test from Lift 1 applies here — if a task can be built and tested independently, it's safe to parallelize.
For your project, natural worktree boundaries might be:
| Worktree | What It Does | Independent? |
|---|---|---|
fix-escalation |
Fix the multi-problem escalation logic | Yes — touches analysis engine only |
add-skyline |
Add Skyline zone support | Yes — new zone, new golden dataset, new pipeline |
better-alerts |
Improve alert message templates | Yes — touches alert generator only |
dashboard-perf |
Optimize dashboard rendering | Mostly — shares UI components but different concerns |
The ones that share files need sequencing or careful merge planning. The ones that are fully independent can run in true parallel.
The Merge Point¶
Parallel workstreams eventually converge. Each worktree branch needs to be merged back into the main branch. This is where your quality infrastructure from Lift 2 pays off:
- Each branch runs evals independently. Before merging, the worktree's branch must pass all golden dataset scenarios. A fix to the escalation logic that breaks Salt Lake's rating doesn't get merged.
- Integration testing happens at merge. After merging two branches, you run the full eval suite again. If the combination introduces a failure that neither branch caused individually, you catch it here.
- The golden dataset is the arbiter. Merge conflicts in analysis logic aren't resolved by reading code — they're resolved by running evals. The version that passes the golden dataset wins.
Team Discussion: Dividing Your System¶
Format: Team Discussion Time: ~2 minutes
Look at the system you're building: data ingestion (UAC, NWS, SNOTEL), analysis engine, alert generator, dashboard. Think about the eval failures you might encounter and the features still to build.
Discuss: How would you divide the work across worktrees? Which tasks are truly independent? Which ones share enough code that they need sequencing? If you had three worktrees running simultaneously, what's your merge strategy — merge one at a time with evals between each, or merge all at once?
Key Insight¶
Worktrees transform parallel execution from "running tasks in the background" to "running independent workstreams in isolated environments." Your role shifts from implementer to architect — you define the task boundaries, write the specs, and design the merge strategy. The worktrees handle isolation. The evals handle verification at merge. The quality of your decomposition determines whether parallel development accelerates you or creates merge chaos.