@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
@@ -34,9 +34,10 @@ The [glossary](glossary.md) has the rest.
34
34
 
35
35
  ## How the file works
36
36
 
37
- - **Two settings are required, and a third before any build.** Every
38
- file has [`version`](#version) and [`repository`](#repository), and a
39
- session can't build a ticket until you set
37
+ - **Three settings are required, and a fourth before any build.** Every
38
+ file has [`version`](#version), [`repository`](#repository), and
39
+ [`code-host.branch-name`](#code-host), which `factory init` writes for
40
+ you, and a session can't build a ticket until you set
40
41
  [`commands.gate`](#commandsgate). Every other setting has a default, and
41
42
  you write it only when you want something else.
42
43
  - **It holds only what a script needs.** Anything that needs judgment,
@@ -85,6 +86,9 @@ The [glossary](glossary.md) has the rest.
85
86
  ```yaml
86
87
  version: 2
87
88
  repository: your-name/your-repo
89
+ code-host:
90
+ type: github
91
+ branch-name: "{ticket}"
88
92
  ```
89
93
 
90
94
  With only this, the factory refines a ticket when you run `/factory-refine N` in a session,
@@ -177,6 +181,13 @@ Where your tickets live, and which board shows them.
177
181
  tickets:
178
182
  type: github
179
183
  board: 1
184
+ columns:
185
+ backlog: Backlog
186
+ refining: In refinement
187
+ ready: Ready
188
+ building: In progress
189
+ review: In review
190
+ done: Done
180
191
  ```
181
192
 
182
193
  - **`type`** is the ticket system. Only `github` is built, and it is the
@@ -184,6 +195,8 @@ tickets:
184
195
  - **`board`** is your GitHub Project's number: the last part of its
185
196
  address, such as `1` in `github.com/users/your-name/projects/1`. The
186
197
  default, `none`, means no board.
198
+ - **`columns`** says which of the board's columns shows each state, and a
199
+ board needs it: see [`tickets.columns`](#ticketscolumns).
187
200
 
188
201
  Without a board, `factory status` still shows every ticket's state, which
189
202
  the factory keeps in comments on the ticket. Builds then start only when
@@ -199,12 +212,14 @@ with it.
199
212
  #### `tickets.columns`
200
213
 
201
214
  The board has one column for each of the six
202
- [states](workflow.md#the-six-states) a ticket goes through. If your
203
- board's columns have the factory's names, write nothing here. If they have
204
- other names, or your board has fewer columns, say which column shows each
205
- state. `factory init` suggests this block when you choose a board without the
206
- factory's columns: see
215
+ [states](workflow.md#the-six-states) a ticket goes through. This block
216
+ says which of your board's columns shows each state, and it names all
217
+ six. `factory init` writes it for you, from the board you choose: see
207
218
  [You already have a board](existing-repo.md#you-already-have-a-board).
219
+ There is no default: your board's column names may not be the
220
+ factory's, and a guess would put tickets in the wrong column without
221
+ telling you.
222
+
208
223
  A new GitHub Project starts with only Todo, In Progress, and Done,
209
224
  so its settings would be:
210
225
 
@@ -213,73 +228,86 @@ tickets:
213
228
  board: 7
214
229
  columns:
215
230
  backlog: Todo
216
- building: In Progress
217
- done: Done
218
231
  refining: none
219
232
  ready: none
233
+ building: In Progress
220
234
  review: none
235
+ done: Done
221
236
  builds:
222
237
  trigger: manual
223
238
  ```
224
239
 
225
- The factory's own names, used for any state you leave out, are:
240
+ When init creates your board, or adds columns to one, it gives them the
241
+ factory's own names:
226
242
 
227
- | State | Column the factory looks for |
228
- | ---------- | ---------------------------- |
229
- | `backlog` | Backlog |
230
- | `refining` | In refinement |
231
- | `ready` | Ready |
232
- | `building` | In progress |
233
- | `review` | In review |
234
- | `done` | Done |
243
+ | Key | Name of the column init creates |
244
+ | ---------- | ------------------------------- |
245
+ | `backlog` | Backlog |
246
+ | `refining` | In refinement |
247
+ | `ready` | Ready |
248
+ | `building` | In progress |
249
+ | `review` | In review |
250
+ | `done` | Done |
235
251
 
236
252
  - **Capitals don't matter,** so "In progress" finds your "In Progress".
237
253
  - **`none` means your board has no column for that state.** A ticket in
238
254
  that state stays in the column of the state before it. With
239
255
  `review: none`, a ticket whose pull request is in review stays in In
240
- progress. Every state can be `none` except `backlog`.
256
+ Progress. Every state can be `none` except `backlog`.
241
257
  - **A state can take a list of columns,** when more than one of yours
242
- means it. `factory init` suggests one column for each state, so you
243
- write a list yourself. A ticket in any of the columns is in that
244
- state. When the factory moves a ticket into the state, it uses the
245
- first, and a ticket already in any of them stays where it is:
258
+ means it. Init never writes a list, so add one to the block yourself.
259
+ A ticket in any of the columns is in that state. When the factory
260
+ moves a ticket into the state, it uses the first, and a ticket already
261
+ in any of them stays where it is:
246
262
 
247
263
  ```yaml
248
264
  tickets:
249
265
  board: 7
250
266
  columns:
251
267
  backlog: Todo
268
+ refining: none
269
+ ready: none
270
+ building: In Progress
252
271
  # When a pull request opens, its ticket moves to Code review.
253
272
  # One you moved to QA stays there.
254
273
  review: [Code review, QA]
274
+ done: Done
255
275
  ```
256
276
 
257
277
  `ready` takes one column, since only a ticket you approved goes there.
258
278
 
259
- - **A ticket never falls back into Ready,** since only a ticket you
260
- approved goes there, so the fallback skips it. With `building: none`
261
- alone, a ticket being built has no column of its own, the state before
262
- building is ready, and Ready is skipped, so it shows in In refinement.
279
+ - **A ticket never stays in the ready column unless you approved it.**
280
+ With `building: none`, a ticket being built would stay in ready's
281
+ column, so it stays in refining's column instead. On a board with the
282
+ factory's columns and `building: none`, it shows in In refinement.
263
283
  - **With `ready: none`, nothing on the board approves a build,** so you
264
284
  need `builds.trigger: manual`, and you start each build by asking a
265
285
  session.
266
286
  - **A ticket in a column no state uses is left alone.** The board sync
267
287
  doesn't move it or fill in its fields, and nothing builds it.
268
- - **If you host your own poller** and rename the Ready column, the poller
269
- needs the new name too: see `FACTORY_READY_COLUMN` in
288
+ - **If you host your own poller,** it needs `FACTORY_READY_COLUMN` set
289
+ to the column `ready` names: see
270
290
  [Builds](builds.md#what-it-reads-from-its-environment).
271
291
 
272
292
  `factory config check` stops, naming the key, when `columns` has:
273
293
 
294
+ - no `board` beside it, or a `board` with no `columns`;
295
+ - a state left out, naming each one;
274
296
  - a state it doesn't know;
275
297
  - `backlog: none`;
276
298
  - one column for two states;
277
299
  - an empty list, or a list for `ready`;
278
- - no `board` beside it;
279
300
  - `ready: none` while [`builds.trigger`](#builds) isn't `manual`,
280
301
  since then a build starts only from the ready column.
281
302
 
282
- It doesn't read your board: `factory board check` does.
303
+ Such as:
304
+
305
+ ```text
306
+ .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
307
+ ```
308
+
309
+ `factory config check` doesn't read your board. `factory board check`
310
+ does, and says which of the columns you named the board lacks.
283
311
 
284
312
  #### `tickets.fields`
285
313
 
@@ -373,13 +401,104 @@ you confirm them.
373
401
 
374
402
  ### `code-host`
375
403
 
376
- Where your repository and its pull requests live. Only `github` is built,
377
- and it is the default, so most files leave this out.
404
+ Where your repository and its pull requests live, and what every
405
+ [build](#words-this-page-uses) names the branch it pushes, in a session
406
+ on your machine and in the cloud alike.
378
407
 
379
408
  ```yaml
380
- code-host: github
409
+ code-host:
410
+ type: github
411
+ branch-name: "feature/{user}/{ticket}"
381
412
  ```
382
413
 
414
+ - **`type`** is the code host. GitHub is the only one so far, and it is
415
+ the default.
416
+ - **`branch-name`** is the pattern for the branch's name. It has no
417
+ default: [`factory init`](github/setup.md) asks for it and offers
418
+ `{ticket}`, so ticket 12 is built on a branch named `12`. A
419
+ [preset](#presets) can set it for every repository that follows it.
420
+
421
+ Without `branch-name`, `factory config check` stops:
422
+
423
+ ```text
424
+ .claude/factory.yaml: code-host.branch-name: is required. Run factory init to set it, or add it, such as branch-name: "{ticket}"
425
+ ```
426
+
427
+ A pattern uses these placeholders. It must have `{ticket}`; `{user}` is
428
+ for a convention that names who did the work, and a pattern can leave
429
+ it out:
430
+
431
+ | Placeholder | What it becomes | For ticket 12 |
432
+ | ----------- | ------------------------------------ | ------------- |
433
+ | `{ticket}` | The ticket's number, without `#` | `12` |
434
+ | `{user}` | The GitHub account the build runs as | `octocat` |
435
+
436
+ In a session, `{user}` is the account the GitHub CLI, `gh`, is signed in
437
+ as, exactly as GitHub spells it, so the same ticket built by two people
438
+ gets two branches. In GitHub Actions, it is the owner of
439
+ the [token the build runs with](github/reference.md#workflows), not
440
+ whoever approved the ticket, so with a shared bot account every branch
441
+ built in Actions carries the bot's name.
442
+
443
+ Keep the quotes, as in the examples. YAML reads an unquoted
444
+ `branch-name: {ticket}` as a map rather than as text, and
445
+ `factory config check` stops and says to quote it.
446
+
447
+ `{ticket}` gives each ticket its own branch, and the same branch every
448
+ time. So a ticket built a second time, such as the
449
+ [follow-ups ticket](workflow.md#follow-ups), a reopened ticket, or one whose first
450
+ build stopped, finds its earlier branch still on GitHub, unless GitHub
451
+ deleted it when its pull request merged. What the build does depends on
452
+ that branch's newest pull request:
453
+
454
+ - **Merged, with nothing pushed to the branch since:** the build deletes
455
+ the old branch and starts fresh, since its work is already merged.
456
+ - **Open:** the build stops before it starts and names the pull request.
457
+ Work that one instead, with `/factory-address-review N` for pull
458
+ request N.
459
+ - **Anything else:** closed without merging, no pull request at all, or
460
+ merged with commits pushed since. The build stops before it starts, so
461
+ no work is lost:
462
+
463
+ ```text
464
+ Branch 12 is already on origin, with work no pull request merged. Open a pull request from it to keep that work, or delete it with: git push origin --delete 12
465
+ ```
466
+
467
+ A build that stopped partway pushes its branch so its work is kept. To
468
+ keep it, open a pull request from the branch on GitHub. Otherwise
469
+ delete the branch, and build the ticket again with `/factory-build 12`.
470
+
471
+ Once you change the pattern, run `factory config check`, then
472
+ `factory sync` (every setting needs it, as
473
+ [How the file works](#how-the-file-works) says), then see what the
474
+ pattern gives one ticket:
475
+
476
+ ```console
477
+ $ factory config check
478
+ ✓ The settings are valid.
479
+ $ factory ticket branch 12
480
+ feature/octocat/12
481
+ ```
482
+
483
+ `factory config check` stops on a placeholder it doesn't know, a pattern
484
+ without `{ticket}`, and a pattern git can't use as a branch name. Git
485
+ refuses a name that:
486
+
487
+ - has a space, a control character, `..`, `//`, or `@{`
488
+ - has any of `~`, `^`, `:`, `?`, `*`, `[`, or `\`
489
+ - starts with `-` or `/`, or ends with `/`, `.`, or `.lock`
490
+ - has a part between slashes that starts with `.` or ends with `.lock`
491
+
492
+ Anything else is fine, `#` and `_` included. The check names the first
493
+ fault it finds:
494
+
495
+ ```text
496
+ .claude/factory.yaml: code-host.branch-name: feature//{ticket} can't be a git branch name: it has //
497
+ ```
498
+
499
+ Commit `.claude/factory.yaml` and `.claude/factory.lock`. The next build
500
+ uses the new pattern; branches already pushed keep their names.
501
+
383
502
  ### `builds`
384
503
 
385
504
  What starts a build when you approve a ticket, and where the build runs.
@@ -423,42 +542,74 @@ marks it "not started": after 5 minutes with `own-server`, and after
423
542
 
424
543
  ### `specs`
425
544
 
426
- Whether a change your users will see also gets a written spec, kept beside
427
- your code.
545
+ Which spec tool your project uses, if any. Either way, refinement writes
546
+ a [Spec, a design, and a list of tasks](workflow.md#a-change-your-users-will-see)
547
+ into the ticket of each change your users will see. A spec tool also
548
+ keeps the Spec in your repository.
428
549
 
429
550
  ```yaml
551
+ # The default: refinement writes the Spec into the ticket, and nothing is
552
+ # kept in your repository. Leaving the line out means the same.
553
+ specs: none
554
+ ```
555
+
556
+ ```yaml
557
+ # Each build also writes the ticket's Spec into openspec/specs/.
430
558
  specs: openspec
431
559
  ```
432
560
 
433
- - **`none`,** the default: the ticket's acceptance criteria are the only
434
- spec.
435
- - **`openspec`:** a visible change that isn't
436
- [small](workflow.md#sizing-the-work-to-the-change) also writes its new
437
- behavior into `openspec/specs/`, using
438
- [OpenSpec](https://github.com/Fission-AI/OpenSpec), so that folder
439
- always describes what your project does. Install it first, with
440
- `npm install -D @fission-ai/openspec`. Without it, a build stops at its
441
- first spec step and says so.
561
+ - **`none`,** the default: the ticket is the only place the Spec is
562
+ written down.
563
+ - **`openspec`:** each build also writes the ticket's Spec into
564
+ `openspec/specs/`, using [OpenSpec](https://github.com/Fission-AI/OpenSpec),
565
+ so that folder always describes what your project does, readable
566
+ without opening a ticket.
567
+
568
+ **`factory init` asks, and writes the answer here.** It asks "Which spec
569
+ tool do you use?" when `.claude/factory.yaml` has no `specs` line and no
570
+ [preset](presets.md) sets one. With `openspec`, init installs OpenSpec as
571
+ a development dependency, `npm install --save-dev @fission-ai/openspec`,
572
+ whenever your `package.json` doesn't list it, and prints
573
+ `Installed @fission-ai/openspec.` It worked when that line prints and
574
+ `package.json` lists the package. So to turn OpenSpec on later, write
575
+ `specs: openspec` and run `factory init` again. A re-run is safe: it
576
+ keeps every setting you have, asks again only which parts you want,
577
+ with yours already checked, and shows everything it will do before it
578
+ does it.
579
+
580
+ **Without OpenSpec installed,** a build stops at its first spec step and
581
+ says to run `factory init`.
582
+
583
+ `factory specs list` prints the specs your repository keeps, one per
584
+ line with its file, which is what to read before changing what a spec
585
+ describes. The build runs `factory specs new`, `check`, and `finish`
586
+ itself; [Your repository's commands](cli.md#your-repositorys-commands)
587
+ says what each prints.
442
588
 
443
589
  #### `specs.check`
444
590
 
445
- The command that checks your written specs are sound.
591
+ The command that checks your written specs are well formed, such as
592
+ that every requirement has a scenario. To set it, write `specs` as a
593
+ block: its `type` is the tool the one-line form names, so
594
+ `specs: openspec` and the block below make the same choice.
446
595
  `factory specs check` runs it, and so does a build each time it writes a
447
- spec.
596
+ spec. It belongs only with `type: openspec`.
448
597
 
449
598
  ```yaml
450
599
  specs:
451
600
  type: openspec
601
+ # Optional: this is the default.
452
602
  check: npx --no-install openspec validate --all --strict --no-interactive
453
603
  ```
454
604
 
455
- - **Default:** the command above,
456
- `npx --no-install openspec validate --all --strict --no-interactive`,
457
- with `type: openspec`, so most repositories leave it out.
605
+ - **Default:** the command above, so most repositories leave `check`
606
+ out and write only `specs: openspec`.
458
607
  - **It runs with `DO_NOT_TRACK=1` set,** so OpenSpec collects no usage
459
608
  statistics.
460
- - **With `specs: none`** there is nothing to check, and writing `check`
461
- fails `factory config check`.
609
+ - **With `specs: none`** there is nothing to check, and a `check` line
610
+ fails `factory config check`: delete it when you switch to `none`.
611
+
612
+ It worked when `factory specs check` ends with `✓ The specs check passed.`
462
613
 
463
614
  ### `commands`
464
615
 
@@ -1021,26 +1172,6 @@ pr-review:
1021
1172
  removes the workflow.
1022
1173
  - `factory review tools` prints everything the reviewer may use.
1023
1174
 
1024
- ### `approvers`
1025
-
1026
- _[Planned](developing.md#what-is-built)_: `factory config check` refuses
1027
- this setting until it is built.
1028
-
1029
- The people whose comments a session takes as instructions, and whose move
1030
- of a ticket to Ready counts as approving it. Everyone else's comments are
1031
- read as information.
1032
-
1033
- ```yaml
1034
- approvers:
1035
- - your-name
1036
- - a-teammate
1037
- ```
1038
-
1039
- - **Default:** the repository's owner, so a repository with one person
1040
- leaves it out.
1041
- - **If a name is wrong,** that person's comments are treated as
1042
- information, and a ticket they approve is not built.
1043
-
1044
1175
  ### `rules`
1045
1176
 
1046
1177
  Two numbers the factory's rules use, for a repository that wants
@@ -1101,6 +1232,17 @@ repository: harbor-goods/storefront
1101
1232
 
1102
1233
  tickets:
1103
1234
  board: 1
1235
+ columns:
1236
+ backlog: Backlog
1237
+ refining: In refinement
1238
+ ready: Ready
1239
+ building: In progress
1240
+ review: In review
1241
+ done: Done
1242
+
1243
+ code-host:
1244
+ type: github
1245
+ branch-name: "{ticket}"
1104
1246
 
1105
1247
  builds:
1106
1248
  trigger: own-server
@@ -1170,6 +1312,17 @@ repository: riverbend-studio/site
1170
1312
 
1171
1313
  tickets:
1172
1314
  board: 4
1315
+ columns:
1316
+ backlog: Backlog
1317
+ refining: In refinement
1318
+ ready: Ready
1319
+ building: In progress
1320
+ review: In review
1321
+ done: Done
1322
+
1323
+ code-host:
1324
+ type: github
1325
+ branch-name: "{ticket}"
1173
1326
 
1174
1327
  commands:
1175
1328
  before-commit:
@@ -1193,6 +1346,17 @@ repository: northwind-php/ledger
1193
1346
 
1194
1347
  tickets:
1195
1348
  board: 2
1349
+ columns:
1350
+ backlog: Backlog
1351
+ refining: In refinement
1352
+ ready: Ready
1353
+ building: In progress
1354
+ review: In review
1355
+ done: Done
1356
+
1357
+ code-host:
1358
+ type: github
1359
+ branch-name: "{ticket}"
1196
1360
 
1197
1361
  commands:
1198
1362
  build-setup: