name: agent-orchestration
description: |
Coordinate parallel agent execution with context handoff. Use when:
(1) task has parallelizable subtasks, (2) need to explore multiple areas,
(3) research and implementation can happen concurrently. Updates AGENTS.md
with status and results.
category: development
user-invocable: true

Agent Orchestration

Coordinates parallel agent execution with context handoff via documentation.

Trigger Conditions

Invoke when:
- Task has independent subtasks
- Need to explore multiple code areas
- Research and implementation can run in parallel
- Complex task benefits from divide-and-conquer

Also invoke explicitly with:
- /agent-orchestration [task]
- "coordinate agents"
- "run in parallel"

Procedure

Step 1: Analyze Task

Break down the task into subtasks:

Questions to ask:
- Can subtasks run independently?
- Do subtasks have dependencies?
- What context does each agent need?
- How will results be combined?

Step 2: Classify Parallelization Pattern

Step 3: Create Agent Specifications

For each agent, define:

## Agent: {{agent_id}}

**Task:** {{specific_task}}
**Type:** Explore | Research | Implement | Review
**Dependencies:** {{none | agent_ids}}
**Expected output:** {{files | summary | decision}}
**Context:** {{what this agent needs to know}}

Step 4: Update AGENTS.md

Before launching:

# Agent Coordination

## Current Task

Implement user authentication with OAuth support

## Active Agents

| ID | Task | Status | Started | Output |
|----|------|--------|---------|--------|
| a1 | Research OAuth providers | running | 14:30 | - |
| a2 | Explore existing auth code | running | 14:30 | - |
| a3 | Review security requirements | running | 14:30 | - |

## Dependencies

a1 ─┐
a2 ─┼─> a4 (implementation)
a3 ─┘

Step 5: Launch Agents

Independent agents (launch in parallel):

Launch agents a1, a2, a3 in parallel:

Agent a1: "Research OAuth providers (Google, GitHub, Microsoft). Compare features, security, implementation complexity. Output to RESEARCH.md"

Agent a2: "Explore existing auth code in src/auth/. Document current patterns, identify extension points. Output findings to AGENTS.md"

Agent a3: "Review security requirements in docs/security.md. List authentication requirements and constraints."

Dependent agents (wait for predecessors):

Wait for a1, a2, a3 to complete.

Agent a4: "Using research from a1, patterns from a2, and requirements from a3, implement OAuth authentication. Follow TDD workflow."

Step 6: Collect Results

Update AGENTS.md with results:

## Completed Agents

### Agent a1: Research OAuth providers

**Status:** complete
**Duration:** 15 min

**Results:**
Recommended Google OAuth for:
- Widest user base
- Best documentation
- Simplest implementation

**Files modified:**
- RESEARCH.md (OAuth findings section)

### Agent a2: Explore existing auth code

**Status:** complete
**Duration:** 12 min

**Results:**
Found extension points in:
- src/auth/middleware.ts (add OAuth check)
- src/auth/providers/ (add Google provider)

**Files modified:**
- None (exploration only)

Step 7: Context Handoff

Document what each agent discovered for the next phase:

## Context Handoff

### From a1 to a4

**Discovered:** Google OAuth is best choice. Use @google-cloud/oauth2 library.

**Next steps:** Implement Google OAuth provider in src/auth/providers/google.ts

### From a2 to a4

**Discovered:** Existing auth middleware at src/auth/middleware.ts can be extended. Pattern: each provider exports `authenticate()` and `getUser()` functions.

**Next steps:** Follow existing pattern when adding Google provider.

Parallelization Patterns

Pattern 1: Independent Exploration

Good for: Understanding codebase, initial research

┌─ Agent a1: Explore frontend ────┐
├─ Agent a2: Explore backend ─────┼─> Synthesize
└─ Agent a3: Explore infrastructure ─┘

Pattern 2: Research Then Decide

Good for: Evaluating options before implementation

┌─ Agent a1: Research option A ───┐
├─ Agent a2: Research option B ───┼─> Decision Agent
└─ Agent a3: Research option C ───┘

Pattern 3: Parallel Implementation

Good for: Independent features or components

┌─ Agent a1: Implement feature A ─┐
├─ Agent a2: Implement feature B ─┼─> Integration
└─ Agent a3: Implement feature C ─┘

Pattern 4: Pipeline

Good for: Sequential transformation

Research Agent ─> Design Agent ─> Implementation Agent ─> Review Agent

Agent Types

Skill Chaining

With TDD

Implementation agents should follow TDD:
1. Write failing test
2. Implement to pass
3. Refactor

With doc-maintenance

After all agents complete:
1. Update PLAN.md with completed tasks
2. Add discovered work to backlog

With research-to-plan

Research agents output feeds into planning:
1. Research agents gather information
2. research-to-plan converts to executable plan

Rationalizations (Do Not Skip)

Example Session

/agent-orchestration "Add OAuth authentication"

Analyzing task...

Identified subtasks:
1. Research OAuth providers (independent)
2. Explore existing auth code (independent)
3. Review security requirements (independent)
4. Implement OAuth (depends on 1, 2, 3)
5. Write tests (depends on 4)

Parallelization plan:

Phase 1 (parallel):
  - a1: Research providers
  - a2: Explore auth code
  - a3: Review requirements

Phase 2 (sequential):
  - a4: Implementation (after phase 1)
  - a5: Tests (after a4)

Launch phase 1? [y/n]

Notes

• Maximum 5 parallel agents recommended
• Each agent should have clear, bounded scope
• Use AGENTS.md for all context handoff
• Prefer explicit over implicit dependencies
• Document agent outputs even if "obvious"

References

For detailed guidance, see:
- context-handoff.md - Agent communication patterns
- parallel-patterns.md - When to parallelize