@davidbyoung/software-factory 0.1.2 → 0.1.4

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 (120) hide show
  1. package/README.md +20 -20
  2. package/actions/factory-agent/action.yml +1 -1
  3. package/agents/factory-e2e-reviewer.md +102 -0
  4. package/agents/factory-test-reviewer.md +26 -64
  5. package/agents/factory-ticket-readiness.md +14 -6
  6. package/dist/agent/claude-code.d.mts +3 -0
  7. package/dist/agent/claude-code.mjs +89 -0
  8. package/dist/agent/index.d.mts +2 -0
  9. package/dist/agent/index.mjs +5 -0
  10. package/dist/board.mjs +1 -1
  11. package/dist/cli.mjs +46 -4
  12. package/dist/code-host/github-setup.d.mts +5 -0
  13. package/dist/code-host/github-setup.mjs +133 -0
  14. package/dist/code-host/github.mjs +4 -0
  15. package/dist/code-host/index.d.mts +1 -1
  16. package/dist/code-host/index.mjs +2 -1
  17. package/dist/code-host/types.d.mts +2 -0
  18. package/dist/commands.d.mts +16 -0
  19. package/dist/commands.mjs +129 -0
  20. package/dist/config.d.mts +87 -20
  21. package/dist/config.mjs +344 -89
  22. package/dist/deps.d.mts +7 -4
  23. package/dist/deps.mjs +20 -9
  24. package/dist/doctor.d.mts +9 -16
  25. package/dist/doctor.mjs +71 -68
  26. package/dist/explain.d.mts +4 -0
  27. package/dist/explain.mjs +174 -0
  28. package/dist/guard-commit.d.mts +7 -2
  29. package/dist/guard-commit.mjs +58 -21
  30. package/dist/init.d.mts +12 -14
  31. package/dist/init.mjs +194 -136
  32. package/dist/lib/default-branch.d.mts +35 -0
  33. package/dist/lib/default-branch.mjs +117 -0
  34. package/dist/lib/has-command.d.mts +5 -0
  35. package/dist/lib/has-command.mjs +8 -0
  36. package/dist/lib/listed.d.mts +2 -0
  37. package/dist/lib/listed.mjs +4 -0
  38. package/dist/lib/refined-check.d.mts +7 -0
  39. package/dist/lib/refined-check.mjs +76 -0
  40. package/dist/lib/work-status.d.mts +12 -2
  41. package/dist/lib/work-status.mjs +14 -3
  42. package/dist/parts.d.mts +18 -15
  43. package/dist/parts.mjs +15 -43
  44. package/dist/patch-coverage.d.mts +13 -0
  45. package/dist/patch-coverage.mjs +73 -0
  46. package/dist/poller.d.mts +20 -3
  47. package/dist/poller.mjs +62 -15
  48. package/dist/pr-watch.d.mts +3 -2
  49. package/dist/pr-watch.mjs +22 -5
  50. package/dist/pr.mjs +34 -2
  51. package/dist/remove.d.mts +11 -0
  52. package/dist/remove.mjs +156 -0
  53. package/dist/runner/github-actions.d.mts +1 -1
  54. package/dist/runner/github-actions.mjs +12 -0
  55. package/dist/runner/index.d.mts +1 -1
  56. package/dist/runner/index.mjs +2 -1
  57. package/dist/runner/setup.d.mts +2 -0
  58. package/dist/runner/setup.mjs +22 -0
  59. package/dist/runner/types.d.mts +3 -0
  60. package/dist/runner/types.mjs +0 -2
  61. package/dist/session-start.d.mts +23 -13
  62. package/dist/session-start.mjs +56 -44
  63. package/dist/setup.d.mts +98 -0
  64. package/dist/setup.mjs +3 -0
  65. package/dist/site/servers.d.mts +6 -2
  66. package/dist/site/servers.mjs +14 -9
  67. package/dist/site.mjs +2 -2
  68. package/dist/status.d.mts +4 -4
  69. package/dist/status.mjs +8 -7
  70. package/dist/sync.d.mts +26 -2
  71. package/dist/sync.mjs +177 -13
  72. package/dist/ticket.mjs +19 -1
  73. package/dist/tickets/github-setup.d.mts +2 -0
  74. package/dist/tickets/github-setup.mjs +50 -0
  75. package/dist/tickets/github.mjs +0 -2
  76. package/dist/tickets/index.mjs +2 -1
  77. package/dist/tickets/transport.mjs +1 -3
  78. package/dist/tickets/types.mjs +0 -2
  79. package/dist/tool-names.d.mts +11 -0
  80. package/dist/tool-names.mjs +20 -0
  81. package/dist/tools.d.mts +56 -0
  82. package/dist/tools.mjs +76 -0
  83. package/docs/builds.md +111 -59
  84. package/docs/cli.md +106 -69
  85. package/docs/configuration.md +489 -171
  86. package/docs/design.md +18 -5
  87. package/docs/developing.md +179 -73
  88. package/docs/existing-repo.md +25 -12
  89. package/docs/github/by-hand.md +334 -0
  90. package/docs/github/reference.md +76 -67
  91. package/docs/github/setup.md +105 -286
  92. package/docs/glossary.md +18 -7
  93. package/docs/limitations.md +39 -12
  94. package/docs/plugins.md +305 -56
  95. package/docs/quick-start.md +85 -100
  96. package/docs/removing.md +37 -17
  97. package/docs/skills.md +121 -62
  98. package/docs/updating.md +150 -9
  99. package/docs/workflow.md +23 -19
  100. package/package.json +1 -1
  101. package/poller.Dockerfile +10 -18
  102. package/review.md +20 -11
  103. package/rules.md +36 -30
  104. package/settings.schema.json +313 -69
  105. package/skills/factory-address-review/SKILL.md +50 -30
  106. package/skills/factory-build/SKILL.md +76 -23
  107. package/skills/factory-deps/SKILL.md +46 -21
  108. package/skills/factory-design/SKILL.md +17 -8
  109. package/skills/factory-diagnose/SKILL.md +22 -20
  110. package/skills/factory-mutate/SKILL.md +38 -24
  111. package/skills/factory-refine/SKILL.md +55 -31
  112. package/skills/factory-resolve-conflicts/SKILL.md +76 -34
  113. package/skills/factory-trace/SKILL.md +80 -0
  114. package/workflows/factory-build.yml +6 -5
  115. package/workflows/factory-conflicts.yml +8 -8
  116. package/workflows/factory-deps-auto-merge.yml +3 -2
  117. package/workflows/factory-deps.yml +1 -1
  118. package/workflows/factory-poller.yml +46 -0
  119. package/workflows/factory-review.yml +1 -1
  120. package/skills/factory-address-review/patch-coverage.py +0 -68
@@ -13,8 +13,10 @@ page explains every key, then shows three complete files.
13
13
  - **Paths are glob patterns.** `*` matches within one folder, `**` matches
14
14
  across folders, and both match names that start with a dot. A pattern with
15
15
  no wildcard matches that one path from the repository's root.
16
- - **A part you can swap is a block with a `type`.** Today each has one type.
17
- When a part has no settings of its own, you may write it as one word:
16
+ - **A command is one line of shell.** Each runs with bash from the
17
+ repository's root, with nothing on its standard input.
18
+ - **A part you can swap is a block with a `type`.** When you write nothing
19
+ else under it, you may write it as one word:
18
20
 
19
21
  ```yaml
20
22
  specs: openspec
@@ -33,31 +35,36 @@ page explains every key, then shows three complete files.
33
35
  ## The shortest file
34
36
 
35
37
  ```yaml
36
- version: 1
38
+ version: 2
37
39
  repository: your-name/your-repo
38
40
  ```
39
41
 
40
- With this, sessions refine and build tickets when you tell them to, nothing
41
- merges without you, and there is no board.
42
+ With this, sessions refine tickets when you tell them to, nothing merges
43
+ without you, and there is no board. A build needs one more key, the gate,
44
+ which is the first entry below.
42
45
 
43
46
  ## The settings most repositories change
44
47
 
45
- Most repositories change three things, and leave every other key at its
46
- default.
48
+ One key is required for a build: [`commands.gate`](#commandsgate). Most
49
+ repositories set it and the four other things below, and leave every other
50
+ key at its default.
47
51
 
52
+ - **The gate,** the commands that check a change, such as your tests and
53
+ your linter. A build cannot finish without it. List them under
54
+ `commands.gate`.
55
+ - **The checks before every commit,** the quick ones of the gate, such as
56
+ your formatter. List them under
57
+ [`commands.before-commit`](#commandsbefore-commit).
48
58
  - **A board,** to see every ticket's state. Set `tickets.board` to your
49
59
  board's number, and when your columns have other names, map them under
50
60
  `tickets.columns`. [`tickets`](#tickets) has both. On GitHub,
51
- [Setting up on GitHub](github/setup.md#a-board) has the steps around
61
+ [Setting up on GitHub](github/setup.md) has the steps around
52
62
  them.
53
63
  - **What merges without you.** List the files that may under
54
64
  `auto-merge.allow`, such as your docs. [`auto-merge`](#auto-merge).
55
- - **Your own reviewers.** An agent of yours, listed under `plugins` with
56
- the files it reads. [`plugins`](#plugins), and
57
- [Plug-ins](plugins.md) for a worked example.
58
-
59
- The commands to run before each commit, [`before-commit`](#before-commit),
60
- are the fourth most repositories set.
65
+ - **Your own reviewers.** An agent of yours, listed under
66
+ `plugins.build.reviewers` with the files it reads.
67
+ [`plugins`](#plugins), and [Plug-ins](plugins.md) for a worked example.
61
68
 
62
69
  After any change, run `factory config check`, and
63
70
  `factory sync`, which rewrites the files a change of
@@ -68,13 +75,16 @@ are read from the settings each time.
68
75
 
69
76
  ### `version`
70
77
 
71
- The shape of this file, not the factory's version. It is `1`. It changes
72
- only when keys are renamed or moved, and an [update](updating.md) converts
73
- your file when it does.
78
+ The shape of this file, not the factory's version. It is `2`. It changes
79
+ only when keys are renamed or moved. No command converts a file: the
80
+ release that changes the shape says so, and
81
+ [Updating](updating.md#moving-to-settings-version-2) shows each key that
82
+ moved, before and after.
74
83
 
75
84
  - **Default:** none. Setup writes it.
76
- - **If wrong:** every command of the factory stops and says which versions it
77
- understands.
85
+ - **If wrong:** every command of the factory that reads the settings stops
86
+ with `version: must be 2`. For a version 1 file it adds where the move
87
+ is described.
78
88
 
79
89
  ### `repository`
80
90
 
@@ -145,8 +155,9 @@ state.
145
155
  when you tell a session to build the ticket or run
146
156
  `factory build N`, so
147
157
  `factory config check` requires `builds.trigger: manual`.
148
- - **If a repository's `ready` column has another name,** the poller needs it
149
- too: see `FACTORY_READY_COLUMN` in [Builds](builds.md).
158
+ - **If a repository's `ready` column has another name,** a poller you host
159
+ needs it too: see `FACTORY_READY_COLUMN` in [Builds](builds.md). A
160
+ scheduled one reads it from here.
150
161
  - `factory config get tickets.columns.ready` prints the
151
162
  name in effect, or `none`.
152
163
 
@@ -206,8 +217,6 @@ It reads no board.
206
217
  else. Only `github` is built. Any other value fails
207
218
  `factory config check` and every ticket command with:
208
219
  `tickets.type "X" is not supported. "github" is the only ticket system built.`
209
- A type that names a package, for an adapter you write yourself, is
210
- planned, not built.
211
220
 
212
221
  ### `code-host`
213
222
 
@@ -237,10 +246,11 @@ builds:
237
246
  runner: github-actions
238
247
  ```
239
248
 
240
- | Key | Meaning | Allowed | Default |
241
- | --------- | --------------------------------------------------- | --------------------------------------- | ---------------- |
242
- | `trigger` | What starts a build for a ticket you moved to Ready | `own-server`, `github-action`, `manual` | `manual` |
243
- | `runner` | Where a build in the cloud runs | `github-actions` | `github-actions` |
249
+ | Key | Meaning | Allowed | Default |
250
+ | -------------- | -------------------------------------------------------------------- | --------------------------------------- | ---------------- |
251
+ | `trigger` | What starts a build for a ticket you moved to Ready | `own-server`, `github-action`, `manual` | `manual` |
252
+ | `runner` | Where a build in the cloud runs | `github-actions` | `github-actions` |
253
+ | `poll-minutes` | How often the scheduled poller reads the board, with `github-action` | 5, 10, 15, 30, or 60 | 5 |
244
254
 
245
255
  `trigger` is what notices a card moved to Ready, and `runner` is where the
246
256
  build it starts then runs: a poller on your own server still starts its
@@ -251,61 +261,126 @@ the settings and reaches the runner, with:
251
261
 
252
262
  - **`manual`:** nothing watches the board. You tell a session "work 12".
253
263
  - **`own-server`:** a small poller you host reads the board once a minute.
254
- - **`github-action`:** a schedule on the cloud runner does the same, more
255
- slowly.
256
- _[Planned](developing.md#what-is-built)_: until it is built, use `own-server` or `manual`.
264
+ - **`github-action`:** a schedule on the cloud runner does the same every
265
+ `poll-minutes` minutes, with nothing to host. On a private repository,
266
+ each pass is billed as at least an Actions minute.
267
+
268
+ `factory config check` fails on `poll-minutes` beside any other trigger,
269
+ and on any value but the five above.
257
270
 
258
- [Builds](builds.md) explains each. **If `trigger` says `own-server` and no
259
- poller is running,** a ticket moved to Ready sits there, and
260
- `factory status` flags it "not started".
271
+ [Builds](builds.md) explains each. **If no poller is running,** a ticket
272
+ moved to Ready sits there, and `factory status` flags it "not started":
273
+ after 5 minutes with `own-server`, and after `poll-minutes` and 15 more
274
+ with `github-action`.
261
275
 
262
276
  ### `specs`
263
277
 
264
- How the written spec for a change your visitors or users will see is kept.
278
+ How the written spec for a change your users will see is kept, and the
279
+ command that checks it.
265
280
 
266
281
  ```yaml
267
282
  specs: openspec
268
283
  ```
269
284
 
270
- | Allowed | Meaning |
285
+ | `type` | Meaning |
271
286
  | ---------- | ------------------------------------------------------------------------- |
272
287
  | `none` | The ticket's acceptance criteria are the only spec |
273
288
  | `openspec` | A visible, non-trivial change also adds its behavior to `openspec/specs/` |
274
289
 
275
290
  - **Default:** `none`.
291
+ - **Written as one word,** as above, or as a block with `type`, which is
292
+ how you also set `check`, the next entry.
276
293
  - **If you set `openspec` without OpenSpec installed:** a build of a visible
277
294
  change stops at its first spec step and says so.
295
+ - `factory config get specs` prints `openspec` or `none`, whichever way it
296
+ is written.
278
297
 
279
- ### `before-commit`
298
+ #### `specs.check`
280
299
 
281
- Commands run, in order, before every commit a session makes. If one fails,
282
- the commit is blocked and the session is shown the output.
300
+ The command that says whether the written specs are sound.
301
+ `factory specs check` runs it, and a build runs that each time it writes a
302
+ spec or folds one into `openspec/specs/`.
283
303
 
284
304
  ```yaml
285
- before-commit:
286
- - npm run -s format:check
287
- - npx tsc --noEmit
288
- - npm run -s lint
305
+ specs:
306
+ type: openspec
307
+ # The command "factory specs check" runs. This is its default.
308
+ check: npx --no-install openspec validate --all --strict --no-interactive
289
309
  ```
290
310
 
291
- - **Default:** none. Setup proposes some from your `package.json`,
292
- `composer.json`, or Makefile, and asks.
293
- - **Keep them fast.** They run on every commit. Your full test suite belongs
294
- in the gate your agent's instructions name, which a session runs before it
295
- reports a task done, and in CI.
296
- - **If one is wrong:** every commit is blocked with that command's error.
311
+ - **Default:** the command above, when `type` is `openspec`. Most
312
+ repositories leave it out.
313
+ - **It runs with `DO_NOT_TRACK=1` in its environment,** so OpenSpec
314
+ collects no usage statistics, and exits with the command's own status.
315
+ - **With `specs: none`,** there is nothing to check: `factory specs check`
316
+ prints `specs are off` and exits 0. Writing `check` there fails
317
+ `factory config check` with `specs.check needs specs.type: openspec`.
318
+ - `factory config get specs.check` prints the command, or `none`.
297
319
 
298
- ### `build-setup`
320
+ ### `commands`
321
+
322
+ The commands a session runs that are your repository's own: how it is set
323
+ up, checked, and tested. The factory's skills name no test runner and no
324
+ linter. They run `factory gate`, `factory test-one`, and the rest, and
325
+ those run what you write here.
326
+
327
+ ```yaml
328
+ # Every command a build runs, each from the repository's root.
329
+ commands:
330
+ # Before an unattended build starts work.
331
+ build-setup:
332
+ - npx playwright install --with-deps chromium
333
+ # Before every commit a session makes.
334
+ before-commit:
335
+ - npm run -s format:check
336
+ - npx tsc --noEmit
337
+ # Before a session reports a task done. "factory gate" runs them in order.
338
+ gate:
339
+ - npm run check
340
+ # One test alone. "factory test-one" sets $FILE and $NAME.
341
+ test-one: npx vitest run $FILE -t "$NAME"
342
+ # One end-to-end spec alone. "factory end-to-end" sets $FILE.
343
+ end-to-end: npx playwright test $FILE
344
+ # Coverage, and where its lcov report lands.
345
+ coverage:
346
+ run: npm run coverage
347
+ report: coverage/lcov.info
348
+ # Rebuilds the lock file after a conflict in it.
349
+ relock: npm install
350
+ ```
299
351
 
300
- Commands run, in order, from the repository's root before a build in the
301
- cloud starts work. Your npm dependencies are already installed by then,
302
- with `npm ci`.
352
+ | Key | Takes | Default | Run by |
353
+ | --------------- | --------------------------- | ------------- | ----------------------------------------------------- |
354
+ | `build-setup` | A list of commands | none | The cloud runner, before an unattended session starts |
355
+ | `before-commit` | A list of commands | none | A hook, before every commit a session makes |
356
+ | `gate` | A list of commands | none | `factory gate` |
357
+ | `test-one` | One command | not set | `factory test-one FILE [NAME]` |
358
+ | `end-to-end` | One command | not set | `factory end-to-end FILE [--times K]` |
359
+ | `coverage` | A block, `run` and `report` | not set | A session judging a pull request's coverage |
360
+ | `relock` | One command | `npm install` | A session, after a conflict in the lock file |
361
+
362
+ - **Only `gate` is needed for a build.** Each of the others turns
363
+ something on, and its entry says what a session does without it.
364
+ - **A list runs in order and stops at the first command that fails.**
365
+ - **`factory config check` fails, naming the key,** on a list that is not a
366
+ list of text, on a single command that is not text or is empty, and on a
367
+ `coverage` block missing `run` or `report`.
368
+ - `factory config get commands.gate` prints one command per line, and
369
+ nothing for an empty list. A single command prints itself, or `none`
370
+ when it is not set, and so do `commands.coverage.run` and
371
+ `commands.coverage.report`.
372
+
373
+ #### `commands.build-setup`
374
+
375
+ Commands run, in order, before a build in the cloud starts work. Your npm
376
+ dependencies are already installed by then, with `npm ci`.
303
377
 
304
378
  ```yaml
305
- # Commands run from the repository's root before an unattended build starts
306
- # work. Your npm dependencies are already installed by then.
307
- build-setup:
308
- - npx playwright install --with-deps chromium
379
+ commands:
380
+ # Commands run from the repository's root before an unattended build
381
+ # starts work. Your npm dependencies are already installed by then.
382
+ build-setup:
383
+ - npx playwright install --with-deps chromium
309
384
  ```
310
385
 
311
386
  - **Default:** none.
@@ -313,8 +388,133 @@ build-setup:
313
388
  such as a browser for end-to-end tests or a system package.
314
389
  - **If one fails:** the run stops before the session starts, with that
315
390
  command's output in its log.
316
- - `factory config get build-setup` prints one command per
317
- line.
391
+
392
+ #### `commands.before-commit`
393
+
394
+ Commands run, in order, before every commit a session makes. If one fails,
395
+ the commit is blocked and the session is shown the output.
396
+
397
+ ```yaml
398
+ commands:
399
+ before-commit:
400
+ - npm run -s format:check
401
+ - npx tsc --noEmit
402
+ - npm run -s lint
403
+ ```
404
+
405
+ - **Default:** none.
406
+ - **Keep them fast.** They run on every commit. Your full test suite
407
+ belongs in [`commands.gate`](#commandsgate), which a session runs once
408
+ before it reports a task done, and in CI.
409
+ - **They apply to a session's commits,** not to the ones you make in your
410
+ own terminal.
411
+ - **If one is wrong:** every commit a session makes is blocked with that
412
+ command's error.
413
+
414
+ #### `commands.gate`
415
+
416
+ The commands that check a change, in order: what has to pass before a
417
+ session reports a task done or opens a pull request. `factory gate` runs
418
+ them, printing `$` and the command before each one.
419
+
420
+ ```yaml
421
+ commands:
422
+ gate:
423
+ - npm run check
424
+ ```
425
+
426
+ - **Default:** none, and nothing stands in for it. With no gate,
427
+ `factory gate` fails with
428
+ `commands.gate is not set: add the commands that check a change to .claude/factory.yaml`,
429
+ and a build stops there: a gate that passed because it was empty would
430
+ look the same as one that passed. `factory init` lists it under "Left to
431
+ do", and `factory doctor` shows it as off.
432
+ - **What goes here:** what your CI runs on a pull request, short of
433
+ anything too slow for a session to wait on: the format check, the type
434
+ check, lint, and the unit tests. Any command works, such as
435
+ `composer test`, `make check`, or `go vet ./...`.
436
+ - **If one fails:** `factory gate` runs none after it, prints
437
+ `gate failed on:` and the command, and exits 1. The session fixes the
438
+ cause and runs the gate again.
439
+
440
+ #### `commands.test-one`
441
+
442
+ Runs one test file alone, or one test in it. `factory test-one FILE NAME`
443
+ runs it with `FILE` and `NAME` in its environment, the way
444
+ [`site.start`](#site) gets `$PORT`. `NAME` is empty when only a file is
445
+ given, so write the command to run the whole file then.
446
+
447
+ ```yaml
448
+ commands:
449
+ # One test alone. An empty NAME runs the whole file.
450
+ test-one: npx vitest run $FILE -t "$NAME"
451
+ ```
452
+
453
+ - **Default:** not set.
454
+ - **What it is for:** watching a new test fail before the change, proving
455
+ a test can fail, and the loop a session builds to find a bug's cause.
456
+ - **Without it,** `factory test-one` fails with
457
+ `commands.test-one is not set`, and a session is left to find its own
458
+ way to run one test.
459
+ - **It exits with the command's own status.**
460
+
461
+ #### `commands.end-to-end`
462
+
463
+ Runs one end-to-end spec alone. `factory end-to-end FILE` runs it with
464
+ `FILE` in its environment. With `--times K` it runs K times in a row,
465
+ stops at the first run that fails, and says which, as
466
+ `failed on run 3 of 10`: a build runs each new spec ten times, since a
467
+ spec that fails one run in ten fails someone's pull request.
468
+
469
+ ```yaml
470
+ commands:
471
+ end-to-end: npx playwright test $FILE
472
+ ```
473
+
474
+ - **Default:** not set. Leave it out of a repository with no end-to-end
475
+ suite.
476
+ - **Setting it also brings `factory-e2e-reviewer`,** the built-in agent
477
+ that reads browser end-to-end tests, in two steps:
478
+ 1. Set this key and run `factory sync`, which writes the agent.
479
+ 2. List it under [`plugins.test.reviewers`](#pluginstest), where it
480
+ runs. That list is the whole list, so list `factory-test-reviewer`
481
+ there too: listing `factory-e2e-reviewer` alone drops it.
482
+ - **Without it,** `factory end-to-end` fails with
483
+ `commands.end-to-end is not set`.
484
+ - **Run `factory sync` after adding or removing it.**
485
+
486
+ #### `commands.coverage`
487
+
488
+ The command that measures test coverage, and where its lcov report lands.
489
+ A session working a pull request's review runs `run` and reads `report` to
490
+ find the changed lines no test covers.
491
+
492
+ ```yaml
493
+ commands:
494
+ coverage:
495
+ run: npm run coverage
496
+ report: coverage/lcov.info
497
+ ```
498
+
499
+ - **Default:** not set. A session then judges no coverage.
500
+ - **Both keys are required** once `coverage` is written.
501
+
502
+ #### `commands.relock`
503
+
504
+ The command that rebuilds your package manager's lock file. After a
505
+ conflict in the lock file, a session takes the default branch's copy and
506
+ runs this, in place of merging the file by hand. A session also runs it to
507
+ install dependencies in a checkout it made.
508
+
509
+ ```yaml
510
+ commands:
511
+ relock: npm install
512
+ ```
513
+
514
+ - **Default:** `npm install`, since the factory itself is installed with
515
+ npm and every repository has that lock file.
516
+ - **Any other generated file** that conflicts is a
517
+ [resolver plug-in's](#pluginsconflicts).
318
518
 
319
519
  ### `session-minutes`
320
520
 
@@ -328,12 +528,12 @@ session-minutes:
328
528
  build: 300
329
529
  ```
330
530
 
331
- | Key | The session | Default |
332
- | -------------- | --------------------------------------------- | ------- |
333
- | `build` | A build of a ticket | `230` |
334
- | `conflicts` | A fix of a pull request's conflicts with main | `110` |
335
- | `review` | An answer to your review of a pull request | `50` |
336
- | `dependencies` | Work on the dependency pull requests | `50` |
531
+ | Key | The session | Default |
532
+ | -------------- | ----------------------------------------------------------- | ------- |
533
+ | `build` | A build of a ticket | `230` |
534
+ | `conflicts` | A fix of a pull request's conflicts with the default branch | `110` |
535
+ | `review` | An answer to your review of a pull request | `50` |
536
+ | `dependencies` | Work on the dependency pull requests | `50` |
337
537
 
338
538
  - **Each is a whole number above zero.** A key you leave out keeps its
339
539
  default.
@@ -352,45 +552,138 @@ session-minutes:
352
552
 
353
553
  ### `plugins`
354
554
 
355
- Your own skills and agents, and the job each does. Refining, building, and
356
- reviewing tests are built in; these add to them.
555
+ Your own skills and agents, grouped by the phase of the work each is called
556
+ in: `refine`, `build`, `test`, and `conflicts`. Under each phase are its
557
+ slots, the moments where the factory hands off. Every slot is optional, and
558
+ leaving one out never turns a step off: the factory's own skill or agent
559
+ does it. [Plug-ins](plugins.md) says what each slot is handed and what it
560
+ has to return.
357
561
 
358
562
  ```yaml
563
+ # Your own skills and agents, by phase. Every slot is optional.
359
564
  plugins:
360
- - skill: design-mockups
361
- role: mockups
362
- - skill: add-endpoint
363
- role: builder
364
- labels:
365
- - new-endpoint
366
- - agent: migration-reviewer
367
- role: reviewer
368
- files:
369
- - db/migrations/**
565
+ refine:
566
+ # Replaces factory-refine. Must deliver what the build reads.
567
+ refiner:
568
+ skill: acme-refine
569
+ # Makes pictures when a decision changes the look. One only.
570
+ mockups:
571
+ skill: design-mockups
572
+ build:
573
+ # Each builds a ticket that carries one of its labels.
574
+ builders:
575
+ - skill: add-endpoint
576
+ labels:
577
+ - new-endpoint
578
+ # Each is considered when a change touches one of its files.
579
+ reviewers:
580
+ - agent: migration-reviewer
581
+ files:
582
+ - db/migrations/**
583
+ test:
584
+ # Replaces factory-mutate: proves each new test can fail.
585
+ prover:
586
+ skill: acme-mutation
587
+ # The whole list of test reviewers. Left out, it is factory-test-reviewer.
588
+ reviewers:
589
+ - agent: factory-test-reviewer
590
+ - agent: factory-e2e-reviewer
591
+ files:
592
+ - e2e/**
593
+ conflicts:
594
+ # Each rebuilds its files after a conflict, in place of a hand merge.
595
+ resolvers:
596
+ - skill: regenerate-api-client
597
+ files:
598
+ - src/generated/**
370
599
  ```
371
600
 
372
- | Key | Meaning |
373
- | ---------------- | --------------------------------------------------------------------- |
374
- | `skill`, `agent` | The name of one of your own skills or agents |
375
- | `role` | `mockups`, `builder`, or `reviewer` |
376
- | `labels` | For a `builder`: it builds a ticket carrying one of these labels |
377
- | `files` | For a `reviewer`: it is considered when a change touches one of these |
378
-
379
- Where your coding agent keeps them: in Claude Code, see
601
+ Each slot takes one kind, a skill or an agent, and either one plug-in or
602
+ a list of them. A reviewer is an agent, since it is launched to read and
603
+ changes nothing. Every other slot is a skill, which the session follows.
604
+
605
+ | Slot | Takes | One or a list | `files` or `labels` | Left out |
606
+ | --------------------- | ------- | ------------- | ------------------- | ---------------------------------------------------------- |
607
+ | `refine.refiner` | A skill | One | Neither | `factory-refine` |
608
+ | `refine.mockups` | A skill | One | Neither | `factory-design` with [`site`](#site) set; otherwise words |
609
+ | `build.builders` | Skills | A list | `labels`, required | The built-in build |
610
+ | `build.reviewers` | Agents | A list | `files`, required | No reviewers of your own |
611
+ | `test.prover` | A skill | One | Neither | `factory-mutate` |
612
+ | `test.reviewers` | Agents | A list | `files`, optional | `factory-test-reviewer` |
613
+ | `conflicts.resolvers` | Skills | A list | `files`, required | A merge by hand, and [`commands.relock`](#commandsrelock) |
614
+
615
+ Where your coding agent keeps skills and agents: in Claude Code, see
380
616
  [Skills in Claude Code](github/reference.md#skills-in-claude-code).
381
617
 
382
- - **Default:** none.
383
- - **`files` is a filter, not the whole rule.** When a reviewer really
384
- applies is in that agent's own description. A reviewer whose files matched
385
- but which did not apply gets one line in the pull request saying why.
386
- - **If a name is wrong:** `factory config check` fails and
387
- names the missing file.
618
+ - **`factory plugins` prints the plug-ins the factory will use,** one to a
619
+ line, the built-in ones included: its kind, its name, its slot, then its
620
+ files or labels. `factory plugins SLOT` prints one slot's, where the
621
+ slot is `refiner`, `mockups`, `builder`, `reviewer`, `prover`,
622
+ `test-reviewer`, or `resolver`.
623
+ - **`factory config check` fails, naming the slot,** on a skill where the
624
+ slot takes an agent or an agent where it takes a skill, on `files` or
625
+ `labels` where the slot takes neither, on a builder with no `labels`,
626
+ on a build reviewer or a resolver with no `files`, and on a name whose
627
+ file does not exist. It warns on a `files` pattern that matches no file.
628
+ - **Written as a list,** the shape before settings version 2, `plugins`
629
+ fails with `plugins: must be grouped by phase: refine, build, test, conflicts`.
630
+ [Updating](updating.md#moving-to-settings-version-2) shows where each
631
+ plug-in goes.
632
+ - **`plugins: {}`, or a phase with nothing under it,** is the same as
633
+ leaving it out.
634
+
635
+ #### `plugins.refine`
636
+
637
+ - **`refiner`:** the skill that refines a ticket, in place of
638
+ `factory-refine`. One skill, with no `files` and no `labels`.
639
+ - **`mockups`:** the skill that makes pictures to choose from when a
640
+ decision changes how something looks. One skill. A repository with
641
+ [`site`](#site) set has the factory's own `factory-design` here without
642
+ writing it; any other describes the decision in words.
643
+
644
+ #### `plugins.build`
645
+
646
+ - **`builders`:** each is a skill that builds a ticket carrying one of its
647
+ `labels`, in place of the built-in build step. `labels` is required.
648
+ When two builders share a label, the first listed builds the ticket.
649
+ - **`reviewers`:** each is an agent considered when a change touches a
650
+ file matching one of its `files`, which is required.
651
+ **`files` is a filter, not the whole rule.** When a reviewer really
652
+ applies is in that agent's own description. A reviewer whose files
653
+ matched but which did not apply gets one line in the pull request saying
654
+ why.
655
+
656
+ #### `plugins.test`
657
+
658
+ - **`prover`:** the skill that proves a new test can fail, in place of
659
+ `factory-mutate`. One skill. It cannot be set to nothing: a test's red
660
+ run before the change is already a proof, and a test written after the
661
+ code needs one.
662
+ - **`reviewers`:** the agents that read new and changed tests. **Written,
663
+ it is the whole list:** `factory-test-reviewer` runs only when you list
664
+ it, and `reviewers: []` means no test reviewer runs. `files` is
665
+ optional: without it a reviewer reads whenever a change touches tests,
666
+ and with it only when the change touches a matching file. Listing
667
+ `factory-e2e-reviewer` needs
668
+ [`commands.end-to-end`](#commandsend-to-end).
669
+
670
+ #### `plugins.conflicts`
671
+
672
+ - **`resolvers`:** each is a skill that rebuilds the files matching its
673
+ `files` after a conflict, in place of merging them by hand, such as a
674
+ generated API client. `files` is required. When two resolvers match one
675
+ file, the first listed rebuilds it. The package manager's lock file
676
+ needs no resolver: [`commands.relock`](#commandsrelock) rebuilds it.
677
+ - **The conflict sweep reads resolvers from your default branch,** never
678
+ from a pull request's branch, so a new resolver is used once it has
679
+ merged.
388
680
 
389
681
  ### `site`
390
682
 
391
683
  How the factory looks at your website. Leave it out if the repository is not
392
- one. With it, and `factory-ui-reviewer` listed under `plugins`, a visible
393
- change is pictured before and after, and the difference is reviewed.
684
+ one. With it, and `factory-ui-reviewer` listed under
685
+ `plugins.build.reviewers`, a visible change is pictured before and after,
686
+ and the difference is reviewed.
394
687
 
395
688
  ```yaml
396
689
  site:
@@ -518,8 +811,7 @@ The automated review of every pull request: Claude reads each one once it
518
811
  is marked ready, comments on what it finds, and posts a verdict. It is on
519
812
  while `ci-review` is written, even with nothing under it, and `factory
520
813
  sync` then writes its workflow, `.github/workflows/factory-claude-review.yml`.
521
- [The automated review](github/setup.md#the-automated-review) has the steps
522
- it needs on GitHub.
814
+ [Setting up on GitHub](github/setup.md) has what it needs on GitHub.
523
815
 
524
816
  ```yaml
525
817
  # The automated review of every pull request, on while this is written.
@@ -569,10 +861,9 @@ and never takes one as an instruction.
569
861
 
570
862
  ### `rules`
571
863
 
572
- _[Planned](developing.md#what-is-built)_: `factory config check`
573
- refuses this key until it is built.
574
-
575
864
  Numbers the process rules use, for a repository that wants different ones.
865
+ `factory sync` writes each into the copies of the rules and skills that
866
+ state it, so run it after changing one.
576
867
 
577
868
  ```yaml
578
869
  rules:
@@ -580,10 +871,10 @@ rules:
580
871
  review-rounds: 2
581
872
  ```
582
873
 
583
- | Key | Meaning | Default |
584
- | -------------------- | --------------------------------------------------------------------- | ------- |
585
- | `small-change-lines` | A change under this many lines, outside tests, takes the lighter path | `30` |
586
- | `review-rounds` | Rounds a session works a review before it hands what is left to you | `2` |
874
+ | Key | Meaning | Default |
875
+ | -------------------- | -------------------------------------------------------------------------------------------------------------------------- | ------- |
876
+ | `small-change-lines` | A change under this many lines outside tests, specs, and content, adding no component and no state, takes the lighter path | `30` |
877
+ | `review-rounds` | Rounds a session works a review before it hands what is left to you | `2` |
587
878
 
588
879
  - **If a value is not a whole number above zero:**
589
880
  `factory config check` fails and names the key.
@@ -594,12 +885,12 @@ factory's rules.
594
885
 
595
886
  ## Checking the file
596
887
 
597
- | Command | What it does |
598
- | ------------------------ | ------------------------------------------------------------------------------------------------------------------ |
599
- | Your editor | The first line of the file points at the factory's schema, which flags a misspelled key as you type it |
600
- | `factory config check` | Fails on an unknown key, a wrong type, a plug-in with no file, and warns on a pattern matching nothing. Runs in CI |
601
- | `factory config explain` | _[Planned](developing.md#what-is-built)_: Prints every setting in effect, with whether it is the default or yours |
602
- | `factory doctor` | Checks the file against the real board, and that each secret your parts read is set |
888
+ | Command | What it does |
889
+ | ------------------------ | ---------------------------------------------------------------------------------------------------------------------- |
890
+ | Your editor | The first line of the file points at the factory's schema, which flags a misspelled key as you type it |
891
+ | `factory config check` | Fails on an unknown key, a wrong type, a plug-in with no file, and warns on a pattern matching nothing. Runs in CI |
892
+ | `factory config explain` | Prints every setting in effect, as the file would read with every default written out, each default marked `# default` |
893
+ | `factory doctor` | Checks the file against the real board, and that each secret your parts read is set |
603
894
 
604
895
  The first line of the file, which the three files below start with:
605
896
 
@@ -636,7 +927,7 @@ unread; anything touching checkout or consent waits for a person.
636
927
  # built-in reviewers run.
637
928
  #
638
929
  # "version" is the shape of this file, not the factory's version.
639
- version: 1
930
+ version: 2
640
931
  repository: harbor-goods/storefront
641
932
 
642
933
  # Where tickets live. "board" is the number in your GitHub Project's address.
@@ -654,40 +945,48 @@ builds:
654
945
  # or none.
655
946
  specs: openspec
656
947
 
657
- # Commands run on the session's machine, from the repository's root, before
658
- # every commit it makes. If one fails, the commit is blocked.
659
- before-commit:
660
- - npm run -s format:check
661
- - npx tsc --noEmit
662
- - npm run -s lint
663
-
664
- # Your own skills and agents. A skill is a set of instructions a session
665
- # follows; an agent is a separate reviewer a session launches. Refining,
666
- # building, and reviewing tests are built in; these add to them. "role" is
667
- # one of:
668
- # mockups makes pictures to choose from when a decision changes the look
669
- # builder builds a ticket that carries one of "labels" (label names),
670
- # in place of the built-in build
671
- # reviewer is asked to read a finished change when it touches a path
672
- # matching "files", and reports problems; it edits nothing
948
+ # Every command a build runs, each from the repository's root.
949
+ commands:
950
+ # Run on the session's machine before every commit it makes. If one
951
+ # fails, the commit is blocked.
952
+ before-commit:
953
+ - npm run -s format:check
954
+ - npx tsc --noEmit
955
+ - npm run -s lint
956
+ # Run before a session reports a task done, in order. A build cannot
957
+ # finish until they pass.
958
+ gate:
959
+ - npm run check
960
+ # Runs one test alone. $FILE is the test's file and $NAME the test's
961
+ # name, which is empty when the whole file is wanted.
962
+ test-one: npx vitest run $FILE -t "$NAME"
963
+
964
+ # Your own skills and agents, grouped by the phase they work in. A skill is
965
+ # a set of instructions a session follows; an agent is a separate reviewer a
966
+ # session launches. Refining, building, and reviewing tests are built in.
967
+ # Under "build":
968
+ # builders each builds a ticket that carries one of its "labels" (label
969
+ # names), in place of the built-in build
970
+ # reviewers each is asked to read a finished change when it touches a
971
+ # path matching its "files", and reports problems; it edits
972
+ # nothing
673
973
  plugins:
674
- - skill: add-endpoint
675
- role: builder
676
- labels:
677
- - new-endpoint
678
- - agent: migration-reviewer
679
- role: reviewer
680
- files:
681
- - db/migrations/**
682
- - agent: factory-ui-reviewer
683
- role: reviewer
684
- files:
685
- - src/components/**
686
- - src/styles/**
687
- - agent: accessibility-reviewer
688
- role: reviewer
689
- files:
690
- - src/components/**
974
+ build:
975
+ builders:
976
+ - skill: add-endpoint
977
+ labels:
978
+ - new-endpoint
979
+ reviewers:
980
+ - agent: migration-reviewer
981
+ files:
982
+ - db/migrations/**
983
+ - agent: factory-ui-reviewer
984
+ files:
985
+ - src/components/**
986
+ - src/styles/**
987
+ - agent: accessibility-reviewer
988
+ files:
989
+ - src/components/**
691
990
 
692
991
  # How the factory looks at this website, for factory-ui-reviewer.
693
992
  site:
@@ -728,18 +1027,24 @@ merging unread. Everything not written here is a default.
728
1027
  # built-in reviewers run.
729
1028
  #
730
1029
  # "version" is the shape of this file, not the factory's version.
731
- version: 1
1030
+ version: 2
732
1031
  repository: riverbend-studio/site
733
1032
 
734
1033
  # Where tickets live. "board" is the number in your GitHub Project's address.
735
1034
  tickets:
736
1035
  board: 4
737
1036
 
738
- # Commands run on the session's machine, from the repository's root, before
739
- # every commit it makes. If one fails, the commit is blocked.
740
- before-commit:
741
- - npm run lint
742
- - npm run typecheck
1037
+ # Every command a build runs, each from the repository's root.
1038
+ commands:
1039
+ # Run on the session's machine before every commit it makes. If one
1040
+ # fails, the commit is blocked.
1041
+ before-commit:
1042
+ - npm run lint
1043
+ - npm run typecheck
1044
+ # Run before a session reports a task done, in order. A build cannot
1045
+ # finish until they pass.
1046
+ gate:
1047
+ - npm test
743
1048
  ```
744
1049
 
745
1050
  Builds start when someone tells a session to work a ticket, since
@@ -747,8 +1052,9 @@ Builds start when someone tells a session to work a ticket, since
747
1052
 
748
1053
  ### A repository that is not JavaScript
749
1054
 
750
- A PHP library. Its commands are Composer's. It lets documentation merge
751
- unread and has one reviewer of its own for its public API.
1055
+ A PHP library. Its commands are Composer's and PHPUnit's. It lets
1056
+ documentation merge unread and has one reviewer of its own for its public
1057
+ API.
752
1058
 
753
1059
  ```yaml
754
1060
  # $schema: ../node_modules/@davidbyoung/software-factory/settings.schema.json
@@ -760,7 +1066,7 @@ unread and has one reviewer of its own for its public API.
760
1066
  # built-in reviewers run.
761
1067
  #
762
1068
  # "version" is the shape of this file, not the factory's version.
763
- version: 1
1069
+ version: 2
764
1070
  repository: northwind-php/ledger
765
1071
 
766
1072
  # Where tickets live. "board" is the number in your GitHub Project's address.
@@ -768,26 +1074,38 @@ tickets:
768
1074
  type: github
769
1075
  board: 2
770
1076
 
771
- # Commands run on the session's machine, from the repository's root, before
772
- # every commit it makes. If one fails, the commit is blocked.
773
- before-commit:
774
- - composer lint
775
- - composer analyse
776
-
777
- # Your own skills and agents. A skill is a set of instructions a session
778
- # follows; an agent is a separate reviewer a session launches. Refining,
779
- # building, and reviewing tests are built in; these add to them. "role" is
780
- # one of:
781
- # mockups makes pictures to choose from when a decision changes the look
782
- # builder builds a ticket that carries one of "labels" (label names),
783
- # in place of the built-in build
784
- # reviewer is asked to read a finished change when it touches a path
785
- # matching "files", and reports problems; it edits nothing
1077
+ # Every command a build runs, each from the repository's root.
1078
+ commands:
1079
+ # Run on the session's machine before every commit it makes. If one
1080
+ # fails, the commit is blocked.
1081
+ before-commit:
1082
+ - composer lint
1083
+ - composer analyse
1084
+ # Run before a session reports a task done, in order. A build cannot
1085
+ # finish until they pass.
1086
+ gate:
1087
+ - composer lint
1088
+ - composer analyse
1089
+ - composer test
1090
+ # Runs one test alone. $FILE is the test's file and $NAME the test's
1091
+ # name, which is empty when the whole file is wanted.
1092
+ test-one: vendor/bin/phpunit $FILE ${NAME:+--filter "$NAME"}
1093
+
1094
+ # Your own skills and agents, grouped by the phase they work in. A skill is
1095
+ # a set of instructions a session follows; an agent is a separate reviewer a
1096
+ # session launches. Refining, building, and reviewing tests are built in.
1097
+ # Under "build":
1098
+ # builders each builds a ticket that carries one of its "labels" (label
1099
+ # names), in place of the built-in build
1100
+ # reviewers each is asked to read a finished change when it touches a
1101
+ # path matching its "files", and reports problems; it edits
1102
+ # nothing
786
1103
  plugins:
787
- - agent: api-compatibility-reviewer
788
- role: reviewer
789
- files:
790
- - src/**
1104
+ build:
1105
+ reviewers:
1106
+ - agent: api-compatibility-reviewer
1107
+ files:
1108
+ - src/**
791
1109
 
792
1110
  # Which pull requests may merge without you. Patterns are globs matched
793
1111
  # against paths from the repository's root, and deny wins over allow. A pull
@@ -802,8 +1120,8 @@ auto-merge:
802
1120
  ```
803
1121
 
804
1122
  If this team moved its tickets to Jira, only the `tickets` block would
805
- change. **No Jira support is built or planned**; the block below shows the
806
- shape the design leaves room for.
1123
+ change. **Only GitHub is built**; the block below shows the shape the
1124
+ design leaves room for.
807
1125
 
808
1126
  ```yaml
809
1127
  tickets: