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

docs: clarify Prometheus invocation workflow (#1466)

Browse Source
This commit is contained in:
YeonGyu-Kim
2026-02-04 11:25:46 +09:00
committed by GitHub
parent 6a66bfccec
commit c57c0a6bcb
1 changed files with 272 additions and 12 deletions
Download Patch File Download Diff File Expand all files Collapse all files

284
docs/orchestration-guide.md
View File

@@ -35,7 +35,216 @@ Oh-My-OpenCode solves this by clearly separating two roles:
---
## 2. Overall Architecture
## 2. Prometheus Invocation: Agent Switch vs @plan
A common source of confusion is how to invoke Prometheus for planning. **Both methods achieve the same result** - use whichever feels natural.
### 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 .sisyphus/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 .sisyphus/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 |
**Key Insight**: Both methods trigger the same Prometheus planning flow. The @plan command is simply a convenience shortcut that:
1. Detects the `@plan` keyword in your message
2. Routes the request to Prometheus automatically
3. Returns you to Sisyphus after planning completes
---
## 3. /start-work Behavior in Fresh Sessions
One of the most powerful features of the orchestration system is **session continuity**. Understanding how `/start-work` behaves across sessions prevents confusion.
### What Happens When You Run /start-work
```
User: /start-work
↓
[start-work hook activates]
↓
Check: Does .sisyphus/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 .sisyphus/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)
```
### When You DON'T Need to Manually Switch to Atlas
Atlas is **automatically activated** when you run `/start-work`. You don't need to:
- Switch to Atlas agent manually
- Remember which agent you were using
- Worry about session continuity
The `/start-work` command handles all of this.
### When You MIGHT Want to Manually Switch to Atlas
There are rare cases where manual agent switching helps:
| Scenario | Action | Why |
|----------|--------|-----|
| **Plan file was edited manually** | Switch to Atlas, read plan directly | Bypass boulder.json resume logic |
| **Debugging orchestration issues** | Switch to Atlas for visibility | See Atlas-specific system prompts |
| **Force fresh execution** | Delete boulder.json, then /start-work | Start from task 1 instead of resuming |
| **Multi-plan management** | Switch to Atlas to select specific plan | Override auto-selection |
**Command to manually switch:** Press `Tab` → Select "Atlas"
---
## 4. Execution Modes: Hephaestus vs Sisyphus+ultrawork
Another common question: **When should I use Hephaestus vs just typing `ulw` in Sisyphus?**
### Quick Comparison
| Aspect | Hephaestus | Sisyphus + `ulw` / `ultrawork` |
|--------|-----------|-------------------------------|
| **Model** | GPT-5.2 Codex (medium reasoning) | Claude Opus 4.5 (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 |
### When to Use Hephaestus
Switch to Hephaestus (Tab → Select Hephaestus) when:
1. **Deep architectural reasoning needed**
- "Design a new plugin system"
- "Refactor this monolith into microservices"
2. **Complex debugging requiring inference chains**
- "Why does this race condition only happen on Tuesdays?"
- "Trace this memory leak through 15 files"
3. **Cross-domain knowledge synthesis**
- "Integrate our Rust core with the TypeScript frontend"
- "Migrate from MongoDB to PostgreSQL with zero downtime"
4. **You specifically want GPT-5.2 Codex reasoning**
- Some problems benefit from GPT-5.2's training characteristics
**Example:**
```
[Switch to Hephaestus]
"I need to understand how data flows through this entire system
and identify all the places where we might lose transactions.
Explore thoroughly before proposing fixes."
```
### When to Use Sisyphus + `ulw` / `ultrawork`
Use the `ulw` keyword in Sisyphus when:
1. **You want the agent to figure it out**
- "ulw fix the failing tests"
- "ulw add input validation to the API"
2. **Complex but well-scoped tasks**
- "ulw implement JWT authentication following our patterns"
- "ulw create a new CLI command for deployments"
3. **You're feeling lazy** (officially supported use case)
- Don't want to write detailed requirements
- Trust the agent to explore and decide
4. **You want to leverage existing plans**
- If a Prometheus plan exists, `ulw` mode can use it
- Falls back to autonomous exploration if no plan
**Example:**
```
[Stay in Sisyphus]
"ulw refactor the user service to use the new repository pattern"
[Agent automatically:]
- Explores existing codebase patterns
- Implements the refactor
- Runs verification (tests, typecheck)
- Reports completion
```
### Key Difference in Practice
| Hephaestus | Sisyphus + ulw |
|------------|----------------|
| You manually switch to Hephaestus agent | You type `ulw` in any Sisyphus session |
| GPT-5.2 Codex with medium reasoning | Your configured default model |
| Optimized for autonomous deep work | Optimized for general execution |
| Always uses explore-first approach | Respects existing plans if available |
| "Smart intern that needs no supervision" | "Smart intern that follows your workflow" |
### 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 specifically need GPT-5.2 Codex's reasoning style or want the "AmpCode deep mode" experience of fully autonomous exploration and execution.
---
## 5. Overall Architecture
```mermaid
flowchart TD
@@ -62,7 +271,7 @@ flowchart TD
---
## 3. Key Components
## 6. Key Components
### 🔮 Prometheus (The Planner)
@@ -85,13 +294,13 @@ flowchart TD
### ⚡ Atlas (The Plan Executor)
- **Model**: `anthropic/claude-opus-4-5` (Extended Thinking 32k)
- **Model**: `anthropic/claude-sonnet-4-5` (Extended Thinking 32k)
- **Role**: Execution and delegation
- **Characteristic**: Doesn't do everything directly, actively delegates to specialized agents (Frontend, Librarian, etc.).
---
## 4. Workflow
## 7. Workflow
### Phase 1: Interview and Planning (Interview Mode)
@@ -113,31 +322,44 @@ When the user requests "Make it a plan", plan generation begins.
When the user enters `/start-work`, the execution phase begins.
1. **State Management**: Creates `boulder.json` file to track current plan and session ID.
1. **State Management**: Creates/reads `boulder.json` file to track current plan and session ID.
2. **Task Execution**: Atlas reads the plan and processes TODOs one by one.
3. **Delegation**: UI work is delegated to Frontend agent, complex logic to Oracle.
4. **Continuity**: Even if the session is interrupted, work continues in the next session through `boulder.json`.
---
## 5. Commands and Usage
## 8. Commands and Usage
### `@plan [request]`
Invokes Prometheus to start a planning session.
Invokes Prometheus to start a planning session from Sisyphus.
- Example: `@plan "I want to refactor the authentication system to NextAuth"`
- Effect: Routes to Prometheus, then returns to Sisyphus when planning completes
### `/start-work`
Executes the generated plan.
- Function: Finds plan in `.sisyphus/plans/` and enters execution mode.
- If there's interrupted work, automatically resumes from where it left off.
- **Fresh session**: Finds plan in `.sisyphus/plans/` and enters execution mode
- **Existing boulder**: Resumes from where you left off (reads boulder.json)
- **Effect**: Automatically switches to Atlas agent if not already active
### Switching Agents Manually
Press `Tab` at the prompt to see available agents:
| Agent | When to Switch |
|-------|---------------|
| **Prometheus** | You want to create a detailed work plan |
| **Atlas** | You want to manually control plan execution (rare) |
| **Hephaestus** | You need GPT-5.2 Codex for deep autonomous work |
| **Sisyphus** | Return to default agent for normal prompting |
---
## 6. Configuration Guide
## 9. Configuration Guide
You can control related features in `oh-my-opencode.json`.
@@ -157,8 +379,46 @@ You can control related features in `oh-my-opencode.json`.
}
```
## 7. Best Practices
---
## 10. Best Practices
1. **Don't Rush Planning**: Invest sufficient time in the interview with Prometheus. The more perfect the plan, the faster the execution.
1. **Don't Rush**: Invest sufficient time in the interview with Prometheus. The more perfect the plan, the faster the execution.
2. **Single Plan Principle**: No matter how large the task, contain all TODOs in one plan file (`.md`). This prevents context fragmentation.
3. **Active Delegation**: During execution, delegate to specialized agents via `delegate_task` rather than modifying code directly.
4. **Trust /start-work Continuity**: Don't worry about session interruptions. `/start-work` will always resume your work from boulder.json.
5. **Use `ulw` for Convenience**: When in doubt, type `ulw` and let the system figure out the best approach.
6. **Reserve Hephaestus for Deep Work**: Don't overthink agent selection. Hephaestus shines for genuinely complex architectural challenges.
---
## 11. Troubleshooting Common Confusions
### "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 `.sisyphus/plans/` → Create one with Prometheus first
- Plans exist but boulder.json points elsewhere → Delete `.sisyphus/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 specifically need GPT-5.2 Codex's reasoning style for deep architectural work or complex debugging.