Orchestrator Agent

The Orchestrator Agent is a multi-domain coordinator that analyzes complex requests, identifies relevant expert domains, and deploys specialized agents in parallel to execute work. It then synthesizes all results into a unified response.

Capabilities

• Analyzes complex requests to identify multiple domains (API, UI, Database, Testing, Security, CI, etc.)
• Deploys 2-8 domain experts in parallel for concurrent execution
• Coordinates work execution using only Task and TaskOutput tools
• Synthesizes expert outputs into unified, conflict-aware responses
• Handles both parallel independent work and sequential dependent work patterns
• Manages integration points between multiple specialized implementations

When to Use

Use this agent when:

• Full-stack features - "Add user profile with API, database schema, UI component, and tests" requires coordination across multiple domains
• Complex multi-domain requests - Single requests spanning API, UI, database, and deployment changes
• Parallel work coordination - Multiple independent pieces of work that should execute simultaneously
• Sequential dependent work - Work that must complete in order (database schema → API → UI → tests)
• Integration coordination - Ensuring multiple implementations work together correctly
• Large refactoring - Database changes that propagate to API, then UI, then tests
• Feature with infrastructure - Feature implementation plus CI/CD pipeline setup

How It Works

The agent follows a structured workflow:

CopyUSER REQUEST
     ↓
┌─────────────────────────────────────┐
│ 1. ANALYZE DOMAINS                  │ → Identify API, UI, Database, etc.
│ 2. PLAN EXECUTION                   │ → Parallel vs sequential dependencies
│ 3. DEPLOY EXPERTS                   │ → Spawn via Task in parallel
│ 4. COLLECT RESULTS                  │ → TaskOutput with block: true
│ 5. SYNTHESIZE RESPONSE              │ → Unified output with integration points
└─────────────────────────────────────┘
     ↓
COORDINATED MULTI-DOMAIN IMPLEMENTATION

Step 1: Analyze Request

The agent analyzes the request for domain keywords and identifies which experts are needed:

Step 2: Plan Execution

The agent determines execution strategy based on dependencies:

Parallel Execution (independent work):

API + UI (both can work simultaneously)
Testing + Documentation (can test while docs written)
Security audit + Performance analysis (independent reviews)

Sequential Execution (dependent work):

Database schema → API implementation → UI component
(Each depends on previous)

Mixed Execution (some parallel, some sequential):

Parallel: Database schema + API tests + Documentation
Then Sequential: API implementation → UI component

Step 3: Deploy Experts

All parallel experts are deployed simultaneously in a single message using background execution:

CopyTask(
  description: "Implement user profile API",
  prompt: "Create /api/profile endpoint with GET/PUT methods...",
  subagent_type: "agileflow-api",
  run_in_background: true
)
 
Task(
  description: "Implement profile UI component",
  prompt: "Create ProfilePage component with form...",
  subagent_type: "agileflow-ui",
  run_in_background: true
)

Step 4: Collect Results

Uses TaskOutput with block: true to wait for all expert responses:

CopyTaskOutput(task_id: "<api_task_id>", block: true)
TaskOutput(task_id: "<ui_task_id>", block: true)

Step 5: Synthesize

Combines all expert outputs into a unified response highlighting:

• What each expert completed
• Integration points between implementations
• Conflicts or compatibility issues
• Recommended next steps

Domain Experts

The Orchestrator coordinates with these domain specialists:

Parallel Patterns

Full-Stack Feature

Deploy database and API in parallel (independent), then UI and tests in parallel (after API exists):

Phase 1 (Parallel):
  - agileflow-database (schema)
  - agileflow-api (endpoint)

Phase 2 (Parallel, after Phase 1):
  - agileflow-ui (component)
  - agileflow-testing (tests)

Code Review / Analysis

Deploy multiple experts to analyze the same code simultaneously:

Parallel (same code, different perspectives):
  - agileflow-security (vulnerability analysis)
  - agileflow-performance (optimization analysis)
  - agileflow-testing (test coverage analysis)

Then:
  - Synthesize findings and prioritize issues

Best-of-N Comparison

Deploy the same task to multiple experts with different approaches and compare:

Parallel (same task, different approaches):
  - Expert A (approach 1: REST API)
  - Expert B (approach 2: GraphQL API)
  - Expert C (approach 3: RPC API)

Then:
  - Compare implementations
  - Select best approach for codebase
  - Provide reasoning

Critical Constraints

The Orchestrator has ONLY Task and TaskOutput tools:

Can Do:

• Spawn experts via Task
• Collect results via TaskOutput
• Analyze requests and plan execution
• Synthesize and coordinate responses

Cannot Do:

• Read files (no Read tool)
• Write files (no Write tool)
• Edit files (no Edit tool)
• Run commands (no Bash tool)
• Search code (no Glob/Grep tools)

MUST delegate ALL work to domain experts.

Conflict Resolution

When experts produce conflicting outputs:

1. Note the conflict in synthesis section
2. Present both options with trade-offs
3. Recommend one based on:
   • Consistency with existing patterns
   • Simplicity and maintainability
   • Performance implications
4. Ask for decision if recommendation unclear

Example conflict:

### Conflicts / Review Needed

API Expert recommends: PUT /api/profile for updates
UI Expert expects: PATCH /api/profile for updates

Recommendation: Use PUT (simpler, consistent with REST conventions)
UI can send full profile object without issues.

Example: Full-Stack User Profile Feature

Request: "Add a complete user profile feature with API, database, React component, and tests"

Orchestrator Response:

Analyzing multi-domain request...

Domains identified:
- Database (schema for user profiles)
- API (REST endpoints)
- UI (React component)
- Testing (unit and integration tests)

Execution plan:
- Phase 1 (Parallel): Database + API (API needs schema)
- Phase 2 (Parallel): UI + Testing (both use API)

[Spawning Phase 1 experts...]
- Database Expert → User profiles schema
- API Expert → /api/profile endpoints

[Collecting Phase 1 results...]

[Spawning Phase 2 experts...]
- UI Expert → ProfilePage component
- Testing Expert → Comprehensive test suite

[Collecting Phase 2 results...]

## Orchestration Complete

### Database Expert ✅
- Created `profiles` table with columns: id, user_id, bio, avatar_url, etc.
- Added indexes on user_id and created_at
- Files: `migrations/001_create_profiles.sql`

### API Expert ✅
- GET /api/profile - Fetch user profile
- PUT /api/profile - Update profile
- DELETE /api/profile - Remove profile
- Files: `src/routes/profile.ts`, `src/controllers/ProfileController.ts`

### UI Expert ✅
- ProfilePage component with form
- Form validation and error handling
- Styling with Tailwind CSS
- Files: `src/components/ProfilePage.tsx`, `src/hooks/useProfile.ts`

### Testing Expert ✅
- Unit tests for ProfilePage component
- Integration tests for API endpoints
- Database query tests
- 87% coverage
- Files: `src/routes/__tests__/profile.test.ts`, `src/components/__tests__/ProfilePage.test.tsx`

### Integration Points
- UI imports API functions from `src/api/profile.ts`
- UI calls GET /api/profile on component mount
- Form submission sends PUT to /api/profile
- Database schema matches API data model

### Next Steps
1. Wire ProfilePage into router in App.tsx
2. Add authentication middleware to API routes
3. Add validation on API layer
4. Deploy to staging for E2E testing

Ready to proceed with integration?

Key Behaviors

• ALWAYS analyzes for multiple domains - Never assumes single-domain work
• ALWAYS plans execution strategy - Parallel vs sequential based on dependencies
• ALWAYS deploys experts in parallel - Never sequentially unless dependencies require
• ALWAYS deploys ALL experts in a SINGLE message - Batches Task calls together
• ALWAYS uses TaskOutput with block: true - Waits for all results before synthesis
• NEVER gives final answer without synthesizing ALL expert responses - All perspectives must integrate
• ALWAYS notes integration points - Highlights how implementations connect

Tools Available

This agent has access to ONLY:

• Task - Deploy domain expert agents in parallel
• TaskOutput - Collect expert results and wait for completion

It does NOT have access to:

• Read, Write, Edit (cannot modify code itself)
• Bash (cannot run commands)
• Glob, Grep (cannot search code)

This constraint ensures the Orchestrator focuses exclusively on coordination, not implementation.

Model Configuration

• Model: Claude Sonnet 3.5 (optimized for coordination)
• Reasoning: Planning, parallel execution, synthesis logic

Related Agents

Domain Specialists (deployed by Orchestrator):

• database - Database schema and query expert
• api - REST API endpoint expert
• ui - Frontend component expert
• testing - Test coverage and strategy expert
• security - Security and authentication expert
• performance - Performance optimization expert
• ci - CI/CD pipeline expert
• devops - Infrastructure and deployment expert
• documentation - Technical documentation expert

Other Meta Agents:

• multi-expert - Analyzes same problem with 3-5 experts (different use case - analysis vs implementation)
• mentor - End-to-end implementation guidance

When NOT to Use

• Simple single-domain tasks - Use direct domain expert instead (faster, simpler)
• Analysis only - Use Multi-Expert agent for high-confidence analysis
• Simple questions - Use specialized agents directly
• Tasks requiring manual coordination - Orchestrator works only with agents