This document provides a comprehensive guide to the orchestration system that implements Oh-My-OpenCode's core philosophy: **"Separation of Planning and Execution"**.
## 1. Overview
Traditional AI agents often mix planning and execution, leading to context pollution, goal drift, and AI slop (low-quality code).
Oh-My-OpenCode solves this by clearly separating two roles:
1.**Prometheus (Planner)**: A pure strategist who never writes code. Establishes perfect plans through interviews and analysis.
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?**
- 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.
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.
