Orchestration
Coordinate multi-agent or multi-session coding work without duplicated effort, context loss, or unnecessary integration overhead. Stay harness-agnostic: use whatever task, teammate, subagent, or mailbox primitives are available, and keep git worktrees as an explicit isolation choice rather than the default.
When to Use
- Complex work that can split by domain, file area, or risk level
- Parallel review, research, testing, or documentation passes
- Background investigation while the lead preserves high-value context
- Risky changes where isolation may be worth the setup and merge cost
Core Rules
- Assign clear ownership: one agent/session owns each file or subsystem.
- Keep the lead session responsible for synthesis, review, and final decisions.
- Prefer one mutating worker in the shared cwd/current branch unless parallel edits are clearly independent.
- Use parallel workers freely for read-only research, review, logs, CI, or test investigation.
- Create a shared task list with dependencies and acceptance criteria.
- Require concise handoff notes: files touched, decisions made, validation run, blockers.
- If the harness supports read-only/mutating flags, mark file-editing workers as mutating.
Workspace Choice
Default to the current shared workspace for small, sequential, or tightly-coupled changes. It keeps local env, ignored files, ports, databases, and devcontainers intact.
Use isolated workspaces — git worktrees, cloned checkouts, containers, VMs, or cloud previews — only when the isolation benefit beats setup/runtime/integration cost.
Before choosing a worktree, answer:
- How are ignored files, dependencies,
.env, generated files, and package caches handled?
- Are ports, databases, queues, and local services isolated?
- Who integrates the branch/patch and resolves semantic conflicts?
- How is cleanup handled after review?
Decomposition Patterns
| Pattern |
Use when |
| Fan-out |
Same operation across independent areas |
| Pipeline |
Research → implement → test → docs |
| Reviewer/implementer |
One session changes, another critiques |
| Speculative branches |
Trying competing approaches safely |
| Background monitor |
Long-running CI, logs, or investigation |
References
- patterns.md - Orchestration patterns
- domains.md - Domain-specific decomposition
- task-management.md - Dependencies, task graphs, file partitioning
- worktree-commands.md - Git worktree command reference
- session-strategies.md - Multi-session patterns
- cleanup.md - Worktree removal and maintenance
1---2name: orchestration-23description: Coordinate parallel agent work. Use when decomposing complex tasks, running review/implementation in parallel, managing task lists, or choosing shared vs isolated workspaces.4---56# Orchestration78Coordinate multi-agent or multi-session coding work without duplicated effort, context loss, or unnecessary integration overhead. Stay harness-agnostic: use whatever task, teammate, subagent, or mailbox primitives are available, and keep git worktrees as an explicit isolation choice rather than the default.910## When to Use1112- Complex work that can split by domain, file area, or risk level13- Parallel review, research, testing, or documentation passes14- Background investigation while the lead preserves high-value context15- Risky changes where isolation may be worth the setup and merge cost1617## Core Rules1819- Assign clear ownership: one agent/session owns each file or subsystem.20- Keep the lead session responsible for synthesis, review, and final decisions.21- Prefer one mutating worker in the shared cwd/current branch unless parallel edits are clearly independent.22- Use parallel workers freely for read-only research, review, logs, CI, or test investigation.23- Create a shared task list with dependencies and acceptance criteria.24- Require concise handoff notes: files touched, decisions made, validation run, blockers.25- If the harness supports read-only/mutating flags, mark file-editing workers as mutating.2627## Workspace Choice2829Default to the current shared workspace for small, sequential, or tightly-coupled changes. It keeps local env, ignored files, ports, databases, and devcontainers intact.3031Use isolated workspaces — git worktrees, cloned checkouts, containers, VMs, or cloud previews — only when the isolation benefit beats setup/runtime/integration cost.3233Before choosing a worktree, answer:3435- How are ignored files, dependencies, `.env`, generated files, and package caches handled?36- Are ports, databases, queues, and local services isolated?37- Who integrates the branch/patch and resolves semantic conflicts?38- How is cleanup handled after review?3940## Decomposition Patterns4142| Pattern | Use when |43| -------------------- | --------------------------------------- |44| Fan-out | Same operation across independent areas |45| Pipeline | Research → implement → test → docs |46| Reviewer/implementer | One session changes, another critiques |47| Speculative branches | Trying competing approaches safely |48| Background monitor | Long-running CI, logs, or investigation |4950## References5152- [patterns.md](references/patterns.md) - Orchestration patterns53- [domains.md](references/domains.md) - Domain-specific decomposition54- [task-management.md](references/task-management.md) - Dependencies, task graphs, file partitioning55- [worktree-commands.md](references/worktree-commands.md) - Git worktree command reference56- [session-strategies.md](references/session-strategies.md) - Multi-session patterns57- [cleanup.md](references/cleanup.md) - Worktree removal and maintenance
spences10