@kafka0102/onespec 0.1.2 → 0.2.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/README.md +45 -48
- package/assets/skills/onespec/SKILL.md +22 -14
- package/assets/skills/onespec/references/archive.md +214 -0
- package/assets/skills/{onespec-design/SKILL.md → onespec/references/design.md} +55 -51
- package/assets/skills/onespec/references/execute.md +291 -0
- package/assets/skills/onespec/references/fast.md +110 -0
- package/assets/skills/onespec/scripts/onespec-closeout.sh +238 -77
- package/assets/skills/onespec/scripts/onespec-commit.sh +191 -11
- package/assets/skills/onespec/scripts/onespec-handoff.sh +19 -6
- package/assets/skills/onespec/scripts/onespec-state.sh +157 -18
- package/assets/skills/onespec-fast/SKILL.md +22 -0
- package/assets/skills/onespec-fast/agents/openai.yaml +4 -0
- package/assets/skills-en/onespec/SKILL.md +22 -13
- package/assets/skills-en/onespec/references/archive.md +213 -0
- package/assets/skills-en/{onespec-design/SKILL.md → onespec/references/design.md} +58 -43
- package/assets/skills-en/onespec/references/execute.md +291 -0
- package/assets/skills-en/onespec/references/fast.md +110 -0
- package/assets/skills-en/onespec-fast/SKILL.md +22 -0
- package/package.json +10 -3
- package/scripts/postinstall.js +3 -3
- package/src/cli.js +120 -110
- package/src/doctor.js +46 -20
- package/src/init.js +24 -10
- package/src/platforms.js +88 -8
- package/src/setup.js +211 -0
- package/assets/skills/onespec-archive/SKILL.md +0 -202
- package/assets/skills/onespec-execute/SKILL.md +0 -219
- package/assets/skills-en/onespec-archive/SKILL.md +0 -199
- package/assets/skills-en/onespec-execute/SKILL.md +0 -219
|
@@ -0,0 +1,291 @@
|
|
|
1
|
+
# Execute Phase
|
|
2
|
+
|
|
3
|
+
Read on demand from `onespec` during the `apply` phase. The goal is to implement only within approved scope and sync the outcome back into OpenSpec state.
|
|
4
|
+
|
|
5
|
+
## 1. Apply Routing
|
|
6
|
+
|
|
7
|
+
Recover state first:
|
|
8
|
+
|
|
9
|
+
```bash
|
|
10
|
+
ONESPEC_ENV="${ONESPEC_ENV:-$(find . "$HOME"/.codex "$HOME"/.claude "$HOME"/.cursor "$HOME"/.gemini "$HOME"/.copilot "$HOME"/.agents "$HOME"/.config -path '*/onespec/scripts/onespec-env.sh' -type f -print -quit 2>/dev/null)}"
|
|
11
|
+
. "$ONESPEC_ENV"
|
|
12
|
+
"$ONESPEC_BASH" "$ONESPEC_STATE" list
|
|
13
|
+
```
|
|
14
|
+
|
|
15
|
+
If a relevant change exists, you must continue with:
|
|
16
|
+
|
|
17
|
+
```bash
|
|
18
|
+
"$ONESPEC_BASH" "$ONESPEC_STATE" recover <change-id>
|
|
19
|
+
```
|
|
20
|
+
|
|
21
|
+
Treat `recover` output as the current phase contract, not as reference information. Read at least `phase`, `next_skill`, `next_reference`, `next_gate`, and `allowed_actions` before deciding whether to continue execution-phase work.
|
|
22
|
+
|
|
23
|
+
Before apply, read at least:
|
|
24
|
+
|
|
25
|
+
- `openspec/changes/<change-id>/proposal.md`
|
|
26
|
+
- `openspec/changes/<change-id>/tasks.md`
|
|
27
|
+
- `openspec/changes/<change-id>/design.md`, if present
|
|
28
|
+
- relevant `openspec/specs/**`
|
|
29
|
+
- relevant `docs/**`
|
|
30
|
+
|
|
31
|
+
Default intent mapping:
|
|
32
|
+
|
|
33
|
+
- Requests like "start implementation", "execute this change", "apply this proposal/change", "continue this change", "start coding/development", or "make plan" default to the Superpowers implementation-prep route for an approved change, not direct native `openspec apply`.
|
|
34
|
+
- Only allow native `OpenSpec apply` if the user explicitly says "do not use Superpowers plan", "do not use subagents", or "just use OpenSpec apply".
|
|
35
|
+
- If the proposal phase already confirmed the implementation route, honor that prior decision instead of overriding it with default mapping.
|
|
36
|
+
|
|
37
|
+
If the proposal is not approved yet, stop immediately.
|
|
38
|
+
|
|
39
|
+
### 1.1 User Confirmation Request Rules
|
|
40
|
+
|
|
41
|
+
When execution requires the user to confirm the implementation path, workspace policy, continued implementation, return to design revision, or post-completion closeout action, render "user choice required" as a standalone block titled `User Confirmation Request`. Do not mix conclusions, verification results, recommendations, and pending confirmation into one paragraph.
|
|
42
|
+
|
|
43
|
+
The confirmation block must include:
|
|
44
|
+
|
|
45
|
+
- one explicit instruction: `Reply with a number.`
|
|
46
|
+
- 2-6 numbered options, with item 1 usually marked as `Recommended`
|
|
47
|
+
- `Other:` explaining how non-numbered content will be handled, usually as continued implementation work or extra constraints
|
|
48
|
+
- if the user adds constraints but still has not made a clear choice, continue presenting updated numbered options until the user chooses, stops, or explicitly tells you to continue
|
|
49
|
+
|
|
50
|
+
If the platform provides structured question UI such as `ask user questions`, `request_user_input`, or an equivalent mechanism, prefer that for these numbered options. If no such mechanism is available, render the `User Confirmation Request` block in the normal message. In either form, do not end with only a sentence like "the next step is that phase" or "I recommend this path."
|
|
51
|
+
|
|
52
|
+
If the proposal phase already confirmed the implementation path:
|
|
53
|
+
|
|
54
|
+
- user chose `Superpowers`: continue into Superpowers Make Plan.
|
|
55
|
+
- user chose native `OpenSpec apply`: switch to native apply.
|
|
56
|
+
- user still has not confirmed: restate the recommendation and require a numbered choice before implementation starts.
|
|
57
|
+
|
|
58
|
+
If execution-time route confirmation is still needed, first detect whether the current checkout is already an attached git worktree, then use the matching numbered menu. The user may reply with digits.
|
|
59
|
+
|
|
60
|
+
When not currently inside an attached worktree:
|
|
61
|
+
1. continue with the recommended combination
|
|
62
|
+
2. switch to `Superpowers + subagent + new worktree`
|
|
63
|
+
3. switch to `Superpowers + local + new worktree`
|
|
64
|
+
4. switch to `Superpowers + local + current branch`
|
|
65
|
+
5. switch to native `OpenSpec apply + native + current branch`
|
|
66
|
+
6. do not start implementation yet; go back and revise proposal / design / tasks
|
|
67
|
+
|
|
68
|
+
When already inside an attached worktree:
|
|
69
|
+
1. continue with the recommended combination
|
|
70
|
+
2. switch to `Superpowers + subagent + current worktree/current branch`
|
|
71
|
+
3. switch to `Superpowers + local + current worktree/current branch`
|
|
72
|
+
4. switch to native `OpenSpec apply + native + current worktree/current branch`
|
|
73
|
+
5. do not start implementation yet; go back and revise proposal / design / tasks
|
|
74
|
+
Other: if intent is not covered by the menu, allow free-form instructions
|
|
75
|
+
|
|
76
|
+
Menu handling rules:
|
|
77
|
+
|
|
78
|
+
- reply `1`: use the current recommended combination; do not ask a second round for `subagent/local` or `worktree/current-branch`
|
|
79
|
+
- when not currently inside an attached worktree, reply `2`: record `implementation_path=superpowers`, `execution_method=subagent`, and `workspace=worktree`
|
|
80
|
+
- when not currently inside an attached worktree, reply `3`: record `implementation_path=superpowers`, `execution_method=local`, and `workspace=worktree`
|
|
81
|
+
- when not currently inside an attached worktree, reply `4`: record `implementation_path=superpowers`, `execution_method=local`, and `workspace=current-branch`
|
|
82
|
+
- when not currently inside an attached worktree, reply `5`: record `implementation_path=openspec-apply`, `execution_method=native`, and `workspace=current-branch`
|
|
83
|
+
- when not currently inside an attached worktree, reply `6`: stop execution and return to design revision
|
|
84
|
+
- when already inside an attached worktree, reply `2`: record `implementation_path=superpowers`, `execution_method=subagent`, and `workspace=current-branch`
|
|
85
|
+
- when already inside an attached worktree, reply `3`: record `implementation_path=superpowers`, `execution_method=local`, and `workspace=current-branch`
|
|
86
|
+
- when already inside an attached worktree, reply `4`: record `implementation_path=openspec-apply`, `execution_method=native`, and `workspace=current-branch`
|
|
87
|
+
- when already inside an attached worktree, reply `5`: stop execution and return to design revision
|
|
88
|
+
- free-form text instead of digits: if intent is clear, follow it; otherwise ask one minimal clarification question
|
|
89
|
+
|
|
90
|
+
## 2. Superpowers Make Plan and Execution
|
|
91
|
+
|
|
92
|
+
On the Superpowers path, apply does not mean "start coding immediately". First translate the approved OpenSpec change into an executable Superpowers plan.
|
|
93
|
+
|
|
94
|
+
Must do:
|
|
95
|
+
|
|
96
|
+
- read and summarize `proposal.md`, `design.md`, `tasks.md`, relevant spec deltas, and relevant project docs
|
|
97
|
+
- extract incomplete tasks from `tasks.md` as the planning scope
|
|
98
|
+
- use `writing-plans` or `superpowers:writing-plans` to generate a plan at `docs/superpowers/plans/YYYY-MM-DD-<change-id>.md`
|
|
99
|
+
- ensure the plan covers every incomplete OpenSpec task; it may split tasks further but may not omit or expand scope
|
|
100
|
+
- if a matching plan already exists, verify that it still covers the current incomplete tasks; update or rewrite it otherwise
|
|
101
|
+
- if the plan conflicts with approved OpenSpec artifacts, fix the OpenSpec artifacts first, then rewrite the plan
|
|
102
|
+
- from the start of implementation until review, maintain `openspec/changes/<change-id>/.onespec.yaml` as the only runtime state file; store only the repo-relative paths directly changed for this change in its `touched_files_b64` field; prefer:
|
|
103
|
+
|
|
104
|
+
```bash
|
|
105
|
+
"$ONESPEC_BASH" "$ONESPEC_COMMIT" track <change-id> <path>...
|
|
106
|
+
```
|
|
107
|
+
|
|
108
|
+
- do not add pre-existing dirty files that are unrelated to the current change into that tracked-file list
|
|
109
|
+
- if you generate a temporary zip, export bundle, or other change-local artifact under `openspec/changes/<change-id>/`, keep it as part of the current change until archive; it does not need a separate `touched_files_b64` entry, but auto-commit must include it together with `.onespec.yaml`
|
|
110
|
+
- if auto-commit happens later, `.onespec.yaml` itself must be committed with the change while it is dirty; it is not a disposable file before archive
|
|
111
|
+
|
|
112
|
+
Record the plan and create handoff:
|
|
113
|
+
|
|
114
|
+
```bash
|
|
115
|
+
"$ONESPEC_BASH" "$ONESPEC_STATE" set <change-id> plan <plan-path>
|
|
116
|
+
"$ONESPEC_BASH" "$ONESPEC_STATE" set <change-id> phase plan-ready
|
|
117
|
+
"$ONESPEC_BASH" "$ONESPEC_HANDOFF" <change-id> plan --write
|
|
118
|
+
```
|
|
119
|
+
|
|
120
|
+
Before writing code, running native apply, or dispatching sub-work, move state into `phase implementing`:
|
|
121
|
+
|
|
122
|
+
```bash
|
|
123
|
+
"$ONESPEC_BASH" "$ONESPEC_STATE" set <change-id> phase implementing
|
|
124
|
+
```
|
|
125
|
+
|
|
126
|
+
If the change is still in `approved` or `plan-ready`, implementation has not formally started yet. Do not treat incidental edits as "continued implementation".
|
|
127
|
+
|
|
128
|
+
If `origin_branch` or `origin_workspace_path` is still `unknown`, fill them in immediately before creating a worktree, switching branches, or starting implementation:
|
|
129
|
+
|
|
130
|
+
```bash
|
|
131
|
+
"$ONESPEC_BASH" "$ONESPEC_STATE" set <change-id> origin_branch "$(git branch --show-current || echo detached)"
|
|
132
|
+
"$ONESPEC_BASH" "$ONESPEC_STATE" set <change-id> origin_workspace_path "$(pwd -P)"
|
|
133
|
+
"$ONESPEC_BASH" "$ONESPEC_STATE" set <change-id> origin_workspace_mode "$( "$ONESPEC_BASH" "$ONESPEC_STATE" get <change-id> workspace )"
|
|
134
|
+
```
|
|
135
|
+
|
|
136
|
+
If the next step is to create a temporary worktree from the current branch, check for uncommitted changes first:
|
|
137
|
+
|
|
138
|
+
- if the current workspace is dirty, handle those changes before creating the worktree
|
|
139
|
+
- if the current branch is `main`/`master` and has uncommitted changes, require a local commit that follows the project commit policy before creating the worktree; do not carry dirty base-branch code straight into a new implementation branch
|
|
140
|
+
- if the user refuses to commit the current dirty changes first, do not continue creating the worktree; pause, or switch to `current-branch` with an explicit risk callout
|
|
141
|
+
|
|
142
|
+
### 2.1 Implementation Workspace Binding
|
|
143
|
+
|
|
144
|
+
After creating or selecting the implementation worktree, immediately bind the absolute implementation workspace path as `implementation_workspace_path`, and verify that it is the working directory for subsequent commands before writing the plan:
|
|
145
|
+
|
|
146
|
+
```bash
|
|
147
|
+
implementation_workspace_path="$(pwd -P)"
|
|
148
|
+
git -C "$implementation_workspace_path" status --short
|
|
149
|
+
```
|
|
150
|
+
|
|
151
|
+
- If `workspace=worktree`, enter the new worktree first, then set `implementation_workspace_path`; do not keep generating the plan in the origin workspace.
|
|
152
|
+
- If `workspace=current-branch`, or if the current checkout is already an attached worktree, `implementation_workspace_path` is the current `pwd -P`.
|
|
153
|
+
- Every OpenSpec artifact read, Superpowers plan write, `.onespec.yaml` update, handoff generation, and implementation command must run with the implementation workspace as the working directory.
|
|
154
|
+
- The plan path `docs/superpowers/plans/YYYY-MM-DD-<change-id>.md` is always relative to `implementation_workspace_path`. Do not write the plan in the origin workspace and then copy it into the implementation worktree.
|
|
155
|
+
- Before recording the plan and handoff, run `git -C "$implementation_workspace_path" status --short` to confirm that the plan and `.onespec.yaml` are in the same implementation workspace.
|
|
156
|
+
|
|
157
|
+
Default execution path:
|
|
158
|
+
|
|
159
|
+
- prefer `subagent-driven-development`
|
|
160
|
+
- when dispatching subagents per task, enforce `test-driven-development`
|
|
161
|
+
- after every task, the controller reviews spec compliance and code quality before moving on
|
|
162
|
+
- if the user explicitly rejects subagents, or the work is too tightly coupled for task-wise dispatch, explain why and switch to `executing-plans`
|
|
163
|
+
- use `using-git-worktrees` when isolation is needed; do not bypass its safety checks manually
|
|
164
|
+
|
|
165
|
+
After implementation, always sync OpenSpec artifacts:
|
|
166
|
+
|
|
167
|
+
- check off completed tasks in `tasks.md`
|
|
168
|
+
- if the Superpowers plan split one OpenSpec task into smaller steps, only mark the OpenSpec task done after implementation, testing, and any necessary review for that task are complete
|
|
169
|
+
- if implementation changed approved facts, update `design.md`, `proposal.md`, or spec deltas before proceeding
|
|
170
|
+
- do not let implementation silently drift away from approved OpenSpec scope
|
|
171
|
+
- run project tests and `openspec validate <change-id> --strict`
|
|
172
|
+
|
|
173
|
+
## 3. Native OpenSpec Apply
|
|
174
|
+
|
|
175
|
+
Only use native `OpenSpec apply` when the user chooses it, accepts the low-complexity recommendation, or explicitly rejects Superpowers.
|
|
176
|
+
|
|
177
|
+
After native apply, still do all of the following:
|
|
178
|
+
|
|
179
|
+
- check off `tasks.md`
|
|
180
|
+
- if new ambiguity or design conflict appears during implementation, stop and fix OpenSpec artifacts first; return to brainstorming if needed
|
|
181
|
+
- run project tests
|
|
182
|
+
- run `openspec validate <change-id> --strict`
|
|
183
|
+
- enter user review and pause with the same numbered next-step menu described above
|
|
184
|
+
- move state to `review`
|
|
185
|
+
|
|
186
|
+
## 4. Stop Conditions
|
|
187
|
+
|
|
188
|
+
Pause and explain if:
|
|
189
|
+
|
|
190
|
+
- proposal is not approved but the user asks to implement directly
|
|
191
|
+
- the Superpowers plan conflicts with approved OpenSpec artifacts
|
|
192
|
+
- `tasks.md` has not been translated into an executable Superpowers plan but the model is about to code anyway
|
|
193
|
+
- implementation reveals a new requirement that would change scope, design, or specs
|
|
194
|
+
- tests or `openspec validate <change-id> --strict` are failing and not yet fixed
|
|
195
|
+
|
|
196
|
+
## 5. Implementation-Complete Gate (Mandatory Pause)
|
|
197
|
+
|
|
198
|
+
> This gate is mandatory. If it is not satisfied, do not output a completion summary, do not give closeout suggestions, and do not enter the next phase.
|
|
199
|
+
|
|
200
|
+
After implementation and verification, the flow must pause explicitly. Do not continue directly into merge, worktree deletion, archive, or any implicit closeout. The goal here is to enter user-review / `review-closeout` waiting state. After development finishes, present the closeout action menu directly; do not require a separate review-confirmation step first and do not split archive into a second confirmation round.
|
|
201
|
+
|
|
202
|
+
### 5.1 Mandatory Script Calls
|
|
203
|
+
|
|
204
|
+
After artifacts are synced and tests pass, you must run:
|
|
205
|
+
|
|
206
|
+
```bash
|
|
207
|
+
"$ONESPEC_BASH" "$ONESPEC_STATE" set <change-id> phase review
|
|
208
|
+
"$ONESPEC_BASH" "$ONESPEC_HANDOFF" <change-id> review --write
|
|
209
|
+
```
|
|
210
|
+
|
|
211
|
+
If these two commands were not executed, the gate has not passed. Do not skip this and jump straight to the completion report.
|
|
212
|
+
|
|
213
|
+
### 5.2 Mandatory Report Checklist
|
|
214
|
+
|
|
215
|
+
After running those commands, the user-facing report must include all of the following:
|
|
216
|
+
|
|
217
|
+
1. current branch name
|
|
218
|
+
2. current workspace path
|
|
219
|
+
3. `origin_branch` and `origin_workspace_path`, including whether they match the current location
|
|
220
|
+
4. which Superpowers plan file was used
|
|
221
|
+
5. which OpenSpec tasks were completed
|
|
222
|
+
6. how `tasks.md` was synced back
|
|
223
|
+
7. whether `proposal.md`, `design.md`, or spec deltas changed
|
|
224
|
+
8. test results
|
|
225
|
+
9. `openspec validate <change-id> --strict` result
|
|
226
|
+
10. the numbered next-step menu, including that any non-numbered reply means continue modifying the current implementation
|
|
227
|
+
|
|
228
|
+
### 5.3 Numbered Next-Step Menu Template
|
|
229
|
+
|
|
230
|
+
Before generating the next-step menu, inspect the current closeout state with the script. Do not infer whether merge/worktree deletion is needed from branch names, path names, or intuition:
|
|
231
|
+
|
|
232
|
+
```bash
|
|
233
|
+
"$ONESPEC_BASH" "$ONESPEC_CLOSEOUT" recommend-actions <change-id>
|
|
234
|
+
```
|
|
235
|
+
|
|
236
|
+
Generate the menu from the inspected state:
|
|
237
|
+
|
|
238
|
+
- If `temporary_worktree: true`, the current implementation lives in a temporary worktree. The report must end with a menu equivalent to:
|
|
239
|
+
|
|
240
|
+
```text
|
|
241
|
+
---
|
|
242
|
+
Implementation and verification are complete.
|
|
243
|
+
|
|
244
|
+
Current branch: <branch>
|
|
245
|
+
Current workspace: <path>
|
|
246
|
+
Origin: <origin_branch> @ <origin_workspace_path>
|
|
247
|
+
|
|
248
|
+
1. Archive the current change, then merge the branch into the base branch
|
|
249
|
+
2. Archive only, without merging
|
|
250
|
+
3. Delete the current temporary worktree and discard the code
|
|
251
|
+
Other: any non-numbered content means continue modifying the current implementation; if the user gives no input, remain paused in the current review stage
|
|
252
|
+
---
|
|
253
|
+
```
|
|
254
|
+
|
|
255
|
+
- If `temporary_worktree: false`, the current implementation is already on the target branch/workspace and there is no temporary worktree to merge back or delete. Regardless of whether that branch is `main`, `master`, `develop`, `feature/*`, or any other name, do not show "merge the branch into the base branch" or "delete the current temporary worktree". In that case the closeout menu must collapse to a single archive-only option:
|
|
256
|
+
|
|
257
|
+
```text
|
|
258
|
+
---
|
|
259
|
+
Implementation and verification are complete.
|
|
260
|
+
|
|
261
|
+
Current branch: <branch>
|
|
262
|
+
Current workspace: <path>
|
|
263
|
+
Origin: <origin_branch> @ <origin_workspace_path>
|
|
264
|
+
|
|
265
|
+
1. Archive only (current checkout is not a temporary worktree; no branch merge or worktree deletion is needed)
|
|
266
|
+
Other: any non-numbered content means continue modifying the current implementation; if the user gives no input, remain paused in the current review stage
|
|
267
|
+
---
|
|
268
|
+
```
|
|
269
|
+
|
|
270
|
+
In other words, when `temporary_worktree: false`, do not prompt for branch merge or worktree deletion on any target branch.
|
|
271
|
+
|
|
272
|
+
If the script reports that the current branch or workspace differs from `origin_*`, add an explicit note that implementation currently lives in a temporary branch or temporary worktree and that any non-numbered reply will be treated as a request for more implementation work.
|
|
273
|
+
|
|
274
|
+
- If `temporary_worktree: true` and the user chooses `1`, archive phase must archive first, then merge the branch into the base branch, then delete the temporary worktree.
|
|
275
|
+
- If `temporary_worktree: true` and the user chooses `2`, archive phase must archive only, without merging and without auto-deleting the current worktree.
|
|
276
|
+
- If `temporary_worktree: true` and the user chooses `3`, archive phase must delete the temporary worktree and discard the code without archiving.
|
|
277
|
+
- If `temporary_worktree: false` and the user chooses `1`, archive phase must archive only; it must not merge a branch or delete any workspace/worktree.
|
|
278
|
+
|
|
279
|
+
Do not stop at an abstract note such as "the next step is archive phase" or just "do review-closeout". You must also give the user a concrete numbered menu.
|
|
280
|
+
|
|
281
|
+
### 5.4 Anti-Patterns (NEVER)
|
|
282
|
+
|
|
283
|
+
The following are gate violations:
|
|
284
|
+
|
|
285
|
+
- reporting "done" without first running the scripts in 5.1
|
|
286
|
+
- omitting current branch / workspace information from the report
|
|
287
|
+
- omitting a concrete numbered next-step menu
|
|
288
|
+
- executing archive, merge, or worktree-deletion actions before the user has chosen one
|
|
289
|
+
- entering archive phase before the user replies
|
|
290
|
+
- replacing the concrete numbered menu with an abstract "next step is archive phase" statement
|
|
291
|
+
- deleting a temporary worktree before review is complete and the user explicitly asks for closeout
|
|
@@ -0,0 +1,110 @@
|
|
|
1
|
+
# Fast Path
|
|
2
|
+
|
|
3
|
+
Read on demand from `onespec` and the standalone `onespec-fast` entrypoint for the `fast` path. The goal is to skip the normal proposal approval gate, complexity check, implementation-path selection, and post-implementation archive choice. Once in the fast path, use native `OpenSpec apply` for the whole implementation and archive directly.
|
|
4
|
+
|
|
5
|
+
## 1. Intake
|
|
6
|
+
|
|
7
|
+
Recover state first:
|
|
8
|
+
|
|
9
|
+
```bash
|
|
10
|
+
ONESPEC_ENV="${ONESPEC_ENV:-$(find . "$HOME"/.codex "$HOME"/.claude "$HOME"/.cursor "$HOME"/.gemini "$HOME"/.copilot "$HOME"/.agents "$HOME"/.config -path '*/onespec/scripts/onespec-env.sh' -type f -print -quit 2>/dev/null)}"
|
|
11
|
+
. "$ONESPEC_ENV"
|
|
12
|
+
"$ONESPEC_BASH" "$ONESPEC_STATE" list
|
|
13
|
+
```
|
|
14
|
+
|
|
15
|
+
If a relevant change exists, run:
|
|
16
|
+
|
|
17
|
+
```bash
|
|
18
|
+
"$ONESPEC_BASH" "$ONESPEC_STATE" recover <change-id>
|
|
19
|
+
```
|
|
20
|
+
|
|
21
|
+
Treat `recover` output as the execution contract. Read at least `phase`, `next_skill`, `next_reference`, `next_gate`, and `allowed_actions`.
|
|
22
|
+
|
|
23
|
+
Use rules:
|
|
24
|
+
|
|
25
|
+
- Use only when the user explicitly asks for `onespec-fast`, the fast path, fast apply, automatic OpenSpec proposal/implementation/archive, or automatic end-to-end execution.
|
|
26
|
+
- Do not ask the user to name the change. Generate a short kebab-case `change-id`; append a numeric suffix if needed.
|
|
27
|
+
- Read the minimum needed context: `openspec/config.yaml`, relevant `openspec/specs/**`, project entry docs, current branch, and workspace state.
|
|
28
|
+
- Pause only when required OpenSpec context is too incomplete to produce a valid proposal, or project docs explicitly forbid automatic edits on the current branch.
|
|
29
|
+
|
|
30
|
+
## 2. Direct Proposal
|
|
31
|
+
|
|
32
|
+
The fast path skips the normal design phase pre-proposal user confirmation.
|
|
33
|
+
|
|
34
|
+
Create the OpenSpec proposal artifacts directly:
|
|
35
|
+
|
|
36
|
+
- `openspec/changes/<change-id>/proposal.md`
|
|
37
|
+
- `openspec/changes/<change-id>/design.md`, only when it has real technical value
|
|
38
|
+
- `openspec/changes/<change-id>/tasks.md`
|
|
39
|
+
- required `specs/**/spec.md`
|
|
40
|
+
|
|
41
|
+
Create state and handoff:
|
|
42
|
+
|
|
43
|
+
```bash
|
|
44
|
+
"$ONESPEC_BASH" "$ONESPEC_STATE" init <change-id>
|
|
45
|
+
"$ONESPEC_BASH" "$ONESPEC_STATE" set <change-id> phase proposal-ready
|
|
46
|
+
"$ONESPEC_BASH" "$ONESPEC_STATE" set <change-id> ambiguity low
|
|
47
|
+
"$ONESPEC_BASH" "$ONESPEC_HANDOFF" <change-id> proposal --write
|
|
48
|
+
```
|
|
49
|
+
|
|
50
|
+
Do not show the normal proposal approval menu. `onespec-fast` means the user has authorized continuing with native `OpenSpec apply` implementation and archive.
|
|
51
|
+
|
|
52
|
+
## 3. OpenSpec Automatic Apply and Archive
|
|
53
|
+
|
|
54
|
+
After proposal creation, do not run a complexity check and do not switch to a Superpowers plan/subagent. Record the fast path directly and start implementation:
|
|
55
|
+
|
|
56
|
+
```bash
|
|
57
|
+
"$ONESPEC_BASH" "$ONESPEC_STATE" set <change-id> implementation_path openspec-apply
|
|
58
|
+
"$ONESPEC_BASH" "$ONESPEC_STATE" set <change-id> execution_method native
|
|
59
|
+
"$ONESPEC_BASH" "$ONESPEC_STATE" set <change-id> workspace current-branch
|
|
60
|
+
"$ONESPEC_BASH" "$ONESPEC_STATE" set <change-id> origin_branch "$(git branch --show-current || echo detached)"
|
|
61
|
+
"$ONESPEC_BASH" "$ONESPEC_STATE" set <change-id> origin_workspace_path "$(pwd -P)"
|
|
62
|
+
"$ONESPEC_BASH" "$ONESPEC_STATE" set <change-id> origin_workspace_mode current-branch
|
|
63
|
+
"$ONESPEC_BASH" "$ONESPEC_STATE" set <change-id> phase approved
|
|
64
|
+
"$ONESPEC_BASH" "$ONESPEC_STATE" set <change-id> phase implementing
|
|
65
|
+
```
|
|
66
|
+
|
|
67
|
+
Implementation rules:
|
|
68
|
+
|
|
69
|
+
- Use native `OpenSpec apply`; do not create a Superpowers plan and do not dispatch subagents.
|
|
70
|
+
- Implement only incomplete tasks in `tasks.md`; do not expand proposal scope.
|
|
71
|
+
- Work in the current workspace; do not auto-create a worktree, auto-push, or auto-merge.
|
|
72
|
+
- If the current branch is `main`/`master`, record `origin_workspace_mode` as `main-override`, but pause only if project docs explicitly forbid direct edits on the main branch.
|
|
73
|
+
- Track directly modified repo-relative paths in `.onespec.yaml`; prefer:
|
|
74
|
+
|
|
75
|
+
```bash
|
|
76
|
+
"$ONESPEC_BASH" "$ONESPEC_COMMIT" track <change-id> <path>...
|
|
77
|
+
```
|
|
78
|
+
|
|
79
|
+
After implementation:
|
|
80
|
+
|
|
81
|
+
- Check off completed tasks in `tasks.md`.
|
|
82
|
+
- If implementation exposes a new design conflict, stop automatic implementation, fix OpenSpec artifacts, and stay on the OpenSpec proposal/apply path; switch to Superpowers only if the user explicitly asks.
|
|
83
|
+
- Run project tests.
|
|
84
|
+
- Run `openspec validate <change-id> --strict`.
|
|
85
|
+
- Write the review handoff, but do not pause for user review:
|
|
86
|
+
|
|
87
|
+
```bash
|
|
88
|
+
"$ONESPEC_BASH" "$ONESPEC_STATE" set <change-id> phase review
|
|
89
|
+
"$ONESPEC_BASH" "$ONESPEC_HANDOFF" <change-id> review --write
|
|
90
|
+
```
|
|
91
|
+
|
|
92
|
+
Then archive directly without showing the archive phase closeout menu:
|
|
93
|
+
|
|
94
|
+
```bash
|
|
95
|
+
"$ONESPEC_BASH" "$ONESPEC_COMMIT" related-dirty <change-id>
|
|
96
|
+
"$ONESPEC_BASH" "$ONESPEC_COMMIT" commit-related <change-id> closeout
|
|
97
|
+
"$ONESPEC_BASH" "$ONESPEC_CLOSEOUT" run-actions <change-id> archive-only
|
|
98
|
+
```
|
|
99
|
+
|
|
100
|
+
If `related-dirty` is empty, do not run `commit-related <change-id> closeout`. `run-actions` sets `phase archived` / `archive archived` and handles the post-archive commit plus runtime cleanup.
|
|
101
|
+
|
|
102
|
+
## 4. Stop Conditions
|
|
103
|
+
|
|
104
|
+
Pause if:
|
|
105
|
+
|
|
106
|
+
- required OpenSpec context is missing and a valid proposal cannot be written
|
|
107
|
+
- the request clearly spans multiple changes that should be split
|
|
108
|
+
- tests or `openspec validate <change-id> --strict` fail and cannot be fixed inside the approved scope
|
|
109
|
+
- implementation reveals scope expansion, design change, or spec semantic change
|
|
110
|
+
- project docs explicitly forbid automatic implementation or automatic archive on the current branch
|
|
@@ -0,0 +1,22 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: onespec-fast
|
|
3
|
+
description: Use when the user explicitly asks for the OneSpec fast path, onespec-fast, fast apply, automatic OpenSpec proposal/implementation/archive, or automatic end-to-end execution. This skill reuses `onespec/references/fast.md` and uses native OpenSpec apply throughout, with no complexity check and no Superpowers plan.
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# OneSpec Fast
|
|
7
|
+
|
|
8
|
+
This is the standalone entrypoint for the OneSpec fast path. It does not duplicate phase rules; it must reuse the main `onespec` skill's `references/fast.md`.
|
|
9
|
+
|
|
10
|
+
Announce at the start:
|
|
11
|
+
|
|
12
|
+
> I am using the `onespec-fast` fast path.
|
|
13
|
+
|
|
14
|
+
## Entry Rules
|
|
15
|
+
|
|
16
|
+
- Use only when the user explicitly asks for `onespec-fast`, the fast path, fast apply, automatic OpenSpec proposal/implementation/archive, or automatic end-to-end execution.
|
|
17
|
+
- First read the sibling `../onespec/SKILL.md` and follow its recovery-first, shared-constraint, and reference-loading rules.
|
|
18
|
+
- Then read `../onespec/references/fast.md` and execute those steps.
|
|
19
|
+
- If the sibling path is unavailable, locate `*/onespec/references/fast.md` under the current project, `$HOME/.codex`, `$HOME/.claude`, `$HOME/.cursor`, `$HOME/.gemini`, `$HOME/.copilot`, `$HOME/.agents`, or `$HOME/.config`. If still missing, stop and ask the user to rerun `onespec init --overwrite`.
|
|
20
|
+
- `references/fast.md` may reuse procedure sections from `design.md`, `execute.md`, and `archive.md`, but it overrides the normal proposal approval, review pause, and closeout-menu gates.
|
|
21
|
+
|
|
22
|
+
Do not restate the fast-path steps in `onespec-fast/SKILL.md`; the full rules live only in `onespec/references/fast.md`.
|
package/package.json
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@kafka0102/onespec",
|
|
3
|
-
"version": "0.
|
|
4
|
-
"description": "OpenSpec + Superpowers workflow skill installer for
|
|
3
|
+
"version": "0.2.2",
|
|
4
|
+
"description": "OpenSpec + Superpowers workflow skill installer for mainstream SKILL.md agents",
|
|
5
5
|
"repository": {
|
|
6
6
|
"type": "git",
|
|
7
7
|
"url": "git+https://github.com/kafka0102/onespec.git"
|
|
@@ -11,6 +11,10 @@
|
|
|
11
11
|
"superpowers",
|
|
12
12
|
"skills",
|
|
13
13
|
"codex",
|
|
14
|
+
"claude-code",
|
|
15
|
+
"cursor",
|
|
16
|
+
"gemini-cli",
|
|
17
|
+
"github-copilot",
|
|
14
18
|
"workflow"
|
|
15
19
|
],
|
|
16
20
|
"type": "module",
|
|
@@ -34,5 +38,8 @@
|
|
|
34
38
|
"engines": {
|
|
35
39
|
"node": ">=20"
|
|
36
40
|
},
|
|
37
|
-
"license": "MIT"
|
|
41
|
+
"license": "MIT",
|
|
42
|
+
"dependencies": {
|
|
43
|
+
"@inquirer/prompts": "^8.4.3"
|
|
44
|
+
}
|
|
38
45
|
}
|
package/scripts/postinstall.js
CHANGED
|
@@ -16,9 +16,9 @@ function main() {
|
|
|
16
16
|
}
|
|
17
17
|
|
|
18
18
|
console.log('\nOneSpec installed. Next run:');
|
|
19
|
-
console.log(' onespec init
|
|
20
|
-
console.log('or
|
|
21
|
-
console.log(' onespec init . --scope project --yes\n');
|
|
19
|
+
console.log(' onespec init');
|
|
20
|
+
console.log('or non-interactive:');
|
|
21
|
+
console.log(' onespec init . --platform codex --scope project --yes\n');
|
|
22
22
|
}
|
|
23
23
|
|
|
24
24
|
try {
|