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?**
**For power users**: Switch to Hephaestus when you specifically need GPT-5.3 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.
