diff --git a/docs/migration-v2-to-v3.md b/docs/migration-v2-to-v3.md deleted file mode 100644 index 3ffcdf993..000000000 --- a/docs/migration-v2-to-v3.md +++ /dev/null @@ -1,450 +0,0 @@ -# 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)