| name | parallelization |
| description | Git worktree management, cascade method for multiple instances, and scaling guidelines. Use when planning parallel agent work, managing worktrees, or deciding when to scale instances. |
Parallelization
Scale Claude Code work across multiple agents, worktrees, and instances. Three strategies: worktree isolation, cascade method, instance scaling.
1. Git Worktree Strategy
Creating Worktrees
Each Designer agent in team workflow gets an isolated worktree:
BASE=$(git rev-parse --abbrev-ref HEAD)
git worktree add ../project-feature-a -b feature-a "$BASE"
Base Selection (default = current HEAD, not an assumed mainline)
Branch every worktree from the current active HEAD of the target repo — the branch the user is actually on — not from an arbitrary main/develop/master. The user is usually working on top of a feature branch with stacked, uncommitted-to-mainline work; branching from develop silently drops that work and produces conflicts or lost changes at merge time.
- Default:
git worktree add <path> -b <new> "$(git rev-parse --abbrev-ref HEAD)".
- Confirm before creating if the base is ambiguous (detached HEAD, the user mentioned a different base, or you are in a submodule): state the base you will use in one line and proceed only if it matches intent.
- Exception: the user explicitly names a different base — then use it.
- Submodules/monorepos: derive the base from each target repo's own current HEAD, independently. When the superproject is a thin shell (docs + submodule pointers) and the real code lives in
fe/be submodules, use submodule-worktree — worktree only the code submodules, keep the superproject as the single _docs/ anchor, defer pointer bumps.
Worktree Rules
| Rule | Why |
|---|
| Base from current HEAD (not arbitrary main/develop) | Includes the user's stacked in-progress work; arbitrary base = lost work / merge conflicts (see "Base Selection") |
| No file overlap between worktrees | Prevents merge conflicts |
| Merge sequentially after completion | Ordered conflict resolution |
| Clean up after merge | git worktree remove to prevent stale trees |
| Max 5 active worktrees | Beyond this, merge overhead exceeds parallelism gains |
_docs/ stays in the primary tree (never in a linked worktree's checkout) | Plans stay readable from main without cd-ing into a worktree; no per-worktree doc copies to diverge (see below) |
_docs/ lives in the primary working tree
_docs/ (plans, specs, handoffs) is a primary-worktree-only bucket — it MUST NOT live in a linked worktree's checkout. The problem this avoids: a plan written inside ../project-feature-a/_docs/… is invisible from the main repo until merged, so reading it means cd-ing into that worktree.
Resolve the primary tree's _docs/ from ANY worktree (cwd-independent — --git-common-dir always resolves to <main>/.git, so its parent is the main root):
MAIN=$(dirname "$(git rev-parse --path-format=absolute --git-common-dir)")
DOCS="$MAIN/_docs"
Rules:
- Read the plan/spec from
"$DOCS/…" by absolute path — never from your own worktree's _docs/. The orchestrator passes this absolute path into each worktree agent's briefing.
- Write doc content (impl notes, findings) directly to
"$DOCS/…" by absolute path, each worktree owning distinct doc files — the same no-file-overlap rule that governs code. A doc written this way lands in the main tree immediately: readable without cd, no merge round-trip.
index.md edits and status-moves (git mv between planning/processing/complete/…) stay orchestrator-serialized — index.md is the one shared mutable doc, so only the orchestrator touches it after worktrees finish. See docs-lifecycle → "Concurrency".
File Assignment Strategy
When splitting work across worktrees:
1. Identify file dependencies (imports, shared types)
2. Group tightly-coupled files into same worktree
3. Shared interfaces/types → define FIRST in main, then branch
4. Each worktree gets a complete, independent unit of work
Anti-pattern: Splitting a single component across worktrees. Keep related files together.
Worktree Merge Order
1. Core/shared types first (foundation)
2. Backend/API changes second (data layer)
3. Frontend/UI changes third (depends on API)
4. Tests last (depends on implementation)
2. Cascade Method
Overview
Run multiple Claude Code instances in parallel, each focused on a different task. Sweep through them sequentially to maintain oversight.
Setup
Instance 1 (leftmost) ── Main implementation
Instance 2 ── Code review / testing
Instance 3 ── Research / documentation
Instance 4 (rightmost) ── Independent feature / debugging
Cascade Rules
| Rule | Details |
|---|
| Max 3-4 concurrent | Beyond this, context-switching overhead dominates |
| No overlapping file edits | Each instance owns its files exclusively |
| Sweep left→right | Check oldest → newest, handle blocks |
| Fork for research | Questions about codebase → separate instance |
| Scope clearly | Each instance has ONE clear objective |
Task Distribution
Main instance: Code changes (owns the implementation)
Fork 1: Codebase questions / exploration
Fork 2: External API research / documentation
Fork 3: Test writing / verification (separate from implementation)
When Cascade Works
- Truly independent modules
- Code review alongside feature implementation
- E2E tests while implementing features
- Independent data/API integrations
When Cascade Fails
- Sequential work (Phase B depends on Phase A output)
- Tightly coupled modules (shared state)
- Single complex file requiring focused attention
3. Instance Scaling Guidelines
When to Scale Up
| Signal | Action |
|---|
| 2+ independent tasks in queue | Spawn parallel agents |
| Build/test takes >2 min | Background + continue other work |
| Research needed alongside implementation | Fork for research |
| Code review bottleneck | Dedicated review instance |
When NOT to Scale
| Signal | Why |
|---|
| Tasks share mutable state | Race conditions, conflicts |
| Sequential dependency chain | Can't parallelize |
| Complex debugging session | Needs focused context |
| Context window is critical | Don't fragment it |
Scaling Configurations
Minimal (1-2 agents):
Solo developer → 1 main + 1 background (tests/build)
Standard (3-4 agents):
Team workflow → Leader + 2-3 Designers in worktrees
Maximum (5+ agents):
Large feature → Leader + Architects + Designers + Testers
Only when tasks are truly independent with no shared files
4. Agent Parallelization in Team Workflow
Phase 1: Parallel Architecture
Team Leader spawns:
├── Architect FE ──→ Frontend plan ─┐
├── Architect BE ──→ Backend plan ─┤── Cross-review → Merged plan
└── Architect Infra ──→ (on-demand) ─┘
Phase 3: Parallel Implementation
Team Leader assigns files:
├── Designer A (worktree-a) ──→ Files: [auth.ts, auth.test.ts]
├── Designer B (worktree-b) ──→ Files: [api.ts, api.test.ts]
└── Designer C (worktree-c) ──→ Files: [ui.tsx, ui.test.tsx]
Phase 4: Parallel Verification
├── Tester A ──→ Unit tests for Designer A's work
├── Tester B ──→ Unit tests for Designer B's work
└── Tester C ──→ E2E tests for integrated flow
5. Background Process Management
Long-Running Tasks
Always use run_in_background: true for:
bun run build / bunx vitest rungit push / git pull- Database migrations
- Large file searches
Notification Pattern
1. Launch background task
2. Continue with other work (don't poll or sleep)
3. System notifies when task completes
4. Handle result when notified
Parallel Tool Calls
Independent tool calls in a single message execute simultaneously:
# These run in parallel (single message, multiple tool calls):
Agent({ prompt: "search auth patterns", model: "haiku" })
Agent({ prompt: "search API endpoints", model: "haiku" })
Agent({ prompt: "search test utilities", model: "haiku" })
Quick Reference
Worktrees: Max 5, no file overlap, merge sequentially, _docs/ in primary tree only
Cascade: 3-4 instances max, sweep left→right, clear scope each
Scale up: Independent tasks, background builds, research forks
Scale down: Shared state, sequential deps, focused debugging
Background: Builds, tests, pushes → run_in_background: true
Parallel calls: Independent tool calls in single message
