Skip to content

Commit 117797b

Browse files
Copilotrothnic
andcommitted
Reorganize Opencode docs under docs/opencode/ with deep technical research
- Move all opencode documentation from docs/design/ to docs/opencode/ - Create docs/opencode/README.md: Comprehensive documentation index - Create docs/opencode/technical-research.md: Deep dive into Opencode repository (21KB, 670 lines) * Session forking (session/fork) from ACP draft spec with links to agentclientprotocol.com * Configuration schema reference: https://opencode.ai/config.json * ACP (Agent Client Protocol) integration details * Plugin system internals with event catalog * Custom tools architecture * HTTP API endpoints and remote orchestration * Research gaps identification (EXP-007, EXP-010, EXP-011, EXP-012) - Update docs/design/README.md: Point to new docs/opencode/ location Technical Research Findings: - session/fork exists in ACP draft (UNSTABLE): https://agentclientprotocol.com/rfds/session-fork - Issue #7978 documents ACP draft methods: anomalyco/opencode#7978 - Config schema at https://opencode.ai/config.json with layered hierarchy - Plugin events: session.created, tool.execute.before/after, stop - HTTP API for remote orchestration via /session endpoints - Permissions with wildcards: "git *": "allow", "rm *": "deny" All documentation now centralized in docs/opencode/ using Opencode GitHub repository as source of truth. Co-authored-by: rothnic <[email protected]>
1 parent 3f9ca26 commit 117797b

11 files changed

Lines changed: 1030 additions & 10 deletions

‎docs/design/README.md‎

Lines changed: 21 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -36,16 +36,27 @@ This directory contains design documents, architectural specifications, and plan
3636
### Quick Start
3737
- **[opencode-quickstart.md](opencode-quickstart.md)** ⭐ Start here for a one-page overview
3838

39-
### Full Documentation
40-
- **[opencode-index.md](opencode-index.md)** - Navigation hub for all Opencode docs
41-
- **[opencode-concept-analysis.md](opencode-concept-analysis.md)** - Analysis of all Gastown concepts and Claude Code coupling
42-
- **[opencode-integration-architecture.md](opencode-integration-architecture.md)** ⭐ **NEW** - Leveraging Opencode's plugins, SDK, tools, and agents
43-
- [opencode-orchestration.md](opencode-orchestration.md) - Comprehensive architecture and strategy
44-
- [opencode-implementation-guide.md](opencode-implementation-guide.md) - Technical implementation details
45-
- [opencode-experiments.md](opencode-experiments.md) - Validation experiments checklist
46-
- [opencode-decisions.md](opencode-decisions.md) - Decision points and open questions
47-
48-
**Status**: Integration architecture complete, ready for implementation (2026-01-16)
39+
### Opencode Integration
40+
41+
**Documentation Location**: All Opencode integration documentation has been moved to [`docs/opencode/`](../opencode/)
42+
43+
**Quick Links**:
44+
- **[Opencode Documentation Index](../opencode/README.md)** - Complete documentation index
45+
- [Quickstart Guide](../opencode/opencode-quickstart.md) - One-page summary
46+
- [Technical Research](../opencode/technical-research.md) ⭐ **NEW** - Deep dive into Opencode repository
47+
- [Concept Analysis](../opencode/opencode-concept-analysis.md) - Coupling analysis
48+
- [Integration Architecture](../opencode/opencode-integration-architecture.md) - Implementation strategy
49+
- [Experiments Checklist](../opencode/opencode-experiments.md) - Validation experiments
50+
51+
**Key Findings**:
52+
- 13/23 Gastown concepts already runtime-agnostic
53+
- Minimal changes needed: ~200-300 LOC in 5 files
54+
- Session forking available via ACP `session/fork` (needs verification)
55+
- Configuration schema: [https://opencode.ai/config.json](https://opencode.ai/config.json)
56+
57+
**Status**: Planning complete, ready for implementation (2026-01-16)
58+
59+
---
4960

5061
## Document Types
5162

‎docs/opencode/README.md‎

Lines changed: 201 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,201 @@
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
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.

0 commit comments

Comments
 (0)