@sublang/playbook 5.0.0 → 7.0.0
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 +22 -14
- package/docs/cli.md +138 -90
- package/docs/configuration.md +113 -29
- package/docs/embedding.md +24 -16
- package/package.json +42 -21
- package/reference/sdlc/captain.playbook/captain.playbook.js +2 -0
- package/reference/sdlc/captain.playbook/captain.playbook.ts +2 -0
- package/reference/sdlc/code.md +55 -97
- package/reference/sdlc/code.playbook/bin/launch-config.js +938 -0
- package/reference/sdlc/code.playbook/bin/playbook.js +145 -562
- package/reference/sdlc/code.playbook/bin/provision.js +84 -38
- package/reference/sdlc/code.playbook/bin/run.js +1171 -983
- package/reference/sdlc/code.playbook/bin/session-store.js +1169 -0
- package/reference/sdlc/code.playbook/code.fsm.d.ts +229 -94
- package/reference/sdlc/code.playbook/code.fsm.introspect.d.ts +26 -44
- package/reference/sdlc/code.playbook/code.fsm.introspect.js +61 -66
- package/reference/sdlc/code.playbook/code.fsm.introspect.ts +100 -149
- package/reference/sdlc/code.playbook/code.fsm.js +587 -1347
- package/reference/sdlc/code.playbook/code.fsm.ts +809 -1650
- package/reference/sdlc/code.playbook/code.gears.md +51 -263
- package/reference/sdlc/code.playbook/code.playbook.d.ts +8 -47
- package/reference/sdlc/code.playbook/code.playbook.js +69 -656
- package/reference/sdlc/code.playbook/code.playbook.ts +90 -867
- package/reference/sdlc/code.playbook/code.registry.d.ts +9 -25
- package/reference/sdlc/code.playbook/code.registry.js +20 -78
- package/reference/sdlc/code.playbook/code.registry.ts +58 -122
- package/reference/sdlc/code.playbook/playbook-captain.d.ts +70 -3
- package/reference/sdlc/code.playbook/playbook-captain.js +954 -80
- package/reference/sdlc/code.playbook/playbook-captain.ts +1408 -80
- package/reference/sdlc/code.playbook/playbook.config.template.yaml +37 -36
- package/reference/sdlc/decide.md +54 -0
- package/reference/sdlc/decide.playbook/decide.fsm.d.ts +261 -0
- package/reference/sdlc/decide.playbook/decide.fsm.js +894 -0
- package/reference/sdlc/decide.playbook/decide.fsm.ts +1152 -0
- package/reference/sdlc/decide.playbook/decide.gears.md +88 -0
- package/reference/sdlc/decide.playbook/decide.playbook.d.ts +67 -0
- package/reference/sdlc/{discuss.playbook/discuss.playbook.js → decide.playbook/decide.playbook.js} +545 -372
- package/reference/sdlc/{discuss.playbook/discuss.playbook.ts → decide.playbook/decide.playbook.ts} +665 -454
- package/reference/sdlc/decide.playbook/decide.registry.d.ts +41 -0
- package/reference/sdlc/decide.playbook/decide.registry.js +60 -0
- package/reference/sdlc/decide.playbook/decide.registry.ts +125 -0
- package/reference/sdlc/review.md +81 -0
- package/reference/sdlc/review.playbook/review.fsm.d.ts +183 -0
- package/reference/sdlc/review.playbook/review.fsm.js +524 -0
- package/reference/sdlc/review.playbook/review.fsm.ts +652 -0
- package/reference/sdlc/review.playbook/review.gears.md +112 -0
- package/reference/sdlc/review.playbook/review.playbook.d.ts +12 -0
- package/reference/sdlc/review.playbook/review.playbook.js +112 -0
- package/reference/sdlc/review.playbook/review.playbook.ts +201 -0
- package/reference/sdlc/review.playbook/review.registry.d.ts +43 -0
- package/reference/sdlc/review.playbook/review.registry.js +73 -0
- package/reference/sdlc/review.playbook/review.registry.ts +138 -0
- package/slc/gears2fsm.md +13 -4
- package/slc/link.md +83 -14
- package/slc/text2gears.md +22 -2
- package/src/runtime.d.ts +21 -2
- package/src/runtime.ts +38 -6
- package/src/xstate-playbook-runtime.d.ts +9 -2
- package/src/xstate-playbook-runtime.js +319 -35
- package/src/xstate-playbook-runtime.ts +412 -41
- package/src/xstate-runtime.d.ts +19 -2
- package/src/xstate-runtime.js +384 -57
- package/src/xstate-runtime.ts +542 -71
- package/reference/sdlc/discuss.md +0 -93
- package/reference/sdlc/discuss.playbook/discuss.fsm.d.ts +0 -396
- package/reference/sdlc/discuss.playbook/discuss.fsm.js +0 -2067
- package/reference/sdlc/discuss.playbook/discuss.fsm.ts +0 -2465
- package/reference/sdlc/discuss.playbook/discuss.gears.md +0 -258
- package/reference/sdlc/discuss.playbook/discuss.playbook.d.ts +0 -113
- package/reference/sdlc/discuss.playbook/discuss.registry.d.ts +0 -58
- package/reference/sdlc/discuss.playbook/discuss.registry.js +0 -97
- package/reference/sdlc/discuss.playbook/discuss.registry.ts +0 -153
|
@@ -1,294 +1,82 @@
|
|
|
1
1
|
<!-- SPDX-License-Identifier: Apache-2.0 -->
|
|
2
2
|
<!-- SPDX-FileCopyrightText: 2026 SubLang International <https://sublang.ai> -->
|
|
3
3
|
|
|
4
|
-
# CODE: Coding Workflow
|
|
4
|
+
# CODE: Commit-Based Coding Workflow
|
|
5
5
|
|
|
6
6
|
Players:
|
|
7
7
|
|
|
8
8
|
- Coder
|
|
9
|
-
- Reviewer
|
|
10
|
-
- Committer = Coder | Reviewer
|
|
11
9
|
|
|
12
10
|
## Coder
|
|
13
11
|
|
|
14
12
|
### CODE-1
|
|
15
13
|
|
|
16
|
-
When
|
|
17
|
-
> Assess whether this can be completed in a single commit, following best practices.
|
|
18
|
-
> If yes, implement and test, updating both code and specs; otherwise, decompose into tasks as a new IR under @specs/intents (or @specs/iterations in older scaffolds) and stop without implementing any IR task.
|
|
19
|
-
> For context discovery, @specs/map.md indexes all spec files and @specs/meta.md describes the spec format.
|
|
20
|
-
> Ensure @specs/map.md reflects the changes.
|
|
21
|
-
> Do not commit.
|
|
22
|
-
The resulting changes are Initial Changes.
|
|
14
|
+
When the first coding phase begins, Captain shall prompt Coder:
|
|
23
15
|
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
When Reviewer raises any findings, Captain shall relay them to Coder along with the following prompt:
|
|
27
|
-
> For each review item below for the above changes, challenge or accept it, with strong reasoning, solid evidence, and comprehensive thinking.
|
|
28
|
-
> Stage all current changes that belong in the repo before making any edits, and leave your edits unstaged/untracked.
|
|
29
|
-
|
|
30
|
-
### CODE-3
|
|
31
|
-
|
|
32
|
-
When a new IR or IR task passes review and is committed, Captain shall prompt Coder:
|
|
33
|
-
> Continue to implement IR-<#> if not all deliverables and tasks are done.
|
|
34
|
-
> Implement one task at a time (including corresponding tests if any).
|
|
35
|
-
> Stop after each task for review — do not commit yet.
|
|
36
|
-
> If relevant, mark progress in the IR.
|
|
37
|
-
The resulting changes are Initial Changes.
|
|
38
|
-
|
|
39
|
-
### CODE-4
|
|
40
|
-
|
|
41
|
-
When an IR is done, Captain shall prompt Coder:
|
|
42
|
-
> Read IR-<#> and corresponding commits.
|
|
43
|
-
> According to @specs/meta.md, add or update spec items to fully capture:
|
|
44
|
-
>
|
|
45
|
-
> - the external behavior users rely on,
|
|
46
|
-
> - the internal system behavior, and
|
|
47
|
-
> - the integration/system test cases.
|
|
48
|
-
>
|
|
49
|
-
> The spec items should be the *minimal* set needed to reimplement code without the IR.
|
|
50
|
-
> The set should be complete and coherent.
|
|
51
|
-
> Avoid implementation specifics.
|
|
52
|
-
> Avoid redundant spec items.
|
|
53
|
-
> Ensure @specs/map.md reflects the changes.
|
|
54
|
-
|
|
55
|
-
## Reviewer
|
|
56
|
-
|
|
57
|
-
For each finding in a review round, Coder either addresses it with changes or challenges it with a rebuttal.
|
|
58
|
-
Any code change to address findings starts a new round of review, even if some findings are also rebutted.
|
|
59
|
-
Rounds continue until Reviewer raises no findings.
|
|
60
|
-
|
|
61
|
-
Spec item files are the files under @specs/ that hold spec items — @specs/packages/ and @specs/compositions/ in the current layout, or @specs/user/, @specs/dev/, and @specs/test/ in the legacy one; decision and intent records (iteration records in older scaffolds), @specs/map.md, and @specs/meta.md are not spec item files.
|
|
62
|
-
|
|
63
|
-
### CODE-5
|
|
64
|
-
|
|
65
|
-
When Committer commits Initial Changes from a Boss coding intent involving changes only in spec item files, Captain shall relay the Boss's coding intent to Reviewer along with the following prompt:
|
|
66
|
-
> Review the latest commit.
|
|
67
|
-
> Refer to the commit message.
|
|
68
|
-
> Verify any affected spec items are:
|
|
69
|
-
>
|
|
70
|
-
> - Complete & coherent: sufficient for you to reimplement code.
|
|
71
|
-
> - Right level: external behavior users rely on or internal system behavior (organized per @specs/meta.md), not implementation specifics; integration/system testing, not unit testing.
|
|
72
|
-
> - Minimal: essential and concise; every item earns its place; also check with other items.
|
|
73
|
-
> - Well organized: spec packages are finely scoped, with high cohesion and low coupling.
|
|
74
|
-
>
|
|
75
|
-
> Flag anything missing, redundant, over-specified, or under-specified.
|
|
76
|
-
> For context discovery, @specs/map.md indexes all spec files and @specs/meta.md describes the spec format.
|
|
77
|
-
> Verify @specs/map.md reflects the changes.
|
|
78
|
-
> If the change is ready to commit or push, don't raise nitpicks.
|
|
79
|
-
> Do not edit files or commit; report findings only.
|
|
80
|
-
|
|
81
|
-
### CODE-6
|
|
82
|
-
|
|
83
|
-
When Committer commits Initial Changes from a Boss coding intent involving changes only outside spec item files, Captain shall relay the Boss's coding intent to Reviewer along with the following prompt:
|
|
84
|
-
> Review the latest commit.
|
|
85
|
-
> Refer to the commit message.
|
|
86
|
-
> Flag any issues or improvements (numbered; no duplication).
|
|
87
|
-
> Think thoroughly — don't just approve or reject.
|
|
88
|
-
> For context discovery, @specs/map.md indexes all spec files and @specs/meta.md describes the spec format.
|
|
89
|
-
> Verify @specs/map.md reflects the changes.
|
|
90
|
-
> If the change is ready to commit or push, don't raise nitpicks.
|
|
91
|
-
> Do not edit files or commit; report findings only.
|
|
92
|
-
|
|
93
|
-
### CODE-7
|
|
94
|
-
|
|
95
|
-
When Committer commits Initial Changes from a Boss coding intent involving changes both in and outside spec item files, Captain shall relay the Boss's coding intent to Reviewer along with the following prompt:
|
|
96
|
-
> Review the latest commit.
|
|
97
|
-
> Refer to the commit message.
|
|
98
|
-
> Flag any issues or improvements (numbered; no duplication).
|
|
99
|
-
> Think thoroughly — don't just approve or reject.
|
|
100
|
-
> Verify any affected spec items are:
|
|
16
|
+
> > <caller-input>
|
|
17
|
+
> > <run-results>
|
|
101
18
|
>
|
|
102
|
-
>
|
|
103
|
-
>
|
|
104
|
-
>
|
|
105
|
-
>
|
|
106
|
-
>
|
|
107
|
-
> Flag anything missing, redundant, over-specified, or under-specified.
|
|
108
|
-
> For context discovery, @specs/map.md indexes all spec files and @specs/meta.md describes the spec format.
|
|
109
|
-
> Verify @specs/map.md reflects the changes.
|
|
110
|
-
> If the change is ready to commit or push, don't raise nitpicks.
|
|
111
|
-
> Do not edit files or commit; report findings only.
|
|
112
|
-
|
|
113
|
-
### CODE-8
|
|
114
|
-
|
|
115
|
-
When Committer commits Initial Changes from an IR task involving changes only in spec item files, Captain shall relay the IR's task description to Reviewer along with the following prompt:
|
|
116
|
-
> Review the latest commit.
|
|
117
|
-
> Refer to the commit message.
|
|
118
|
-
> Verify any affected spec items are:
|
|
19
|
+
> Assess whether the coding intent can be completed well in one commit.
|
|
20
|
+
> If yes, implement and test it, update the affected specs, and ensure @specs/map.md remains accurate.
|
|
21
|
+
> Otherwise, decompose it into tasks sized to exactly one commit each, add a new IR under @specs/intents, and do not implement any IR task in this phase.
|
|
22
|
+
> Plan affected spec updates before, with, or after their corresponding code changes, either as standalone IR tasks or as explicit work within related tasks.
|
|
119
23
|
>
|
|
120
|
-
>
|
|
121
|
-
> - Right level: external behavior users rely on or internal system behavior (organized per @specs/meta.md), not implementation specifics; integration/system testing, not unit testing.
|
|
122
|
-
> - Minimal: essential and concise; every item earns its place; also check with other items.
|
|
123
|
-
> - Well organized: spec packages are finely scoped, with high cohesion and low coupling.
|
|
24
|
+
> Consult @specs/map.md for relevant context and @specs/meta.md for spec requirements, if needed.
|
|
124
25
|
>
|
|
125
|
-
>
|
|
126
|
-
>
|
|
127
|
-
>
|
|
128
|
-
>
|
|
129
|
-
>
|
|
26
|
+
> Do not re-run tests or builds whose inputs have not changed since any previous reported run.
|
|
27
|
+
> Make the phase's minimal changes and then one new commit, following @specs/packages/git.md; never amend an existing commit.
|
|
28
|
+
> Make the commit message explain concisely what changed and why, including relevant verification.
|
|
29
|
+
> Report it as exactly one final-response line beginning `Commit: `, followed only by the exact commit identity.
|
|
30
|
+
> Coder is <coder-llm>; format the model token in conventional human form.
|
|
130
31
|
|
|
131
|
-
|
|
32
|
+
Results:
|
|
33
|
+
- `directCommit`: Coder completed and committed the direct implementation phase. Output shall include `coderOutput: <verbatim final text>` and `latestCommit: <commit identity>`.
|
|
34
|
+
- `irCommit`: Coder created and committed a new IR without implementing an IR task. Output shall include `coderOutput: <verbatim final text>`, `latestCommit: <commit identity>`, `irNumber`, and `irTask` naming the exact next unfinished task.
|
|
132
35
|
|
|
133
|
-
|
|
134
|
-
> Review the latest commit.
|
|
135
|
-
> Refer to the commit message.
|
|
136
|
-
> Flag any issues or improvements (numbered; no duplication).
|
|
137
|
-
> Think thoroughly — don't just approve or reject.
|
|
138
|
-
> For context discovery, @specs/map.md indexes all spec files and @specs/meta.md describes the spec format.
|
|
139
|
-
> Verify @specs/map.md reflects the changes.
|
|
140
|
-
> If the change is ready to commit or push, don't raise nitpicks.
|
|
141
|
-
> Do not edit files or commit; report findings only.
|
|
142
|
-
|
|
143
|
-
### CODE-10
|
|
144
|
-
|
|
145
|
-
When Committer commits Initial Changes from an IR task involving changes both in and outside spec item files, Captain shall relay the IR's task description to Reviewer along with the following prompt:
|
|
146
|
-
> Review the latest commit.
|
|
147
|
-
> Refer to the commit message.
|
|
148
|
-
> Flag any issues or improvements (numbered; no duplication).
|
|
149
|
-
> Think thoroughly — don't just approve or reject.
|
|
150
|
-
> Verify any affected spec items are:
|
|
151
|
-
>
|
|
152
|
-
> - Complete & coherent: sufficient for you to reimplement code.
|
|
153
|
-
> - Right level: external behavior users rely on or internal system behavior (organized per @specs/meta.md), not implementation specifics; integration/system testing, not unit testing.
|
|
154
|
-
> - Minimal: essential and concise; every item earns its place; also check with other items.
|
|
155
|
-
> - Well organized: spec packages are finely scoped, with high cohesion and low coupling.
|
|
156
|
-
>
|
|
157
|
-
> Flag anything missing, redundant, over-specified, or under-specified.
|
|
158
|
-
> For context discovery, @specs/map.md indexes all spec files and @specs/meta.md describes the spec format.
|
|
159
|
-
> Verify @specs/map.md reflects the changes.
|
|
160
|
-
> If the change is ready to commit or push, don't raise nitpicks.
|
|
161
|
-
> Do not edit files or commit; report findings only.
|
|
162
|
-
|
|
163
|
-
### CODE-11
|
|
164
|
-
|
|
165
|
-
When Coder makes unreviewed changes (outside of any Initial Changes) involving changes only in spec item files without raising rebuttals, Captain shall prompt Reviewer to begin a review round:
|
|
166
|
-
> Review the unstaged and untracked changes in the context of the staged changes.
|
|
167
|
-
> Understand the intent.
|
|
168
|
-
> Verify any affected spec items are:
|
|
169
|
-
>
|
|
170
|
-
> - Complete & coherent: sufficient for you to reimplement code.
|
|
171
|
-
> - Right level: external behavior users rely on or internal system behavior (organized per @specs/meta.md), not implementation specifics; integration/system testing, not unit testing.
|
|
172
|
-
> - Minimal: essential and concise; every item earns its place; also check with other items.
|
|
173
|
-
> - Well organized: spec packages are finely scoped, with high cohesion and low coupling.
|
|
174
|
-
>
|
|
175
|
-
> Flag anything missing, redundant, over-specified, or under-specified.
|
|
176
|
-
> For context discovery, @specs/map.md indexes all spec files and @specs/meta.md describes the spec format.
|
|
177
|
-
> Verify @specs/map.md reflects the changes.
|
|
178
|
-
> If the change is ready to commit or push, don't raise nitpicks.
|
|
179
|
-
> Do not edit files or commit; report findings only.
|
|
180
|
-
|
|
181
|
-
### CODE-12
|
|
182
|
-
|
|
183
|
-
When Coder makes unreviewed changes (outside of any Initial Changes) involving changes only outside spec item files without raising rebuttals, Captain shall prompt Reviewer to begin a review round:
|
|
184
|
-
> Review the unstaged and untracked changes in the context of the staged changes.
|
|
185
|
-
> Understand the intent.
|
|
186
|
-
> Flag any issues or improvements (numbered; no duplication).
|
|
187
|
-
> Think thoroughly — don't just approve or reject.
|
|
188
|
-
> For context discovery, @specs/map.md indexes all spec files and @specs/meta.md describes the spec format.
|
|
189
|
-
> Verify @specs/map.md reflects the changes.
|
|
190
|
-
> If the change is ready to commit or push, don't raise nitpicks.
|
|
191
|
-
> Do not edit files or commit; report findings only.
|
|
192
|
-
|
|
193
|
-
### CODE-13
|
|
194
|
-
|
|
195
|
-
When Coder makes unreviewed changes (outside of any Initial Changes) involving changes both in and outside spec item files without raising rebuttals, Captain shall prompt Reviewer to begin a review round:
|
|
196
|
-
> Review the unstaged and untracked changes in the context of the staged changes.
|
|
197
|
-
> Understand the intent.
|
|
198
|
-
> Flag any issues or improvements (numbered; no duplication).
|
|
199
|
-
> Think thoroughly — don't just approve or reject.
|
|
200
|
-
> Verify any affected spec items are:
|
|
201
|
-
>
|
|
202
|
-
> - Complete & coherent: sufficient for you to reimplement code.
|
|
203
|
-
> - Right level: external behavior users rely on or internal system behavior (organized per @specs/meta.md), not implementation specifics; integration/system testing, not unit testing.
|
|
204
|
-
> - Minimal: essential and concise; every item earns its place; also check with other items.
|
|
205
|
-
> - Well organized: spec packages are finely scoped, with high cohesion and low coupling.
|
|
206
|
-
>
|
|
207
|
-
> Flag anything missing, redundant, over-specified, or under-specified.
|
|
208
|
-
> For context discovery, @specs/map.md indexes all spec files and @specs/meta.md describes the spec format.
|
|
209
|
-
> Verify @specs/map.md reflects the changes.
|
|
210
|
-
> If the change is ready to commit or push, don't raise nitpicks.
|
|
211
|
-
> Do not edit files or commit; report findings only.
|
|
212
|
-
|
|
213
|
-
### CODE-14
|
|
36
|
+
### CODE-2
|
|
214
37
|
|
|
215
|
-
When
|
|
216
|
-
> For each rebuttal below, challenge or accept it, with strong reasoning, solid evidence, and comprehensive thinking.
|
|
217
|
-
> Do not edit files or commit; report findings only.
|
|
38
|
+
When the first phase has one new commit, Captain shall call playbook `review`:
|
|
218
39
|
|
|
219
|
-
|
|
40
|
+
> > Initial intent: <caller-input>
|
|
41
|
+
> > Coder output: <coder-output>
|
|
220
42
|
|
|
221
|
-
|
|
222
|
-
|
|
223
|
-
|
|
224
|
-
|
|
225
|
-
|
|
226
|
-
> - Complete & coherent: sufficient for you to reimplement code.
|
|
227
|
-
> - Right level: external behavior users rely on or internal system behavior (organized per @specs/meta.md), not implementation specifics; integration/system testing, not unit testing.
|
|
228
|
-
> - Minimal: essential and concise; every item earns its place; also check with other items.
|
|
229
|
-
> - Well organized: spec packages are finely scoped, with high cohesion and low coupling.
|
|
230
|
-
>
|
|
231
|
-
> Flag anything missing, redundant, over-specified, or under-specified.
|
|
232
|
-
> For context discovery, @specs/map.md indexes all spec files and @specs/meta.md describes the spec format.
|
|
233
|
-
> Verify @specs/map.md reflects the changes.
|
|
234
|
-
> If the change is ready to commit or push, don't raise nitpicks.
|
|
235
|
-
> Do not edit files or commit; report findings only.
|
|
236
|
-
> For each rebuttal below, challenge or accept it, with strong reasoning, solid evidence, and comprehensive thinking.
|
|
43
|
+
Workflow outcomes:
|
|
44
|
+
- Exact approval after a direct implementation phase completes `code`.
|
|
45
|
+
- Exact approval after a new-IR phase continues with its next unfinished IR task.
|
|
46
|
+
- An authored `review` abort, error, or invalid approval terminates `code` with the failure and last `code`-owned commit.
|
|
47
|
+
- Any other nested-call error parks `code` as failed and retains the control-plane error.
|
|
237
48
|
|
|
238
|
-
### CODE-
|
|
239
|
-
|
|
240
|
-
When Coder makes unreviewed changes (outside of any Initial Changes) involving changes only outside spec item files and also raises rebuttals, Captain shall prompt Reviewer to begin a review round and relay the rebuttals along with the following prompt:
|
|
241
|
-
> Review the unstaged and untracked changes in the context of the staged changes.
|
|
242
|
-
> Understand the intent.
|
|
243
|
-
> Flag any issues or improvements (numbered; no duplication).
|
|
244
|
-
> Think thoroughly — don't just approve or reject.
|
|
245
|
-
> For context discovery, @specs/map.md indexes all spec files and @specs/meta.md describes the spec format.
|
|
246
|
-
> Verify @specs/map.md reflects the changes.
|
|
247
|
-
> If the change is ready to commit or push, don't raise nitpicks.
|
|
248
|
-
> Do not edit files or commit; report findings only.
|
|
249
|
-
> For each rebuttal below, challenge or accept it, with strong reasoning, solid evidence, and comprehensive thinking.
|
|
49
|
+
### CODE-3
|
|
250
50
|
|
|
251
|
-
|
|
51
|
+
When a reviewed IR has a next unfinished task, Captain shall prompt Coder:
|
|
252
52
|
|
|
253
|
-
|
|
254
|
-
>
|
|
255
|
-
> Understand the intent.
|
|
256
|
-
> Flag any issues or improvements (numbered; no duplication).
|
|
257
|
-
> Think thoroughly — don't just approve or reject.
|
|
258
|
-
> Verify any affected spec items are:
|
|
53
|
+
> > <ir-task>
|
|
54
|
+
> > <run-results>
|
|
259
55
|
>
|
|
260
|
-
>
|
|
261
|
-
>
|
|
262
|
-
>
|
|
263
|
-
>
|
|
56
|
+
> Read IR-<#> and implement exactly the next unfinished task, including corresponding tests or specs if any.
|
|
57
|
+
> Do not implement a later task in this phase.
|
|
58
|
+
> Mark the IR's progress and deliverables when relevant.
|
|
59
|
+
> If the IR will be finished after this phase, double-check that all acceptance criteria are met.
|
|
264
60
|
>
|
|
265
|
-
>
|
|
266
|
-
>
|
|
267
|
-
>
|
|
268
|
-
>
|
|
269
|
-
>
|
|
270
|
-
> For each rebuttal below, challenge or accept it, with strong reasoning, solid evidence, and comprehensive thinking.
|
|
271
|
-
|
|
272
|
-
## Committer
|
|
61
|
+
> Do not re-run tests or builds whose inputs have not changed since any previous reported run.
|
|
62
|
+
> Make the phase's minimal changes and then one new commit, following @specs/packages/git.md; never amend an existing commit.
|
|
63
|
+
> Make the commit message explain concisely what changed and why, including relevant verification.
|
|
64
|
+
> Report it as exactly one final-response line beginning `Commit: `, followed only by the exact commit identity.
|
|
65
|
+
> Coder is <coder-llm>; format the model token in conventional human form.
|
|
273
66
|
|
|
274
|
-
|
|
67
|
+
Results:
|
|
68
|
+
- `moreTasks`: Coder completed and committed the current IR task and at least one task remains. Output shall include `coderOutput: <verbatim final text>`, `latestCommit: <commit identity>`, and `irTask` naming the exact next unfinished task.
|
|
69
|
+
- `finalTask`: Coder completed and committed the final IR task. Output shall include `coderOutput: <verbatim final text>` and `latestCommit: <commit identity>`.
|
|
275
70
|
|
|
276
|
-
|
|
277
|
-
> Make a commit of the changes that belong in the repo, following @specs/packages/git.md (reread if necessary).
|
|
278
|
-
> If that spec is absent, follow the legacy @specs/dev/git.md; if neither exists, follow the repository's existing commit conventions and do not search elsewhere.
|
|
279
|
-
> Write the commit message concisely.
|
|
280
|
-
> Coder is <coder-llm>.
|
|
281
|
-
> Format the `Co-authored-by` `<model>` token as the conventional human form of the substituted id (e.g., `claude-opus-4-7` → `Claude-Opus-4.7`, `gpt-5.5` → `GPT-5.5`).
|
|
282
|
-
|
|
283
|
-
Result guard: `needsBossInput` — Committing requires additional Boss input or rescoping rather than a specific answer to resume this same state.
|
|
71
|
+
### CODE-4
|
|
284
72
|
|
|
285
|
-
|
|
73
|
+
When an IR-task phase has one new commit, Captain shall call playbook `review`:
|
|
286
74
|
|
|
287
|
-
|
|
288
|
-
>
|
|
289
|
-
> If that spec is absent, follow the legacy @specs/dev/git.md; if neither exists, follow the repository's existing commit conventions and do not search elsewhere.
|
|
290
|
-
> Write the commit message concisely.
|
|
291
|
-
> Coder is <coder-llm>; Reviewer is <reviewer-llm>.
|
|
292
|
-
> Format the `Co-authored-by` `<model>` token as the conventional human form of the substituted id (e.g., `claude-opus-4-7` → `Claude-Opus-4.7`, `gpt-5.5` → `GPT-5.5`).
|
|
75
|
+
> > IR task: <ir-task>
|
|
76
|
+
> > Coder output: <coder-output>
|
|
293
77
|
|
|
294
|
-
|
|
78
|
+
Workflow outcomes:
|
|
79
|
+
- Exact approval after a nonfinal IR-task phase continues with its next unfinished IR task.
|
|
80
|
+
- Exact approval after the final IR-task phase completes `code`.
|
|
81
|
+
- An authored `review` abort, error, or invalid approval terminates `code` with the failure and last `code`-owned commit.
|
|
82
|
+
- Any other nested-call error parks `code` as failed and retains the control-plane error.
|
|
@@ -1,54 +1,15 @@
|
|
|
1
|
-
import {
|
|
2
|
-
import {
|
|
3
|
-
|
|
4
|
-
export type { CaptainCallOptions, CaptainResult, JsonValue, NormalizedError, PlayerCallOptions, PlaybookCallRequest, PlaybookCallResult, PlaybookCallStart, PlaybookPendingCall, PlaybookRunResult, PlayerResult, PlaybookPorts, PlaybookSession, PlaybookState, PlaybookStateValue, PlaybookTraceEvent, PlaybookTraceType, PlaybookRuntime, PlaybookRuntimeFactory, PlaybookRuntimeSnapshot, };
|
|
1
|
+
import { type CodingInput, type PlayerInput } from './code.fsm.js';
|
|
2
|
+
import type { CaptainCallOptions, CaptainResult, JsonValue, NormalizedError, PlayerCallOptions, PlaybookCallRequest, PlaybookCallResult, PlaybookCallStart, PlaybookControlReceipt, PlaybookControlView, PlaybookPendingCall, PlaybookPorts, PlaybookRunResult, PlaybookRuntime, PlaybookRuntimeFactory, PlaybookRuntimeSnapshot, PlaybookSession, PlaybookState, PlaybookStateValue, PlaybookTraceEvent, PlaybookTraceType, PlayerResult, PlayerSessionStore } from '@sublang/playbook/runtime';
|
|
3
|
+
export type { CaptainCallOptions, CaptainResult, JsonValue, NormalizedError, PlayerCallOptions, PlaybookCallRequest, PlaybookCallResult, PlaybookCallStart, PlaybookControlReceipt, PlaybookControlView, PlaybookPendingCall, PlaybookPorts, PlaybookRunResult, PlaybookRuntime, PlaybookRuntimeFactory, PlaybookRuntimeSnapshot, PlaybookSession, PlaybookState, PlaybookStateValue, PlaybookTraceEvent, PlaybookTraceType, PlayerResult, PlayerSessionStore, };
|
|
5
4
|
export type CodePlaybookOptions = CodingInput;
|
|
6
|
-
|
|
5
|
+
/**
|
|
6
|
+
* Preserve authored Markdown quote markers around every line of relayed
|
|
7
|
+
* runtime text. The generic composer preserves the marker itself; CODE's
|
|
8
|
+
* override additionally keeps a multiline value inside that quote.
|
|
9
|
+
*/
|
|
7
10
|
declare function composePlayerPrompt(input: PlayerInput): string;
|
|
8
|
-
declare function resolvePlayerId(input: PlayerInput): string;
|
|
9
|
-
declare function adjudicate(input: PlayerInput, finalText: string, ports: PlaybookPorts, signal: AbortSignal, boundary?: RuntimeBoundaryCalls): Promise<PlayerOutput>;
|
|
10
|
-
declare function classifyBossText(text: string, ports: PlaybookPorts, signal: AbortSignal, snapshotOrState?: unknown, boundary?: RuntimeBoundaryCalls): Promise<CodingEvent | undefined>;
|
|
11
|
-
declare function captainBridge(ports: PlaybookPorts, getActiveSignal?: () => AbortSignal | undefined, boundary?: RuntimeBoundaryCalls, onControlPlaneError?: (error: unknown) => void): import("xstate").PromiseActorLogic<import("../../../src/xstate-playbook-runtime.js").PlaybookActorOutput, PlaybookPlayerInput>;
|
|
12
|
-
interface StateMetadata {
|
|
13
|
-
player: PlayerInput['player'];
|
|
14
|
-
sourceItem: string;
|
|
15
|
-
label: string;
|
|
16
|
-
}
|
|
17
|
-
type BossReplyQuestionId = NonNullable<Extract<CodingEvent, {
|
|
18
|
-
type: 'BOSS_REPLY';
|
|
19
|
-
}>['questionId']>;
|
|
20
|
-
interface PendingBossQuestionForStatus {
|
|
21
|
-
questionId: BossReplyQuestionId;
|
|
22
|
-
resumeStateId: string;
|
|
23
|
-
sourceItem: string;
|
|
24
|
-
player: string;
|
|
25
|
-
question: string;
|
|
26
|
-
}
|
|
27
|
-
declare function pendingBossQuestionFromContext(context: Record<string, unknown>): PendingBossQuestionForStatus | undefined;
|
|
28
|
-
declare function formatAwaitBossReplyQuestion(context: Record<string, unknown>): string;
|
|
29
|
-
declare function formatAwaitBossReplyMarker(context: Record<string, unknown>): string;
|
|
30
|
-
declare function formatStateEntry(stateId: string): string | undefined;
|
|
31
|
-
declare function formatTransition(event: unknown): string | undefined;
|
|
32
|
-
declare function formatClassification(eventType: string): string;
|
|
33
|
-
declare function stateTelemetryPayload(from: unknown, to: string, event: unknown, context: Record<string, unknown>): Record<string, unknown>;
|
|
34
11
|
export declare const _internal: {
|
|
35
12
|
composePlayerPrompt: typeof composePlayerPrompt;
|
|
36
|
-
resolvePlayerId: typeof resolvePlayerId;
|
|
37
|
-
adjudicate: typeof adjudicate;
|
|
38
|
-
classifyBossText: typeof classifyBossText;
|
|
39
|
-
captainBridge: typeof captainBridge;
|
|
40
|
-
STATE_LABELS: Readonly<Record<string, string>>;
|
|
41
|
-
stateMetadata: ReadonlyMap<string, StateMetadata>;
|
|
42
|
-
pendingBossQuestionFromContext: typeof pendingBossQuestionFromContext;
|
|
43
|
-
formatAwaitBossReplyQuestion: typeof formatAwaitBossReplyQuestion;
|
|
44
|
-
formatAwaitBossReplyMarker: typeof formatAwaitBossReplyMarker;
|
|
45
|
-
formatStateEntry: typeof formatStateEntry;
|
|
46
|
-
formatTransition: typeof formatTransition;
|
|
47
|
-
formatClassification: typeof formatClassification;
|
|
48
|
-
stateTelemetryPayload: typeof stateTelemetryPayload;
|
|
49
|
-
normalizeErrorCompact: typeof normalizeErrorCompact;
|
|
50
|
-
normalizeErrorFull: typeof normalizeErrorFull;
|
|
51
|
-
normalizeEventForTelemetry: typeof normalizeEventForTelemetry;
|
|
52
13
|
VERBATIM_PAYLOAD_FIELDS: ReadonlySet<string>;
|
|
53
14
|
};
|
|
54
15
|
declare const createPlaybookRuntime: PlaybookRuntimeFactory<CodePlaybookOptions>;
|