From 1cb6b3de7d76df0a55796e85fed34bec1fd529f7 Mon Sep 17 00:00:00 2001 From: Sisyphus Date: Tue, 27 Jan 2026 11:59:15 +0900 Subject: [PATCH] docs: add v2.x to v3.x migration guide (#1057) Comprehensive migration guide covering: - TL;DR quick upgrade section for most users - What's new in v3.x (Atlas, Prometheus, categories, skills) - Breaking changes checklist (high/medium/low impact) - Step-by-step upgrade path - Configuration changes (categories, permissions) - API changes for plugin developers - Troubleshooting common issues - Complete agent and category reference Consulted Oracle for migration guide strategy and structure. Closes #1034 (item 4) Co-authored-by: sisyphus-dev-ai --- docs/migration-v2-to-v3.md | 450 +++++++++++++++++++++++++++++++++++++ 1 file changed, 450 insertions(+) create mode 100644 docs/migration-v2-to-v3.md diff --git a/docs/migration-v2-to-v3.md b/docs/migration-v2-to-v3.md new file mode 100644 index 00000000..3ffcdf99 --- /dev/null +++ b/docs/migration-v2-to-v3.md @@ -0,0 +1,450 @@ +# Migrating from v2.x to v3.x + +v3 brings the Titans. Atlas holds your workflow together. Prometheus plans before you code. Your Sisyphus now has a team. + +## TL;DR: Upgrade in 60 Seconds + +**For most users**: Just update. Your config probably works. + +```bash +bunx oh-my-opencode@3 install +``` + +**Must check**: +- [ ] Agent names in custom code are lowercase (`sisyphus-junior` not `Sisyphus-Junior`) +- [ ] `disabled_hooks` array is updated if you reference old hook names +- [ ] Custom `delegate_task` calls use `category` + `skills` (new preferred method) + +**Works unchanged**: All existing config files, Claude Code compatibility, MCPs. + +**New toys**: Atlas orchestrator, Prometheus planner, category-based delegation, skill injection. + +--- + +## What's New in v3 (The Good Stuff) + +| Feature | Description | Why Care | +|---------|-------------|----------| +| **Atlas Orchestrator** | Master orchestrator that coordinates complex multi-agent workflows | Your agents now have a traffic controller | +| **Prometheus Planner** | Strategic planning with interview mode, creates detailed work plans | Better planning = fewer wrong turns | +| **Metis + Momus** | Plan consultant (pre-planning) + reviewer (validation) | Plans get vetted before execution | +| **Category System** | `delegate_task(category="visual-engineering")` routes to optimal model | Right model for the job, automatically | +| **Skills Injection** | `delegate_task(skills=["git-master"])` adds specialized knowledge | Agents learn new tricks on demand | +| **Model Resolution** | 3-step fallback: User Override -> Provider Chain -> System Default | Always gets a working model | +| **10 New Hooks** | atlas, delegate-task-retry, prometheus-md-only, and more | More control points | + +--- + +## Breaking Changes Checklist + +### High Impact (Will break things) + +- [ ] **Agent names are lowercase in API calls** + + ```typescript + // v2.x - Mixed case worked + delegate_task({ agent: "Sisyphus-Junior", prompt: "..." }) + + // v3.x - Must be lowercase + delegate_task({ agent: "sisyphus-junior", prompt: "..." }) + ``` + + **Affects**: Custom tools, scripts calling agents by name + **Fix**: Find/replace in your codebase + +- [ ] **Removed agents** + + | Removed Agent | Migration Path | + |---------------|----------------| + | `document-writer` | Use `delegate_task(category="writing")` | + | `frontend-ui-ux-engineer` | Use `delegate_task(category="visual-engineering", skills=["frontend-ui-ux"])` | + +### Medium Impact (May affect advanced users) + +- [ ] **Category system is primary delegation method** + + ```typescript + // v2.x style (still works) + delegate_task({ agent: "oracle", prompt: "..." }) + + // v3.x preferred style + delegate_task({ + category: "ultrabrain", + skills: ["git-master"], + prompt: "..." + }) + ``` + +- [ ] **Hook renames** + + | v2.x Name | v3.x Name | + |-----------|-----------| + | `anthropic-auto-compact` | `anthropic-context-window-limit-recovery` | + | `sisyphus-orchestrator` | `atlas` | + +- [ ] **Removed hooks** (will be filtered out automatically) + + | Removed Hook | Reason | + |--------------|--------| + | `preemptive-compaction` | Replaced by `anthropic-context-window-limit-recovery` | + | `empty-message-sanitizer` | Functionality integrated elsewhere | + +### Low Impact (Mostly additive) + +- [ ] **10 new hooks added** - none renamed or removed + - New: atlas, delegate-task-retry, prometheus-md-only, compaction-context-injector, start-work, background-notification, task-resume-info, and more + - **Action**: Review if you want to disable any + +- [ ] **New built-in skills** + - `playwright` - Browser automation + - `frontend-ui-ux` - UI/UX design patterns + - `git-master` - Advanced git operations + - **Disable if unwanted**: `"disabled_skills": ["frontend-ui-ux"]` + +--- + +## Upgrade Path + +### Standard Upgrade (Recommended) + +1. **Backup your config** (optional but wise) + ```bash + cp ~/.config/opencode/oh-my-opencode.json ~/.config/opencode/oh-my-opencode.json.v2-backup + ``` + +2. **Update the package** + ```bash + bunx oh-my-opencode@3 install + ``` + +3. **Run doctor** + ```bash + bunx oh-my-opencode doctor --verbose + ``` + +4. **Test with a simple task** + ``` + ulw fix a typo in README + ``` + +### Fresh Install (Nuclear option) + +1. **Remove old config** + ```bash + rm -rf ~/.config/opencode/oh-my-opencode.json + rm -rf .opencode/oh-my-opencode.json + ``` + +2. **Run installer** + ```bash + bunx oh-my-opencode@3 install + ``` + +--- + +## Configuration Changes + +### New: Category-Based Configuration + +v3.x introduces **categories** for semantic task delegation instead of hardcoded agent names. + +**Available Categories:** +- `visual-engineering` - UI/UX work (default: Gemini 3 Pro) +- `ultrabrain` - Complex reasoning (default: GPT-5.2) +- `artistry` - Creative work +- `quick` - Fast/cheap tasks (default: GPT-5-nano) +- `unspecified-high` - High capability (default: Claude Opus 4.5) +- `unspecified-low` - Low capability (default: Claude Sonnet 4.5) +- `writing` - Content creation + +**v2.x Pattern (Direct Agent Calls):** +```jsonc +{ + "agents": { + "document-writer": { "model": "anthropic/claude-opus-4-5" }, + "frontend-ui-ux-engineer": { "model": "google/gemini-3-pro" } + } +} +``` + +**v3.x Pattern (Category-Based):** +```jsonc +{ + "categories": { + "writing": { "model": "anthropic/claude-opus-4-5" }, + "visual-engineering": { "model": "google/gemini-3-pro" } + } +} +``` + +### New Config Options + +| Option | Type | Default | Description | +|--------|------|---------|-------------| +| `categories` | object | built-in defaults | Category-based delegation config | +| `categories.*.model` | string | varies | Model for category | +| `categories.*.skills` | string[] | [] | Auto-inject skills | +| `agents.*.category` | string | - | Inherit from category config | +| `agents.*.skills` | string[] | [] | Inject skills into agent | +| `disabled_skills` | string[] | [] | Disable built-in skills | + +### Config File Example (v3) + +```jsonc +{ + "$schema": "https://raw.githubusercontent.com/code-yeongyu/oh-my-opencode/master/assets/oh-my-opencode.schema.json", + + // NEW: Category-based model routing + "categories": { + "visual-engineering": { "model": "google/gemini-3-pro" }, + "ultrabrain": { "model": "openai/gpt-5.2-codex" }, + "quick": { "model": "anthropic/claude-haiku-4-5" } + }, + + // NEW: Skills can be injected into agents + "agents": { + "sisyphus-junior": { + "skills": ["git-master"] // Always has git expertise + } + }, + + // UNCHANGED: These still work exactly the same + "disabled_hooks": ["comment-checker"], + "disabled_mcps": ["websearch"], + "disabled_agents": ["multimodal-looker"] +} +``` + +### Tools to Permissions Migration + +v3.x replaces the `tools` format with `permission`. + +**v2.x (Legacy):** +```jsonc +{ + "agents": { + "explore": { + "tools": { + "edit": false, + "bash": false + } + } + } +} +``` + +**v3.x (Permission-Based):** +```jsonc +{ + "agents": { + "explore": { + "permission": { + "edit": "deny", + "bash": "deny", + "webfetch": "allow" + } + } + } +} +``` + +**Permission Values:** +- `ask` - Prompt user for each use +- `allow` - Always allow +- `deny` - Always deny + +--- + +## API Changes for Plugin Developers + +### Agent Name Normalization + +All agent names are lowercase in API calls. Internal lookup is case-insensitive, but the string you pass must match the normalized form. + +```typescript +// v2.x - Mixed case worked +await callAgent("Sisyphus-Junior", { prompt: "..." }) + +// v3.x - Must be lowercase +await callAgent("sisyphus-junior", { prompt: "..." }) +``` + +### delegate_task Changes + +```typescript +// v2.x signature (still works) +delegate_task({ + agent: "oracle", + prompt: "Review this code" +}) + +// v3.x preferred signature +delegate_task({ + category: "ultrabrain", // NEW: Route by category + skills: ["git-master"], // NEW: Inject skills + prompt: "Review this code", + run_in_background: false +}) +``` + +### New Type Definitions + +```typescript +// AgentOverrideConfigSchema additions +{ + category?: string // NEW: Inherit from category + skills?: string[] // NEW: Inject skills +} + +// New CategoryConfigSchema +{ + model?: string + variant?: string + temperature?: number + thinking?: { type: "enabled" | "disabled", budgetTokens?: number } + // ... +} +``` + +--- + +## Troubleshooting + +### "Agent not found: Sisyphus-Junior" + +**Cause**: Agent names are now lowercase. +**Fix**: Use `sisyphus-junior` instead of `Sisyphus-Junior`. + +### "Category 'business-logic' not found" + +**Cause**: Category was renamed in v3. +**Fix**: Use `ultrabrain` for strategic/architecture tasks. + +### "Model resolution failed" + +**Cause**: No provider available for required model. +**Fix**: +1. Run `bunx oh-my-opencode doctor --verbose` +2. Check "Model Resolution" section +3. Either configure the missing provider or override the model + +### Agents behaving differently + +**Cause**: New orchestration layer (Atlas) changes agent coordination. +**Fix**: +- If you want v2 behavior: `"disabled_hooks": ["atlas"]` +- If Atlas is too aggressive: Adjust via `sisyphus_agent` config + +### Performance regression + +**Cause**: New hooks add overhead. +**Fix**: Disable non-critical hooks: +```jsonc +{ + "disabled_hooks": [ + "agent-usage-reminder", + "auto-update-checker", + "background-notification" + ] +} +``` + +--- + +## Migration Checklist + +### Step 1: Update Dependencies +```bash +bunx oh-my-opencode@3 install +``` + +### Step 2: Check Agent Names +Search your codebase for uppercase agent names and convert to lowercase. + +### Step 3: Update Configuration + +```jsonc +// BEFORE (V2.x) +{ + "agents": { + "document-writer": { "model": "anthropic/claude-opus-4-5" } + }, + "disabled_hooks": ["anthropic-auto-compact", "sisyphus-orchestrator"] +} + +// AFTER (V3.x) +{ + "categories": { + "writing": { "model": "anthropic/claude-opus-4-5" } + }, + "disabled_hooks": ["anthropic-context-window-limit-recovery", "atlas"] +} +``` + +### Step 4: Update Tools to Permissions +```jsonc +// BEFORE +"tools": { "edit": false, "bash": false } + +// AFTER +"permission": { "edit": "deny", "bash": "deny" } +``` + +### Step 5: Verify +```bash +bunx oh-my-opencode doctor +``` + +--- + +## Automatic Migration + +v3.x automatically handles most changes: + +- Agent name renames (case-insensitive) +- Hook name renames +- Config file backup creation +- Removed hooks filtering + +**Manual steps required:** +- Remove `document-writer` and `frontend-ui-ux-engineer` agents +- Convert `model` to `category` in agent configs (optional, old style still works) +- Convert `tools` to `permission` format +- Remove `google_auth` config option (use external plugin) + +--- + +## Reference: Complete Agent List + +### v3.x Built-in Agents +``` +sisyphus - Main orchestrator (was: Sisyphus, OmO) +prometheus - Planner (was: Prometheus (Planner), OmO-Plan) +atlas - Orchestrator (was: orchestrator-sisyphus) +sisyphus-junior - Focused executor +metis - Plan consultant (was: Metis (Plan Consultant)) +momus - Plan reviewer (was: Momus (Plan Reviewer)) +oracle - Debugging & architecture +librarian - Docs & code search +explore - Fast codebase grep +multimodal-looker - Image/PDF analysis +``` + +### v3.x Built-in Categories +``` +visual-engineering - UI/UX work +ultrabrain - Complex reasoning +artistry - Creative work +quick - Fast/cheap tasks +unspecified-high - High capability +unspecified-low - Low capability +writing - Content creation +``` + +--- + +## Need Help? + +- [Full v3 Documentation](./configurations.md) +- [Discord Community](https://discord.gg/PUwSMR9XNk) +- [Report Migration Issues](https://github.com/code-yeongyu/oh-my-opencode/issues)