Orchestration System Guide

Oh My OpenAgent's orchestration system transforms a simple AI agent into a coordinated development team through separation of planning and execution.

TL;DR - When to Use What

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 Architecture

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<br/>(Planner)<br/>claude-opus-4-7 / gpt-5.5 / glm-5.2"]
        Metis[" Metis<br/>(Consultant)<br/>claude-sonnet-4-6 / claude-opus-4-7 / gpt-5.5 / glm-5.2"]
        Momus[" Momus<br/>(Reviewer)<br/>gpt-5.6-terra / gpt-5.5 / claude-opus-4-7 / gemini-3.1-pro / glm-5.2"]
    end

    subgraph Execution["Execution Layer (Orchestrator)"]
        Orchestrator[" Atlas<br/>(Conductor)<br/>claude-sonnet-4-6 / kimi-k2.6 / gpt-5.5 / minimax-m3 / minimax-m2.7"]
    end

    subgraph Workers["Worker Layer (Specialized Agents)"]
        Junior[" Sisyphus-Junior<br/>(Task Executor)<br/>claude-sonnet-4-6 / kimi-k2.6 / gpt-5.5 / minimax-m3 / minimax-m2.7"]
        Oracle[" Oracle<br/>(Architecture)<br/>gpt-5.5 / gemini-3.1-pro / claude-opus-4-7 / glm-5.2"]
        Explore[" Explore<br/>(Codebase Grep)<br/>gpt-5.4-mini-fast / minimax-m2.7-highspeed / minimax-m3 / claude-haiku-4-5"]
        Librarian[" Librarian<br/>(Docs/OSS)<br/>gpt-5.4-mini-fast / minimax-m2.7-highspeed / minimax-m3 / claude-haiku-4-5"]
        Frontend[" visual-engineering<br/>(category + frontend)<br/>gemini-3.1-pro / glm-5 / claude-opus-4-7"]
    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.

Agent Inventory and Modes (Current)

The system has 11 built-in agents:

Primary: sisyphus, hephaestus, prometheus, atlas
Subagent: oracle, librarian, explore, multimodal-looker, metis, momus, sisyphus-junior

Canonical assembly order for primary agents is:

Sisyphus → Hephaestus → Prometheus → Atlas

Mode distinction:

mode: "primary": top-level session agents selected directly in UI/CLI
mode: "subagent": worker/consultant agents invoked via task(..., subagent_type="...") or call_omo_agent(...)

Display Names vs Providers

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:

Agent display name: Sisyphus - ultraworker, Atlas - Plan Executor, Hephaestus - Deep Agent
Provider namespace: anthropic, openai, github-copilot, opencode, opencode-go, vercel
Model id: claude-opus-4-7, kimi-k2.6, gpt-5.5, glm-5

The 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-k2.6, 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.

Delegation Semantics (Important)

task(category="...") routes to Sisyphus-Junior with category-optimized model routing
task(subagent_type="...") invokes that specific agent directly (for example oracle, explore, librarian)
Category and subagent_type are mutually exclusive inputs in one call

Planning: Prometheus + Metis + Momus + Oracle

Prometheus: Your Strategic Consultant

Prometheus 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?"

Metis: The Gap Analyzer

Before Prometheus writes the plan, Metis catches what Prometheus missed:

Hidden intentions in user's request
Ambiguities that could derail implementation
AI-slop patterns (over-engineering, scope creep)
Missing acceptance criteria
Edge cases not addressed

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 Review: Momus + Oracle

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:

Referenced files exist and support the plan's claims
Every task gives a developer a usable starting point
Tasks do not contradict each other
QA scenarios name the tool, steps, and expected result
No missing information would completely stop execution

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.

Where to Spend a Scarce Premium Model

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.

Execution: Atlas

The Conductor Mindset

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:

Read files to understand context
Run commands to verify results
Use lsp_diagnostics to check for errors
Search patterns with grep/glob/ast-grep

What Atlas MUST delegate:

Writing or editing code files
Fixing bugs
Creating tests
Git commits

Wisdom Accumulation

The power of orchestration is cumulative learning. After each task:

Extract learnings from subagent's response
Categorize into: Conventions, Successes, Failures, Gotchas, Commands
Pass forward to ALL subsequent subagents

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

Workers: Sisyphus-Junior and Specialists

Sisyphus-Junior: The Task Executor

Junior is the workhorse that actually writes code. Key characteristics:

Focused: Cannot delegate (blocked from task tool)
Disciplined: Obsessive todo tracking
Verified: Must pass lsp_diagnostics before completion
Constrained: Cannot modify plan files (READ-ONLY)

Why the fallback chain is sufficient:

Junior doesn't need to be the smartest - it needs to be reliable. With:

Detailed prompts from Atlas (50-200 lines)
Accumulated wisdom passed forward
Clear MUST DO / MUST NOT DO constraints
Verification requirements

Even a mid-tier execution model works when the harness is strict. The current fallback order is claude-sonnet-4-6 → kimi-k2.6 → gpt-5.5 → minimax-m3 → minimax-m2.7 → big-pickle. The intelligence is in the system, not a single worker model.

System Reminder Mechanism

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.

Category + Skill System

Why Categories are Revolutionary

The Problem with Model Names:

// OLD: Model name creates distributional bias
task({ agent: "gpt-5.5", prompt: "..." }); // Model knows its limitations
task({ agent: "claude-opus-4-7", 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"

Delegate-Task Categories

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:

Built-in defaults are defined in packages/omo-opencode/src/tools/delegate-task/*-categories.ts and packages/omo-opencode/src/shared/model-requirements.ts
Projects/users can extend categories via config; additional category names may appear in your session prompt
Regardless of category name, category dispatch goes through Sisyphus-Junior

Skills: Domain-Specific Instructions

Skills 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 MCP (Tier 3)

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

Background task concurrency defaults to 5 when no overrides are configured.

Keyed by model/provider routing key
Configurable via background_task.defaultConcurrency, background_task.providerConcurrency, and background_task.modelConcurrency

Team Mode

Team mode is parallel multi-agent orchestration and is OFF by default.

For subagent_type team members, current eligibility is:

Eligible: sisyphus, atlas, sisyphus-junior
Conditional: hephaestus (requires teammate permission enablement)
Hard-reject: oracle, librarian, explore, multimodal-looker, metis, momus, prometheus

Why oracle/prometheus are rejected in team members:

Oracle is read-only (cannot write/edit/patch/delegate)
Prometheus is constrained to .omo/*.md writes by the prometheus-md-only hook

Usage Patterns

How to Invoke Prometheus

Method 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.

/start-work Behavior and Session Continuity

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:

active_plan: Path to the current plan file
session_ids: All sessions that have worked on this plan
started_at: When work began
plan_name: Human-readable plan identifier

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.

Hephaestus vs Sisyphus + ultrawork

Quick Comparison:

Aspect	Hephaestus	Sisyphus + `ulw` / `ultrawork`
Model	`gpt-5.6-sol` (`medium`) when available, then `gpt-5.5` (`medium`)	`claude-opus-4-7` / `kimi-k2.6` / `gpt-5.5` / `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
- "Design a new plugin system"
- "Refactor this monolith into microservices"
Complex debugging requiring inference chains
- "Why does this race condition only happen on Tuesdays?"
- "Trace this memory leak through 15 files"
Cross-domain knowledge synthesis
- "Integrate our Rust core with the TypeScript frontend"
- "Migrate from MongoDB to PostgreSQL with zero downtime"
You specifically want GPT-native autonomous reasoning
- Hephaestus prefers GPT-5.6 Sol when OpenAI or Vercel exposes it and retains GPT-5.5 as the broad fallback

When to Use Sisyphus + ulw:

Use the ulw keyword in Sisyphus when:

You want the agent to figure it out
- "ulw fix the failing tests"
- "ulw add input validation to the API"
Complex but well-scoped tasks
- "ulw implement JWT authentication following our patterns"
- "ulw create a new CLI command for deployments"
You're feeling lazy (officially supported use case)
- Don't want to write detailed requirements
- Trust the agent to explore and decide
You want to leverage existing plans
- If a Prometheus plan exists, ulw mode can use it
- Falls back to autonomous exploration if no plan

Recommendation:

For most users: Use ulw keyword in Sisyphus. It's the default path and works excellently for 90% of complex tasks.
For power users: Switch to Hephaestus when you want GPT-native reasoning or the "AmpCode deep mode" experience of fully autonomous exploration and execution.

Brownfield / KISS Mode

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.

Configuration

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)
  ],
}

Troubleshooting

"I switched to Prometheus but nothing happened"

Prometheus enters interview mode by default. It will ask you questions about your requirements. Answer them, then say "make it a plan" when ready.

"/start-work says 'no active plan found'"

Either:

No plans exist in .omo/plans/ → Create one with Prometheus first
Plans exist but boulder.json points elsewhere → Delete .omo/boulder.json and retry

"I'm in Atlas but I want to switch back to normal mode"

Type exit or start a new session. Atlas is primarily entered via /start-work - you don't typically "switch to Atlas" manually.

"What's the difference between @plan and just switching to Prometheus?"

Nothing functional. Both invoke Prometheus. @plan is a convenience command while switching agents is explicit control. Use whichever feels natural.

"Should I use Hephaestus or type ulw?"

For most tasks: Type ulw in Sisyphus.

Use Hephaestus when: You need GPT-native reasoning for deep architectural work or complex debugging.

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Orchestration System Guide

TL;DR - When to Use What

The Architecture

Agent Inventory and Modes (Current)

Display Names vs Providers

Delegation Semantics (Important)

Planning: Prometheus + Metis + Momus + Oracle

Prometheus: Your Strategic Consultant

Metis: The Gap Analyzer

High-Accuracy Review: Momus + Oracle

Where to Spend a Scarce Premium Model

Execution: Atlas

The Conductor Mindset

Wisdom Accumulation

Workers: Sisyphus-Junior and Specialists

Sisyphus-Junior: The Task Executor

System Reminder Mechanism

Category + Skill System

Why Categories are Revolutionary

Delegate-Task Categories

Skills: Domain-Specific Instructions

Skill MCP (Tier 3)

Background Task Concurrency

Team Mode

Usage Patterns

How to Invoke Prometheus

/start-work Behavior and Session Continuity

Hephaestus vs Sisyphus + ultrawork

Brownfield / KISS Mode

Configuration

Troubleshooting

"I switched to Prometheus but nothing happened"

"/start-work says 'no active plan found'"

"I'm in Atlas but I want to switch back to normal mode"

"What's the difference between @plan and just switching to Prometheus?"

"Should I use Hephaestus or type ulw?"

Further Reading

FilesExpand file tree

orchestration.md

Latest commit

History

orchestration.md

File metadata and controls

Orchestration System Guide

TL;DR - When to Use What

The Architecture

Agent Inventory and Modes (Current)

Display Names vs Providers

Delegation Semantics (Important)

Planning: Prometheus + Metis + Momus + Oracle

Prometheus: Your Strategic Consultant

Metis: The Gap Analyzer

High-Accuracy Review: Momus + Oracle

Where to Spend a Scarce Premium Model

Execution: Atlas

The Conductor Mindset

Wisdom Accumulation

Workers: Sisyphus-Junior and Specialists

Sisyphus-Junior: The Task Executor

System Reminder Mechanism

Category + Skill System

Why Categories are Revolutionary

Delegate-Task Categories

Skills: Domain-Specific Instructions

Skill MCP (Tier 3)

Background Task Concurrency

Team Mode

Usage Patterns

How to Invoke Prometheus

/start-work Behavior and Session Continuity

Hephaestus vs Sisyphus + ultrawork

Brownfield / KISS Mode

Configuration

Troubleshooting

"I switched to Prometheus but nothing happened"

"/start-work says 'no active plan found'"

"I'm in Atlas but I want to switch back to normal mode"

"What's the difference between @plan and just switching to Prometheus?"

"Should I use Hephaestus or type ulw?"

Further Reading