[Epic] PAI-OpenCode v3.0 — The Community Port (Scoped)

[Steffen025]

Epic: PAI-OpenCode v3.0 — The Community Port

🎯 Scope Note: PAI-OpenCode is a community contribution — focused, minimal, "as little as necessary." For the future vision (Voice-to-Voice, Ambient AI, OMI integration), see Open Arc. Read the Scope Boundary →

🎯 Vision

"Take PAI's core system and port it cleanly to OpenCode, leveraging OpenCode's native capabilities."

PAI-OpenCode v3.0 is a community port, not a commercial product:

• ✅ Preserves PAI's core (Algorithm v3.7.0, Skills, Euphoric Surprise)
• ✅ Leverages OpenCode-native features (Model Tiers ✅, Lazy Loading, MCP, Events)
• ✅ Stays focused: "as little as necessary" — resist scope creep into product territory
• ❌ Does NOT include: Voice-to-Voice, OMI Ambient AI, Product UX (see Open Arc)

Two Projects, Clear Separation:

Project	Purpose	Scope
PAI-OpenCode	Community port	Core PAI on OpenCode
Open Arc (jeremaiah.ai)	Commercial product	Voice, Ambient AI, Brand UX

---

🔥 Key Differentiators

✅ Production-Ready Today

• Model Tiers: Already implemented in custom OpenCode binary (15+ agents configured)
• Cost Optimization: 60x savings ($1.25/M vs $75/M tokens) via intelligent routing
• Custom Binary: Uses forked OpenCode with model_tier support (feature/model-tiers branch)

🆕 OpenCode-Native Features (Research-Validated)

Feature	Status	Action
Lazy Loading	✅ Native	Use skill tool, remove 233KB static context
Plugin Events	✅ Native	Migrate hooks → events (20+ events available)
MCP Integration	✅ Native	Configure skills as MCP servers
Context Compaction	✅ Native	Auto-handled by OpenCode
Agent Swarms	❌ Not available	Skip (Claude-Code-only feature)

🛡️ Security-First (WP3.5)

• Prompt Injection Protection: Detection + sanitization layer
• Input Validation: Pre-processing security guardrails
• Security Event Logging: Audit trail for all operations
• Regular Testing: Integration with PromptInjection skill for pentesting

---

📋 Work Packages (8 Total, 47-67h)

Critical Path

WP1 → WP2 → WP3 → WP3.5 → WP7 → WP8

WP	Name	Effort	Key Deliverable
WP1	Algorithm v3.7.0 + Model Tiers	8-12h	Port Algorithm, integrate existing Model Tier system
WP2	Context Modernization	6-8h	233KB → 20KB using native lazy loading
WP3	Event-Driven Plugins	5-7h	Migrate hooks → OpenCode native events
WP3.5	Security Hardening	4-6h	Prompt Injection protection, sanitization, logging
WP4	Skill Hierarchy	8-10h	39 skills → 11 PAI v4.0.3 categories
WP5	MCP Configuration	4-6h	3-5 skills as MCP servers (configure, not build)
WP6	Voice Foundation	MOVED	→ Open Arc (jeremaiah-ai/openark)
WP7	Migration & Installer	6-8h	v2→v3 script + custom binary installer
WP8	Testing & Release	6-10h	Full test suite, beta, v3.0.0 release

Total Critical Path: 47-67 hours (reduced from 73h by removing Open Arc scope)
Parallel Work: WP4, WP5 can run simultaneously after WP1
Open Arc (separate): Voice-to-Voice and Ambient AI features

WP6: Voice & Ambient AI Foundation → MOVED TO OPEN ARC

Status: ❌ EXCLUDED FROM PAI-OpenCode v3.0
New Home: github.com/jeremaiah-ai/openark
Decision Date: 2026-03-03
Decision Rationale: Scope separation — PAI-OpenCode is community port, Open Arc is product vision

Why This Was Removed:

• Voice-to-Voice is product feature, not core PAI port
• OMI Ambient AI integration is commercial product territory
• PAI-OpenCode must stay focused: "as little as necessary"
• Open Arc will contain: Voice architecture, OMI integration, Brand UX, End-user features

---

🏗️ Architecture Changes

Before (v2.x)

233KB static context
Custom context-loader.ts
Hook emulation layer
Flat skill structure (39 skills)
Fixed models per agent

After (v3.0)

~20KB minimal bootstrap (Algorithm + TELOS)
Native OpenCode skill tool
Event-driven plugins (pai-core.ts)
Hierarchical structure (11 categories)
Dynamic Model Tiers (quick/standard/advanced)
Prompt Injection protection
MCP-first skill architecture

---

🚫 Dropped Features

• StatusLine: OpenCode TUI limitation → Use Voice notifications
• Agent Swarms: Not in OpenCode → Use Task tool with subagents
• Static 233KB Context: Inefficient → Lazy loading
• Hook Emulation: Technical debt → Native events
• WP6 (Voice/OMI): Product scope → Moved to Open Arc

---

📁 Scope Boundary

Simple Rule:

• If it is an OpenCode-native feature that makes PAI run better on OpenCode → PAI-OpenCode
• If it is a new abstraction or product feature beyond OpenCode's built-in capabilities → Open Arc

Examples:

Feature	Decision	Reasoning
Model Tiers using opencode.json agent config	✅ PAI-OpenCode	Native OpenCode feature
Custom voice orchestration server	❌ Open Arc	New abstraction beyond PAI core
Lazy Loading via skill tool	✅ PAI-OpenCode	Native OpenCode feature
OMI ambient AI integration	❌ Open Arc	Hardware/product feature
Event-driven plugins using OpenCode events	✅ PAI-OpenCode	Native OpenCode feature
Custom branded UX wrapper	❌ Open Arc	Product layer

Full Documentation: docs/SCOPE-BOUNDARY.md

---

🎓 Research Sources

• DeepWiki Analysis: 6 queries, 100% success (7-11s response time)
• Fabric Pattern Analysis: Daniel Miessler's PAI v4.0 videos
• GitHub Research: OpenCode issues #12661, #12711, #7756
• Production Config: ~/.opencode/opencode.json (15 agents with Model Tiers)

---

🎯 Success Criteria

1. ✅ Algorithm v3.7.0 with ISC fully functional
2. ✅ Initial context <25KB (vs 233KB current)
3. ✅ Dynamic Model Tier routing working (15+ agents)
4. ✅ Prompt Injection protection active
5. ✅ 3+ skills as MCP servers
6. ✅ Unified event-driven plugin
7. ✅ All 39 skills in hierarchical structure
8. ✅ Migration script tested
9. ✅ Documentation complete
10. ✅ CI/CD passing

---

📁 Branches

• Main Epic Branch: v3.0-rearchitecture
• WP Branches: v3.0-wp1-algorithm, v3.0-wp2-context, etc.
• Base Branch: dev (create PRs here)

---

📚 References

• Epic Document: docs/epic/EPIC-v3.0-Synthesis-Architecture.md (updated with scope clarity)
• Scope Boundary: docs/SCOPE-BOUNDARY.md (new document)
• PAI v4.0.3: /Releases/v4.0.3/.claude/ (hierarchical structure)
• OpenCode Docs: opencode.ai/docs
• Open Arc: github.com/jeremaiah-ai/openark

---

🚀 Next Actions

1. ✅ Epic updated with scope clarification (this issue)
2. ⏳ Start WP1: Algorithm v3.7.0 + Model Tier integration on v3.0-wp1-algorithm
3. ⏳ Implement core Algorithm components
4. ⏳ Begin work on v3.0-rearchitecture branch

---

PAI-OpenCode = Community contribution. Minimal. Focused. Native.
Open Arc = Commercial vision. Voice. Ambient. Product.
Target: PAI-OpenCode v3.0.0

/cc @Steffen025

[coderabbitai]

⚠️ Possible Duplicate Issue(s)

• [Epic] PAI-OpenCode v3.0 — The Synthesis Architecture #30

---

📝 Issue Planner

_{Check the box below or use the @coderabbitai plan command to generate an implementation plan and prompts that you can use with your favorite coding assistant.}

• Create Plan

---

🧪 Issue enrichment is currently in open beta.

You can configure auto-planning by selecting labels in the issue_enrichment configuration.

To disable automatic issue enrichment, add the following to your .coderabbit.yaml:

issue_enrichment:
  auto_enrich:
    enabled: false

💬 Have feedback or questions? Drop into our discord!

[Steffen025]

📋 Issue Integration Update

The following open issues have been reviewed and integrated into v3.0 Work Packages:

Issue #27 — Provider Agnostic vs Wizard

Status: Verified (documentation enhancement)
WP: WP7 (Migration & Installer)
Action: Documentation must clarify: Wizard = Quick Start (3 providers), slash-connect + opencode.json = 75+ providers

Issue #28 — Rating Capture fails with parts

Status: Bug confirmed
WP: WP3 (Event-Driven Plugins)
Problem: extractTextContent only checks message.content, not output.parts
Fix: Plugin must parse all OpenCode message formats correctly

Issue #29 — USER Directory Mismatch

Status: Structural problem confirmed
WP: WP4 (Skill Hierarchy) + WP1 (Initial Structure)
Problem: dot-opencode-USER exists at the root (incorrect), upstream only has dot-opencode-PAI-USER
Fix: Alignment with PAI v4.0.3 structure

---

Updated Work Packages:

• WP1: + Structure alignment (Issue .opencode/USER directory mismatch vs upstream PAI #29)
• WP3: + Rating capture bug fix (Issue Explicit rating capture fails when message content is delivered via parts #28)
• WP4: + USER directory consolidation (Issue .opencode/USER directory mismatch vs upstream PAI #29)
• WP7: + Provider documentation (Issue Clarification on “Provider Agnostic” Claim vs Wizard Startup Options #27)

Details in the respective issues.