|
| 1 | +# Opencode Integration Documentation |
| 2 | + |
| 3 | +> Comprehensive documentation for integrating Opencode as an alternative orchestration layer in Gastown |
| 4 | +
|
| 5 | +**Location**: All Opencode integration documentation is centralized in this folder |
| 6 | + |
| 7 | +**Repository Source**: Based on [anomalyco/opencode](https://github.com/anomalyco/opencode) GitHub repository |
| 8 | + |
| 9 | +**Status**: Planning Complete - Ready for Implementation |
| 10 | + |
| 11 | +--- |
| 12 | + |
| 13 | +## 📚 Documentation Index |
| 14 | + |
| 15 | +### Quick Start |
| 16 | + |
| 17 | +**[Quickstart Guide](opencode-quickstart.md)** - One-page summary to get oriented quickly |
| 18 | + |
| 19 | +--- |
| 20 | + |
| 21 | +### Core Planning & Architecture |
| 22 | + |
| 23 | +**[Concept Analysis](opencode-concept-analysis.md)** - Analysis of all 23 Gastown concepts and Claude Code coupling |
| 24 | +- Identifies which concepts need abstraction |
| 25 | +- Coupling levels: 13 runtime-agnostic, 2 low, 4 medium, 4 high |
| 26 | +- Priority list with effort estimates |
| 27 | + |
| 28 | +**[Integration Architecture](opencode-integration-architecture.md)** - Detailed integration strategy leveraging Opencode features |
| 29 | +- Opencode research findings (plugins, SDK, tools, agents) |
| 30 | +- Core logic extraction pattern |
| 31 | +- Concept-by-concept integration with code examples |
| 32 | +- 4-phase implementation roadmap |
| 33 | + |
| 34 | +**[Orchestration Plan](opencode-orchestration.md)** - High-level architecture and strategy |
| 35 | +- Executive summary |
| 36 | +- Current state vs future state |
| 37 | +- Design goals and architecture |
| 38 | +- Integration points and workflow patterns |
| 39 | + |
| 40 | +**[Implementation Guide](opencode-implementation-guide.md)** - Technical specifications |
| 41 | +- Go interface definitions |
| 42 | +- Code structure and organization |
| 43 | +- Configuration examples |
| 44 | +- Testing strategy |
| 45 | + |
| 46 | +--- |
| 47 | + |
| 48 | +### Technical Research |
| 49 | + |
| 50 | +**[Technical Research](technical-research.md)** ⭐ **NEW** - Deep dive into Opencode repository |
| 51 | +- Session forking (`session/fork`) from ACP draft spec |
| 52 | +- Configuration schema ([https://opencode.ai/config.json](https://opencode.ai/config.json)) |
| 53 | +- ACP (Agent Client Protocol) integration |
| 54 | +- Plugin system internals with code examples |
| 55 | +- HTTP API endpoints and usage |
| 56 | +- Remote orchestration patterns |
| 57 | +- Research gaps and experiments needed |
| 58 | + |
| 59 | +--- |
| 60 | + |
| 61 | +### Research & Decision Support |
| 62 | + |
| 63 | +**[Experiments Checklist](opencode-experiments.md)** - 12 validation experiments |
| 64 | +- 5 basic experiments (MVP requirements) |
| 65 | +- 4 advanced experiments (design improvements) |
| 66 | +- 3 blocking experiments (must resolve) |
| 67 | +- Procedures and success criteria for each |
| 68 | + |
| 69 | +**[Decisions & Questions](opencode-decisions.md)** - Decision points and open questions |
| 70 | +- 5 critical architectural decisions |
| 71 | +- 10 open questions requiring research |
| 72 | +- Known divergences between Claude and Opencode |
| 73 | +- Assumptions registry with validation status |
| 74 | + |
| 75 | +--- |
| 76 | + |
| 77 | +### Navigation |
| 78 | + |
| 79 | +**[Index & Reading Paths](opencode-index.md)** - Comprehensive navigation hub |
| 80 | +- Reading paths by role (Architects, Engineers, PMs, Users, Researchers) |
| 81 | +- Reading paths by goal |
| 82 | +- Documentation status tracking |
| 83 | +- Implementation timeline |
| 84 | + |
| 85 | +--- |
| 86 | + |
| 87 | +## 🎯 Quick Navigation |
| 88 | + |
| 89 | +| Want to... | Read This | |
| 90 | +|------------|-----------| |
| 91 | +| Get oriented quickly | [Quickstart](opencode-quickstart.md) (5 min) | |
| 92 | +| Understand concept coupling | [Concept Analysis](opencode-concept-analysis.md) | |
| 93 | +| Learn how Opencode works | [Technical Research](technical-research.md) ⭐ | |
| 94 | +| See integration patterns | [Integration Architecture](opencode-integration-architecture.md) | |
| 95 | +| Understand the big picture | [Orchestration Plan](opencode-orchestration.md) | |
| 96 | +| Get implementation details | [Implementation Guide](opencode-implementation-guide.md) | |
| 97 | +| Run experiments | [Experiments Checklist](opencode-experiments.md) | |
| 98 | +| Make decisions | [Decisions & Questions](opencode-decisions.md) | |
| 99 | +| Navigate everything | [Full Index](opencode-index.md) | |
| 100 | + |
| 101 | +--- |
| 102 | + |
| 103 | +## 📊 Documentation Stats |
| 104 | + |
| 105 | +| Document | Size | Lines | Purpose | |
| 106 | +|----------|------|-------|---------| |
| 107 | +| Concept Analysis | 24KB | 730 | Coupling analysis of all Gastown concepts | |
| 108 | +| Integration Architecture | 30KB | 940 | Integration strategy with code examples | |
| 109 | +| Technical Research | 21KB | 670 | Deep dive into Opencode repository | |
| 110 | +| Orchestration Plan | 20KB | 620 | High-level architecture | |
| 111 | +| Implementation Guide | 18KB | 550 | Technical specifications | |
| 112 | +| Experiments | 19KB | 600 | Validation experiments | |
| 113 | +| Decisions | 14KB | 450 | Decision points and questions | |
| 114 | +| Index | 14KB | 320 | Navigation hub | |
| 115 | +| Quickstart | 5KB | 150 | One-page summary | |
| 116 | + |
| 117 | +**Total**: 9 documents, ~165KB, 5,030 lines |
| 118 | + |
| 119 | +--- |
| 120 | + |
| 121 | +## 🔍 Key Insights |
| 122 | + |
| 123 | +### From Concept Analysis |
| 124 | +- **13/23 Gastown concepts already runtime-agnostic** |
| 125 | +- **Runtime config abstraction already exists** - just needs adoption |
| 126 | +- **Minimal changes required**: ~200-300 LOC in 5 manager files |
| 127 | + |
| 128 | +### From Integration Architecture |
| 129 | +- **Core logic extraction pattern**: Extract once, adapt twice (Claude + Opencode) |
| 130 | +- **Mail already works cross-runtime**: Same CLI command for both |
| 131 | +- **Opencode provides natural integration points**: Plugins, tools, HTTP API |
| 132 | + |
| 133 | +### From Technical Research |
| 134 | +- **Session fork exists**: `session/fork` in ACP draft spec (needs verification) |
| 135 | +- **Configuration schema**: [https://opencode.ai/config.json](https://opencode.ai/config.json) |
| 136 | +- **Plugin events**: `session.created`, `tool.execute.before/after`, `stop`, etc. |
| 137 | +- **HTTP API**: RESTful endpoints for remote orchestration |
| 138 | +- **Permissions**: Fine-grained with wildcards (`"git *": "allow"`, `"rm *": "deny"`) |
| 139 | + |
| 140 | +--- |
| 141 | + |
| 142 | +## 🚀 Implementation Roadmap |
| 143 | + |
| 144 | +### Phase 1: Core Logic Extraction (Week 1) |
| 145 | +- Extract `internal/mail/`, `internal/session/`, `internal/work/` |
| 146 | +- Create runtime-agnostic interfaces |
| 147 | + |
| 148 | +### Phase 2: Opencode Adapters (Week 2) |
| 149 | +- Update plugins: `gastown.js`, `gastown-mail.js`, `gastown-polecat.js` |
| 150 | +- Create custom tools: `mail.ts`, `convoy.ts`, `worktree.ts` |
| 151 | +- Implement SDK wrapper: `internal/opencode/client.go` |
| 152 | + |
| 153 | +### Phase 3: Unified Interface (Week 3) |
| 154 | +- Update 5 agent managers to use runtime config |
| 155 | +- Replace `claude.EnsureSettings` with `runtime.EnsureSettingsForRole` |
| 156 | + |
| 157 | +### Phase 4: Testing & Documentation (Week 4) |
| 158 | +- Run experiments (EXP-002, EXP-003, EXP-007, EXP-008, EXP-010, EXP-011, EXP-012) |
| 159 | +- Integration tests |
| 160 | +- User documentation |
| 161 | + |
| 162 | +**Total Effort**: 3-4 weeks |
| 163 | + |
| 164 | +--- |
| 165 | + |
| 166 | +## 🔗 External References |
| 167 | + |
| 168 | +### Primary Sources |
| 169 | +- [Opencode Repository](https://github.com/anomalyco/opencode) - Source of truth |
| 170 | +- [ACP Specification](https://agentclientprotocol.com/) - Agent Client Protocol |
| 171 | +- [Configuration Schema](https://opencode.ai/config.json) - Official schema |
| 172 | +- [OpenCode Documentation](https://opencode.ai/docs/) - Official docs |
| 173 | +- [DeepWiki](https://deepwiki.com/anomalyco/opencode/) - Technical deep dives |
| 174 | + |
| 175 | +### Key Issues & RFCs |
| 176 | +- [Issue #7978](https://github.com/anomalyco/opencode/issues/7978) - ACP draft methods (session/fork, session/list) |
| 177 | +- [ACP RFC: Session Fork](https://agentclientprotocol.com/rfds/session-fork) - Fork specification |
| 178 | +- [Issue #1473](https://github.com/anomalyco/opencode/issues/1473) - Hooks support discussion |
| 179 | + |
| 180 | +--- |
| 181 | + |
| 182 | +## 📝 Document Updates |
| 183 | + |
| 184 | +**Latest Changes** (2026-01-16): |
| 185 | +- ✅ Reorganized all documentation under `docs/opencode/` |
| 186 | +- ✅ Added comprehensive technical research from Opencode repository |
| 187 | +- ✅ Documented `session/fork` from ACP draft spec |
| 188 | +- ✅ Added configuration schema references |
| 189 | +- ✅ Updated all cross-references |
| 190 | + |
| 191 | +**Next Updates**: |
| 192 | +- After EXP-007: Update with session fork findings |
| 193 | +- After EXP-010: Complete plugin event catalog |
| 194 | +- After EXP-011: Document plugin state persistence |
| 195 | +- After EXP-012: Add remote orchestration patterns |
| 196 | + |
| 197 | +--- |
| 198 | + |
| 199 | +**Last Updated**: 2026-01-16 |
| 200 | +**Status**: Documentation Complete - Implementation Ready |
| 201 | +**Maintainer**: Gastown Team |
0 commit comments