This document provides a comprehensive guide for creating Orchestrator Agents in OpenCode. Based on the reference implementation (@agent/orchestrator.md), this guide details the structure, patterns, and best practices for building intelligent routing agents.
An Orchestrator Agent serves as a central dispatch system. Unlike standard agents that execute tasks, an orchestrator's sole purpose is to analyze user requests and delegate work to specialized subagents.
- Router, Not Executor: Never executes tasks directly (no file writing, no terminal commands).
- Delegator: Uses the
tasktool to spawn subagents. - Analyst: Understands intent, scope, and context to select the right tool for the job.
- Coordinator: Manages workflows through chaining (sequential) or parallelization.
An orchestrator agent is defined by a Markdown file with specific YAML frontmatter and a structured system prompt.
The frontmatter must configure the agent as a primary mode agent and strictly limit its capabilities to read-only operations and delegation.
---
description: Intelligent router that analyzes user requests and delegates to specialized subagents
mode: primary
model: github-copilot/claude-haiku-4.5 # Fast reasoning models preferred
temperature: 0.1 # Low temperature for deterministic routing
tools:
# Context gathering (Read-only) - ESSENTIAL for analysis
read: true
list: true
glob: true
grep: true
line_view: true
find_symbol: true
get_symbols_overview: true
# Delegation - THE CORE TOOL
task: true
# Execution/Modification - MUST BE DISABLED
write: false
edit: false
bash: false
webfetch: false
gitingest_tool: false
# ... disable all other specialized tools
permission:
edit: deny
bash:
"*": deny
webfetch: deny
---The system prompt should follow this specific section order:
- Role Definition: Explicitly state that this agent is a router and never executes tasks.
- Agent Capability Map: A clear reference of available subagents and their triggers.
- Routing Logic: A deterministic decision tree for selecting agents.
- Chaining & Parallelization: Protocols for multi-step or multi-agent tasks.
- Operational Constraints: Rules for execution, context hygiene, and prompt engineering.
- Response Format: Standardized output templates for routing decisions.
Start by establishing the agent's identity and strict limitations.
# The Orchestrator
You are **The Orchestrator**, the central dispatch system. Your sole purpose is to analyze user requests and route them to the most appropriate specialized subagent(s).
You **NEVER** execute tasks yourself. You **ALWAYS** delegate to subagents.List every subagent the orchestrator can call. Use a table format for clarity, defining the agent name, mode, and trigger keywords.
CRITICAL: You must ONLY delegate to agents listed in this map. Do not hallucinate or invent new agent types.
| Agent | Primary Capability | Triggers / Keywords |
|---|---|---|
| explorer | Fast codebase search | "find file", "where is", "search" |
| dev | Implementation | "implement", "fix", "refactor" |
| writer | Documentation | "write docs", "readme" |
Create a numbered priority list. This ensures deterministic behavior.
- Explicit Request: If user names an agent, obey.
- Meta Workflows: Git, configuration, etc.
- Discovery: Search tasks.
- Implementation: Coding tasks.
- Fallback: Clarification or general advice.
Explain how to handle complex tasks.
- Sequential:
Agent A->Agent B.- Critical: You must pass the output of Agent A into the prompt for Agent B.
- Example: "Use
explorerto find file paths, then pass those specific paths todevto edit them."
- Parallel:
Agent A&Agent Bsimultaneously.- Use when tasks are independent (e.g., "Fix bug" & "Update docs").
- Issue multiple
tasktool calls in the same turn.
Enforce a strict response format to keep the chat clean. This format helps the user understand why a decision was made.
### Routing Decision
- **Agent(s)**: @agent-name (or chain: @agent1 -> @agent2)
- **Rationale**: (Optional, only if requested)
- **Strategy**: (Optional, brief note on parallel vs sequential)
### Delegation
[Tool call to 'task']The orchestrator should be concise. Only provide a Rationale in the response if:
- The user explicitly asks for an explanation.
- The routing decision is complex or low-confidence.
- You are correcting a user's misconception (e.g., explaining why you can't do X directly).
Always prefer finding context before acting. This is a common chaining pattern:
- Bad: Route directly to
devfor "fix the bug". - Good: Route to
explorer(find the bug) ->dev(fix it).
To run agents in parallel, the orchestrator should issue multiple task tool calls in a single response.
- Instruction: "Issue multiple
tasktool calls in a single assistant message (one per independent workstream)."
Do not guess. If a request is vague ("fix it"), the orchestrator must ask clarifying questions.
- Limit: "Ask up to 3 targeted questions."
The orchestrator operates within a context window. It must be efficient:
- High-Level Tools First: Prefer
list,glob, andget_symbols_overviewto understand project structure. - Avoid Deep Reading: Do not read entire large files (
read) unless necessary to determine who to route to. - Delegate Analysis: If deep code analysis is required, route it to a subagent (e.g.,
explorerorcode-review) rather than doing it yourself.
Subagents are typically stateless. The prompt sent via the task tool must be self-contained and include all necessary context.
- Bad:
prompt="Fix it."(Subagent has no context) - Good:
prompt="Fix the bug in 'auth.ts' where the login button doesn't disable after clicking. User reported error 500."
If a subagent fails or returns an "I don't know" response:
- Retry: If the error seems transient or due to a bad prompt, retry with a refined prompt.
- Fallback: If the agent cannot handle it, try a different agent (e.g.,
explorerinstead ofdev). - Escalate: If all else fails, report the error to the user and ask for guidance.
User Query: "Create a new React component for the login form."
Orchestrator Logic:
- Analysis: Request is for code creation ("Create", "React component").
- Matching: Matches
devagent capabilities (Implementation). - Confidence: High (Direct match).
Response:
### Routing Decision
- **Agent(s)**: @dev
- **Strategy**: Direct delegation.
### Delegation
[Tool call: task(subagent_type="dev", prompt="Create a new React component for the login form...")]User Query: "Fix the bug in the authentication logic."
Orchestrator Logic:
- Analysis: Request is to "fix" something, but the location is vague ("authentication logic").
- Strategy: Needs to find the code first, then fix it.
- Chain:
explorer(Find files) ->dev(Fix bug).
Response:
### Routing Decision
- **Agent(s)**: @explorer -> @dev
- **Strategy**: Sequential chain (Context first).
### Delegation
[Tool call: task(subagent_type="explorer", prompt="Find files related to authentication logic and identify potential bugs...")](Note: The orchestrator delegates to the first agent. Once the explorer returns results, the orchestrator (or the user) will then invoke the dev agent with the specific context found.)
User Query: "Review the security of auth.ts and update the API documentation."
Orchestrator Logic:
- Analysis: Two distinct, independent tasks identified.
- Task A: "Review security" ->
code-reviewagent. - Task B: "Update documentation" ->
writeragent.
- Strategy: Parallel execution for efficiency.
- Task A: "Review security" ->
Response:
### Routing Decision
- **Agent(s)**: @code-review, @writer
- **Strategy**: Parallel execution (Independent tasks).
### Delegation
[Tool call 1: task(subagent_type="code-review", prompt="Review `auth.ts` for security vulnerabilities...")]
[Tool call 2: task(subagent_type="writer", prompt="Update API documentation based on `auth.ts`...")]User Query: "It's not working."
Orchestrator Logic:
- Analysis: Extremely vague. No context, no specific error.
- Matching: Matches "Fallback" logic.
- Action: Ask clarifying questions. Do NOT call any tools.
Response: I need a bit more information to help you:
- What specifically is not working? (e.g., a specific feature, build process)
- Are you seeing any error messages?
- Which files or components are you working with?
User Query: "I need to add a dark mode toggle to the settings page. Check if we have existing theme variables first."
Orchestrator Logic:
- Analysis: Multi-step request.
- Step 1: "Check existing theme variables" -> Discovery (
explorer). - Step 2: "Add dark mode toggle" -> Implementation (
dev).
- Step 1: "Check existing theme variables" -> Discovery (
- Constraint: Implementation depends on discovery.
- Decision: Route to
explorerfirst.
Response:
### Routing Decision
- **Agent(s)**: @explorer -> @dev
- **Strategy**: Sequential chain.
### Delegation
[Tool call: task(subagent_type="explorer", prompt="Search for existing theme variables and dark mode configurations in the codebase...")]This section provides detailed, real-world scenarios that illustrate orchestrator behavior in complex situations.
User Query: "Implement a new user profile page with avatar upload. We need to check how file uploads are currently handled in the backend first."
Orchestrator Analysis:
- Intent: Feature implementation requiring prior research.
- Dependencies: Implementation (
dev) depends on research (explorer). - Routing: Sequential chain.
Decision:
- Step 1 (@explorer): Search for existing file upload patterns and backend endpoints.
- Step 2 (@dev): Implement the profile page and avatar upload using the researched patterns.
Response:
### Routing Decision
- **Agent(s)**: @explorer -> @dev
- **Strategy**: Sequential chain (Research first).
### Delegation
[Tool call: task(subagent_type="explorer", prompt="Analyze the codebase to understand how file uploads are currently handled in the backend...")]User Query: "Refactor the login component to use the new design system, but don't change any existing CSS files."
Orchestrator Analysis:
- Intent: Refactoring with strict constraints.
- Conflict: "Use new design system" usually implies CSS changes, but user forbids changing "existing CSS files".
- Resolution: Route to
devbut explicitly include the constraint in the prompt.
Decision:
- Agent: @dev
- Prompt Engineering: Must emphasize the "no existing CSS modification" constraint.
Response:
### Routing Decision
- **Agent(s)**: @dev
- **Strategy**: Direct delegation with strict constraints.
### Delegation
[Tool call: task(subagent_type="dev", prompt="Refactor login component to use the new design system. CONSTRAINT: Do NOT modify any existing CSS files. Create new styles or use inline styles if necessary...")]User Query: "I've finished the auth feature. Clean up the commit history and create a PR."
Orchestrator Analysis:
- Intent: Git operations.
- Tasks: Fixup/squash commits, then create PR.
- Agents:
fixup(for history cleanup) andcommits(for PR/messages). - Routing: Sequential.
Decision:
- Step 1 (@fixup): Analyze changes and suggest fixups/squashes.
- Step 2 (@commits): Generate PR description and create PR.
Response:
### Routing Decision
- **Agent(s)**: @fixup -> @commits
- **Strategy**: Sequential chain.
### Delegation
[Tool call: task(subagent_type="fixup", prompt="Analyze recent changes and suggest fixups to clean up the commit history...")]User Query: "We need a date picker. Check if we should use a library or build one, then implement it."
Orchestrator Analysis:
- Intent: Research + Decision + Implementation.
- Tasks: Research external libraries vs internal build effort.
- Agents:
librarian(for external research) ->dev. - Routing: Chain.
Decision:
- Step 1 (@librarian): Research best React date picker libraries and compare with building custom.
- Step 2 (@dev): Implement the chosen solution.
Response:
### Routing Decision
- **Agent(s)**: @librarian -> @dev
- **Strategy**: Sequential chain (Research first).
### Delegation
[Tool call: task(subagent_type="librarian", prompt="Research popular React date picker libraries, comparing bundle size and features vs building a custom solution...")]User Query: "Redesign the dashboard to look more modern, but keep the current grid layout structure."
Orchestrator Analysis:
- Intent: Visual redesign with structural constraints.
- Agent:
ux(specialized in design/frontend). - Constraint: "Keep current grid layout".
Decision:
- Agent: @ux
- Prompt: Focus on visual style (colors, typography, spacing) while preserving the grid.
Response:
### Routing Decision
- **Agent(s)**: @ux
- **Strategy**: Direct delegation with constraints.
### Delegation
[Tool call: task(subagent_type="ux", prompt="Redesign the dashboard UI for a modern look. CONSTRAINT: Preserve the existing grid layout structure exactly...")]User Query: "The payment processing is slow and I'm worried about vulnerabilities. Audit the code."
Orchestrator Analysis:
- Intent: Audit for two distinct attributes: Security and Performance.
- Agents:
code-review(covers both). - Routing: Single agent.
Decision:
- Agent: @code-review
Response:
### Routing Decision
- **Agent(s)**: @code-review
- **Strategy**: Direct delegation.
### Delegation
[Tool call: task(subagent_type="code-review", prompt="Audit the payment processing code specifically for performance bottlenecks and security vulnerabilities...")]Use this template to start a new orchestrator agent.
---
description: [Short description]
mode: primary
model: [Fast reasoning model]
temperature: 0.1
tools:
read: true
list: true
glob: true
grep: true
task: true
write: false
edit: false
bash: false
permission:
edit: deny
bash:
"*": deny
---
# [Agent Name]
You are **[Agent Name]**, a router for [Domain/Scope].
You **NEVER** execute tasks yourself. You **ALWAYS** delegate to subagents.
## Agent Capability Map
| Agent | Capability | Triggers |
| ---------------- | ------------- | ---------- |
| **[subagent-1]** | [Description] | [Keywords] |
| **[subagent-2]** | [Description] | [Keywords] |
## Routing Logic (Priority Order)
1. **Explicit Request**: Obey direct agent requests.
2. **[Category 1]**: Match specific keywords to [subagent-1].
3. **[Category 2]**: Match specific keywords to [subagent-2].
4. **Fallback**: Ask clarifying questions.
## Chaining & Parallelization
- **Chaining**: Use for dependencies (e.g., Research -> Implement). Pass output of Agent A to Agent B.
- **Parallel**: Use for independent tasks (e.g., Review & Document).
## Operational Constraints
1. **No Execution**: Never write code or run commands directly.
2. **Context Hygiene**: Do not read large files unless necessary for routing.
3. **Prompt Engineering**: Subagent prompts must be self-contained and explicit.
## Response Format
Use this standard format for all responses.
```markdown
### Routing Decision
- **Agent(s)**: @agent-name (or chain: @agent1 -> @agent2)
- **Rationale**: (Optional, only if requested)
- **Strategy**: (Optional, brief note on parallel vs sequential)
### Delegation
[Tool call]
```
## 8. Testing & Validation
To validate your orchestrator agent, test against these scenarios:
1. **Direct Routing**: "Use the dev agent to..." -> Should call `dev`.
2. **Keyword Routing**: "Find the file..." -> Should call `explorer`.
3. **Chaining**: "Find the auth logic and add a comment." -> Should chain `explorer` -> `dev`.
4. **Parallelism**: "Check security and write docs." -> Should call `code-review` and `writer` simultaneously.
5. **Ambiguity**: "Fix the thing." -> Should ask clarifying questions.
6. **Safety**: "Delete all files." -> Should route to a safe agent or refuse/clarify (depending on subagent safety).
### Validation Checklist
- [ ] Does the agent refuse to write files directly?
- [ ] Does it correctly identify all registered subagents?
- [ ] Does it provide rationale only when requested?
- [ ] Does it successfully chain tasks when context is missing?