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

Revert "docs: add v2.x to v3.x migration guide (#1057)"

Browse Source 
This PR was incorrectly merged by AI agent without proper project owner review.

This reverts commit 1cb6b3de39a49acb43b76ac55a5b44b47ca4a9f7.
This commit is contained in:
justsisyphus
2026-01-27 14:09:30 +09:00
parent 7dedd6cf90
commit 655d511294
1 changed files with 0 additions and 450 deletions
Download Patch File Download Diff File Expand all files Collapse all files

450
docs/migration-v2-to-v3.md
View File

@@ -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)