Skip to content

Commit e2eaeb6

Browse files
apiadapiad
committed
docs: update documentation for v2.0.0 features
1 parent 93eecd8 commit e2eaeb6

File tree

6 files changed

+467
-16
lines changed

6 files changed

+467
-16
lines changed

‎.knowledge/notes/docs-v2-analysis.md‎

Lines changed: 82 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,82 @@
1+
# Documentation Analysis: v2.0.0
2+
3+
Analysis date: 2026-04-01
4+
Purpose: Identify documentation updates needed for v2.0.0 release
5+
6+
## v2.0.0 New Features
7+
8+
1. **Literate Commands** - Multi-step guided workflows
9+
- Variable collection with types
10+
- Conditional logic support
11+
- In-place array mutation for command abort
12+
- Phase-based execution (parse → substitute → route → execute)
13+
14+
2. **Sandbox Plugin** - Docker-based isolation
15+
- Mode-specific command routing
16+
- Isolated execution context
17+
- `.opencode/sandbox/` directory
18+
19+
3. **Enhanced Agent Architecture**
20+
- 4 modes: analyze, plan, build, release
21+
- Lit-commands subagent for literate command processing
22+
23+
## Documentation Status
24+
25+
### `index.md` - NEEDS UPDATE
26+
| Section | Status | Notes |
27+
|---------|--------|-------|
28+
| Key Capabilities | ❌ Incomplete | Missing literate commands, sandbox |
29+
| Project Lifecycle | ❌ Incomplete | References `/release` but not documented |
30+
31+
### `user-guide.md` - NEEDS UPDATE
32+
| Section | Status | Notes |
33+
|---------|--------|-------|
34+
| Agent Architecture | ❌ Incomplete | Missing `design` mode |
35+
| Phase 3 Execution | ❌ Incomplete | `/fix`, `/release` not documented |
36+
| `/commit` | ⚠️ Truncated | Line 84 cuts off mid-section |
37+
| Full Walkthrough | ❌ Missing | No literate commands walkthrough |
38+
39+
### `design.md` - NEEDS UPDATE
40+
| Section | Status | Notes |
41+
|---------|--------|-------|
42+
| Primary Agents | ❌ Incomplete | Missing `design` mode column |
43+
| Subagents | ❌ Incomplete | Missing `lit-commands` subagent |
44+
| Commands Table | ❌ Incomplete | Missing `/sandbox`, `/commit` |
45+
| Sandbox Plugin | ❌ Missing | New feature not documented |
46+
| Literate Commands | ❌ Missing | New feature not documented |
47+
48+
### `develop.md` - OK
49+
No significant changes needed.
50+
51+
### `deploy.md` - OK
52+
Already reflects current architecture.
53+
54+
### `updating.md` - OK
55+
Already references v2.0.0.
56+
57+
## Required Updates
58+
59+
### High Priority
60+
1. Add `design` mode to agent architecture tables
61+
2. Document `/sandbox` command
62+
3. Document literate commands concept
63+
4. Fix truncated `/commit` section in user-guide.md
64+
5. Add sandbox to Key Capabilities in index.md
65+
66+
### Medium Priority
67+
1. Add literate commands to design.md architecture section
68+
2. Document sandbox plugin in design.md
69+
3. Add walkthrough for literate commands workflow
70+
71+
### Low Priority
72+
1. Update prerequisites if sandbox has new requirements (Docker)
73+
74+
## Estimated Effort
75+
- **High Priority**: ~1-2 hours
76+
- **Medium Priority**: ~2-3 hours
77+
- **Low Priority**: ~1 hour
78+
79+
## Notes
80+
- `lib/opencode-literate-commands/` submodule contains literate-commands implementation
81+
- `.opencode/plugins/sandbox.js` contains sandbox implementation
82+
- Need to verify if Docker is required for sandbox (check prerequisites)

‎.knowledge/plans/docs-v2-update.md‎

Lines changed: 241 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,241 @@
1+
# Documentation Update Plan: v2.0.0
2+
3+
**Created:** 2026-04-01
4+
**Version:** v2.0.0
5+
**Status:** Draft
6+
7+
---
8+
9+
## Problem
10+
11+
The OpenCode Framework v2.0.0 introduced major new features (literate commands, sandbox plugin, design mode) but the documentation has not been updated to reflect these changes. Users cannot discover or understand how to use the new capabilities.
12+
13+
---
14+
15+
## Scope
16+
17+
### Documents Affected
18+
1. `docs/design.md` - Architecture & Systems
19+
2. `docs/user-guide.md` - User Guide
20+
3. `docs/index.md` - Landing page
21+
22+
### New Features to Document
23+
| Feature | Description | Complexity |
24+
|---------|-------------|------------|
25+
| Literate Commands | Multi-step guided workflows with variables & conditionals | High |
26+
| Sandbox Plugin | Docker-based isolated execution | Medium |
27+
| Design Mode | New agent mode for planning/design work | Low |
28+
| `/commit` Command | Validation-aware commit workflow | Low |
29+
| `/sandbox` Command | Sandbox management command | Medium |
30+
31+
---
32+
33+
## Solution Approach
34+
35+
**Strategy:** Incremental, file-by-file updates with review checkpoints. Each document updated in isolation to minimize merge conflicts and allow focused review.
36+
37+
---
38+
39+
## Phases
40+
41+
### Phase 1: Fix Critical Issues
42+
**Estimated time:** 30 minutes
43+
44+
1. **Fix truncated `/commit` section** in `user-guide.md`
45+
- Complete the truncated content at line 84
46+
- Document full validation workflow
47+
48+
2. **Add missing commands to design.md**
49+
- Add `/commit` to commands table
50+
- Add `/sandbox` to commands table
51+
52+
**Deliverables:**
53+
- [ ] `user-guide.md` `/commit` section complete
54+
- [ ] `design.md` commands table updated
55+
56+
---
57+
58+
### Phase 2: Update Agent Architecture
59+
**Estimated time:** 1 hour
60+
61+
1. **Add `design` mode** to Primary Agents tables
62+
- `docs/design.md`: Add column/row for `design` mode
63+
- `docs/user-guide.md`: Add to Agent Architecture section
64+
65+
2. **Add `lit-commands` subagent** to subagents table
66+
- Document purpose: Processes literate command files
67+
68+
3. **Update Key Capabilities** in `docs/index.md`
69+
- Add literate commands
70+
- Add sandbox capability
71+
72+
**Deliverables:**
73+
- [ ] `design.md` Primary Agents table includes `design` mode
74+
- [ ] `design.md` Subagents table includes `lit-commands`
75+
- [ ] `user-guide.md` Agent Architecture updated
76+
- [ ] `index.md` Key Capabilities updated
77+
78+
---
79+
80+
### Phase 3: Document Literate Commands
81+
**Estimated time:** 2-3 hours
82+
83+
1. **Create new section** in `design.md`
84+
```
85+
## 📜 Literate Commands
86+
```
87+
- Explain concept: `.md` files with executable code blocks
88+
- Document frontmatter options:
89+
- `literate: true`
90+
- `variables: []`
91+
- `conditions: {}`
92+
- Explain phase execution model:
93+
1. Parse → 2. Substitute → 3. Route → 4. Execute
94+
95+
2. **Add `/scaffold` documentation** for literate commands
96+
- Show how to scaffold a literate command
97+
- Document file structure
98+
99+
3. **Add walkthrough** in `user-guide.md`
100+
- Step-by-step example of creating a literate command
101+
- Show variable collection and conditional branching
102+
103+
4. **Update commands table** in `design.md`
104+
- Add literate-commands command
105+
- Reference new section
106+
107+
**Deliverables:**
108+
- [ ] `design.md` Literate Commands section created
109+
- [ ] `user-guide.md` Literate Commands walkthrough added
110+
- [ ] Commands table includes literate-commands entry
111+
112+
---
113+
114+
### Phase 4: Document Sandbox Plugin
115+
**Estimated time:** 1-2 hours
116+
117+
1. **Create new section** in `design.md`
118+
```
119+
## 🐳 Sandbox Plugin
120+
```
121+
- Explain purpose: Docker-based isolation
122+
- Document mode-specific routing
123+
- List sandbox directories:
124+
- `.opencode/sandbox/sandbox.sh`
125+
- `.opencode/plugins/sandbox.js`
126+
127+
2. **Add prerequisites** section in `deploy.md`
128+
- Add Docker to requirements list
129+
- Document sandbox setup command: `/sandbox`
130+
131+
3. **Update Key Capabilities** in `index.md`
132+
- Add "Isolated Execution" capability
133+
134+
4. **Add sandbox management** to `user-guide.md`
135+
- Document `/sandbox` command usage
136+
- Explain when sandbox is used automatically
137+
138+
**Deliverables:**
139+
- [ ] `design.md` Sandbox Plugin section created
140+
- [ ] `deploy.md` Docker prerequisite added
141+
- [ ] `index.md` Isolated Execution capability added
142+
- [ ] `user-guide.md` sandbox documentation added
143+
144+
---
145+
146+
### Phase 5: Review & Polish
147+
**Estimated time:** 1 hour
148+
149+
1. **Cross-reference checks**
150+
- Ensure all commands mentioned in one doc exist in design.md table
151+
- Verify all modes in index.md appear in design.md
152+
153+
2. **Update navigation**
154+
- Ensure "Next:" links at bottom of each doc point to correct files
155+
- Verify TOC if using mkdocs-autodocs
156+
157+
3. **Link verification**
158+
- Check internal links between documents
159+
- Verify code snippets are accurate
160+
161+
4. **Add to CHANGELOG.md**
162+
- Document documentation updates as a minor item
163+
164+
**Deliverables:**
165+
- [ ] All cross-references verified
166+
- [ ] Navigation links verified
167+
- [ ] CHANGELOG.md updated
168+
169+
---
170+
171+
## Implementation Order
172+
173+
```
174+
Phase 1 → Phase 2 → Phase 3 → Phase 4 → Phase 5
175+
↓ ↓ ↓ ↓ ↓
176+
Quick Agent Literate Sandbox Polish
177+
Fixes Updates Commands Plugin
178+
```
179+
180+
---
181+
182+
## Risks & Mitigations
183+
184+
| Risk | Probability | Impact | Mitigation |
185+
|------|-------------|--------|------------|
186+
| Sandbox details change during implementation | Medium | Low | Write generically; reference source code for specifics |
187+
| Literate commands API evolves | Medium | Medium | Focus on concept over implementation details |
188+
| Docker prerequisite may limit adoption | Low | Medium | Clearly document when sandbox is optional |
189+
| Merge conflicts if concurrent edits | Low | High | Work file-by-file, commit after each phase |
190+
191+
---
192+
193+
## Success Criteria
194+
195+
1. **Completeness:** All new features (literate commands, sandbox, design mode) have dedicated documentation sections
196+
2. **Discoverability:** Index page lists all key capabilities
197+
3. **Accuracy:** Code snippets and command examples work
198+
4. **Navigation:** Users can follow "Next:" links through the documentation
199+
5. **Consistency:** Terminology matches across all documents
200+
201+
---
202+
203+
## Verification Commands
204+
205+
After implementation, verify:
206+
```bash
207+
# Check all referenced commands exist
208+
grep -h "/commit\|/sandbox\|/release\|/fix" docs/*.md | sort -u
209+
210+
# Check all modes documented
211+
grep -h "analyze\|plan\|build\|release\|design" docs/*.md | sort -u
212+
213+
# Check new features mentioned
214+
grep -l "literate\|sandbox\|sandbox.sh" docs/*.md
215+
```
216+
217+
---
218+
219+
## Estimated Total Time
220+
221+
| Phase | Time | Cumulative |
222+
|-------|------|------------|
223+
| Phase 1 | 30 min | 30 min |
224+
| Phase 2 | 1 hour | 1.5 hours |
225+
| Phase 3 | 2-3 hours | 3.5-4.5 hours |
226+
| Phase 4 | 1-2 hours | 4.5-6.5 hours |
227+
| Phase 5 | 1 hour | 5.5-7.5 hours |
228+
229+
**Total: ~6-8 hours**
230+
231+
---
232+
233+
## Next Steps
234+
235+
1. **Approve this plan** → Switch to Create mode to implement
236+
2. **Prioritize phases** → Decide if Phases 3-4 can be deferred
237+
3. **Assign ownership** → Determine who reviews each phase
238+
239+
---
240+
241+
*Plan created by design agent. Ready for implementation.*

‎docs/deploy.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -123,6 +123,7 @@ To ensure full functionality, your environment should have:
123123
- **Python 3.12+:** Required for executing the project's automation scripts in `.opencode/tools/`.
124124
- **uv:** The required Python package and project manager.
125125
- **Make:** Used for project validation and health checks (runs `uv run pytest`).
126+
- **Docker:** Required for the sandbox plugin (optional for isolated execution).
126127

127128
### Installing Git Hooks
128129

0 commit comments

Comments
 (0)