This document describes the workflow for an orchestrator agent to break down a large task into sub-tasks, delegate to worker agents, and coordinate the work to completion.
┌─────────────────────────────────────────────────────────────────┐
│ Orchestrator Agent │
│ │
│ 1. Create umbrella issue │
│ 2. Analyze task & plan breakdown │
│ 3. Create sub-issues │
│ 4. Create umbrella branch │
│ 5. Spawn worker agents (parallel where possible) │
│ 6. Monitor progress, merge PRs │
│ 7. Open final PR to main │
└─────────────────────────────────────────────────────────────────┘
│ ▲
│ spawn │ report back
▼ │
┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
│ Worker Agent │ │ Worker Agent │ │ Worker Agent │
│ │ │ │ │ │
│ - Create branch│ │ - Create branch│ │ - Create branch│
│ - Implement │ │ - Implement │ │ - Implement │
│ - Open PR │ │ - Open PR │ │ - Open PR │
│ - Report back │ │ - Report back │ │ - Report back │
└─────────────────┘ └─────────────────┘ └─────────────────┘
Create a GitHub issue that describes the overall feature/change. This becomes the tracking point for all sub-work.
The umbrella issue should include:
- High-level description of the change
- Goals and non-goals
- Link to design docs if applicable
- Section for tracking sub-issues (updated as they're created)
Before creating sub-issues, analyze the work to determine:
- File scope: Which files/modules will be modified?
- Dependencies: Which changes depend on others?
- Parallelization: Which changes can happen simultaneously without merge conflicts?
Key principle: Minimize file overlap between parallel tasks to avoid complex merges.
Create individual issues for each sub-task. Each sub-issue should include:
- Clear description of the specific work
- Relevant file paths
- Dependencies on other sub-issues (if any)
- Reference to umbrella issue ("Part of #X")
Create all sub-issues upfront before spawning any agents. This provides visibility into the full plan.
Add a tracking table to the umbrella issue:
## Sub-Issues
| Issue | Title | Status | Blocked By |
|-------|-------|--------|------------|
| #101 | Backend API changes | Open | - |
| #102 | Database schema | Open | - |
| #103 | Frontend components | Open | #101 |
| #104 | Integration tests | Open | #101, #102 |git checkout -b issue/<umbrella-id>
git push -u origin issue/<umbrella-id>This branch is the merge target for all sub-task PRs.
Before spawning agents, display the dependency structure:
Dependency Tree:
#100 (Umbrella: Feature X)
├── #101 (Backend API) ─────────────┐
│ ├── #103 (Frontend)
├── #102 (Database schema) ────────┤
│ └── #104 (Integration tests)
Parallel Tracks:
- #101 and #102 → can run in parallel (no file overlap)
- #103 and #104 → can run in parallel after dependencies merge
Execution Order:
#101 ──┬──► #103
│
#102 ──┴──► #104
Spawn agents for tasks that are ready (no unmet dependencies).
When spawning a worker agent, provide:
- Issue ID: The sub-issue number
- Target branch: The umbrella branch (e.g.,
issue/100) - Implementation summary: Clear description of what to implement
Instructions for worker agents:
- Create branch
issue/<sub-issue-id>from target branch - Implement the assigned task
- Open PR targeting the umbrella branch (not
main) - Report back when complete
Maintain a status display as work progresses:
Issues Status:
| Issue | Title | Status | Agent Session | PR |
|---|---|---|---|---|
| #100 | Feature X (umbrella) | Open | - | - |
| #101 | Backend API | In Progress | abc123... |
- |
| #102 | Database schema | In Progress | def456... |
- |
| #103 | Frontend components | Blocked by #101 | - | - |
| #104 | Integration tests | Blocked by #101, #102 | - | - |
Agents Spawned:
| Agent Session | Issue | Task |
|---|---|---|
abc123-... |
#101 | Backend API changes |
def456-... |
#102 | Database schema |
Branch Structure:
issue/100– Umbrella branch (merge target)issue/101– Created by worker, targetsissue/100issue/102– Created by worker, targetsissue/100
When a worker agent reports back:
- Verify the PR - Check that it targets the umbrella branch and has passed code review
- Merge the PR into the umbrella branch
- Update tracking - Mark issue as complete
- Check unblocked tasks - Spawn agents for newly unblocked work
Note: Worker agents are responsible for requesting and addressing code review with a separate review agent. The orchestrator does not perform code review.
If a PR has merge conflicts (due to previously merged work):
- Ask the worker agent to rebase their branch on the updated umbrella branch
- Wait for agent to force-push the rebased branch
- Retry the merge
Repeat the spawn → wait → merge cycle until all sub-issues are complete.
Update the status table after each significant event:
Issues Status:
| Issue | Title | Status | Agent Session | PR |
|---|---|---|---|---|
| #100 | Feature X (umbrella) | Open | - | - |
| #101 | Backend API | ✅ Complete | abc123... |
#105 (merged) |
| #102 | Database schema | ✅ Complete | def456... |
#106 (merged) |
| #103 | Frontend components | In Progress | ghi789... |
- |
| #104 | Integration tests | In Progress | jkl012... |
- |
Once all sub-issues are complete and merged into the umbrella branch:
- Verify the umbrella branch builds/tests successfully
- Review the combined changes
- Update the umbrella issue with completion summary
Create a PR from the umbrella branch to main:
gh pr create --base main --head issue/<umbrella-id> --title "Feature X" --body "..."The PR description should:
- Reference the umbrella issue ("Closes #100")
- Summarize all changes
- List all sub-issues that were completed
Leave the final PR open for human review and merge.
The orchestrator should minimize file reads to preserve context window for coordination tasks:
- Do not review code directly - worker agents handle code review with a separate review agent
- Do read files when necessary to resolve merge conflicts
- Do read files when answering specific questions from worker agents
- Do rely on PR descriptions and agent reports for understanding changes
- Right-size tasks: Each sub-task should be completable in a single agent session
- Minimize overlap: Avoid multiple agents modifying the same files
- Clear boundaries: Each task should have well-defined scope and success criteria
- Independent first: Start with tasks that have no dependencies
- Maximize parallelism: Spawn all unblocked tasks simultaneously
- Pipeline: As tasks complete, immediately spawn newly unblocked work
- Clear handoffs: Provide complete context when spawning agents
- Track everything: Keep status tables updated
- Document decisions: Note any deviations from the original plan
- Conflicts: Ask agent to rebase, don't try to resolve yourself
- Failed tasks: Can respawn a new agent for the same issue
- Blocked agents: Check if dependencies are actually blocking or can be worked around
When spawning a worker agent, include:
You are implementing issue #<sub-issue-id> (<title>) for the <repo> repository.
## Task
<clear description of what to implement>
## Files
<relevant file paths>
## Branch Instructions
1. Create your branch from `issue/<umbrella-id>`: `git checkout -b issue/<sub-issue-id> origin/issue/<umbrella-id>`
2. Implement the changes
3. Open a PR targeting `issue/<umbrella-id>` (not main)
4. Request code review from a review agent
5. Address any review feedback
6. Report back when complete and review is approved
## Context
<any additional context, links to related issues, design docs, etc.>