sapient/oh-my-openagent
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs(orchestration): align model tables with current runtime

Browse Source 
Ultraworked with [Sisyphus](https://github.com/code-yeongyu/oh-my-opencode)

Co-authored-by: Sisyphus <clio-agent@sisyphuslabs.ai>
This commit is contained in:
YeonGyu-Kim
2026-03-06 20:50:11 +09:00
parent 3ee974b966
commit 2b40d4e6f4
1 changed files with 77 additions and 71 deletions
Download Patch File Download Diff File Expand all files Collapse all files

148
docs/guide/orchestration.md
View File

@@ -6,11 +6,11 @@ Oh My OpenCode's orchestration system transforms a simple AI agent into a coordi
## 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. |
| 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:**
@@ -36,37 +36,37 @@ flowchart TB
User[(" User")]
Prometheus[" Prometheus<br/>(Planner)<br/>Claude Opus 4.6"]
Metis[" Metis<br/>(Consultant)<br/>Claude Opus 4.6"]
Momus[" Momus<br/>(Reviewer)<br/>GPT-5.2"]
Momus[" Momus<br/>(Reviewer)<br/>GPT-5.4"]
end
subgraph Execution["Execution Layer (Orchestrator)"]
Orchestrator[" Atlas<br/>(Conductor)<br/>K2P5 (Kimi)"]
Orchestrator[" Atlas<br/>(Conductor)<br/>Claude Sonnet 4.6"]
end
subgraph Workers["Worker Layer (Specialized Agents)"]
Junior[" Sisyphus-Junior<br/>(Task Executor)<br/>Claude Sonnet 4.6"]
Oracle[" Oracle<br/>(Architecture)<br/>GPT-5.2"]
Explore[" Explore<br/>(Codebase Grep)<br/>Grok Code"]
Librarian[" Librarian<br/>(Docs/OSS)<br/>GLM-4.7"]
Frontend[" Frontend<br/>(UI/UX)<br/>Gemini 3 Pro"]
Librarian[" Librarian<br/>(Docs/OSS)<br/>Gemini 3 Flash"]
Frontend[" Frontend<br/>(UI/UX)<br/>Gemini 3.1 Pro"]
end
User -->|"Describe work"| Prometheus
Prometheus -->|"Consult"| Metis
Prometheus -->|"Interview"| User
Prometheus -->|"Generate plan"| Plan[".sisyphus/plans/*.md"]
Plan -->|"High accuracy?"| Momus
Momus -->|"OKAY / REJECT"| Prometheus
User -->|"/start-work"| Orchestrator
Plan -->|"Read"| Orchestrator
Orchestrator -->|"task(category)"| Junior
Orchestrator -->|"task(agent)"| Oracle
Orchestrator -->|"task(agent)"| Explore
Orchestrator -->|"task(agent)"| Librarian
Orchestrator -->|"task(agent)"| Frontend
Junior -->|"Results + Learnings"| Orchestrator
Oracle -->|"Advice"| Orchestrator
Explore -->|"Code patterns"| Orchestrator
@@ -90,10 +90,10 @@ stateDiagram-v2
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?
@@ -102,17 +102,17 @@ stateDiagram-v2
Check: Technical approach decided?
Check: Test strategy confirmed?
}
PlanGeneration --> MetisConsult: Mandatory gap analysis
MetisConsult --> WritePlan: Incorporate findings
WritePlan --> HighAccuracyChoice: Present to user
HighAccuracyChoice --> MomusLoop: User wants high accuracy
HighAccuracyChoice --> Done: User accepts plan
MomusLoop --> WritePlan: REJECTED - fix issues
MomusLoop --> Done: OKAY - plan approved
Done --> [*]: Guide to /start-work
```
@@ -120,12 +120,12 @@ stateDiagram-v2
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?" |
| 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
@@ -153,6 +153,7 @@ For high-accuracy mode, Momus validates plans against four core criteria:
**The Momus Loop:**
Momus only says "OKAY" when:
- 100% of file references verified
- ≥80% of tasks have clear reference sources
- ≥90% of tasks have concrete acceptance criteria
@@ -179,25 +180,27 @@ flowchart LR
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
@@ -240,6 +243,7 @@ Junior is the workhorse that actually writes code. Key characteristics:
**Why Sonnet is Sufficient:**
Junior doesn't need to be the smartest - it needs to be reliable. With:
1. Detailed prompts from Atlas (50-200 lines)
2. Accumulated wisdom passed forward
3. Clear MUST DO / MUST NOT DO constraints
@@ -274,31 +278,31 @@ This "boulder pushing" mechanism is why the system is named after Sisyphus.
```typescript
// OLD: Model name creates distributional bias
task(agent="gpt-5.2", prompt="...") // Model knows its limitations
task(agent="claude-opus-4.6", prompt="...") // Different self-perception
task({ agent: "gpt-5.4", prompt: "..." }); // Model knows its limitations
task({ agent: "claude-opus-4.6", prompt: "..." }); // Different self-perception
```
**The Solution: Semantic Categories:**
```typescript
// 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: "ultrabrain", prompt: "..." }); // "Think strategically"
task({ category: "visual-engineering", prompt: "..." }); // "Design beautifully"
task({ category: "quick", prompt: "..." }); // "Just get it done fast"
```
### Built-in Categories
| Category | Model | When to Use |
|----------|-------|-------------|
| `visual-engineering` | Gemini 3 Pro | Frontend, UI/UX, design, styling, animation |
| `ultrabrain` | GPT-5.3 Codex (xhigh) | Deep logical reasoning, complex architecture decisions |
| `artistry` | Gemini 3 Pro (max) | Highly creative or artistic tasks, novel ideas |
| `quick` | Claude Haiku 4.5 | Trivial tasks - single file changes, typo fixes |
| `deep` | GPT-5.3 Codex (medium) | Goal-oriented autonomous problem-solving, thorough research |
| `unspecified-low` | Claude Sonnet 4.6 | Tasks that don't fit other categories, low effort |
| `unspecified-high` | Claude Opus 4.6 (max) | Tasks that don't fit other categories, high effort |
| `writing` | K2P5 (Kimi) | Documentation, prose, technical writing |
| Category | Model | When to Use |
| -------------------- | ---------------------- | ----------------------------------------------------------- |
| `visual-engineering` | Gemini 3.1 Pro | Frontend, UI/UX, design, styling, animation |
| `ultrabrain` | GPT-5.3 Codex (xhigh) | Deep logical reasoning, complex architecture decisions |
| `artistry` | Gemini 3.1 Pro (high) | Highly creative or artistic tasks, novel ideas |
| `quick` | Claude Haiku 4.5 | Trivial tasks - single file changes, typo fixes |
| `deep` | GPT-5.3 Codex (medium) | Goal-oriented autonomous problem-solving, thorough research |
| `unspecified-low` | Claude Sonnet 4.6 | Tasks that don't fit other categories, low effort |
| `unspecified-high` | GPT-5.4 (high) | Tasks that don't fit other categories, high effort |
| `writing` | Gemini 3 Flash | Documentation, prose, technical writing |
### Skills: Domain-Specific Instructions
@@ -307,16 +311,16 @@ Skills prepend specialized instructions to subagent prompts:
```typescript
// Category + Skill combination
task(
category="visual-engineering",
load_skills=["frontend-ui-ux"], // Adds UI/UX expertise
prompt="..."
)
(category = "visual-engineering"),
(load_skills = ["frontend-ui-ux"]), // Adds UI/UX expertise
(prompt = "..."),
);
task(
category="general",
load_skills=["playwright"], // Adds browser automation expertise
prompt="..."
)
(category = "general"),
(load_skills = ["playwright"]), // Adds browser automation expertise
(prompt = "..."),
);
```
---
@@ -347,12 +351,12 @@ task(
**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 |
| 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.
@@ -383,6 +387,7 @@ Check: Does .sisyphus/boulder.json exist?
**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
@@ -413,14 +418,14 @@ Atlas is automatically activated when you run `/start-work`. You don't need to m
**Quick Comparison:**
| Aspect | Hephaestus | Sisyphus + `ulw` / `ultrawork` |
|--------|-----------|-------------------------------|
| **Model** | GPT-5.3 Codex (medium reasoning) | Claude Opus 4.6 (your default) |
| **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 |
| Aspect | Hephaestus | Sisyphus + `ulw` / `ultrawork` |
| --------------- | ------------------------------------------ | ---------------------------------------------------- |
| **Model** | GPT-5.3 Codex (medium reasoning) | Claude Opus 4.6 / GPT-5.4 / 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:**
@@ -475,16 +480,16 @@ You can control related features in `oh-my-opencode.json`:
```jsonc
{
"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)
"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)
]
],
}
```
@@ -499,6 +504,7 @@ Prometheus enters interview mode by default. It will ask you questions about you
### "/start-work says 'no active plan found'"
Either:
- No plans exist in `.sisyphus/plans/` → Create one with Prometheus first
- Plans exist but boulder.json points elsewhere → Delete `.sisyphus/boulder.json` and retry