Agent Team Orchestration

Overview

Evaluate whether parallel sub-agents fit the task, design workstreams, execute with quality gates.

Core principle: Sub-agents add coordination overhead and token cost. Only use them when parallelism genuinely saves time over single-session work.

When to Use

digraph fitness {
    "Task received" [shape=diamond];
    "3+ independent workstreams?" [shape=diamond];
    "Cross-layer changes?" [shape=diamond];
    "Multi-angle research?" [shape=diamond];
    "Use agent team" [shape=box];
    "Single session is better" [shape=box];

    "Task received" -> "3+ independent workstreams?";
    "3+ independent workstreams?" -> "Use agent team" [label="yes"];
    "3+ independent workstreams?" -> "Cross-layer changes?" [label="no"];
    "Cross-layer changes?" -> "Use agent team" [label="yes"];
    "Cross-layer changes?" -> "Multi-angle research?" [label="no"];
    "Multi-angle research?" -> "Use agent team" [label="yes"];
    "Multi-angle research?" -> "Single session is better" [label="no"];
}

Good fit:

• 3+ independent workstreams that can run in parallel
• Cross-layer changes (frontend + backend + tests)
• Research/review tasks with multiple angles
• Debugging with competing hypotheses
• Large refactors where different modules can be owned by different agents

Poor fit — single session instead:

• Sequential tasks with many dependencies
• Changes to a single file or tightly coupled files
• Simple bug fixes or small features
• Coordination overhead exceeds the benefit

Step 1: Evaluate Fit

Make the decision explicit before proceeding:

TEAM ASSESSMENT: [Good fit / Marginal / Poor fit]
Reason: [1-2 sentences]

If poor fit: explain why, suggest the better approach, and stop.

Step 2: Design Workstreams

Roles

For implementer/researcher/tester/planner, use the default general-purpose subagent type.

Model Selection

• fast: Mechanical tasks — file searches, pattern matching, formatting checks, simple validations
• inherit (default): Standard implementation, code review, testing, research
• Only override model when the task specifically benefits from it

Present the Plan

Before dispatching, present and wait for user confirmation:

PROPOSED WORKSTREAMS:
- Lead (me): Coordination, task management, synthesis
- code-reviewer: Reviews at quality gates
- [role]: [purpose]

TASK BREAKDOWN:
1. [task] -> assigned to [role]
2. [task] -> assigned to [role]

QUALITY GATES:
- Gate 1: After [milestone] -> code-reviewer + /deslop
- Gate 2: After [milestone] -> code-reviewer + /deslop
- Final: Before merge/completion -> full review + /deslop

Step 3: Quality Gates

Quality gates are mandatory checkpoints where work pauses for review.

Gate Rules

1. Code reviewer runs at every gate. Dispatch a code-review agent with all changes since last gate. It checks for bugs, style violations, CLAUDE.md compliance, and correctness.
2. /deslop runs at every gate. After the code reviewer finishes, the lead runs /deslop on all files modified since the last gate to catch AI-generated slop patterns.
3. Gate placement:
   • After each major implementation milestone (e.g., "backend API complete", "frontend wired up")
   • Before any merge, commit, or PR creation
   • When switching from one workstream to another
   • Minimum: one mid-point gate and one final gate
4. Gate failures block progress.
   • Critical/High issues must be fixed before proceeding
   • Medium issues should be fixed unless the user explicitly defers them
   • Create fix tasks and complete them before moving past the gate

Gate Flow

[Sub-agent completes milestone]
    -> Lead pauses new dispatches
    -> Dispatch code-reviewer with file list + diff context
    -> Run /deslop on all files modified since last gate
    -> If issues found: create fix tasks, complete them, re-dispatch reviewer
    -> If clean: proceed to next phase

Step 4: Execute

1. Create todos with all tasks, including quality gate tasks as explicit items
2. Dispatch sub-agents — one call per role/task
   • Pass ALL necessary context in the prompt (sub-agents are one-shot — they start fresh with no access to this conversation)
   • Include: relevant file contents, git diff, requirements, constraints, expected output format
   • Dispatch independent workstreams in a single message (parallel execution)
   • Dispatch dependent workstreams sequentially after prior results
3. Synthesize results — review each sub-agent's output before dispatching the next wave
4. Enforce gates — dispatch code-reviewer at every gate checkpoint

Step 5: Wrap Up

1. Run final /deslop across all modified files
2. Dispatch a final code-reviewer for holistic review of all changes
3. Present summary: what was accomplished, deferred issues, next steps

Reminders

• Sub-agents have no access to this conversation — give them rich context in prompts
• Never dispatch two sub-agents to edit the same file — break ownership clearly
• Code-reviewer should NOT get implementation tasks — keep it independent
• If unsure whether a task needs parallel agents, it probably doesn't
• Pass file contents directly in prompts — don't rely on sub-agents finding files