Agent Orchestration Overview
Relevant source files
The following files were used as context for generating this wiki page:
Agent Orchestration within the OhMyOpenCode ecosystem is a multi-tiered system designed to transform high-level user goals into verified, production-ready code. The architecture separates concerns between strategic planning, master coordination, and specialized execution. It employs a "Plan-First" philosophy where complex tasks are decomposed into parallel execution waves to maximize throughput and ensure technical accuracy.
The system relies on a hierarchy of specialized agents, each with distinct identity constraints and toolsets. Orchestration is driven by an "Intent Gate" that classifies requests into tiers (Trivial, Standard, Architecture, etc.) to determine the appropriate depth of planning and delegation.
Sources: src/agents/prometheus/gpt.ts:43-52, src/agents/sisyphus/default.ts:184-210, src/agents/prometheus/identity-constraints.ts:8-15
Core Agent Hierarchy
The orchestration flow is characterized by the separation of the "Planner" (Prometheus), the "Orchestrator" (Atlas), and the "Worker" (Sisyphus/Hephaestus).
Orchestration Roles
| Agent | Role | Primary Responsibility |
|---|---|---|
| Metis | Pre-Planning Consultant | Identifies hidden intent, ambiguities, and AI-slop patterns. |
| Prometheus | Strategic Planner | Conducts interviews and generates "decision-complete" work plans. |
| Atlas | Master Orchestrator | Conducts the execution of plans by delegating to subagents. |
| Sisyphus | Executive Agent | The primary worker capable of both self-execution and delegation. |
| Hephaestus | Autonomous Deep Worker | Senior Staff Engineer persona focused on solving complex sub-tasks. |
| Oracle | High-IQ Consultant | Read-only model for debugging and architectural advice. |
Sources: src/agents/metis.ts:16-25, src/agents/prometheus/gpt.ts:12-21, src/agents/atlas/gpt-prompt-sections.ts:1-6, src/agents/sisyphus/default.ts:110-120, src/agents/hephaestus/gpt.ts:114-118
Architectural Flow Diagram
This diagram illustrates the progression from a user request to the final verified implementation.
Phase 0: Intent Classification and Grounding
Every orchestration begins with an "Intent Gate" to determine the strategy. This prevents "AI slop" by ensuring the system doesn't over-engineer simple fixes or under-plan architectural changes.
Intent Tiers
- Trivial: Single file, <10 lines. Handled directly by workers like Sisyphus or Hephaestus.
- Standard: 1-5 files. Requires full interview and plan generation.
- Architecture: 5+ modules. Requires deep interview and mandatory Oracle consultation.
- Research: Broad investigation where the goal is clear but the path is not.
Sources: src/agents/prometheus/gpt.ts:71-80, src/agents/prometheus/gemini.ts:78-86, src/agents/sisyphus/default.ts:153-165
Grounding and Exploration
Before asking user questions, agents must perform "Silent Exploration" using Explore (internal codebase search) and Librarian (external documentation search) agents. The system enforces a mandate of at least 2-3 parallel background searches to ground the agent in the actual environment.
Sources: src/agents/prometheus/gpt.ts:85-110, src/agents/prometheus/gemini.ts:40-49
Phase 1: Strategic Planning (Prometheus)
Prometheus is strictly a planner, forbidden from writing or editing source code. Its mission is to produce decision-complete plans where the implementer needs zero judgment calls.
The Planning Workflow
- Interview: Gather requirements and record them in a
.sisyphus/drafts/{name}.mdfile. - Metis Consultation: A mandatory step where the Metis agent reviews the session to identify missing questions or guardrails.
- Plan Generation: Prometheus writes the work plan to
.sisyphus/plans/{name}.mdusing an incremental write protocol to handle token limits. - Momus Review: An optional "High Accuracy Mode" where the Momus agent verifies every detail of the plan.
Sources: src/agents/prometheus/gpt.ts:133-145, src/agents/prometheus/identity-constraints.ts:145-170, src/agents/prometheus/plan-generation.ts:114-125
Plan Structure
A standard work plan includes a Dependency Matrix and Parallel Execution Waves. Tasks are grouped into waves (e.g., Wave 1 for foundation, Wave 2 for core modules) to maximize concurrent execution.
Sources: src/agents/prometheus/plan-template.ts:77-110
Phase 2: Master Orchestration (Atlas)
Atlas is the "Conductor" responsible for executing the Prometheus plan. It follows a strict boundary: it manages the .sisyphus/plans/*.md file but delegates all code-writing tasks.
Delegation and Verification Sequence
Atlas employs a 4-phase critical QA protocol for every single delegation:
Execution Disciplines
Task Management (Todo Discipline)
Orchestration requires strict adherence to task tracking. Agents must create tasks/todos before starting work, update status to in_progress one at a time, and mark completed immediately.
- Task creation rule: Required for any multi-step work (2+ steps).
- Session Continuity: Agents must use
session_idfor retries and follow-ups to preserve context and save tokens.
Sources: src/agents/hephaestus/gpt.ts:25-50, src/agents/sisyphus/default.ts:32-60, src/agents/atlas/default-prompt-sections.ts:165-185
Parallel Execution Rules
Orchestrators must parallelize independent tool calls and agent fires.
- Exploration Agents: ALWAYS run in background (
run_in_background=true). - Implementation Tasks: NEVER run in background for the master session; the orchestrator waits for completion to verify.
Sources: src/agents/atlas/gpt-prompt-sections.ts:153-172, src/agents/sisyphus/default.ts:232-250
Conclusion
The agent orchestration system in OhMyOpenCode provides a robust framework for autonomous software engineering. By enforcing a separation between planning (Prometheus), orchestration (Atlas), and execution (Sisyphus), the project ensures that code changes are grounded in codebase context, reviewed by specialists, and verified through a mandatory 4-phase QA protocol. This tiered approach allows the system to handle everything from trivial typos to complex architectural refactors with high precision and throughput.