@davidbyoung/software-factory 0.1.9 → 0.1.11
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/agents/factory-ticket-readiness.md +20 -15
- package/dist/board.d.mts +1 -1
- package/dist/board.mjs +4 -7
- package/dist/cli.mjs +23 -1
- package/dist/code-host/github.d.mts +1 -1
- package/dist/code-host/github.mjs +31 -2
- package/dist/code-host/types.d.mts +20 -1
- package/dist/code-host/types.mjs +8 -0
- package/dist/columns-suggest.d.mts +25 -5
- package/dist/columns-suggest.mjs +117 -21
- package/dist/commands.d.mts +8 -2
- package/dist/commands.mjs +92 -8
- package/dist/config.d.mts +19 -7
- package/dist/config.mjs +109 -30
- package/dist/doctor.mjs +1 -2
- package/dist/explain.mjs +7 -1
- package/dist/init.d.mts +19 -0
- package/dist/init.mjs +139 -23
- package/dist/lib/gh.d.mts +6 -0
- package/dist/lib/gh.mjs +11 -1
- package/dist/lib/listed.d.mts +3 -2
- package/dist/lib/listed.mjs +5 -4
- package/dist/lib/work-status.d.mts +5 -5
- package/dist/lib/work-status.mjs +7 -8
- package/dist/merge-policy.mjs +7 -3
- package/dist/poller.d.mts +1 -1
- package/dist/poller.mjs +9 -6
- package/dist/pr.d.mts +8 -6
- package/dist/pr.mjs +47 -22
- package/dist/review-verdict.d.mts +22 -4
- package/dist/review-verdict.mjs +55 -17
- package/dist/specs/index.d.mts +6 -0
- package/dist/specs/index.mjs +15 -0
- package/dist/specs/openspec.d.mts +2 -0
- package/dist/specs/openspec.mjs +78 -0
- package/dist/specs/types.d.mts +53 -0
- package/dist/specs/types.mjs +4 -0
- package/dist/ticket.d.mts +6 -1
- package/dist/ticket.mjs +62 -3
- package/dist/tickets/github-access.d.mts +5 -0
- package/dist/tickets/github-access.mjs +22 -0
- package/dist/tickets/github.mjs +2 -0
- package/dist/tickets/types.d.mts +4 -0
- package/dist/tool-names.d.mts +2 -0
- package/dist/tool-names.mjs +3 -0
- package/dist/tools.d.mts +2 -0
- package/dist/tools.mjs +3 -0
- package/docs/builds.md +30 -14
- package/docs/cli.md +48 -30
- package/docs/configuration.md +237 -73
- package/docs/developing.md +104 -59
- package/docs/existing-repo.md +51 -29
- package/docs/github/by-hand.md +13 -1
- package/docs/github/setup.md +26 -2
- package/docs/glossary.md +7 -6
- package/docs/limitations.md +8 -5
- package/docs/presets.md +15 -3
- package/docs/updating.md +147 -2
- package/docs/workflow.md +26 -9
- package/package.json +1 -1
- package/rules.md +36 -30
- package/settings.schema.json +14 -9
- package/skills/factory-address-review/SKILL.md +40 -39
- package/skills/factory-build/SKILL.md +77 -52
- package/skills/factory-deps/SKILL.md +6 -4
- package/skills/factory-refine/SKILL.md +30 -22
- package/skills/factory-resolve-conflicts/SKILL.md +8 -7
package/docs/updating.md
CHANGED
|
@@ -3,8 +3,12 @@
|
|
|
3
3
|
**When a new version is released, a pull request appears in your
|
|
4
4
|
repository. You read it and merge it.** That is all you have to do.
|
|
5
5
|
|
|
6
|
-
|
|
7
|
-
settings file: [Moving to settings version
|
|
6
|
+
Three releases ask more of you, because they need lines in your
|
|
7
|
+
settings file that it doesn't have: [Moving to settings version
|
|
8
|
+
2](#moving-to-settings-version-2) and [Naming build
|
|
9
|
+
branches](#naming-build-branches), for every repository, and [Naming
|
|
10
|
+
every column](#naming-every-column), for a repository whose settings
|
|
11
|
+
have a [`tickets.board`](configuration.md#tickets).
|
|
8
12
|
|
|
9
13
|
## What happens
|
|
10
14
|
|
|
@@ -149,6 +153,10 @@ After:
|
|
|
149
153
|
version: 2
|
|
150
154
|
repository: your-name/your-repo
|
|
151
155
|
|
|
156
|
+
code-host:
|
|
157
|
+
type: github
|
|
158
|
+
branch-name: "{ticket}"
|
|
159
|
+
|
|
152
160
|
specs: openspec
|
|
153
161
|
|
|
154
162
|
commands:
|
|
@@ -207,6 +215,141 @@ needed, and the rest are worth a look while the file is open.
|
|
|
207
215
|
branch is not `main` needs no setting: `factory sync` writes the
|
|
208
216
|
branch's name where the workflows need it.
|
|
209
217
|
|
|
218
|
+
## Naming every column
|
|
219
|
+
|
|
220
|
+
From this release, a repository with a board names a column for all six
|
|
221
|
+
states in [`tickets.columns`](configuration.md#ticketscolumns). Before
|
|
222
|
+
it, a state you left out used the factory's own column name, so a
|
|
223
|
+
repository set up earlier has no `columns` block, or one with only the
|
|
224
|
+
states whose column has another name. A repository with no
|
|
225
|
+
`tickets.board` needs nothing.
|
|
226
|
+
|
|
227
|
+
Until the block names all six, every command that reads the settings
|
|
228
|
+
stops with one of these, the second naming the states you left out:
|
|
229
|
+
|
|
230
|
+
```text
|
|
231
|
+
.claude/factory.yaml: tickets.columns: is required with tickets.board: run factory init to choose which of board 3's columns shows each state
|
|
232
|
+
.claude/factory.yaml: tickets.columns: building and done have no column: give each a column, a list of columns, or none, or run factory init to choose them
|
|
233
|
+
```
|
|
234
|
+
|
|
235
|
+
So on the factory's update pull request, `factory-deps`, which opens
|
|
236
|
+
and finishes it ([What happens](#what-happens)), cannot run
|
|
237
|
+
`factory sync`. It stops and opens an issue in your repository quoting
|
|
238
|
+
the line. Check out the pull request's branch, and from your
|
|
239
|
+
repository's root run:
|
|
240
|
+
|
|
241
|
+
```bash
|
|
242
|
+
gh pr checkout 123 # the update pull request's number
|
|
243
|
+
factory init
|
|
244
|
+
```
|
|
245
|
+
|
|
246
|
+
Init keeps everything your settings already say and adds only the
|
|
247
|
+
missing states. It shows the whole block it saves, the states you had
|
|
248
|
+
and the ones it added. A state whose column of the factory's name is on
|
|
249
|
+
your board, which is the column the factory was reading for it, is added
|
|
250
|
+
with no question:
|
|
251
|
+
|
|
252
|
+
```text
|
|
253
|
+
Your settings give no column to building or done.
|
|
254
|
+
Board 3 has a column of the factory's name for each:
|
|
255
|
+
|
|
256
|
+
State Column
|
|
257
|
+
backlog Todo
|
|
258
|
+
refining none, shows in Todo
|
|
259
|
+
ready none
|
|
260
|
+
building In Progress
|
|
261
|
+
review Code review
|
|
262
|
+
done Done
|
|
263
|
+
```
|
|
264
|
+
|
|
265
|
+
For a state whose column your board doesn't have, init asks which column
|
|
266
|
+
shows it, offering your columns, no column, or a new column with the
|
|
267
|
+
factory's name. When it needs Claude Code to suggest columns, it asks
|
|
268
|
+
as [You already have a board](existing-repo.md#you-already-have-a-board)
|
|
269
|
+
shows.
|
|
270
|
+
|
|
271
|
+
You can add the lines by hand instead. For each state your block leaves
|
|
272
|
+
out, the factory used the name in the table in
|
|
273
|
+
[`tickets.columns`](configuration.md#ticketscolumns), so write that name
|
|
274
|
+
to keep things as they were. If your board has no column of that name,
|
|
275
|
+
write one of your columns, or `none`.
|
|
276
|
+
|
|
277
|
+
Then run `factory sync`, which rewrites the factory's files for the new
|
|
278
|
+
version, commit what changed, `.claude/factory.yaml` included, and push.
|
|
279
|
+
The pull request's checks run again, and you close the issue
|
|
280
|
+
`factory-deps` opened.
|
|
281
|
+
|
|
282
|
+
**It worked when** `factory config check` prints
|
|
283
|
+
`✓ The settings are valid.`, and `factory sync --check` passes.
|
|
284
|
+
|
|
285
|
+
## Naming build branches
|
|
286
|
+
|
|
287
|
+
From this release, every repository says how a build names its branch,
|
|
288
|
+
in [`code-host.branch-name`](configuration.md#code-host). Before it, a
|
|
289
|
+
build named its branch `issue-` with the ticket's number and a few words
|
|
290
|
+
of its title, such as `issue-47-terminal-color`, and no setting said so.
|
|
291
|
+
So a repository set up earlier has no `branch-name`, or writes
|
|
292
|
+
`code-host: github` on one line, and every command that reads the
|
|
293
|
+
settings stops with `code-host.branch-name: is required`.
|
|
294
|
+
|
|
295
|
+
There is no pattern that keeps the old names, since they held words a
|
|
296
|
+
session chose. The pattern you choose names new builds only: branches
|
|
297
|
+
already pushed keep their names, and their pull requests carry on as
|
|
298
|
+
before.
|
|
299
|
+
|
|
300
|
+
So on the factory's update pull request, `factory-deps` cannot run
|
|
301
|
+
`factory sync`. It stops and opens an issue in your repository quoting
|
|
302
|
+
the line. Check out the pull request's branch, and from your
|
|
303
|
+
repository's root run:
|
|
304
|
+
|
|
305
|
+
```bash
|
|
306
|
+
gh pr checkout 123 # the update pull request's number
|
|
307
|
+
factory init
|
|
308
|
+
```
|
|
309
|
+
|
|
310
|
+
Init keeps everything your settings already say, so it asks again only
|
|
311
|
+
what they lack: how a build names its branch, offering `{ticket}`. Press
|
|
312
|
+
Enter to keep it, or type your team's pattern, such as
|
|
313
|
+
`feature/{user}/{ticket}`; [`code-host`](configuration.md#code-host)
|
|
314
|
+
lists what a pattern can hold. If the update also needs [Naming every
|
|
315
|
+
column](#naming-every-column), the same run fills in both. When a
|
|
316
|
+
[preset](presets.md) you follow sets the pattern, init asks nothing.
|
|
317
|
+
|
|
318
|
+
You can add the lines by hand instead:
|
|
319
|
+
|
|
320
|
+
```yaml
|
|
321
|
+
code-host:
|
|
322
|
+
type: github
|
|
323
|
+
branch-name: "{ticket}"
|
|
324
|
+
```
|
|
325
|
+
|
|
326
|
+
Keep the quotes: without them, YAML reads `{ticket}` as a map rather
|
|
327
|
+
than as text. Then run `factory sync`, commit what changed,
|
|
328
|
+
`.claude/factory.yaml` included, and push. The pull request's checks run
|
|
329
|
+
again, and you close the issue `factory-deps` opened.
|
|
330
|
+
|
|
331
|
+
**It worked when** `factory config check` prints
|
|
332
|
+
`✓ The settings are valid.`, and `factory ticket branch 12` prints the
|
|
333
|
+
branch a build of ticket 12 would push.
|
|
334
|
+
|
|
335
|
+
## A spec for every visible change
|
|
336
|
+
|
|
337
|
+
From this release, a change your users will see, and that isn't small,
|
|
338
|
+
gets the `spec` label and a [Spec, a design, and a list of
|
|
339
|
+
tasks](workflow.md#a-change-your-users-will-see) in its ticket, whatever
|
|
340
|
+
[`specs`](configuration.md#specs) says. Before it, a repository with
|
|
341
|
+
`specs: none`, or no `specs` line, which means the same, got only a list
|
|
342
|
+
of acceptance criteria. Nothing stops on the update: tickets refined
|
|
343
|
+
earlier build as they are, and the next one refinement writes has the
|
|
344
|
+
longer shape.
|
|
345
|
+
|
|
346
|
+
`factory specs change-name N` is gone. A script of yours that ran it
|
|
347
|
+
runs `factory specs new N` and `factory specs finish N` instead
|
|
348
|
+
([Your repository's commands](cli.md#your-repositorys-commands)).
|
|
349
|
+
|
|
350
|
+
The next time you run `factory init`, it asks once which spec tool you
|
|
351
|
+
use, and writes your answer; choosing OpenSpec installs it.
|
|
352
|
+
|
|
210
353
|
## The commands
|
|
211
354
|
|
|
212
355
|
| Command | When |
|
|
@@ -234,6 +377,8 @@ not match `package-lock.json`.
|
|
|
234
377
|
| CI fails with "of the factory's files don't match the settings" | A factory file was edited by hand, or settings changed without a sync | Run `factory sync` and commit the result |
|
|
235
378
|
| `factory doctor` says your installed version is older than the repository's | You pulled an update and have not installed it | Run `npm ci` |
|
|
236
379
|
| A command stops with `version: must be 2` | The update changed the shape of the settings file | [Move the file](#moving-to-settings-version-2) |
|
|
380
|
+
| A command stops with `tickets.columns: is required` or `have no column` | The update needs a column named for every state | [Name every column](#naming-every-column) |
|
|
381
|
+
| A command stops with `code-host.branch-name: is required` | The update needs the pattern a build names its branch by | [Name build branches](#naming-build-branches) |
|
|
237
382
|
| A command stops with `.claude/factory.lock is from an earlier version of the factory` | The update's sync has not run on this checkout | Run `factory sync` and commit the result |
|
|
238
383
|
| A command stops with `.claude/factory.yaml changed since the last sync` | The settings changed without a sync | Run `factory sync` and commit the result |
|
|
239
384
|
| The update pull request conflicts with your default branch | Something else changed the same file | `factory-deps` resolves it on its next run, or close it and update by hand |
|
package/docs/workflow.md
CHANGED
|
@@ -25,7 +25,7 @@ A ticket is always in one of six states. They are fixed: you cannot add one
|
|
|
25
25
|
or reorder them. Your board shows them as columns, and which column shows
|
|
26
26
|
which state is your repository's choice
|
|
27
27
|
([`tickets.columns`](configuration.md#ticketscolumns)). The table gives the
|
|
28
|
-
|
|
28
|
+
names `factory init` gives the columns it adds.
|
|
29
29
|
|
|
30
30
|
A state with no column of its own shows in the column of the nearest earlier
|
|
31
31
|
state that has one, and a ticket is shown in the `ready` column only when it
|
|
@@ -188,11 +188,28 @@ verdict.
|
|
|
188
188
|
|
|
189
189
|
## A change your users will see
|
|
190
190
|
|
|
191
|
-
|
|
192
|
-
|
|
193
|
-
|
|
194
|
-
|
|
195
|
-
|
|
196
|
-
|
|
197
|
-
|
|
198
|
-
|
|
191
|
+
A change that adds or alters behavior someone can see, and is not
|
|
192
|
+
[small](#sizing-the-work-to-the-change), gets the `spec` label, which
|
|
193
|
+
refinement adds and the build reads. Refinement writes three things into
|
|
194
|
+
its ticket, after your own text:
|
|
195
|
+
|
|
196
|
+
- **Spec:** what the change must do, as numbered "When this, then that"
|
|
197
|
+
lines, such as "3. When a visitor sends the form with no email, the
|
|
198
|
+
form still sends." To change one, name it by its number where
|
|
199
|
+
refinement asks you, in the session or in a comment on the ticket,
|
|
200
|
+
such as "3: and when the email is not valid, it says so."
|
|
201
|
+
- **Design:** where the change goes and the cases it must handle.
|
|
202
|
+
- **Tasks:** the steps to build it, each naming the test that checks it.
|
|
203
|
+
|
|
204
|
+
The design and tasks sit in a collapsed "For the builder" section, so
|
|
205
|
+
you can read the Spec and approve the ticket as you approve any other
|
|
206
|
+
([From a ticket to a merge](#from-a-ticket-to-a-merge)). The build works
|
|
207
|
+
from the ticket alone, and its pull request's description lists the
|
|
208
|
+
test that checks each Spec line.
|
|
209
|
+
|
|
210
|
+
A [spec tool](configuration.md#specs), such as OpenSpec, also keeps the
|
|
211
|
+
Spec in your repository.
|
|
212
|
+
|
|
213
|
+
Every other ticket, such as a bug fix, a copy change, or a small change,
|
|
214
|
+
has a list of acceptance criteria instead: what must be true for it to
|
|
215
|
+
be done.
|
package/package.json
CHANGED
package/rules.md
CHANGED
|
@@ -30,11 +30,11 @@ here rather than restate it.
|
|
|
30
30
|
such as "small: one test, red first, one UI reviewer read", so the
|
|
31
31
|
owner can overrule it before the work starts rather than halfway through.
|
|
32
32
|
- **No `spec` label**, even when a user sees it: the issue's acceptance
|
|
33
|
-
criteria are the spec. No
|
|
34
|
-
a line of
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
which then waits for the owner. A fix that restores what a spec says
|
|
33
|
+
criteria are the spec. No spec tool change either, unless the change
|
|
34
|
+
makes a line of a spec `npx --no-install factory specs list` prints
|
|
35
|
+
false, as renaming a label a spec quotes would. That issue also carries
|
|
36
|
+
a Spec section of the changed line, and the build folds it into the
|
|
37
|
+
specs in the same pull request, which then waits for the owner. A fix that restores what a spec says
|
|
38
38
|
changes no line of it.
|
|
39
39
|
- **No `factory-ticket-readiness` read and no read by the test reviewers**
|
|
40
40
|
(`npx --no-install factory plugins test-reviewer` lists them), with two
|
|
@@ -167,28 +167,34 @@ always the owner's.
|
|
|
167
167
|
|
|
168
168
|
## Spec track
|
|
169
169
|
|
|
170
|
-
The spec
|
|
171
|
-
|
|
172
|
-
|
|
173
|
-
|
|
174
|
-
|
|
175
|
-
|
|
176
|
-
|
|
177
|
-
|
|
178
|
-
|
|
179
|
-
|
|
180
|
-
|
|
181
|
-
|
|
182
|
-
|
|
183
|
-
|
|
184
|
-
|
|
185
|
-
|
|
186
|
-
|
|
187
|
-
|
|
188
|
-
|
|
189
|
-
|
|
190
|
-
|
|
191
|
-
`
|
|
170
|
+
The GitHub issue is the spec: `factory-refine` writes it, the owner
|
|
171
|
+
approves it by moving its card to Ready or telling a session to build
|
|
172
|
+
it, and `factory-build` builds it. A change that adds or alters behavior
|
|
173
|
+
a user can see carries the `spec` label, which `factory-refine` adds,
|
|
174
|
+
unless it is small ("Small changes" above), whatever spec tool the
|
|
175
|
+
repository uses. Its issue holds "Decisions", numbered "Spec" lines, and
|
|
176
|
+
"For the builder" with a design and tasks, so a build needs nothing
|
|
177
|
+
else.
|
|
178
|
+
|
|
179
|
+
Everything else, such as copy, bug fixes that restore intended behavior,
|
|
180
|
+
style tweaks, tooling, CI, and docs, builds from the issue's "Acceptance
|
|
181
|
+
criteria" with no spec files and no "For the builder" section, since the
|
|
182
|
+
area's `CLAUDE.md` says how it is built. A small change that makes a
|
|
183
|
+
spec line false is the one exception ("Small changes" above). Neither
|
|
184
|
+
skill removes `spec` or adds it back once the owner removed it: both act
|
|
185
|
+
through the owner's GitHub account, so a label already decided is the
|
|
186
|
+
owner's call.
|
|
187
|
+
|
|
188
|
+
A spec tool, which `npx --no-install factory config get specs` names,
|
|
189
|
+
also keeps each Spec in the repository: `factory-build` starts it with
|
|
190
|
+
`npx --no-install factory specs new N` and folds it in with
|
|
191
|
+
`npx --no-install factory specs finish N`, in the same pull request.
|
|
192
|
+
`npx --no-install factory specs list` prints the specs the repository
|
|
193
|
+
keeps, its current description of what it does; a change to one starts
|
|
194
|
+
by reading it. With `specs: none` each of these says each ticket holds
|
|
195
|
+
its own spec, and the issue is the only copy. No skill, agent, rule, or
|
|
196
|
+
workflow runs a spec tool's own commands: the `factory specs` commands
|
|
197
|
+
reach it.
|
|
192
198
|
|
|
193
199
|
## Issues that wait on another
|
|
194
200
|
|
|
@@ -258,8 +264,8 @@ hook refuses the same in text sent to GitHub directly, as the
|
|
|
258
264
|
the line unchecked.
|
|
259
265
|
- A follow-up gets its own issue only when it would need the `spec` label,
|
|
260
266
|
because it adds or alters behavior a user can see, or would make a
|
|
261
|
-
line of `
|
|
262
|
-
own issue.
|
|
267
|
+
line of a spec `factory specs list` prints false. A request from the
|
|
268
|
+
owner is always its own issue.
|
|
263
269
|
- The `factory-resolve-conflicts` conflict stop keeps opening its own issue: which side
|
|
264
270
|
wins is the owner's decision, and nothing else records it.
|
|
265
271
|
|
|
@@ -269,7 +275,7 @@ telling a session to build it. The pull request closes it with `Closes #N`
|
|
|
269
275
|
only when every line is checked; otherwise it starts with `Part of #N`,
|
|
270
276
|
and the unchecked lines wait there. The sync reads `Part of #N` as a
|
|
271
277
|
partial build, so any other link to the follow-ups issue words it
|
|
272
|
-
differently. It has no
|
|
278
|
+
differently. It has no spec tool change. `factory-build` appends a line and
|
|
273
279
|
builds the issue; `factory-refine` refines it per line. Its lines can be
|
|
274
280
|
about anything, so the one pull request waits for the owner when any line
|
|
275
281
|
touches a file that does, and gets the fresh-agent trace ("Changing the
|
package/settings.schema.json
CHANGED
|
@@ -36,7 +36,7 @@
|
|
|
36
36
|
]
|
|
37
37
|
},
|
|
38
38
|
"code-host": {
|
|
39
|
-
"description": "Where pull requests are.",
|
|
39
|
+
"description": "Where pull requests are, and what a build names its branch.",
|
|
40
40
|
"anyOf": [
|
|
41
41
|
{
|
|
42
42
|
"$ref": "#/definitions/code-host/properties/type"
|
|
@@ -114,7 +114,7 @@
|
|
|
114
114
|
},
|
|
115
115
|
"tickets.columns": {
|
|
116
116
|
"type": "object",
|
|
117
|
-
"description": "Which of your board's columns shows each state. Needs a board.",
|
|
117
|
+
"description": "Which of your board's columns shows each state. Needs a board. With a board, all six states are required, here or from a preset.",
|
|
118
118
|
"additionalProperties": false,
|
|
119
119
|
"properties": {
|
|
120
120
|
"backlog": {
|
|
@@ -132,7 +132,7 @@
|
|
|
132
132
|
}
|
|
133
133
|
}
|
|
134
134
|
],
|
|
135
|
-
"description": "The board's column for the backlog state, or a list of its columns.
|
|
135
|
+
"description": "The board's column for the backlog state, or a list of its columns."
|
|
136
136
|
},
|
|
137
137
|
"refining": {
|
|
138
138
|
"oneOf": [
|
|
@@ -149,12 +149,12 @@
|
|
|
149
149
|
}
|
|
150
150
|
}
|
|
151
151
|
],
|
|
152
|
-
"description": "The board's column for the refining state, or a list of its columns.
|
|
152
|
+
"description": "The board's column for the refining state, or a list of its columns. May be none."
|
|
153
153
|
},
|
|
154
154
|
"ready": {
|
|
155
155
|
"type": "string",
|
|
156
156
|
"minLength": 1,
|
|
157
|
-
"description": "The board's column for the ready state.
|
|
157
|
+
"description": "The board's column for the ready state. May be none."
|
|
158
158
|
},
|
|
159
159
|
"building": {
|
|
160
160
|
"oneOf": [
|
|
@@ -171,7 +171,7 @@
|
|
|
171
171
|
}
|
|
172
172
|
}
|
|
173
173
|
],
|
|
174
|
-
"description": "The board's column for the building state, or a list of its columns.
|
|
174
|
+
"description": "The board's column for the building state, or a list of its columns. May be none."
|
|
175
175
|
},
|
|
176
176
|
"review": {
|
|
177
177
|
"oneOf": [
|
|
@@ -188,7 +188,7 @@
|
|
|
188
188
|
}
|
|
189
189
|
}
|
|
190
190
|
],
|
|
191
|
-
"description": "The board's column for the review state, or a list of its columns.
|
|
191
|
+
"description": "The board's column for the review state, or a list of its columns. May be none."
|
|
192
192
|
},
|
|
193
193
|
"done": {
|
|
194
194
|
"oneOf": [
|
|
@@ -205,7 +205,7 @@
|
|
|
205
205
|
}
|
|
206
206
|
}
|
|
207
207
|
],
|
|
208
|
-
"description": "The board's column for the done state, or a list of its columns.
|
|
208
|
+
"description": "The board's column for the done state, or a list of its columns. May be none."
|
|
209
209
|
}
|
|
210
210
|
}
|
|
211
211
|
},
|
|
@@ -260,12 +260,17 @@
|
|
|
260
260
|
},
|
|
261
261
|
"code-host": {
|
|
262
262
|
"type": "object",
|
|
263
|
-
"description": "Where pull requests are.",
|
|
263
|
+
"description": "Where pull requests are, and what a build names its branch. branch-name is required, here or from a preset.",
|
|
264
264
|
"additionalProperties": false,
|
|
265
265
|
"properties": {
|
|
266
266
|
"type": {
|
|
267
267
|
"enum": ["github"],
|
|
268
268
|
"description": "The code host. Default: github."
|
|
269
|
+
},
|
|
270
|
+
"branch-name": {
|
|
271
|
+
"type": "string",
|
|
272
|
+
"minLength": 1,
|
|
273
|
+
"description": "The pattern a build names its branch by: {ticket}, the ticket's number, which it must have, and {user}, the code host account the build runs as. Quote it, as \"{ticket}\" or \"feature/{user}/{ticket}\". No default: factory init asks for it."
|
|
269
274
|
}
|
|
270
275
|
}
|
|
271
276
|
},
|
|
@@ -94,25 +94,25 @@ reporting a clean review. Never report a review as clean when none has run.
|
|
|
94
94
|
|
|
95
95
|
## 0a. The owner's review
|
|
96
96
|
|
|
97
|
-
|
|
98
|
-
|
|
99
|
-
|
|
100
|
-
|
|
101
|
-
|
|
102
|
-
|
|
103
|
-
|
|
104
|
-
OWNER_LOGIN=$(npx --no-install factory config get repository | cut -d/ -f1)
|
|
105
|
-
```
|
|
97
|
+
An approver, anyone whose account can write to the repository, reviews
|
|
98
|
+
pull requests too. Their comments are worked like the Claude reviewer's
|
|
99
|
+
findings, with two differences: a pushback on one stays open for an
|
|
100
|
+
approver to decide, and an approver's reply after a pushback is final.
|
|
101
|
+
Who is an approver is the code host's to say: `factory pr state` and
|
|
102
|
+
`factory pr review-pending` already keep only an approver's reviews and
|
|
103
|
+
turns, so no step here tests a name.
|
|
106
104
|
|
|
107
105
|
**Only reviews count:** inline comments, and the body of a submitted
|
|
108
106
|
review. A Conversation-tab comment that is not part of a review starts
|
|
109
107
|
nothing and is never acted on. Do not go by the review's state: agents open
|
|
110
|
-
pull requests through
|
|
111
|
-
author approve or request changes on their own pull request, so the
|
|
112
|
-
reviews are all
|
|
108
|
+
pull requests through an approver's account, and GitHub does not let an
|
|
109
|
+
author approve or request changes on their own pull request, so the
|
|
110
|
+
reviews of an approver who is the pull request's author are all
|
|
111
|
+
`COMMENTED`.
|
|
113
112
|
|
|
114
113
|
Every comment this skill posts contains `<!-- agent -->` (section 4), so a
|
|
115
|
-
comment from
|
|
114
|
+
comment without it, from an account those commands count, is an
|
|
115
|
+
approver's. Match with
|
|
116
116
|
"contains", not "ends with": an automatic footer can follow the marker.
|
|
117
117
|
|
|
118
118
|
### A run started by the owner's review
|
|
@@ -139,9 +139,10 @@ passed.
|
|
|
139
139
|
It prints the review's author and body, and each comment it left on a
|
|
140
140
|
line with its `id`, `replyTo`, `path`, `line`, and `body`.
|
|
141
141
|
|
|
142
|
-
3. **Nothing of
|
|
143
|
-
a review by someone
|
|
144
|
-
records each thread reply as a review under the
|
|
142
|
+
3. **Nothing of an approver's in it:** stop without changing anything. That
|
|
143
|
+
is a review by someone who is not an approver, or one of this skill's
|
|
144
|
+
own replies: GitHub records each thread reply as a review under the
|
|
145
|
+
account that posted it, with an
|
|
145
146
|
empty body and one comment carrying the marker. Otherwise work the
|
|
146
147
|
comments without the marker, and the body if it is non-empty and lacks
|
|
147
148
|
the marker.
|
|
@@ -162,7 +163,7 @@ passed.
|
|
|
162
163
|
4. Check out the pull request's branch, Dependabot's included. Read whether
|
|
163
164
|
it can merge as `factory-address-review` section 0 does, and if that is `dirty`
|
|
164
165
|
and the pull request is one the conflict sweep's queue admits, run "A
|
|
165
|
-
conflict with the default branch" in the `factory-resolve-conflicts` skill first, then work each comment as "Each
|
|
166
|
+
conflict with the default branch" in the `factory-resolve-conflicts` skill first, then work each comment as "Each approver comment"
|
|
166
167
|
below says. Run the gate ("Gate" under "A
|
|
167
168
|
conflict with the default branch" in that skill), commit, and push to that branch
|
|
168
169
|
only, never with force. **A push refused because the branch moved**
|
|
@@ -176,13 +177,13 @@ passed.
|
|
|
176
177
|
section 8, reporting as section 8 lays out. Otherwise no review is
|
|
177
178
|
coming: work the review threads that already exist, and end with the
|
|
178
179
|
same report. In this loop, section 1 works only the threads
|
|
179
|
-
`github-actions[bot]` opened;
|
|
180
|
+
`github-actions[bot]` opened; approver threads belong to the runs their
|
|
180
181
|
reviews started.
|
|
181
182
|
6. **Only the latest push's run goes on.** In step 5's loop only, before
|
|
182
183
|
working a Claude review and again before each push it makes, compare the pull request's head with your
|
|
183
184
|
last commit (`npx --no-install factory pr view N --field head`). If
|
|
184
185
|
another run has pushed since, stop: its push starts the next Claude
|
|
185
|
-
review, and that run works it, open threads included. A push of
|
|
186
|
+
review, and that run works it, open threads included. A push of approver
|
|
186
187
|
fixes in step 4 that is refused is still pulled and pushed again.
|
|
187
188
|
|
|
188
189
|
Each run works only its own review, and only the run that pushed last
|
|
@@ -197,19 +198,19 @@ This run never merges, enables auto-merge, marks a draft ready, or adds the
|
|
|
197
198
|
branch.
|
|
198
199
|
|
|
199
200
|
**Outside a run started by a review,** as in a local session working the
|
|
200
|
-
pull request, the
|
|
201
|
-
last comment is
|
|
202
|
-
review bodies submitted after the last Conversation comment carrying the
|
|
201
|
+
pull request, the approver comments to work are the unresolved threads
|
|
202
|
+
whose last comment is an approver's and lacks the marker, and the non-empty
|
|
203
|
+
approver review bodies submitted after the last Conversation comment carrying the
|
|
203
204
|
marker. A comment that also carries `<!-- conflict-fix -->`,
|
|
204
205
|
`conflict-stop`, or `<!-- session-handoff -->`, the `factory-resolve-conflicts` skill's
|
|
205
206
|
comment markers, does not count as that last comment, so a sweep's comment
|
|
206
|
-
does not hide an
|
|
207
|
-
not answer a review body. The report lists these as "
|
|
208
|
-
to answer", and marks an unresolved thread "
|
|
209
|
-
comment is
|
|
207
|
+
does not hide an approver's unanswered review body. Thread replies do not count there, since a reply on one thread does
|
|
208
|
+
not answer a review body. The report lists these as "approver review bodies
|
|
209
|
+
to answer", and marks an unresolved thread "approver's turn" when its last
|
|
210
|
+
comment is an approver's without the marker. Read a review body in full
|
|
210
211
|
with `npx --no-install factory pr review N ID`.
|
|
211
212
|
|
|
212
|
-
### Each
|
|
213
|
+
### Each approver comment
|
|
213
214
|
|
|
214
215
|
A comment with a `replyTo` is a reply in an existing thread: read
|
|
215
216
|
the whole thread first (`npx --no-install factory pr threads N --all`
|
|
@@ -223,19 +224,19 @@ to see whether it follows a pushback of yours.
|
|
|
223
224
|
- **Agreed:** fix it (section 3), push, reply with what changed and the
|
|
224
225
|
commit, and resolve the thread.
|
|
225
226
|
- **Disagreed:** reply once with the evidence, a quoted source, a failing
|
|
226
|
-
test, or the code, and leave the thread open. Never resolve an
|
|
227
|
+
test, or the code, and leave the thread open. Never resolve an approver
|
|
227
228
|
thread you did not fix, except as the next bullet says.
|
|
228
|
-
- **
|
|
229
|
+
- **An approver replied after your pushback.** That reply is final; do not
|
|
229
230
|
push back again.
|
|
230
231
|
- **It asks for the change:** make it, reply that you are following the
|
|
231
|
-
|
|
232
|
+
approver's call, with the commit, and resolve the thread.
|
|
232
233
|
- **It accepts the pushback:** reply that you are leaving the code as it
|
|
233
|
-
is, per
|
|
234
|
+
is, per that reply, and resolve the thread.
|
|
234
235
|
- **You cannot tell which:** ask in one line and leave it open.
|
|
235
236
|
- **A review body.** Handle each point in it the same way, and answer it in
|
|
236
237
|
the end comment (section 4); there is no thread to resolve.
|
|
237
238
|
|
|
238
|
-
|
|
239
|
+
Approver threads are outside section 6's round count and its escalation.
|
|
239
240
|
|
|
240
241
|
## 1. Collect
|
|
241
242
|
|
|
@@ -425,7 +426,7 @@ the reasoning survives, and the user reads these instead of the transcript.
|
|
|
425
426
|
|
|
426
427
|
**Every comment this skill posts, a thread reply or a conversation comment,
|
|
427
428
|
contains `<!-- agent -->` on its own line.** That marker is how the next
|
|
428
|
-
run tells its own words from
|
|
429
|
+
run tells its own words from an approver's (section 0a). Put it at the end of
|
|
429
430
|
the body; an automatic footer may follow it.
|
|
430
431
|
|
|
431
432
|
```bash
|
|
@@ -446,9 +447,9 @@ npx --no-install factory pr resolve N COMMENT_ID
|
|
|
446
447
|
```
|
|
447
448
|
|
|
448
449
|
Resolve accepted and rejected threads alike, with one exception: **an
|
|
449
|
-
|
|
450
|
-
|
|
451
|
-
thread stays open for
|
|
450
|
+
approver thread is resolved only when you fixed it, or an approver
|
|
451
|
+
overruled or accepted your pushback** (section 0a). A pushback on an
|
|
452
|
+
approver thread stays open for an approver. GitHub has no "ignored" state:
|
|
452
453
|
a rejection is a reply carrying the evidence, followed by the same resolve.
|
|
453
454
|
Resolving without replying destroys the reasoning, which is the only reason
|
|
454
455
|
the user can audit the decision later.
|
|
@@ -506,9 +507,9 @@ other push: pull with
|
|
|
506
507
|
|
|
507
508
|
## 6. Two rounds, then escalate
|
|
508
509
|
|
|
509
|
-
|
|
510
|
-
escalation does not apply to them: an open
|
|
511
|
-
|
|
510
|
+
Approver threads (section 0a) are outside this count, and this section's
|
|
511
|
+
escalation does not apply to them: an open approver thread is already an
|
|
512
|
+
approver's to decide. A run started by the owner's review has no memory of
|
|
512
513
|
earlier sessions, so it counts rounds from the `claude-review sha=`
|
|
513
514
|
summaries of the commits it pushed itself.
|
|
514
515
|
|