| name | subagent-orchestration |
| description | Fresh subagents per task with two-stage reviews. Trigger: When coordinating parallel agents for complex workflows. |
| license | Apache 2.0 |
| metadata | {"version":"1.0","type":"behavioral","skills":["writing-plans","verification-protocol"]} |
Subagent Orchestration
Coordinate multiple fresh subagents for complex tasks with two-stage review cycles. Ensures isolation and quality at each step.
When to Use
- Complex multi-task workflows requiring specialization
- Tasks benefiting from fresh context per step
- Parallel execution of independent tasks
- Two-stage review workflows (spec → quality)
Don't use for:
- Simple sequential tasks (use plan-execution)
- Single-agent workflows
- Tasks requiring shared context across steps
Critical Patterns
✅ REQUIRED: Fresh Subagent Per Task
Launch new subagent for each major task (not reuse).
# ✅ CORRECT: Fresh agent per task
## Task 1: Implement user registration
**Agent**: subagent-1 (fresh)
**Input**: User registration spec, User entity schema
**Output**: Registration endpoint + tests
**Status**: ✅ Complete
**Review**: Two-stage (spec ✅, quality ✅)
---
## Task 2: Implement password reset
**Agent**: subagent-2 (fresh, no context from subagent-1)
**Input**: Password reset spec, User entity schema, Email service interface
**Output**: Password reset endpoint + tests
**Status**: ✅ Complete
**Review**: Two-stage (spec ✅, quality ✅)
---
# ❌ WRONG: Reusing agent
Agent-1 does Task 1 → Agent-1 does Task 2
Problem: Carries assumptions from Task 1, stale context, decision fatigue
Why fresh agents?
- Isolation: Each agent starts with clean slate
- Specialization: Agent focuses on single task
- Parallel: Independent agents can work simultaneously
- Quality: No accumulated technical debt or assumptions
✅ REQUIRED: Craft Context — Never Inherit Session History
Each subagent prompt must be self-contained. Never pass your session history or assume the subagent knows what happened before.
# ❌ WRONG: Implicit context inheritance
Agent.spawn("Now implement the password reset endpoint")
// Agent has no idea what was built, what interfaces exist, what constraints apply
# ✅ CORRECT: Explicit crafted context
Agent.spawn(`
Implement POST /auth/reset-password.
User schema: see src/models/user.ts
Email service interface: see src/services/email.interface.ts
Error format: { error: string, code: string } — see src/types/errors.ts
Test pattern: see tests/auth-register.test.ts
Do NOT read other test files — only the interfaces above.
`)
✅ REQUIRED: Two-Stage Review Per Task
Review each task output in two stages: spec compliance FIRST, then code quality.
## Task 1: User Registration Endpoint
### Stage 1: Spec Compliance Review (Architect)
- ✅ Accepts email/password via POST /auth/register
- ❌ Missing: Rate limiting (spec section 3.2)
- ❌ Missing: Email uniqueness check returns 409
**Decision**: ❌ FAIL → Return to subagent with feedback
[After subagent fixes]
### Stage 1 (Retry): Spec Compliance
- ✅ All spec requirements met
**Decision**: ✅ PASS → Proceed to Stage 2
### Stage 2: Code Quality Review
- ✅ TypeScript strict mode enabled
- ⚠️ Password hashing uses deprecated bcrypt.hashSync
- ✅ Tests cover happy path + edge cases
**Decision**: ✅ PASS with minor improvements noted
Two-stage benefits:
- Prevents quality review on incorrect behavior
- Clear separation: correctness vs maintainability
- Architect reviews spec, senior dev reviews quality
- Faster iteration (fix spec issues first)
Full walkthrough: orchestration-patterns.md
✅ REQUIRED: Task Handoff Protocol
Clear handoff between agents with explicit context.
Handoff structure:
- From / To: Identify source and destination agent
- Files to read (shared context): Interfaces, schemas, helpers
- Constraints: Error formats, test patterns, rate limits to follow
- NOT provided: Implementation details or assumptions from prior task
Handoff includes:
- Shared interfaces: What APIs to use
- Constraints: What rules to follow
- NOT included: How prior task was implemented (allows fresh approach)
Full template with instructions: orchestration-patterns.md
✅ REQUIRED: Parallel Execution When Possible
Launch independent tasks in parallel for efficiency.
## Batch 1: Parallel Execution
### Parallel Group 1 (independent tasks)
**Subagent-A** (parallel):
- Task 1: User registration endpoint
- Dependencies: User entity, bcrypt
- Estimated: 15 min
**Subagent-B** (parallel):
- Task 2: Product catalog API (completely independent)
- Dependencies: Product entity, database
- Estimated: 20 min
**Status**: Both running in parallel ⏳
---
[Wait for both to complete]
**Subagent-A**: ✅ Complete (16 min actual)
**Subagent-B**: ✅ Complete (18 min actual)
Benefits of parallel execution:
- Faster total time (15 min + 20 min = 20 min parallel vs 35 min sequential)
- Better resource utilization
- Independent quality (one failure doesn't block the other)
Decision Tree
Complex workflow with 5+ tasks?
→ Break into independent tasks
→ Launch fresh subagent per task
→ Two-stage review per output
Tasks independent?
→ Execute in parallel (multiple subagents)
→ Benefits: Speed, isolation
Tasks dependent?
→ Execute sequentially with handoff protocol
→ Provide only necessary context
Review failed?
→ Spec failed (Stage 1)?
→ Return to subagent with spec feedback
→ Re-review Stage 1 after fix
→ Quality failed (Stage 2)?
→ Minor issues: Note and proceed
→ Major issues: Return to subagent
Subagent blocked?
→ Document blocker
→ Launch next independent task
→ Return when unblocked
Edge Cases
Subagent produces incorrect output: If Stage 1 review fails badly (completely wrong approach), consider launching fresh agent with better instructions instead of asking same agent to fix.
Cross-task integration needed: If Task 3 needs to integrate Task 1 + Task 2 outputs, create Integration Task with both outputs as context.
## Task 3: Integration (Registration + Password Reset)
**Agent**: subagent-3 (fresh)
**Input**:
- Task 1 output (registration endpoint)
- Task 2 output (password reset endpoint)
- Integration spec
**Goal**: Ensure both endpoints share same error format, rate limiting strategy, email service
Very large tasks (>30 min): Break into sub-tasks with dedicated sub-agents. Example: "Task 2: Product catalog" → Task 2.1 (list), Task 2.2 (create), Task 2.3 (update).
Shared state issues: If parallel agents modify same files, merge conflicts arise. Solution: Assign file ownership per agent or run sequentially.
Cost optimization: Fresh agents use tokens. For very small tasks (<5 min), consider grouping into single agent task.
Checklist
Example
# Subagent Orchestration: User Authentication Feature
## Overview
- **Total Tasks**: 4
- **Parallel Groups**: 1 (tasks 1-2)
- **Sequential Tasks**: 2 (tasks 3-4 depend on 1-2)
- **Estimated Time**: 45 min
## Batch 1: Parallel Execution (Tasks 1-2)
**Subagent-A**: User Registration endpoint (fresh agent)
**Subagent-B**: Email Service integration (fresh agent, parallel with A)
[Both complete after ~22 min parallel vs ~40 min sequential]
- Subagent-A: ✅ Passed two-stage review
- Subagent-B: ⚠️ Stage 1 failed (missing retry logic) → fixed → ✅ PASS
## Batch 2: Sequential (Tasks 3-4)
**Subagent-C**: Password Reset endpoint (depends on Tasks 1+2) → ✅ PASS
**Subagent-D**: Integration Tests (depends on Tasks 1-3) → ✅ PASS
## Final Summary
- **Agents Used**: 4 fresh agents
- **Total Time**: 47 min (22 parallel + 15 + 10)
- **vs Sequential**: 65 min — saved 18 min (28% faster)
- **Quality**: All 4 tasks passed two-stage review
Full execution details with all review stages: orchestration-patterns.md
Resources
