Skip to content
This repository was archived by the owner on Jun 9, 2026. It is now read-only.

UPGRADE.md

Latest commit

 

History

History
229 lines (160 loc) · 5.1 KB

UPGRADE.md

File metadata and controls

229 lines (160 loc) · 5.1 KB
Raw

Upgrading to PAI-OpenCode v3.0

Migration guide for v2.x users

Overview

PAI-OpenCode v3.0 introduces significant architectural improvements:

  • Plugin Event Bus — replaces hooks with event-driven architecture
  • Hierarchical Skills — Category/Skill structure (replaces flat)
  • Agent-based routing — each agent has exactly one model configured in opencode.json
  • Security Layer — prompt injection protection
  • Installer — CLI-only installation flow
  • DB Archiving — automated session management

Before You Start

1. Backup Your Data

# Automatic backup created by migration script
bun Tools/migration-v2-to-v3.ts --dry-run

# Or manual backup
cp -r ~/.opencode ~/.opencode-backup-$(date +%Y%m%d)

2. Stop OpenCode

Exit all OpenCode sessions before migrating.

Migration Steps

Step 1: Run Migration Script

cd /path/to/pai-opencode
bun Tools/migration-v2-to-v3.ts

This will:

  • Detect your current version (v2.x vs v3.x)
  • Create timestamped backup
  • Update skill structure (flat → hierarchical)
  • Update MINIMAL_BOOTSTRAP.md paths

Options:

--dry-run          # Preview only, no changes
--force            # Skip version check
--backup-dir=/path # Custom backup location

Step 2: Verify Skills

bun run skills:validate

Expected output: ✅ Validation passed! (0 errors)

Step 3: Update Configuration

v3.0 uses dual-file configuration:

File Purpose
~/.opencode/opencode.json OpenCode settings (agent models, MCP)
~/.opencode/settings.json PAI settings (identity, paths)

The migration script preserves your settings. Verify:

# Confirm no legacy model_tiers / model_tier keys remain (should return nothing)
grep -E 'model_tiers|model_tier' ~/.opencode/opencode.json
cat ~/.opencode/settings.json | grep daidentity

Step 4: Test OpenCode

opencode

Check that:

  • /db-archive command works
  • Plugin events fire (see DB-MAINTENANCE.md)
  • Skills load correctly

Breaking Changes

Plugin System (WP-A)

v2.x v3.0
Hooks (hook files) Event bus (plugin handlers)
hook.execute bus.on('tool.execute.before')

Impact: If you had custom hooks, port them to plugin handlers:

// v2.x style (hook)
export default {
  before: async (context) => { /* ... */ }
}

// v3.0 style (plugin handler)
import { bus } from '../lib/bus';
bus.on('tool.execute.before', async (event) => { /* ... */ });

Skills Structure (WP-C)

v2.x v3.0
Flat: skills/SkillName/ Hierarchical: skills/Category/SkillName/

Impact: Skills are now organized by category. The migration script handles this automatically.

Manual fix if needed:

# Example: move flat skill to category
mkdir -p ~/.opencode/skills/CustomCategory/
mv ~/.opencode/skills/MySkill ~/.opencode/skills/CustomCategory/

Configuration Files

v2.x v3.0
CLAUDE.md AGENTS.md
Single config file Dual: opencode.json + settings.json
~/.claude/ ~/.opencode/

Impact: All paths updated automatically.

Post-Migration Checklist

  • bun run skills:validate passes
  • opencode starts without errors
  • /db-archive shows DB stats
  • Plugin events logged (check ~/.opencode/logs/)
  • Custom skills still work
  • No .claude/ references in error messages

Troubleshooting

"Skills validation failed"

# Check for nested directories
ls ~/.opencode/skills/Telos/
# Should see: DashboardTemplate, ReportTemplate, SKILL.md
# Should NOT see: Telos/ (nested)

# Fix nested skills
mv ~/.opencode/skills/Telos/Telos/* ~/.opencode/skills/Telos/
rmdir ~/.opencode/skills/Telos/Telos/

"Database locked during migration"

# 1. Stop all OpenCode processes
# 2. Retry migration
bun Tools/migration-v2-to-v3.ts --force

"Custom skills not found"

Check skill structure:

# v3.0 requires frontmatter in SKILL.md
head -5 ~/.opencode/skills/CustomCategory/MySkill/SKILL.md
# Should show: --- name: ... description: ... ---

Rollback

If migration fails:

# Restore from backup
cp -r ~/.opencode-backup-YYYYMMDD/* ~/.opencode/

# Or use git (if you track ~/.opencode/)
cd ~/.opencode && git checkout v2.x-branch

What's New in v3.0

Feature Benefit
Plugin Event Bus Cleaner code, better testability
Agent-based routing Cost optimization via appropriate agent selection
Prompt Injection Guard Security against adversarial attacks
Installer (CLI-only) Deterministic install flow (no GUI path)
DB Archiving Automated session cleanup
Hierarchical Skills Better organization, lazy loading

See CHANGELOG.md for complete list.

Support

Migration complete? Run opencode and enjoy v3.0! 🎉