@davidbyoung/software-factory 0.1.3 → 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 (72) hide show
  1. package/README.md +12 -11
  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/cli.mjs +29 -2
  7. package/dist/commands.d.mts +16 -0
  8. package/dist/commands.mjs +129 -0
  9. package/dist/config.d.mts +61 -13
  10. package/dist/config.mjs +267 -65
  11. package/dist/deps.d.mts +7 -4
  12. package/dist/deps.mjs +20 -9
  13. package/dist/doctor.d.mts +3 -2
  14. package/dist/doctor.mjs +19 -4
  15. package/dist/explain.d.mts +4 -2
  16. package/dist/explain.mjs +66 -19
  17. package/dist/guard-commit.d.mts +7 -2
  18. package/dist/guard-commit.mjs +58 -21
  19. package/dist/init.d.mts +4 -2
  20. package/dist/init.mjs +15 -5
  21. package/dist/lib/default-branch.d.mts +35 -0
  22. package/dist/lib/default-branch.mjs +117 -0
  23. package/dist/lib/refined-check.d.mts +7 -0
  24. package/dist/lib/refined-check.mjs +76 -0
  25. package/dist/patch-coverage.d.mts +13 -0
  26. package/dist/patch-coverage.mjs +73 -0
  27. package/dist/pr-watch.d.mts +3 -2
  28. package/dist/pr-watch.mjs +22 -5
  29. package/dist/pr.mjs +34 -2
  30. package/dist/session-start.d.mts +23 -13
  31. package/dist/session-start.mjs +56 -44
  32. package/dist/site/servers.d.mts +6 -2
  33. package/dist/site/servers.mjs +14 -9
  34. package/dist/site.mjs +2 -2
  35. package/dist/sync.d.mts +8 -2
  36. package/dist/sync.mjs +40 -6
  37. package/dist/ticket.mjs +19 -1
  38. package/docs/builds.md +8 -8
  39. package/docs/cli.md +82 -45
  40. package/docs/configuration.md +455 -139
  41. package/docs/design.md +17 -4
  42. package/docs/developing.md +37 -6
  43. package/docs/existing-repo.md +8 -6
  44. package/docs/github/by-hand.md +23 -10
  45. package/docs/github/reference.md +19 -14
  46. package/docs/github/setup.md +12 -9
  47. package/docs/glossary.md +13 -3
  48. package/docs/limitations.md +27 -2
  49. package/docs/plugins.md +302 -48
  50. package/docs/quick-start.md +36 -8
  51. package/docs/removing.md +1 -1
  52. package/docs/skills.md +101 -52
  53. package/docs/updating.md +148 -3
  54. package/docs/workflow.md +13 -10
  55. package/package.json +1 -1
  56. package/review.md +20 -11
  57. package/rules.md +22 -18
  58. package/settings.schema.json +289 -69
  59. package/skills/factory-address-review/SKILL.md +50 -30
  60. package/skills/factory-build/SKILL.md +75 -22
  61. package/skills/factory-deps/SKILL.md +46 -21
  62. package/skills/factory-design/SKILL.md +17 -8
  63. package/skills/factory-diagnose/SKILL.md +22 -20
  64. package/skills/factory-mutate/SKILL.md +38 -24
  65. package/skills/factory-refine/SKILL.md +55 -31
  66. package/skills/factory-resolve-conflicts/SKILL.md +76 -34
  67. package/skills/factory-trace/SKILL.md +3 -2
  68. package/workflows/factory-build.yml +1 -1
  69. package/workflows/factory-conflicts.yml +8 -8
  70. package/workflows/factory-deps.yml +1 -1
  71. package/workflows/factory-review.yml +1 -1
  72. 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,18 +35,26 @@ 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,
@@ -52,12 +62,9 @@ default.
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
 
@@ -265,51 +275,112 @@ with `github-action`.
265
275
 
266
276
  ### `specs`
267
277
 
268
- 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.
269
280
 
270
281
  ```yaml
271
282
  specs: openspec
272
283
  ```
273
284
 
274
- | Allowed | Meaning |
285
+ | `type` | Meaning |
275
286
  | ---------- | ------------------------------------------------------------------------- |
276
287
  | `none` | The ticket's acceptance criteria are the only spec |
277
288
  | `openspec` | A visible, non-trivial change also adds its behavior to `openspec/specs/` |
278
289
 
279
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.
280
293
  - **If you set `openspec` without OpenSpec installed:** a build of a visible
281
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.
282
297
 
283
- ### `before-commit`
298
+ #### `specs.check`
284
299
 
285
- Commands run, in order, before every commit a session makes. If one fails,
286
- 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/`.
287
303
 
288
304
  ```yaml
289
- before-commit:
290
- - npm run -s format:check
291
- - npx tsc --noEmit
292
- - 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
293
309
  ```
294
310
 
295
- - **Default:** none. Setup proposes some from your `package.json`,
296
- `composer.json`, or Makefile, and asks.
297
- - **Keep them fast.** They run on every commit. Your full test suite belongs
298
- in the gate your agent's instructions name, which a session runs before it
299
- reports a task done, and in CI.
300
- - **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`.
301
319
 
302
- ### `build-setup`
320
+ ### `commands`
303
321
 
304
- Commands run, in order, from the repository's root before a build in the
305
- cloud starts work. Your npm dependencies are already installed by then,
306
- with `npm ci`.
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.
307
326
 
308
327
  ```yaml
309
- # Commands run from the repository's root before an unattended build starts
310
- # work. Your npm dependencies are already installed by then.
311
- build-setup:
312
- - npx playwright install --with-deps chromium
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
+ ```
351
+
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`.
377
+
378
+ ```yaml
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
313
384
  ```
314
385
 
315
386
  - **Default:** none.
@@ -317,8 +388,133 @@ build-setup:
317
388
  such as a browser for end-to-end tests or a system package.
318
389
  - **If one fails:** the run stops before the session starts, with that
319
390
  command's output in its log.
320
- - `factory config get build-setup` prints one command per
321
- 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).
322
518
 
323
519
  ### `session-minutes`
324
520
 
@@ -332,12 +528,12 @@ session-minutes:
332
528
  build: 300
333
529
  ```
334
530
 
335
- | Key | The session | Default |
336
- | -------------- | --------------------------------------------- | ------- |
337
- | `build` | A build of a ticket | `230` |
338
- | `conflicts` | A fix of a pull request's conflicts with main | `110` |
339
- | `review` | An answer to your review of a pull request | `50` |
340
- | `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` |
341
537
 
342
538
  - **Each is a whole number above zero.** A key you leave out keeps its
343
539
  default.
@@ -356,45 +552,138 @@ session-minutes:
356
552
 
357
553
  ### `plugins`
358
554
 
359
- Your own skills and agents, and the job each does. Refining, building, and
360
- 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.
361
561
 
362
562
  ```yaml
563
+ # Your own skills and agents, by phase. Every slot is optional.
363
564
  plugins:
364
- - skill: design-mockups
365
- role: mockups
366
- - skill: add-endpoint
367
- role: builder
368
- labels:
369
- - new-endpoint
370
- - agent: migration-reviewer
371
- role: reviewer
372
- files:
373
- - 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/**
374
599
  ```
375
600
 
376
- | Key | Meaning |
377
- | ---------------- | --------------------------------------------------------------------- |
378
- | `skill`, `agent` | The name of one of your own skills or agents |
379
- | `role` | `mockups`, `builder`, or `reviewer` |
380
- | `labels` | For a `builder`: it builds a ticket carrying one of these labels |
381
- | `files` | For a `reviewer`: it is considered when a change touches one of these |
382
-
383
- 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
384
616
  [Skills in Claude Code](github/reference.md#skills-in-claude-code).
385
617
 
386
- - **Default:** none.
387
- - **`files` is a filter, not the whole rule.** When a reviewer really
388
- applies is in that agent's own description. A reviewer whose files matched
389
- but which did not apply gets one line in the pull request saying why.
390
- - **If a name is wrong:** `factory config check` fails and
391
- 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.
392
680
 
393
681
  ### `site`
394
682
 
395
683
  How the factory looks at your website. Leave it out if the repository is not
396
- one. With it, and `factory-ui-reviewer` listed under `plugins`, a visible
397
- 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.
398
687
 
399
688
  ```yaml
400
689
  site:
@@ -638,7 +927,7 @@ unread; anything touching checkout or consent waits for a person.
638
927
  # built-in reviewers run.
639
928
  #
640
929
  # "version" is the shape of this file, not the factory's version.
641
- version: 1
930
+ version: 2
642
931
  repository: harbor-goods/storefront
643
932
 
644
933
  # Where tickets live. "board" is the number in your GitHub Project's address.
@@ -656,40 +945,48 @@ builds:
656
945
  # or none.
657
946
  specs: openspec
658
947
 
659
- # Commands run on the session's machine, from the repository's root, before
660
- # every commit it makes. If one fails, the commit is blocked.
661
- before-commit:
662
- - npm run -s format:check
663
- - npx tsc --noEmit
664
- - npm run -s lint
665
-
666
- # Your own skills and agents. A skill is a set of instructions a session
667
- # follows; an agent is a separate reviewer a session launches. Refining,
668
- # building, and reviewing tests are built in; these add to them. "role" is
669
- # one of:
670
- # mockups makes pictures to choose from when a decision changes the look
671
- # builder builds a ticket that carries one of "labels" (label names),
672
- # in place of the built-in build
673
- # reviewer is asked to read a finished change when it touches a path
674
- # 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
675
973
  plugins:
676
- - skill: add-endpoint
677
- role: builder
678
- labels:
679
- - new-endpoint
680
- - agent: migration-reviewer
681
- role: reviewer
682
- files:
683
- - db/migrations/**
684
- - agent: factory-ui-reviewer
685
- role: reviewer
686
- files:
687
- - src/components/**
688
- - src/styles/**
689
- - agent: accessibility-reviewer
690
- role: reviewer
691
- files:
692
- - 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/**
693
990
 
694
991
  # How the factory looks at this website, for factory-ui-reviewer.
695
992
  site:
@@ -730,18 +1027,24 @@ merging unread. Everything not written here is a default.
730
1027
  # built-in reviewers run.
731
1028
  #
732
1029
  # "version" is the shape of this file, not the factory's version.
733
- version: 1
1030
+ version: 2
734
1031
  repository: riverbend-studio/site
735
1032
 
736
1033
  # Where tickets live. "board" is the number in your GitHub Project's address.
737
1034
  tickets:
738
1035
  board: 4
739
1036
 
740
- # Commands run on the session's machine, from the repository's root, before
741
- # every commit it makes. If one fails, the commit is blocked.
742
- before-commit:
743
- - npm run lint
744
- - 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
745
1048
  ```
746
1049
 
747
1050
  Builds start when someone tells a session to work a ticket, since
@@ -749,8 +1052,9 @@ Builds start when someone tells a session to work a ticket, since
749
1052
 
750
1053
  ### A repository that is not JavaScript
751
1054
 
752
- A PHP library. Its commands are Composer's. It lets documentation merge
753
- 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.
754
1058
 
755
1059
  ```yaml
756
1060
  # $schema: ../node_modules/@davidbyoung/software-factory/settings.schema.json
@@ -762,7 +1066,7 @@ unread and has one reviewer of its own for its public API.
762
1066
  # built-in reviewers run.
763
1067
  #
764
1068
  # "version" is the shape of this file, not the factory's version.
765
- version: 1
1069
+ version: 2
766
1070
  repository: northwind-php/ledger
767
1071
 
768
1072
  # Where tickets live. "board" is the number in your GitHub Project's address.
@@ -770,26 +1074,38 @@ tickets:
770
1074
  type: github
771
1075
  board: 2
772
1076
 
773
- # Commands run on the session's machine, from the repository's root, before
774
- # every commit it makes. If one fails, the commit is blocked.
775
- before-commit:
776
- - composer lint
777
- - composer analyse
778
-
779
- # Your own skills and agents. A skill is a set of instructions a session
780
- # follows; an agent is a separate reviewer a session launches. Refining,
781
- # building, and reviewing tests are built in; these add to them. "role" is
782
- # one of:
783
- # mockups makes pictures to choose from when a decision changes the look
784
- # builder builds a ticket that carries one of "labels" (label names),
785
- # in place of the built-in build
786
- # reviewer is asked to read a finished change when it touches a path
787
- # 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
788
1103
  plugins:
789
- - agent: api-compatibility-reviewer
790
- role: reviewer
791
- files:
792
- - src/**
1104
+ build:
1105
+ reviewers:
1106
+ - agent: api-compatibility-reviewer
1107
+ files:
1108
+ - src/**
793
1109
 
794
1110
  # Which pull requests may merge without you. Patterns are globs matched
795
1111
  # against paths from the repository's root, and deny wins over allow. A pull