@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.
Files changed (67) hide show
  1. package/agents/factory-ticket-readiness.md +20 -15
  2. package/dist/board.d.mts +1 -1
  3. package/dist/board.mjs +4 -7
  4. package/dist/cli.mjs +23 -1
  5. package/dist/code-host/github.d.mts +1 -1
  6. package/dist/code-host/github.mjs +31 -2
  7. package/dist/code-host/types.d.mts +20 -1
  8. package/dist/code-host/types.mjs +8 -0
  9. package/dist/columns-suggest.d.mts +25 -5
  10. package/dist/columns-suggest.mjs +117 -21
  11. package/dist/commands.d.mts +8 -2
  12. package/dist/commands.mjs +92 -8
  13. package/dist/config.d.mts +19 -7
  14. package/dist/config.mjs +109 -30
  15. package/dist/doctor.mjs +1 -2
  16. package/dist/explain.mjs +7 -1
  17. package/dist/init.d.mts +19 -0
  18. package/dist/init.mjs +139 -23
  19. package/dist/lib/gh.d.mts +6 -0
  20. package/dist/lib/gh.mjs +11 -1
  21. package/dist/lib/listed.d.mts +3 -2
  22. package/dist/lib/listed.mjs +5 -4
  23. package/dist/lib/work-status.d.mts +5 -5
  24. package/dist/lib/work-status.mjs +7 -8
  25. package/dist/merge-policy.mjs +7 -3
  26. package/dist/poller.d.mts +1 -1
  27. package/dist/poller.mjs +9 -6
  28. package/dist/pr.d.mts +8 -6
  29. package/dist/pr.mjs +47 -22
  30. package/dist/review-verdict.d.mts +22 -4
  31. package/dist/review-verdict.mjs +55 -17
  32. package/dist/specs/index.d.mts +6 -0
  33. package/dist/specs/index.mjs +15 -0
  34. package/dist/specs/openspec.d.mts +2 -0
  35. package/dist/specs/openspec.mjs +78 -0
  36. package/dist/specs/types.d.mts +53 -0
  37. package/dist/specs/types.mjs +4 -0
  38. package/dist/ticket.d.mts +6 -1
  39. package/dist/ticket.mjs +62 -3
  40. package/dist/tickets/github-access.d.mts +5 -0
  41. package/dist/tickets/github-access.mjs +22 -0
  42. package/dist/tickets/github.mjs +2 -0
  43. package/dist/tickets/types.d.mts +4 -0
  44. package/dist/tool-names.d.mts +2 -0
  45. package/dist/tool-names.mjs +3 -0
  46. package/dist/tools.d.mts +2 -0
  47. package/dist/tools.mjs +3 -0
  48. package/docs/builds.md +30 -14
  49. package/docs/cli.md +48 -30
  50. package/docs/configuration.md +237 -73
  51. package/docs/developing.md +104 -59
  52. package/docs/existing-repo.md +51 -29
  53. package/docs/github/by-hand.md +13 -1
  54. package/docs/github/setup.md +26 -2
  55. package/docs/glossary.md +7 -6
  56. package/docs/limitations.md +8 -5
  57. package/docs/presets.md +15 -3
  58. package/docs/updating.md +147 -2
  59. package/docs/workflow.md +26 -9
  60. package/package.json +1 -1
  61. package/rules.md +36 -30
  62. package/settings.schema.json +14 -9
  63. package/skills/factory-address-review/SKILL.md +40 -39
  64. package/skills/factory-build/SKILL.md +77 -52
  65. package/skills/factory-deps/SKILL.md +6 -4
  66. package/skills/factory-refine/SKILL.md +30 -22
  67. 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
- One release asks more of you, because it changes the shape of your
7
- settings file: [Moving to settings version 2](#moving-to-settings-version-2).
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
- default names.
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
- With [`specs: openspec`](configuration.md#specs), a change that adds or
192
- alters behavior someone can see, and is not small, carries the `spec`
193
- label. Its ticket holds a "Spec" section of plain "When this, then that"
194
- lines. The build turns those lines into an OpenSpec change, builds to
195
- them, and folds them into `openspec/specs/` in the same pull request, so
196
- that folder always describes what the project does now.
197
-
198
- With `specs: none`, the ticket's acceptance criteria are the whole spec.
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
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@davidbyoung/software-factory",
3
- "version": "0.1.9",
3
+ "version": "0.1.11",
4
4
  "description": "Refines, builds, and reviews tickets with Claude Code sessions, from a board to a merged pull request.",
5
5
  "license": "MIT",
6
6
  "repository": {
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 OpenSpec change either, unless the change makes
34
- a line of `openspec/specs/` false, as renaming a label a spec quotes
35
- would. That issue also carries a Spec section of the changed line, and
36
- the build archives a proposal and spec delta in the same pull request,
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 track applies only when
171
- `npx --no-install factory config get specs` prints `openspec`. Then the GitHub
172
- issue is the spec: `factory-refine` writes it, the owner approves it by
173
- moving its card to Ready or telling a session to build it, and
174
- `factory-build` turns it into an OpenSpec change, builds it, and archives it
175
- into `openspec/specs/` in the same pull request. `openspec/specs/` is the
176
- current description of what the repository does; a change to it starts by
177
- reading its spec.
178
-
179
- A change that adds or alters behavior a user can see carries the
180
- `spec` label, which `factory-refine` adds, unless it is small ("Small
181
- changes" above). Everything else, such as copy, bug fixes that
182
- restore intended behavior, style tweaks, tooling, CI, and docs, builds
183
- from the issue's "Acceptance criteria" with no spec files and no "For the
184
- builder" section, since the area's `CLAUDE.md` says how it is built. A
185
- small change that makes a spec line false is the one exception ("Small
186
- changes" above). Neither skill removes `spec` or adds it back once
187
- the owner removed it: both act through the owner's GitHub account, so a
188
- label already decided is the owner's call.
189
-
190
- OpenSpec collects anonymous usage statistics unless told not to. Run it with
191
- `DO_NOT_TRACK=1`.
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 `openspec/specs/` false. A request from the owner is always its
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 OpenSpec change. `factory-build` appends a line and
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
@@ -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. Default: Backlog."
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. Default: In refinement. May be none."
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. Default: Ready. May be none."
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. Default: In progress. May be none."
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. Default: In review. May be none."
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. Default: Done. May be none."
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
- The repository owner reviews pull requests too. Their comments are worked
98
- like the Claude reviewer's findings, with two differences: a pushback on
99
- one stays open for the owner to decide, and the owner's reply after a
100
- pushback is final. The owner is the repository owner's login, read rather
101
- than hard-coded: the part of the repository's name before the slash.
102
-
103
- ```bash
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 the owner's account, and GitHub does not let an
111
- author approve or request changes on their own pull request, so the owner's
112
- reviews are all `COMMENTED`.
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 `OWNER_LOGIN` without it is the owner's. Match with
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 the owner's in it:** stop without changing anything. That is
143
- a review by someone else, or one of this skill's own replies: GitHub
144
- records each thread reply as a review under the owner's account, with an
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 owner comment"
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; owner threads belong to the runs their
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 owner
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 owner comments to work are the unresolved threads whose
201
- last comment is the owner's and lacks the marker, and the non-empty owner
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 owner's unanswered review body. Thread replies do not count there, since a reply on one thread does
207
- not answer a review body. The report lists these as "owner review bodies
208
- to answer", and marks an unresolved thread "owner's turn" when its last
209
- comment is the owner's without the marker. Read a review body in full
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 owner comment
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 owner
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
- - **The owner replied after your pushback.** That reply is final; do not
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
- owner's call, with the commit, and resolve the thread.
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 the owner's reply, and resolve the thread.
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
- Owner threads are outside section 6's round count and its escalation.
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 the owner's (section 0a). Put it at the end of
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
- owner thread is resolved only when you fixed it, the owner overruled your
450
- pushback, or the owner accepted it** (section 0a). A pushback on an owner
451
- thread stays open for the owner. GitHub has no "ignored" state:
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
- Owner threads (section 0a) are outside this count, and this section's
510
- escalation does not apply to them: an open owner thread is already the
511
- owner's to decide. A run started by the owner's review has no memory of
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