Break complex tasks into parallel subagent workstreams for maximum speed
Orchestrate multiple specialized subagents working in parallel on different parts of a large task. Instead of doing everything sequentially, split work so 3-5 agents work simultaneously.
Borrowed from: obra/superpowers — subagent-driven-development
ORCHESTRATOR (you, the main agent)
│
├── SUBAGENT A: [independent task]
├── SUBAGENT B: [independent task] ← all run in parallel
├── SUBAGENT C: [independent task]
│
└── Wait for all → Integrate results → Verify
Before launching any subagents, map all subtasks:
For a "build user authentication" feature:
Independent tasks (can parallelize):
- [A] Backend: POST /api/auth/register endpoint
- [B] Backend: POST /api/auth/login endpoint + JWT generation
- [C] Frontend: Registration form component
- [D] Frontend: Login form component
Sequential dependencies (must be done before others):
- Database schema + migrations → before [A] and [B]
- Auth middleware → before any protected routes
Test tasks (after implementation):
- [E] Unit tests for auth service
- [F] API tests for auth endpoints
- [G] E2E tests for login/register flow
For each subagent, define exactly:
Input: What they receive (file paths, specifications, existing code)
Output: What they must produce (file paths, function signatures, test names)
Constraints: What they must NOT change
Good subagent prompt structure:
You are [role]. Your ONLY job is [specific task].
Context:
- The project is [description]
- Related code is at [file paths]
- The existing [X] does [Y]
Your task:
1. [Specific action]
2. [Specific action]
3. [Specific action]
Produce:
- [file path 1]: [what it should contain]
- [file path 2]: [what it should contain]
Do NOT:
- Change files outside your task scope
- Install new dependencies without noting them
- Modify [specific protected thing]
When done, report:
- Files created/modified
- Functions/APIs you implemented
- Anything the orchestrator needs to know for integration
In Claude Code: Use Task tool to spawn subagents. In Cursor: Open multiple Composer windows. In other IDEs: Sequential is fine for smaller tasks.
□ Review each subagent's output for quality
□ Check for conflicts (two agents modified same file?)
□ Wire up the pieces (subagent A's output → subagent B's input)
□ Run all tests
□ Fix integration issues (these are expected and normal)
□ Final security scan: npx ecc-agentshield scan
Max 5 subagents active simultaneously
→ More than 5 = hard to track, integration becomes a nightmare
Max 20k tokens per subagent context
→ Large context = slower, more likely to miss instructions
Each subagent gets 1 clear responsibility
→ Two responsibilities = confusing, inconsistent output
Orchestrator never does implementation work
→ Orchestrator only decomposes, launches, monitors, integrates
When a subagent produces wrong/incomplete output:
1. Don't re-prompt the same subagent vaguely ("do it better")
2. Identify exactly what went wrong
3. Write a more specific prompt with the failure mode explicitly excluded
4. Or: do that subtask yourself if it's blocking everything
Task: "Add Stripe payment integration"
PREREQUISITES (do first, sequentially):
- Install: stripe package
- Add env vars: STRIPE_SECRET_KEY, STRIPE_WEBHOOK_SECRET
- Create DB migration: payments table
PARALLEL SUBAGENTS:
- [A] Backend: stripe service (create payment intent, handle webhooks)
- [B] Backend: payments endpoints (POST /checkout, POST /webhook)
- [C] Frontend: checkout component (card form, loading states, errors)
- [D] Tests: unit tests for stripe service (mock stripe SDK)
INTEGRATION:
- Connect frontend form → backend endpoints
- Test webhook flow end-to-end
- Security: verify webhook signatures are checked