@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.
- package/README.md +12 -11
- package/actions/factory-agent/action.yml +1 -1
- package/agents/factory-e2e-reviewer.md +102 -0
- package/agents/factory-test-reviewer.md +26 -64
- package/agents/factory-ticket-readiness.md +14 -6
- package/dist/cli.mjs +29 -2
- package/dist/commands.d.mts +16 -0
- package/dist/commands.mjs +129 -0
- package/dist/config.d.mts +61 -13
- package/dist/config.mjs +267 -65
- package/dist/deps.d.mts +7 -4
- package/dist/deps.mjs +20 -9
- package/dist/doctor.d.mts +3 -2
- package/dist/doctor.mjs +19 -4
- package/dist/explain.d.mts +4 -2
- package/dist/explain.mjs +66 -19
- package/dist/guard-commit.d.mts +7 -2
- package/dist/guard-commit.mjs +58 -21
- package/dist/init.d.mts +4 -2
- package/dist/init.mjs +15 -5
- package/dist/lib/default-branch.d.mts +35 -0
- package/dist/lib/default-branch.mjs +117 -0
- package/dist/lib/refined-check.d.mts +7 -0
- package/dist/lib/refined-check.mjs +76 -0
- package/dist/patch-coverage.d.mts +13 -0
- package/dist/patch-coverage.mjs +73 -0
- package/dist/pr-watch.d.mts +3 -2
- package/dist/pr-watch.mjs +22 -5
- package/dist/pr.mjs +34 -2
- package/dist/session-start.d.mts +23 -13
- package/dist/session-start.mjs +56 -44
- package/dist/site/servers.d.mts +6 -2
- package/dist/site/servers.mjs +14 -9
- package/dist/site.mjs +2 -2
- package/dist/sync.d.mts +8 -2
- package/dist/sync.mjs +40 -6
- package/dist/ticket.mjs +19 -1
- package/docs/builds.md +8 -8
- package/docs/cli.md +82 -45
- package/docs/configuration.md +455 -139
- package/docs/design.md +17 -4
- package/docs/developing.md +37 -6
- package/docs/existing-repo.md +8 -6
- package/docs/github/by-hand.md +23 -10
- package/docs/github/reference.md +19 -14
- package/docs/github/setup.md +12 -9
- package/docs/glossary.md +13 -3
- package/docs/limitations.md +27 -2
- package/docs/plugins.md +302 -48
- package/docs/quick-start.md +36 -8
- package/docs/removing.md +1 -1
- package/docs/skills.md +101 -52
- package/docs/updating.md +148 -3
- package/docs/workflow.md +13 -10
- package/package.json +1 -1
- package/review.md +20 -11
- package/rules.md +22 -18
- package/settings.schema.json +289 -69
- package/skills/factory-address-review/SKILL.md +50 -30
- package/skills/factory-build/SKILL.md +75 -22
- package/skills/factory-deps/SKILL.md +46 -21
- package/skills/factory-design/SKILL.md +17 -8
- package/skills/factory-diagnose/SKILL.md +22 -20
- package/skills/factory-mutate/SKILL.md +38 -24
- package/skills/factory-refine/SKILL.md +55 -31
- package/skills/factory-resolve-conflicts/SKILL.md +76 -34
- package/skills/factory-trace/SKILL.md +3 -2
- package/workflows/factory-build.yml +1 -1
- package/workflows/factory-conflicts.yml +8 -8
- package/workflows/factory-deps.yml +1 -1
- package/workflows/factory-review.yml +1 -1
- package/skills/factory-address-review/patch-coverage.py +0 -68
package/docs/configuration.md
CHANGED
|
@@ -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
|
|
17
|
-
|
|
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:
|
|
38
|
+
version: 2
|
|
37
39
|
repository: your-name/your-repo
|
|
38
40
|
```
|
|
39
41
|
|
|
40
|
-
With this, sessions refine
|
|
41
|
-
|
|
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
|
-
|
|
46
|
-
|
|
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
|
|
56
|
-
the files it reads.
|
|
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 `
|
|
72
|
-
only when keys are renamed or moved
|
|
73
|
-
|
|
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
|
|
77
|
-
|
|
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
|
|
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
|
-
|
|
|
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
|
-
|
|
298
|
+
#### `specs.check`
|
|
284
299
|
|
|
285
|
-
|
|
286
|
-
|
|
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
|
-
|
|
290
|
-
|
|
291
|
-
|
|
292
|
-
-
|
|
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:**
|
|
296
|
-
|
|
297
|
-
- **
|
|
298
|
-
|
|
299
|
-
|
|
300
|
-
|
|
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
|
-
### `
|
|
320
|
+
### `commands`
|
|
303
321
|
|
|
304
|
-
|
|
305
|
-
|
|
306
|
-
|
|
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
|
-
#
|
|
310
|
-
|
|
311
|
-
build
|
|
312
|
-
-
|
|
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
|
-
|
|
321
|
-
|
|
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
|
|
336
|
-
| -------------- |
|
|
337
|
-
| `build` | A build of a ticket
|
|
338
|
-
| `conflicts` | A fix of a pull request's conflicts with
|
|
339
|
-
| `review` | An answer to your review of a pull request
|
|
340
|
-
| `dependencies` | Work on the dependency pull requests
|
|
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,
|
|
360
|
-
|
|
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
|
-
|
|
365
|
-
|
|
366
|
-
|
|
367
|
-
|
|
368
|
-
|
|
369
|
-
|
|
370
|
-
|
|
371
|
-
|
|
372
|
-
|
|
373
|
-
|
|
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
|
-
|
|
377
|
-
|
|
378
|
-
|
|
379
|
-
|
|
380
|
-
|
|
|
381
|
-
|
|
|
382
|
-
|
|
383
|
-
|
|
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
|
-
-
|
|
387
|
-
-
|
|
388
|
-
|
|
389
|
-
|
|
390
|
-
-
|
|
391
|
-
|
|
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
|
|
397
|
-
change is pictured before and after,
|
|
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:
|
|
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
|
-
#
|
|
660
|
-
|
|
661
|
-
before
|
|
662
|
-
|
|
663
|
-
-
|
|
664
|
-
|
|
665
|
-
|
|
666
|
-
|
|
667
|
-
#
|
|
668
|
-
#
|
|
669
|
-
|
|
670
|
-
|
|
671
|
-
#
|
|
672
|
-
#
|
|
673
|
-
|
|
674
|
-
|
|
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
|
-
|
|
677
|
-
|
|
678
|
-
|
|
679
|
-
|
|
680
|
-
|
|
681
|
-
|
|
682
|
-
|
|
683
|
-
|
|
684
|
-
|
|
685
|
-
|
|
686
|
-
|
|
687
|
-
|
|
688
|
-
|
|
689
|
-
|
|
690
|
-
|
|
691
|
-
|
|
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:
|
|
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
|
-
#
|
|
741
|
-
|
|
742
|
-
before
|
|
743
|
-
|
|
744
|
-
-
|
|
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
|
|
753
|
-
unread and has one reviewer of its own for its public
|
|
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:
|
|
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
|
-
#
|
|
774
|
-
|
|
775
|
-
before
|
|
776
|
-
|
|
777
|
-
-
|
|
778
|
-
|
|
779
|
-
|
|
780
|
-
#
|
|
781
|
-
#
|
|
782
|
-
|
|
783
|
-
|
|
784
|
-
|
|
785
|
-
|
|
786
|
-
#
|
|
787
|
-
#
|
|
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
|
-
|
|
790
|
-
|
|
791
|
-
|
|
792
|
-
|
|
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
|