diff --git a/docs/guide/orchestration.md b/docs/guide/orchestration.md index b3be73494..72fa18e1c 100644 --- a/docs/guide/orchestration.md +++ b/docs/guide/orchestration.md @@ -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
(Planner)
Claude Opus 4.6"] Metis[" Metis
(Consultant)
Claude Opus 4.6"] - Momus[" Momus
(Reviewer)
GPT-5.2"] + Momus[" Momus
(Reviewer)
GPT-5.4"] end - + subgraph Execution["Execution Layer (Orchestrator)"] - Orchestrator[" Atlas
(Conductor)
K2P5 (Kimi)"] + Orchestrator[" Atlas
(Conductor)
Claude Sonnet 4.6"] end - + subgraph Workers["Worker Layer (Specialized Agents)"] Junior[" Sisyphus-Junior
(Task Executor)
Claude Sonnet 4.6"] Oracle[" Oracle
(Architecture)
GPT-5.2"] Explore[" Explore
(Codebase Grep)
Grok Code"] - Librarian[" Librarian
(Docs/OSS)
GLM-4.7"] - Frontend[" Frontend
(UI/UX)
Gemini 3 Pro"] + Librarian[" Librarian
(Docs/OSS)
Gemini 3 Flash"] + Frontend[" Frontend
(UI/UX)
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