gsd-opencode 1.5.0 → 1.5.2
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/command/gsd/add-phase.md +1 -1
- package/command/gsd/add-todo.md +2 -2
- package/command/gsd/create-roadmap.md +1 -1
- package/command/gsd/debug.md +2 -2
- package/command/gsd/help.md +2 -2
- package/command/gsd/insert-phase.md +1 -1
- package/command/gsd/new-project.md +2 -2
- package/command/gsd/pause-work.md +1 -1
- package/command/gsd/progress.md +6 -6
- package/command/gsd/status.md +1 -1
- package/get-shit-done/references/checkpoints.md +22 -22
- package/get-shit-done/references/continuation-format.md +11 -11
- package/get-shit-done/references/git-integration.md +4 -4
- package/get-shit-done/references/plan-format.md +24 -24
- package/get-shit-done/references/principles.md +14 -14
- package/get-shit-done/references/questioning.md +2 -2
- package/get-shit-done/references/scope-estimation.md +3 -3
- package/get-shit-done/templates/DEBUG.md +6 -6
- package/get-shit-done/templates/checkpoint-return.md +2 -2
- package/get-shit-done/templates/codebase/architecture.md +1 -1
- package/get-shit-done/templates/codebase/concerns.md +1 -1
- package/get-shit-done/templates/codebase/conventions.md +1 -1
- package/get-shit-done/templates/context.md +4 -4
- package/get-shit-done/templates/continue-here.md +1 -1
- package/get-shit-done/templates/milestone-context.md +3 -3
- package/get-shit-done/templates/phase-prompt.md +3 -3
- package/get-shit-done/templates/project.md +1 -1
- package/get-shit-done/templates/research.md +2 -2
- package/get-shit-done/templates/state.md +1 -1
- package/get-shit-done/workflows/_archive/execute-phase.md +1 -1
- package/get-shit-done/workflows/complete-milestone.md +1 -1
- package/get-shit-done/workflows/create-milestone.md +1 -1
- package/get-shit-done/workflows/create-roadmap.md +2 -2
- package/get-shit-done/workflows/debug.md +3 -3
- package/get-shit-done/workflows/discovery-phase.md +1 -1
- package/get-shit-done/workflows/discuss-milestone.md +1 -1
- package/get-shit-done/workflows/discuss-phase.md +2 -2
- package/get-shit-done/workflows/execute-phase.md +1 -1
- package/get-shit-done/workflows/execute-plan.md +6 -6
- package/get-shit-done/workflows/list-phase-assumptions.md +7 -7
- package/get-shit-done/workflows/map-codebase.md +2 -2
- package/get-shit-done/workflows/plan-phase.md +3 -3
- package/get-shit-done/workflows/research-phase.md +9 -9
- package/get-shit-done/workflows/resume-project.md +2 -2
- package/get-shit-done/workflows/transition.md +2 -2
- package/get-shit-done/workflows/verify-work.md +1 -1
- package/package.json +1 -1
package/command/gsd/add-phase.md
CHANGED
package/command/gsd/add-todo.md
CHANGED
|
@@ -110,7 +110,7 @@ files:
|
|
|
110
110
|
|
|
111
111
|
## Problem
|
|
112
112
|
|
|
113
|
-
[problem description - enough context for future
|
|
113
|
+
[problem description - enough context for future OpenCode to understand weeks later]
|
|
114
114
|
|
|
115
115
|
## Solution
|
|
116
116
|
|
|
@@ -176,7 +176,7 @@ Would you like to:
|
|
|
176
176
|
<success_criteria>
|
|
177
177
|
- [ ] Directory structure exists
|
|
178
178
|
- [ ] Todo file created with valid frontmatter
|
|
179
|
-
- [ ] Problem section has enough context for future
|
|
179
|
+
- [ ] Problem section has enough context for future OpenCode
|
|
180
180
|
- [ ] No duplicates (checked and resolved)
|
|
181
181
|
- [ ] Area consistent with existing todos
|
|
182
182
|
- [ ] STATE.md updated if exists
|
package/command/gsd/debug.md
CHANGED
|
@@ -13,7 +13,7 @@ allowed-tools:
|
|
|
13
13
|
---
|
|
14
14
|
|
|
15
15
|
<objective>
|
|
16
|
-
Debug issues using scientific method with a persistent debug document that survives `/
|
|
16
|
+
Debug issues using scientific method with a persistent debug document that survives `/new`.
|
|
17
17
|
|
|
18
18
|
If resuming (no arguments and active session exists): pick up where you left off.
|
|
19
19
|
If starting new: gather symptoms, then investigate autonomously.
|
|
@@ -45,7 +45,7 @@ Follow the workflow in @~/.config/opencode/get-shit-done/workflows/debug.md
|
|
|
45
45
|
5. **Fix and verify** - Minimal fix, verify against original symptoms
|
|
46
46
|
6. **Archive** - Move to `.planning/debug/resolved/`
|
|
47
47
|
|
|
48
|
-
**Key principle:** The DEBUG.md is your memory. Update it constantly. It survives `/
|
|
48
|
+
**Key principle:** The DEBUG.md is your memory. Update it constantly. It survives `/new`.
|
|
49
49
|
</process>
|
|
50
50
|
|
|
51
51
|
<success_criteria>
|
package/command/gsd/help.md
CHANGED
|
@@ -247,7 +247,7 @@ Systematic debugging with persistent state across context resets.
|
|
|
247
247
|
- Gathers symptoms through adaptive questioning
|
|
248
248
|
- Creates `.planning/debug/[slug].md` to track investigation
|
|
249
249
|
- Investigates using scientific method (evidence → hypothesis → test)
|
|
250
|
-
- Survives `/
|
|
250
|
+
- Survives `/new` — run `/gsd-debug` with no args to resume
|
|
251
251
|
- Archives resolved issues to `.planning/debug/resolved/`
|
|
252
252
|
|
|
253
253
|
Usage: `/gsd-debug "login button doesn't work"`
|
|
@@ -379,7 +379,7 @@ Change anytime by editing `.planning/config.json`
|
|
|
379
379
|
```
|
|
380
380
|
/gsd-debug "form submission fails silently" # Start debug session
|
|
381
381
|
# ... investigation happens, context fills up ...
|
|
382
|
-
/
|
|
382
|
+
/new
|
|
383
383
|
/gsd-debug # Resume from where you left off
|
|
384
384
|
```
|
|
385
385
|
|
|
@@ -57,7 +57,7 @@ Creates `.planning/` with PROJECT.md and config.json.
|
|
|
57
57
|
HAS_CODEBASE_MAP=$([ -d .planning/codebase ] && echo "yes")
|
|
58
58
|
```
|
|
59
59
|
|
|
60
|
-
**You MUST run all bash commands above using the
|
|
60
|
+
**You MUST run all bash commands above using the bash tool before proceeding.**
|
|
61
61
|
|
|
62
62
|
</step>
|
|
63
63
|
|
|
@@ -307,7 +307,7 @@ Project initialized:
|
|
|
307
307
|
|
|
308
308
|
`/gsd-create-roadmap`
|
|
309
309
|
|
|
310
|
-
*`/
|
|
310
|
+
*`/new` first → fresh context window*
|
|
311
311
|
|
|
312
312
|
---
|
|
313
313
|
```
|
|
@@ -86,7 +86,7 @@ Start with: [specific first action when resuming]
|
|
|
86
86
|
</next_action>
|
|
87
87
|
```
|
|
88
88
|
|
|
89
|
-
Be specific enough for a fresh
|
|
89
|
+
Be specific enough for a fresh OpenCode to understand immediately.
|
|
90
90
|
</step>
|
|
91
91
|
|
|
92
92
|
<step name="commit">
|
package/command/gsd/progress.md
CHANGED
|
@@ -149,7 +149,7 @@ Read its `<objective>` section.
|
|
|
149
149
|
|
|
150
150
|
`/gsd-execute-plan [full-path-to-PLAN.md]`
|
|
151
151
|
|
|
152
|
-
*`/
|
|
152
|
+
*`/new` first → fresh context window*
|
|
153
153
|
|
|
154
154
|
---
|
|
155
155
|
```
|
|
@@ -172,7 +172,7 @@ Check if `{phase}-CONTEXT.md` exists in phase directory.
|
|
|
172
172
|
|
|
173
173
|
`/gsd-plan-phase {phase-number}`
|
|
174
174
|
|
|
175
|
-
*`/
|
|
175
|
+
*`/new` first → fresh context window*
|
|
176
176
|
|
|
177
177
|
---
|
|
178
178
|
```
|
|
@@ -188,7 +188,7 @@ Check if `{phase}-CONTEXT.md` exists in phase directory.
|
|
|
188
188
|
|
|
189
189
|
`/gsd-plan-phase {phase}`
|
|
190
190
|
|
|
191
|
-
*`/
|
|
191
|
+
*`/new` first → fresh context window*
|
|
192
192
|
|
|
193
193
|
---
|
|
194
194
|
|
|
@@ -215,7 +215,7 @@ ISSUES.md exists without matching FIX.md. User needs to plan fixes.
|
|
|
215
215
|
|
|
216
216
|
`/gsd-plan-fix {plan}`
|
|
217
217
|
|
|
218
|
-
*`/
|
|
218
|
+
*`/new` first → fresh context window*
|
|
219
219
|
|
|
220
220
|
---
|
|
221
221
|
|
|
@@ -262,7 +262,7 @@ Read ROADMAP.md to get the next phase's name and goal.
|
|
|
262
262
|
|
|
263
263
|
`/gsd-plan-phase {Z+1}`
|
|
264
264
|
|
|
265
|
-
*`/
|
|
265
|
+
*`/new` first → fresh context window*
|
|
266
266
|
|
|
267
267
|
---
|
|
268
268
|
|
|
@@ -291,7 +291,7 @@ All {N} phases finished!
|
|
|
291
291
|
|
|
292
292
|
`/gsd-complete-milestone`
|
|
293
293
|
|
|
294
|
-
*`/
|
|
294
|
+
*`/new` first → fresh context window*
|
|
295
295
|
|
|
296
296
|
---
|
|
297
297
|
|
package/command/gsd/status.md
CHANGED
|
@@ -1,21 +1,21 @@
|
|
|
1
1
|
<overview>
|
|
2
2
|
Plans execute autonomously. Checkpoints formalize interaction points where human verification or decisions are needed.
|
|
3
3
|
|
|
4
|
-
**Core principle:**
|
|
4
|
+
**Core principle:** OpenCode automates everything with CLI/API. Checkpoints are for verification and decisions, not manual work.
|
|
5
5
|
</overview>
|
|
6
6
|
|
|
7
7
|
<checkpoint_types>
|
|
8
8
|
|
|
9
9
|
## checkpoint:human-verify (90% of checkpoints)
|
|
10
10
|
|
|
11
|
-
**When:**
|
|
11
|
+
**When:** OpenCode completed automated work, human confirms it works correctly.
|
|
12
12
|
|
|
13
13
|
**Use for:** Visual UI checks, interactive flows, functional verification, audio/video quality, animation smoothness, accessibility testing.
|
|
14
14
|
|
|
15
15
|
**Structure:**
|
|
16
16
|
```xml
|
|
17
17
|
<task type="checkpoint:human-verify" gate="blocking">
|
|
18
|
-
<what-built>[What
|
|
18
|
+
<what-built>[What OpenCode automated]</what-built>
|
|
19
19
|
<how-to-verify>[Numbered steps - URLs, commands, expected behavior]</how-to-verify>
|
|
20
20
|
<resume-signal>[How to continue - "approved" or describe issues]</resume-signal>
|
|
21
21
|
</task>
|
|
@@ -80,14 +80,14 @@ Plans execute autonomously. Checkpoints formalize interaction points where human
|
|
|
80
80
|
|
|
81
81
|
**Use ONLY for:** Email verification links, SMS 2FA codes, manual account approvals, 3D Secure payment flows, OAuth app approvals.
|
|
82
82
|
|
|
83
|
-
**Do NOT use for:** Deployments (use CLI), creating resources (use CLI/API), builds/tests (use
|
|
83
|
+
**Do NOT use for:** Deployments (use CLI), creating resources (use CLI/API), builds/tests (use bash tool), file operations (use write/edit tools).
|
|
84
84
|
|
|
85
85
|
**Structure:**
|
|
86
86
|
```xml
|
|
87
87
|
<task type="checkpoint:human-action" gate="blocking">
|
|
88
88
|
<action>[Unavoidable manual step]</action>
|
|
89
|
-
<instructions>[What
|
|
90
|
-
<verification>[What
|
|
89
|
+
<instructions>[What OpenCode automated] [ONE thing requiring human action]</instructions>
|
|
90
|
+
<verification>[What OpenCode checks afterward]</verification>
|
|
91
91
|
<resume-signal>[How to continue]</resume-signal>
|
|
92
92
|
</task>
|
|
93
93
|
```
|
|
@@ -109,7 +109,7 @@ Plans execute autonomously. Checkpoints formalize interaction points where human
|
|
|
109
109
|
|
|
110
110
|
<execution_protocol>
|
|
111
111
|
|
|
112
|
-
When
|
|
112
|
+
When OpenCode encounters `type="checkpoint:*"`:
|
|
113
113
|
|
|
114
114
|
1. **Stop immediately** - do not proceed to next task
|
|
115
115
|
2. **Display checkpoint clearly:**
|
|
@@ -135,9 +135,9 @@ Task [X] of [Y]: [Name]
|
|
|
135
135
|
|
|
136
136
|
<authentication_gates>
|
|
137
137
|
|
|
138
|
-
**Critical:** When
|
|
138
|
+
**Critical:** When OpenCode tries CLI/API and gets auth error, this is NOT a failure - it's a gate requiring human input to unblock automation.
|
|
139
139
|
|
|
140
|
-
**Pattern:**
|
|
140
|
+
**Pattern:** OpenCode tries automation → auth error → creates checkpoint → you authenticate → OpenCode retries → continues
|
|
141
141
|
|
|
142
142
|
**Gate protocol:**
|
|
143
143
|
1. Recognize it's not a failure - missing auth is expected
|
|
@@ -150,7 +150,7 @@ Task [X] of [Y]: [Name]
|
|
|
150
150
|
|
|
151
151
|
**Example (Vercel auth gate):**
|
|
152
152
|
```xml
|
|
153
|
-
<!--
|
|
153
|
+
<!-- OpenCode tries to deploy -->
|
|
154
154
|
<task type="auto">
|
|
155
155
|
<name>Deploy to Vercel</name>
|
|
156
156
|
<action>Run `vercel --yes` to deploy</action>
|
|
@@ -167,7 +167,7 @@ Task [X] of [Y]: [Name]
|
|
|
167
167
|
<resume-signal>Type "done" when authenticated</resume-signal>
|
|
168
168
|
</task>
|
|
169
169
|
|
|
170
|
-
<!-- After auth,
|
|
170
|
+
<!-- After auth, OpenCode retries automatically -->
|
|
171
171
|
<task type="auto">
|
|
172
172
|
<name>Retry deployment</name>
|
|
173
173
|
<action>Run `vercel --yes` (now authenticated)</action>
|
|
@@ -175,14 +175,14 @@ Task [X] of [Y]: [Name]
|
|
|
175
175
|
```
|
|
176
176
|
|
|
177
177
|
**Key distinction:**
|
|
178
|
-
- Pre-planned checkpoint: "I need you to do X" (wrong -
|
|
178
|
+
- Pre-planned checkpoint: "I need you to do X" (wrong - OpenCode should automate)
|
|
179
179
|
- Auth gate: "I tried to automate X but need credentials" (correct - unblocks automation)
|
|
180
180
|
|
|
181
181
|
</authentication_gates>
|
|
182
182
|
|
|
183
183
|
<automation_reference>
|
|
184
184
|
|
|
185
|
-
**The rule:** If it has CLI/API,
|
|
185
|
+
**The rule:** If it has CLI/API, OpenCode does it. Never ask human to perform automatable work.
|
|
186
186
|
|
|
187
187
|
| Service | CLI/API | Key Commands | Auth Gate |
|
|
188
188
|
|---------|---------|--------------|-----------|
|
|
@@ -197,15 +197,15 @@ Task [X] of [Y]: [Name]
|
|
|
197
197
|
| Node | `npm`/`pnpm` | `install`, `run build`, `test` | N/A |
|
|
198
198
|
| Xcode | `xcodebuild` | `-project`, `-scheme`, `build`, `test` | N/A |
|
|
199
199
|
|
|
200
|
-
**Env files:** Use
|
|
200
|
+
**Env files:** Use write/edit tools. Never ask human to create .env manually.
|
|
201
201
|
|
|
202
202
|
**Quick reference:**
|
|
203
203
|
|
|
204
|
-
| Action | Automatable? |
|
|
204
|
+
| Action | Automatable? | OpenCode does it? |
|
|
205
205
|
|--------|--------------|-----------------|
|
|
206
206
|
| Deploy to Vercel | Yes (`vercel`) | YES |
|
|
207
207
|
| Create Stripe webhook | Yes (API) | YES |
|
|
208
|
-
| Write .env file | Yes (
|
|
208
|
+
| Write .env file | Yes (write/edit tools) | YES |
|
|
209
209
|
| Create Upstash DB | Yes (`upstash`) | YES |
|
|
210
210
|
| Run tests | Yes (`npm test`) | YES |
|
|
211
211
|
| Click email verification link | No | NO |
|
|
@@ -223,7 +223,7 @@ Task [X] of [Y]: [Name]
|
|
|
223
223
|
- Make verification executable
|
|
224
224
|
|
|
225
225
|
**DON'T:**
|
|
226
|
-
- Ask human to do work
|
|
226
|
+
- Ask human to do work OpenCode can automate
|
|
227
227
|
- Assume knowledge: "Configure the usual settings"
|
|
228
228
|
- Mix multiple verifications in one checkpoint
|
|
229
229
|
- Use checkpoints too frequently (verification fatigue)
|
|
@@ -256,7 +256,7 @@ Why bad: Vercel has CLI. Use `vercel --yes`.
|
|
|
256
256
|
```
|
|
257
257
|
Why bad: Verification fatigue. Combine into one checkpoint at end.
|
|
258
258
|
|
|
259
|
-
**GOOD:
|
|
259
|
+
**GOOD: OpenCode automates, human verifies once**
|
|
260
260
|
```xml
|
|
261
261
|
<task type="auto">Create schema</task>
|
|
262
262
|
<task type="auto">Create API</task>
|
|
@@ -272,16 +272,16 @@ Why bad: Verification fatigue. Combine into one checkpoint at end.
|
|
|
272
272
|
|
|
273
273
|
<summary>
|
|
274
274
|
|
|
275
|
-
**The golden rule:** If
|
|
275
|
+
**The golden rule:** If OpenCode CAN automate it, OpenCode MUST automate it.
|
|
276
276
|
|
|
277
277
|
**Checkpoint priority:**
|
|
278
|
-
1. **checkpoint:human-verify** (90%) -
|
|
278
|
+
1. **checkpoint:human-verify** (90%) - OpenCode automated, human confirms visual/functional correctness
|
|
279
279
|
2. **checkpoint:decision** (9%) - Human makes architectural/technology choices
|
|
280
280
|
3. **checkpoint:human-action** (1%) - Truly unavoidable manual steps with no API/CLI
|
|
281
281
|
|
|
282
282
|
**When NOT to use checkpoints:**
|
|
283
|
-
- Things
|
|
284
|
-
- File operations (
|
|
283
|
+
- Things OpenCode can verify programmatically (tests, builds)
|
|
284
|
+
- File operations (OpenCode can read/write)
|
|
285
285
|
- Anything with CLI/API available
|
|
286
286
|
|
|
287
287
|
</summary>
|
|
@@ -13,7 +13,7 @@ Standard format for presenting next steps after completing a command or workflow
|
|
|
13
13
|
|
|
14
14
|
`{command to copy-paste}`
|
|
15
15
|
|
|
16
|
-
*`/
|
|
16
|
+
*`/new` first → fresh context window*
|
|
17
17
|
|
|
18
18
|
---
|
|
19
19
|
|
|
@@ -29,7 +29,7 @@ Standard format for presenting next steps after completing a command or workflow
|
|
|
29
29
|
1. **Always show what it is** — name + description, never just a command path
|
|
30
30
|
2. **Pull context from source** — ROADMAP.md for phases, PLAN.md `<objective>` for plans
|
|
31
31
|
3. **Command in inline code** — backticks, easy to copy-paste, renders as clickable link
|
|
32
|
-
4. **`/
|
|
32
|
+
4. **`/new` explanation** — always include, keeps it concise but explains why
|
|
33
33
|
5. **"Also available" not "Other options"** — sounds more app-like
|
|
34
34
|
6. **Visual separators** — `---` above and below to make it stand out
|
|
35
35
|
|
|
@@ -46,7 +46,7 @@ Standard format for presenting next steps after completing a command or workflow
|
|
|
46
46
|
|
|
47
47
|
`/gsd-execute-plan .planning/phases/02-auth/02-03-PLAN.md`
|
|
48
48
|
|
|
49
|
-
*`/
|
|
49
|
+
*`/new` first → fresh context window*
|
|
50
50
|
|
|
51
51
|
---
|
|
52
52
|
|
|
@@ -71,7 +71,7 @@ Add note that this is the last plan and what comes after:
|
|
|
71
71
|
|
|
72
72
|
`/gsd-execute-plan .planning/phases/02-auth/02-03-PLAN.md`
|
|
73
73
|
|
|
74
|
-
*`/
|
|
74
|
+
*`/new` first → fresh context window*
|
|
75
75
|
|
|
76
76
|
---
|
|
77
77
|
|
|
@@ -93,7 +93,7 @@ Add note that this is the last plan and what comes after:
|
|
|
93
93
|
|
|
94
94
|
`/gsd-plan-phase 2`
|
|
95
95
|
|
|
96
|
-
*`/
|
|
96
|
+
*`/new` first → fresh context window*
|
|
97
97
|
|
|
98
98
|
---
|
|
99
99
|
|
|
@@ -122,7 +122,7 @@ Show completion status before next action:
|
|
|
122
122
|
|
|
123
123
|
`/gsd-plan-phase 3`
|
|
124
124
|
|
|
125
|
-
*`/
|
|
125
|
+
*`/new` first → fresh context window*
|
|
126
126
|
|
|
127
127
|
---
|
|
128
128
|
|
|
@@ -151,7 +151,7 @@ When there's no clear primary action:
|
|
|
151
151
|
|
|
152
152
|
**To research unknowns:** `/gsd-research-phase 3`
|
|
153
153
|
|
|
154
|
-
*`/
|
|
154
|
+
*`/new` first → fresh context window*
|
|
155
155
|
|
|
156
156
|
---
|
|
157
157
|
```
|
|
@@ -171,7 +171,7 @@ All 4 phases shipped
|
|
|
171
171
|
|
|
172
172
|
`/gsd-discuss-milestone`
|
|
173
173
|
|
|
174
|
-
*`/
|
|
174
|
+
*`/new` first → fresh context window*
|
|
175
175
|
|
|
176
176
|
---
|
|
177
177
|
|
|
@@ -219,18 +219,18 @@ Extract: `**02-03: Refresh Token Rotation** — Add /api/auth/refresh with slidi
|
|
|
219
219
|
```
|
|
220
220
|
## To Continue
|
|
221
221
|
|
|
222
|
-
Run `/
|
|
222
|
+
Run `/new`, then paste:
|
|
223
223
|
/gsd-execute-plan .planning/phases/02-auth/02-03-PLAN.md
|
|
224
224
|
```
|
|
225
225
|
|
|
226
226
|
User has no idea what 02-03 is about.
|
|
227
227
|
|
|
228
|
-
### Don't: Missing /
|
|
228
|
+
### Don't: Missing /new explanation
|
|
229
229
|
|
|
230
230
|
```
|
|
231
231
|
`/gsd-plan-phase 3`
|
|
232
232
|
|
|
233
|
-
Run /
|
|
233
|
+
Run /new first.
|
|
234
234
|
```
|
|
235
235
|
|
|
236
236
|
Doesn't explain why. User might skip it.
|
|
@@ -231,14 +231,14 @@ Each plan produces 2-4 commits (tasks + metadata). Clear, granular, bisectable.
|
|
|
231
231
|
## Why Per-Task Commits?
|
|
232
232
|
|
|
233
233
|
**Context engineering for AI:**
|
|
234
|
-
- Git history becomes primary context source for future
|
|
234
|
+
- Git history becomes primary context source for future OpenCode sessions
|
|
235
235
|
- `git log --grep="{phase}-{plan}"` shows all work for a plan
|
|
236
236
|
- `git diff <hash>^..<hash>` shows exact changes per task
|
|
237
237
|
- Less reliance on parsing SUMMARY.md = more context for actual work
|
|
238
238
|
|
|
239
239
|
**Failure recovery:**
|
|
240
240
|
- Task 1 committed ✅, Task 2 failed ❌
|
|
241
|
-
-
|
|
241
|
+
- OpenCode in next session: sees task 1 complete, can retry task 2
|
|
242
242
|
- Can `git reset --hard` to last successful task
|
|
243
243
|
|
|
244
244
|
**Debugging:**
|
|
@@ -247,8 +247,8 @@ Each plan produces 2-4 commits (tasks + metadata). Clear, granular, bisectable.
|
|
|
247
247
|
- Each commit is independently revertable
|
|
248
248
|
|
|
249
249
|
**Observability:**
|
|
250
|
-
- Solo developer +
|
|
250
|
+
- Solo developer + OpenCode workflow benefits from granular attribution
|
|
251
251
|
- Atomic commits are git best practice
|
|
252
|
-
- "Commit noise" irrelevant when consumer is
|
|
252
|
+
- "Commit noise" irrelevant when consumer is OpenCode, not humans
|
|
253
253
|
|
|
254
254
|
</commit_strategy_rationale>
|
|
@@ -1,13 +1,13 @@
|
|
|
1
1
|
<overview>
|
|
2
|
-
|
|
2
|
+
OpenCode-executable plans have a specific format that enables OpenCode to implement without interpretation. This reference defines what makes a plan executable vs. vague.
|
|
3
3
|
|
|
4
|
-
**Key insight:** PLAN.md IS the executable prompt. It contains everything
|
|
4
|
+
**Key insight:** PLAN.md IS the executable prompt. It contains everything OpenCode needs to execute the phase, including objective, context references, tasks, verification, success criteria, and output specification.
|
|
5
5
|
</overview>
|
|
6
6
|
|
|
7
7
|
<core_principle>
|
|
8
|
-
A plan is
|
|
8
|
+
A plan is OpenCode-executable when OpenCode can read the PLAN.md and immediately start implementing without asking clarifying questions.
|
|
9
9
|
|
|
10
|
-
If
|
|
10
|
+
If OpenCode has to guess, interpret, or make assumptions - the task is too vague.
|
|
11
11
|
</core_principle>
|
|
12
12
|
|
|
13
13
|
<frontmatter>
|
|
@@ -88,7 +88,7 @@ Output: [...]
|
|
|
88
88
|
</task>
|
|
89
89
|
|
|
90
90
|
<task type="checkpoint:human-verify" gate="blocking">
|
|
91
|
-
<what-built>[what
|
|
91
|
+
<what-built>[what OpenCode automated]</what-built>
|
|
92
92
|
<how-to-verify>[numbered verification steps]</how-to-verify>
|
|
93
93
|
<resume-signal>[how to continue - "approved" or describe issues]</resume-signal>
|
|
94
94
|
</task>
|
|
@@ -170,7 +170,7 @@ Should be testable without subjective judgment.
|
|
|
170
170
|
Tasks have a `type` attribute that determines how they execute:
|
|
171
171
|
|
|
172
172
|
<type name="auto">
|
|
173
|
-
**Default task type** -
|
|
173
|
+
**Default task type** - OpenCode executes autonomously.
|
|
174
174
|
|
|
175
175
|
**Structure:**
|
|
176
176
|
|
|
@@ -184,11 +184,11 @@ Tasks have a `type` attribute that determines how they execute:
|
|
|
184
184
|
</task>
|
|
185
185
|
```
|
|
186
186
|
|
|
187
|
-
Use for: Everything
|
|
187
|
+
Use for: Everything OpenCode can do independently (code, tests, builds, file operations).
|
|
188
188
|
</type>
|
|
189
189
|
|
|
190
190
|
<type name="checkpoint:human-action">
|
|
191
|
-
**RARELY USED** - Only for actions with NO CLI/API.
|
|
191
|
+
**RARELY USED** - Only for actions with NO CLI/API. OpenCode automates everything possible first.
|
|
192
192
|
|
|
193
193
|
**Structure:**
|
|
194
194
|
|
|
@@ -196,10 +196,10 @@ Use for: Everything Opencode agent can do independently (code, tests, builds, fi
|
|
|
196
196
|
<task type="checkpoint:human-action" gate="blocking">
|
|
197
197
|
<action>[Unavoidable manual step - email link, 2FA code]</action>
|
|
198
198
|
<instructions>
|
|
199
|
-
[What
|
|
199
|
+
[What OpenCode already automated]
|
|
200
200
|
[The ONE thing requiring human action]
|
|
201
201
|
</instructions>
|
|
202
|
-
<verification>[What
|
|
202
|
+
<verification>[What OpenCode can check afterward]</verification>
|
|
203
203
|
<resume-signal>[How to continue]</resume-signal>
|
|
204
204
|
</task>
|
|
205
205
|
```
|
|
@@ -208,11 +208,11 @@ Use ONLY for: Email verification links, SMS 2FA codes, manual approvals with no
|
|
|
208
208
|
|
|
209
209
|
Do NOT use for: Anything with a CLI (Vercel, Stripe, Upstash, Railway, GitHub), builds, tests, file creation, deployments.
|
|
210
210
|
|
|
211
|
-
**Execution:**
|
|
211
|
+
**Execution:** OpenCode automates everything with CLI/API, stops only for truly unavoidable manual steps.
|
|
212
212
|
</type>
|
|
213
213
|
|
|
214
214
|
<type name="checkpoint:human-verify">
|
|
215
|
-
**Human must verify
|
|
215
|
+
**Human must verify OpenCode's work** - Visual checks, UX testing.
|
|
216
216
|
|
|
217
217
|
**Structure:**
|
|
218
218
|
|
|
@@ -233,7 +233,7 @@ Do NOT use for: Anything with a CLI (Vercel, Stripe, Upstash, Railway, GitHub),
|
|
|
233
233
|
|
|
234
234
|
Use for: UI/UX verification, visual design checks, animation smoothness, accessibility testing.
|
|
235
235
|
|
|
236
|
-
**Execution:**
|
|
236
|
+
**Execution:** OpenCode builds the feature, stops, provides testing instructions, waits for approval/feedback.
|
|
237
237
|
</type>
|
|
238
238
|
|
|
239
239
|
<type name="checkpoint:decision">
|
|
@@ -268,23 +268,23 @@ Use for: UI/UX verification, visual design checks, animation smoothness, accessi
|
|
|
268
268
|
|
|
269
269
|
Use for: Technology selection, architecture decisions, design choices, feature prioritization.
|
|
270
270
|
|
|
271
|
-
**Execution:**
|
|
271
|
+
**Execution:** OpenCode presents options with balanced pros/cons, waits for decision, proceeds with chosen direction.
|
|
272
272
|
</type>
|
|
273
273
|
|
|
274
274
|
**When to use checkpoints:**
|
|
275
275
|
|
|
276
|
-
- Visual/UX verification (after
|
|
276
|
+
- Visual/UX verification (after OpenCode builds) → `checkpoint:human-verify`
|
|
277
277
|
- Implementation direction choice → `checkpoint:decision`
|
|
278
278
|
- Truly unavoidable manual actions (email links, 2FA) → `checkpoint:human-action` (rare)
|
|
279
279
|
|
|
280
280
|
**When NOT to use checkpoints:**
|
|
281
281
|
|
|
282
|
-
- Anything with CLI/API (
|
|
282
|
+
- Anything with CLI/API (OpenCode automates it) → `type="auto"`
|
|
283
283
|
- Deployments (Vercel, Railway, Fly) → `type="auto"` with CLI
|
|
284
284
|
- Creating resources (Upstash, Stripe, GitHub) → `type="auto"` with CLI/API
|
|
285
285
|
- File operations, tests, builds → `type="auto"`
|
|
286
286
|
|
|
287
|
-
**Golden rule:** If
|
|
287
|
+
**Golden rule:** If OpenCode CAN automate it, OpenCode MUST automate it.
|
|
288
288
|
|
|
289
289
|
**Checkpoint impact on parallelization:**
|
|
290
290
|
- Plans with checkpoints set `autonomous: false` in frontmatter
|
|
@@ -341,7 +341,7 @@ Use @file references to load context for the prompt:
|
|
|
341
341
|
</context>
|
|
342
342
|
```
|
|
343
343
|
|
|
344
|
-
Reference files that
|
|
344
|
+
Reference files that OpenCode needs to understand before implementing.
|
|
345
345
|
|
|
346
346
|
**Anti-pattern:** Reflexive chaining (02 refs 01, 03 refs 02). Only reference what you actually need.
|
|
347
347
|
</context_references>
|
|
@@ -401,7 +401,7 @@ After completion, create `.planning/phases/XX-name/{phase}-{plan}-SUMMARY.md`
|
|
|
401
401
|
</task>
|
|
402
402
|
```
|
|
403
403
|
|
|
404
|
-
|
|
404
|
+
OpenCode: "How? What type? What library? Where?"
|
|
405
405
|
</too_vague>
|
|
406
406
|
|
|
407
407
|
<just_right>
|
|
@@ -416,7 +416,7 @@ Claude: "How? What type? What library? Where?"
|
|
|
416
416
|
</task>
|
|
417
417
|
```
|
|
418
418
|
|
|
419
|
-
|
|
419
|
+
OpenCode can implement this immediately.
|
|
420
420
|
</just_right>
|
|
421
421
|
|
|
422
422
|
<note_on_tdd>
|
|
@@ -426,7 +426,7 @@ If email validation warrants TDD, create a TDD plan for it. See `./tdd.md` for T
|
|
|
426
426
|
</note_on_tdd>
|
|
427
427
|
|
|
428
428
|
<too_detailed>
|
|
429
|
-
Writing the actual code in the plan. Trust
|
|
429
|
+
Writing the actual code in the plan. Trust OpenCode to implement from clear instructions.
|
|
430
430
|
</too_detailed>
|
|
431
431
|
</specificity_levels>
|
|
432
432
|
|
|
@@ -438,7 +438,7 @@ Writing the actual code in the plan. Trust Opencode agent to implement from clea
|
|
|
438
438
|
- "Make it production-ready"
|
|
439
439
|
- "Add proper error handling"
|
|
440
440
|
|
|
441
|
-
These require
|
|
441
|
+
These require OpenCode to decide WHAT to do. Specify it.
|
|
442
442
|
</vague_actions>
|
|
443
443
|
|
|
444
444
|
<unverifiable_completion>
|
|
@@ -457,12 +457,12 @@ These require subjective judgment. Make it objective.
|
|
|
457
457
|
- "Follow best practices"
|
|
458
458
|
- "Like the other endpoints"
|
|
459
459
|
|
|
460
|
-
|
|
460
|
+
OpenCode doesn't know your standards. Be explicit.
|
|
461
461
|
</missing_context>
|
|
462
462
|
</anti_patterns>
|
|
463
463
|
|
|
464
464
|
<sizing_tasks>
|
|
465
|
-
Good task size: 15-60 minutes of
|
|
465
|
+
Good task size: 15-60 minutes of OpenCode work.
|
|
466
466
|
|
|
467
467
|
**Too small**: "Add import statement for bcrypt" (combine with related task)
|
|
468
468
|
**Just right**: "Create login endpoint with JWT validation" (focused, specific)
|