docs/guide/orchestration.md
Oh My OpenAgent's orchestration system transforms a simple AI agent into a coordinated development team through separation of planning and execution.
| Complexity | Approach | When to Use |
|---|---|---|
| Simple | Just prompt | Simple tasks, quick fixes, single-file changes |
| Complex + Lazy | Type ulw or ultrawork | Complex tasks where explaining context is tedious. Agent figures it out. |
| Complex + Precise | @plan → /start-work | Precise, multi-step work requiring true orchestration. Prometheus plans, Atlas executes. |
Decision Flow:
Is it a quick fix or simple task?
└─ YES → Just prompt normally
└─ NO → Is explaining the full context tedious?
└─ YES → Type "ulw" and let the agent figure it out
└─ NO → Do you need precise, verifiable execution?
└─ YES → Use @plan for Prometheus planning, then /start-work
└─ NO → Just use "ulw"
The orchestration system uses a three-layer architecture that solves context overload, cognitive drift, and verification gaps through specialization and delegation.
flowchart TB
subgraph Planning["Planning Layer (Human + Prometheus)"]
User[(" User")]
Prometheus[" Prometheus
(Planner)
claude-opus-4-8 / gpt-5.6-sol / glm-5.2"]
Metis[" Metis
(Consultant)
claude-sonnet-4-6 / claude-opus-4-8 / gpt-5.6-sol / glm-5.2"]
Momus[" Momus
(Reviewer)
gpt-5.6-terra / gpt-5.6-sol / claude-opus-4-8 / gemini-3.1-pro / glm-5.2"]
end
subgraph Execution["Execution Layer (Orchestrator)"]
Orchestrator[" Atlas
(Conductor)
claude-sonnet-4-6 / kimi-k3 / gpt-5.6-sol / minimax-m3 / minimax-m2.7"]
end
subgraph Workers["Worker Layer (Specialized Agents)"]
Junior[" Sisyphus-Junior
(Task Executor)
claude-sonnet-4-6 / kimi-k3 / gpt-5.6-sol / minimax-m3 / minimax-m2.7"]
Oracle[" Oracle
(Architecture)
gpt-5.6-sol / gemini-3.1-pro / claude-opus-4-8 / glm-5.2"]
Explore[" Explore
(Codebase Grep)
gpt-5.4-mini-fast / minimax-m2.7-highspeed / minimax-m3 / claude-haiku-4-5"]
Librarian[" Librarian
(Docs/OSS)
gpt-5.4-mini-fast / minimax-m2.7-highspeed / minimax-m3 / claude-haiku-4-5"]
Frontend[" visual-engineering
(category + frontend)
gemini-3.1-pro / glm-5 / claude-opus-4-8"]
end
User -->|"Describe work"| Prometheus
Prometheus -->|"Consult"| Metis
Prometheus -->|"Interview"| User
Prometheus -->|"Generate plan"| Plan[".omo/plans/*.md"]
Plan -->|"High accuracy review"| Momus
Plan -->|"Independent review"| Oracle
Momus -->|"OKAY / REJECT"| Prometheus
Oracle -->|"OKAY / REJECT"| Prometheus
User -->|"/start-work"| Orchestrator
Plan -->|"Read"| Orchestrator
Orchestrator -->|"task(category=deep/quick/unspecified-*)"| Junior
Orchestrator -->|"task(subagent_type=oracle)"| Oracle
Orchestrator -->|"call_omo_agent(subagent_type=explore)"| Explore
Orchestrator -->|"call_omo_agent(subagent_type=librarian)"| Librarian
Orchestrator -->|"task(category=visual-engineering, load_skills=[frontend])"| Frontend
Junior -->|"Results + Learnings"| Orchestrator
Oracle -->|"Advice"| Orchestrator
Explore -->|"Code patterns"| Orchestrator
Librarian -->|"Documentation"| Orchestrator
Frontend -->|"UI code"| Orchestrator
Model labels above show the current fallback stacks from packages/omo-opencode/src/shared/model-requirements.ts, not marketing names.
The system has 11 built-in agents:
sisyphus, hephaestus, prometheus, atlasoracle, librarian, explore, multimodal-looker, metis, momus, sisyphus-juniorCanonical assembly order for primary agents is:
Sisyphus → Hephaestus → Prometheus → Atlas
Mode distinction:
mode: "primary": top-level session agents selected directly in UI/CLImode: "subagent": worker/consultant agents invoked via task(..., subagent_type="...") or call_omo_agent(...)Sisyphus - ultraworker is the display name for the primary Sisyphus agent. It is not a separate provider, proxy, or replacement for your original model account.
Three names can appear together in logs or the TUI:
Sisyphus - ultraworker, Atlas - Plan Executor, Hephaestus - Deep Agentanthropic, openai, github-copilot, opencode, opencode-go, vercelclaude-opus-4-8, kimi-k3, gpt-5.6-sol, glm-5The agent decides the prompt and behavior. The provider namespace decides which connected account or gateway serves the request. The model id decides the model family. If you see Sisyphus running through opencode-go/kimi-k3, that means the Sisyphus prompt is using Kimi through the OpenCode Go provider path; it does not mean OMO replaced your provider silently.
When ulw or ultrawork is present, Sisyphus receives the ultrawork instruction set for a harder autonomous task. By default it keeps the agent's configured model or fallback chain. An explicit agents.sisyphus.ultrawork.model or variant setting can override that routing for ultrawork prompts.
task(category="...") routes to Sisyphus-Junior with category-optimized model routingtask(subagent_type="...") invokes that specific agent directly (for example oracle, explore, librarian)subagent_type are mutually exclusive inputs in one callPrometheus is not just a planner, it's an intelligent interviewer that helps you think through what you actually need. It is READ-ONLY - can only create or modify markdown files within .omo/ directory.
The Interview Process:
stateDiagram-v2
[*] --> Interview: User describes work
Interview --> Research: Launch explore/librarian agents
Research --> Interview: Gather codebase context
Interview --> ClearanceCheck: After each response
ClearanceCheck --> Interview: Requirements unclear
ClearanceCheck --> PlanGeneration: All requirements clear
state ClearanceCheck {
[*] --> Check
Check: Core objective defined?
Check: Scope boundaries established?
Check: No critical ambiguities?
Check: Technical approach decided?
Check: Test strategy confirmed?
}
PlanGeneration --> MetisConsult: Mandatory gap analysis
MetisConsult --> WritePlan: Incorporate findings
WritePlan --> HighAccuracyChoice: Present to user
state "Momus + Oracle review" as DualReview
HighAccuracyChoice --> DualReview: High accuracy required or selected
HighAccuracyChoice --> Done: User accepts plan
DualReview --> WritePlan: EITHER REJECTS - fix issues
DualReview --> Done: BOTH APPROVE - plan approved
Done --> [*]: Guide to /start-work
Intent-Specific Strategies:
Prometheus adapts its interview style based on what you're doing:
| Intent | Prometheus Focus | Example Questions |
|---|---|---|
| Refactoring | Safety - behavior preservation | "What tests verify current behavior?" "Rollback strategy?" |
| Build from Scratch | Discovery - patterns first | "Found pattern X in codebase. Follow it or deviate?" |
| Mid-sized Task | Guardrails - exact boundaries | "What must NOT be included? Hard constraints?" |
| Architecture | Strategic - long-term impact | "Expected lifespan? Scale requirements?" |
Before Prometheus writes the plan, Metis catches what Prometheus missed:
Why Metis Exists:
The plan author (Prometheus) has "ADHD working memory" - it makes connections that never make it onto the page. Metis forces externalization of implicit knowledge.
High-accuracy mode runs two independent reviews in parallel: Momus checks plan quality and Oracle checks the plan on the strongest available reasoning model. Both must approve before handoff.
The Dual-Review Loop:
Momus is approval-biased and rejects only verified blockers. It checks that:
Minor gaps and details that a developer can resolve during implementation do not block approval; a plan that is roughly 80% clear is considered executable.
If either reviewer rejects the plan, Prometheus fixes every cited issue and resubmits to both reviewers. No maximum retry limit.
Choose a compatible role before optimizing for invocation frequency. For example, a scarce Claude-family model such as Fable 5 fits Metis better than GPT-oriented Oracle or Momus. High-accuracy planning also runs Oracle and Momus together on every review round, so neither is purely an on-demand slot in that workflow.
See Agent-Model Matching: Where to Spend One Scarce Premium Model for the family-aware heuristic and a concrete configuration.
Atlas is like an orchestra conductor: it doesn't play instruments, it ensures perfect harmony.
flowchart LR
subgraph Orchestrator["Atlas"]
Read["1. Read Plan"]
Analyze["2. Analyze Tasks"]
Wisdom["3. Accumulate Wisdom"]
Delegate["4. Delegate Tasks"]
Verify["5. Verify Results"]
Report["6. Final Report"]
end
Read --> Analyze
Analyze --> Wisdom
Wisdom --> Delegate
Delegate --> Verify
Verify -->|"More tasks"| Delegate
Verify -->|"All done"| Report
Delegate -->|"background=false"| Workers["Workers"]
Workers -->|"Results + Learnings"| Verify
What Atlas CAN do:
What Atlas MUST delegate:
The power of orchestration is cumulative learning. After each task:
This prevents repeating mistakes and ensures consistent patterns.
Notepad System:
.omo/notepads/{plan-name}/
├── learnings.md # Patterns, conventions, successful approaches
├── decisions.md # Architectural choices and rationales
├── issues.md # Problems, blockers, gotchas encountered
├── verification.md # Test results, validation outcomes
└── problems.md # Unresolved issues, technical debt
Junior is the workhorse that actually writes code. Key characteristics:
Why the fallback chain is sufficient:
Junior doesn't need to be the smartest - it needs to be reliable. With:
Even a mid-tier execution model works when the harness is strict. The current fallback order is claude-sonnet-4-6 → kimi-k3 → gpt-5.6-sol → minimax-m3 → minimax-m2.7 → big-pickle. The intelligence is in the system, not a single worker model.
The hook system ensures Junior never stops halfway:
[SYSTEM REMINDER - TODO CONTINUATION]
You have incomplete todos! Complete ALL before responding:
- [ ] Implement user service ← IN PROGRESS
- [ ] Add validation
- [ ] Write tests
DO NOT respond until all todos are marked completed.
This "boulder pushing" mechanism is why the system is named after Sisyphus.
The Problem with Model Names:
// OLD: Model name creates distributional bias
task({ agent: "gpt-5.6-sol", prompt: "..." }); // Model knows its limitations
task({ agent: "claude-opus-4-8", prompt: "..." }); // Different self-perception
The Solution: Semantic Categories:
// NEW: Category describes INTENT, not implementation
task({ category: "ultrabrain", prompt: "..." }); // "Think strategically"
task({ category: "visual-engineering", prompt: "..." }); // "Design beautifully"
task({ category: "quick", prompt: "..." }); // "Just get it done fast"
task(category="...") supports these category names in user-facing orchestration:
visual-engineering, artistry, ultrabrain, deep, quick, unspecified-low, unspecified-high, writing, quick-rust, quick-zig, git
Notes:
packages/omo-opencode/src/tools/delegate-task/*-categories.ts and packages/omo-opencode/src/shared/model-requirements.tsSkills prepend specialized instructions to subagent prompts:
// Category + Skill combination
task(
(category = "visual-engineering"),
(load_skills = ["frontend"]), // Adds UI/UX expertise
(prompt = "..."),
);
task(
(category = "deep"),
(load_skills = ["playwright"]), // Adds browser automation expertise
(prompt = "..."),
);
Skill loading priority is:
project > opencode > user > builtin
Skill-embedded MCP servers are isolated per session using a composite key pattern:
${sessionID}:${skillName}:${serverName}
This prevents state bleed across sessions when the same skill/MCP is used concurrently.
Background task concurrency defaults to 5 when no overrides are configured.
background_task.defaultConcurrency, background_task.providerConcurrency, and background_task.modelConcurrencyTeam mode is parallel multi-agent orchestration and is OFF by default.
For subagent_type team members, current eligibility is:
sisyphus, atlas, sisyphus-juniorhephaestus (requires teammate permission enablement)oracle, librarian, explore, multimodal-looker, metis, momus, prometheusWhy oracle/prometheus are rejected in team members:
.omo/*.md writes by the prometheus-md-only hookMethod 1: Switch to Prometheus Agent (Tab → Select Prometheus)
1. Press Tab at the prompt
2. Select "Prometheus" from the agent list
3. Describe your work: "I want to refactor the auth system"
4. Answer interview questions
5. Prometheus creates plan in .omo/plans/{name}.md
Method 2: Use @plan Command (in Sisyphus)
1. Stay in Sisyphus (default agent)
2. Type: @plan "I want to refactor the auth system"
3. The @plan command automatically switches to Prometheus
4. Answer interview questions
5. Prometheus creates plan in .omo/plans/{name}.md
Which Should You Use?
| Scenario | Recommended Method | Why |
|---|---|---|
| New session, starting fresh | Switch to Prometheus agent | Clean mental model - you're entering "planning mode" |
| Already in Sisyphus, mid-work | Use @plan | Convenient, no agent switch needed |
| Want explicit control | Switch to Prometheus agent | Clear separation of planning vs execution contexts |
| Quick planning interrupt | Use @plan | Fastest path from current context |
Both methods trigger the same Prometheus planning flow. The @plan command is simply a convenience shortcut.
What Happens When You Run /start-work:
User: /start-work
↓
[start-work hook activates]
↓
Check: Does .omo/boulder.json exist?
↓
├─ YES (existing work) → RESUME MODE
│ - Read the existing boulder state
│ - Calculate progress (checked vs unchecked boxes)
│ - Inject continuation prompt with remaining tasks
│ - Atlas continues where you left off
│
└─ NO (fresh start) → INIT MODE
- Find the most recent plan in .omo/plans/
- Create new boulder.json tracking this plan
- Switch session agent to Atlas
- Begin execution from task 1
Session Continuity Explained:
The boulder.json file tracks:
Example Timeline:
Monday 9:00 AM
└─ @plan "Build user authentication"
└─ Prometheus interviews and creates plan
└─ User: /start-work
└─ Atlas begins execution, creates boulder.json
└─ Task 1 complete, Task 2 in progress...
└─ [Session ends - computer crash, user logout, etc.]
Monday 2:00 PM (NEW SESSION)
└─ User opens new session (agent = Sisyphus by default)
└─ User: /start-work
└─ [start-work hook reads boulder.json]
└─ "Resuming 'Build user authentication' - 3 of 8 tasks complete"
└─ Atlas continues from Task 3 (no context lost)
Atlas is automatically activated when you run /start-work. You don't need to manually switch to Atlas.
Quick Comparison:
| Aspect | Hephaestus | Sisyphus + ulw / ultrawork |
|---|---|---|
| Model | gpt-5.6-sol (medium) when available, with gpt-5.6-sol (medium) only | claude-opus-4-8 / kimi-k3 / gpt-5.6-sol / glm-5 depending on setup |
| Approach | Autonomous deep worker | Keyword-activated ultrawork mode |
| Best For | Complex architectural work, deep reasoning | General complex tasks, "just do it" scenarios |
| Planning | Self-plans during execution | Uses Prometheus plans if available |
| Delegation | Heavy use of explore/librarian agents | Uses category-based delegation |
| Temperature | 0.1 | 0.1 |
When to Use Hephaestus:
Switch to Hephaestus (Tab → Select Hephaestus) when:
Deep architectural reasoning needed
Complex debugging requiring inference chains
Cross-domain knowledge synthesis
You specifically want GPT-native autonomous reasoning
When to Use Sisyphus + ulw:
Use the ulw keyword in Sisyphus when:
You want the agent to figure it out
Complex but well-scoped tasks
You're feeling lazy (officially supported use case)
You want to leverage existing plans
ulw mode can use itRecommendation:
ulw keyword in Sisyphus. It's the default path and works excellently for 90% of complex tasks.For mature projects, the safest default is not "make the best architecture." It is "make the smallest correct change that fits the architecture already here."
Use Prometheus first when a brownfield task could invite broad cleanup, rewrites, or speculative abstractions. Select Prometheus with the agent selector or /agent, then ask it to produce a constrained plan with explicit boundaries:
Fix <problem> in this existing codebase.
Preserve the current architecture and public behavior.
Use the smallest viable change.
Follow local patterns in <files or areas>.
Do not refactor, rename, reorganize, or clean up unrelated code.
List exact files in scope and exact verification commands.
Then run /start-work from that plan. Atlas will execute against the written scope instead of treating the task as an open-ended modernization pass.
Use ulw directly only when the target is already narrow:
ulw fix the null handling in packages/foo/src/bar.ts using the existing helper style. No unrelated cleanup.
Use Hephaestus when you deliberately want autonomous deep implementation or architectural exploration. If the job is "touch the old system without disturbing it," an explicit Prometheus plan provides written scope boundaries before Atlas starts execution.
You can control related features in oh-my-openagent.json:
{
"sisyphus_agent": {
"disabled": false, // Enable Atlas orchestration (default: false)
"planner_enabled": true, // Enable Prometheus (default: true)
"replace_plan": true, // Replace default plan agent with Prometheus (default: true)
},
// Hook settings (add to disable)
"disabled_hooks": [
// "start-work", // Disable execution trigger
// "prometheus-md-only" // Remove Prometheus write restrictions (not recommended)
],
}
Prometheus enters interview mode by default. It will ask you questions about your requirements. Answer them, then say "make it a plan" when ready.
Either:
.omo/plans/ → Create one with Prometheus first.omo/boulder.json and retryType exit or start a new session. Atlas is primarily entered via /start-work - you don't typically "switch to Atlas" manually.
Nothing functional. Both invoke Prometheus. @plan is a convenience command while switching agents is explicit control. Use whichever feels natural.
For most tasks: Type ulw in Sisyphus.
Use Hephaestus when: You need GPT-native reasoning for deep architectural work or complex debugging.