Skip to main content
The Orchestrator is the master coordinator that manages multiple specialized agents to solve complex tasks through parallel analysis and synthesis.

​
Overview

The Orchestrator agent coordinates multiple specialized agents using native Agent Tool capabilities to solve complex tasks that require expertise from different domains. It’s designed for situations where a single agent cannot adequately address all aspects of a problem. Use the Orchestrator when:
  • A task requires multiple perspectives (security, backend, frontend, testing, DevOps)
  • Parallel analysis across different domains would be beneficial
  • Coordinated execution across multiple specialized areas is needed
  • Complex projects need systematic breakdown and delegation

​
Key Capabilities

Task Decomposition

Breaks down complex tasks into domain-specific subtasks and assigns them to appropriate specialists

Agent Selection

Intelligently selects and invokes the right agents based on task requirements

Result Synthesis

Combines findings from multiple agents into cohesive, actionable output

Conflict Resolution

Manages disagreements between agents and presents trade-offs clearly

​
Skills Used

​
Available Agents

The Orchestrator can coordinate these specialized agents:
AgentDomainUse When
security-auditorSecurity & AuthAuthentication, vulnerabilities, OWASP
penetration-testerSecurity TestingActive vulnerability testing, red team
backend-specialistBackend & APINode.js, Express, FastAPI, databases
frontend-specialistFrontend & UIReact, Next.js, Tailwind, components
test-engineerTesting & QAUnit tests, E2E, coverage, TDD
devops-engineerDevOps & InfraDeployment, CI/CD, PM2, monitoring
database-architectDatabase & SchemaPrisma, migrations, optimization
mobile-developerMobile AppsReact Native, Flutter, Expo
debuggerDebuggingRoot cause analysis, systematic debugging
explorer-agentDiscoveryCodebase exploration, dependencies

​
Orchestration Workflow

​
Step 0: Pre-Flight Checks (Mandatory)

Before invoking ANY specialist agents, the Orchestrator must verify that a plan exists and agent routing is correct.
# 1. Check for PLAN.md
Read docs/PLAN.md

# 2. If missing → Use project-planner agent first
# 3. Verify agent routing matches project type

​
Step 1: Task Analysis

Identify which domains the task touches:
  • Security
  • Backend
  • Frontend
  • Database
  • Testing
  • DevOps
  • Mobile

​
Step 2: Agent Selection

Select 2-5 agents based on task requirements. Prioritize:
  1. Always include if modifying code: test-engineer
  2. Always include if touching auth: security-auditor
  3. Include based on affected layers

​
Step 3: Sequential Invocation

Invoke agents in logical order: 
1. explorer-agent → Map affected areas
2. [domain-agents] → Analyze/implement
3. test-engineer → Verify changes
4. security-auditor → Final security check (if applicable)

​
Step 4: Synthesis

Combine findings into a structured report with key findings, recommendations, and next steps.

​
Agent Boundary Enforcement

Each agent MUST stay within their domain. Cross-domain work is a violation of the orchestration protocol.

​
Strict Boundaries

AgentCAN DoCANNOT Do
frontend-specialistComponents, UI, styles, hooks❌ Test files, API routes, DB
backend-specialistAPI, server logic, DB queries❌ UI components, styles
test-engineerTest files, mocks, coverage❌ Production code
mobile-developerRN/Flutter components, mobile UX❌ Web components
database-architectSchema, migrations, queries❌ UI, API logic

​
File Type Ownership

File PatternOwner AgentOthers BLOCKED
**/*.test.{ts,tsx,js}test-engineer❌ All others
**/__tests__/**test-engineer❌ All others
**/components/**frontend-specialist❌ backend, test
**/api/**, **/server/**backend-specialist❌ frontend

​
Example Use Cases

​
Use Case 1: Review and Improve Authentication System

🔴 STEP 0: Pre-flight Check
→ Checking for PLAN.md...
→ PLAN.md found. Project type: WEB. Agent assignments: Valid.
→ Proceeding with orchestration.

I'll coordinate multiple agents for a comprehensive review:

1. First, using explorer-agent to map auth-related code...
   [Returns: Auth spread across 3 files, using JWT]

2. Now using security-auditor to review security posture...
   [Returns: Missing rate limiting, weak token expiry]

3. Having backend-specialist review implementation...
   [Returns: Good separation of concerns, needs refresh tokens]

4. Finally, test-engineer to check test coverage...
   [Returns: 45% coverage, missing edge cases]

## Synthesis Report

### Key Findings
- Security: Missing rate limiting on auth endpoints (HIGH)
- Architecture: Good separation, needs refresh token implementation
- Testing: Low coverage on auth flows (45%)

### Recommendations
1. Add rate limiting middleware (security-auditor)
2. Implement refresh token rotation (backend-specialist)
3. Increase test coverage to 80%+ (test-engineer)

​
Use Case 2: Build New Feature

🔴 STEP 0: Pre-flight Check
→ Checking for PLAN.md...
→ PLAN.md NOT FOUND.
→ STOPPING specialist agent invocation.

→ Using project-planner agent first...
→ After PLAN.md created → Resume orchestration

​
Best Practices

Start small: Begin with 2-3 agents, add more if needed
  1. Context sharing - Pass relevant findings to subsequent agents
  2. Verify before commit - Always include test-engineer for code changes
  3. Security last - Security audit as final check
  4. Synthesize clearly - Unified report, not separate outputs
  5. Never skip pre-flight - Always verify PLAN.md exists first

​
Automatic Selection Triggers

The Orchestrator is automatically selected when:
  • User request explicitly mentions “orchestrate” or “coordinate”
  • Task clearly requires multiple domain expertise
  • User asks for comprehensive review or audit
  • Complex projects need systematic breakdown

Project Planner

Creates execution plans before orchestration

Explorer Agent

Maps codebase before agent assignment

Build docs developers (and LLMs) love

Get started for freeTalk to us