@davidbyoung/software-factory 0.1.4 → 0.1.6

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 (57) hide show
  1. package/README.md +9 -8
  2. package/dist/cli.mjs +13 -1
  3. package/dist/code-host/github-setup.mjs +1 -1
  4. package/dist/config.d.mts +74 -20
  5. package/dist/config.mjs +326 -76
  6. package/dist/deps.d.mts +6 -4
  7. package/dist/deps.mjs +29 -7
  8. package/dist/doctor.d.mts +3 -0
  9. package/dist/doctor.mjs +7 -4
  10. package/dist/explain.d.mts +13 -2
  11. package/dist/explain.mjs +58 -43
  12. package/dist/init.mjs +9 -7
  13. package/dist/lib/default-branch.d.mts +1 -1
  14. package/dist/lib/default-branch.mjs +2 -2
  15. package/dist/lib/refined-check.mjs +1 -1
  16. package/dist/lib/work-status.d.mts +2 -2
  17. package/dist/lib/work-status.mjs +4 -4
  18. package/dist/parts.d.mts +1 -1
  19. package/dist/parts.mjs +2 -2
  20. package/dist/preset-commands.d.mts +65 -0
  21. package/dist/preset-commands.mjs +1148 -0
  22. package/dist/preset.d.mts +169 -0
  23. package/dist/preset.mjs +550 -0
  24. package/dist/remove.mjs +34 -1
  25. package/dist/review-cost.mjs +1 -1
  26. package/dist/review-tools.mjs +3 -3
  27. package/dist/session-start.d.mts +3 -0
  28. package/dist/session-start.mjs +12 -1
  29. package/dist/sync.d.mts +42 -7
  30. package/dist/sync.mjs +166 -32
  31. package/docs/builds.md +12 -11
  32. package/docs/cli.md +27 -8
  33. package/docs/configuration.md +723 -714
  34. package/docs/design.md +1 -1
  35. package/docs/developing.md +20 -8
  36. package/docs/existing-repo.md +1 -1
  37. package/docs/github/by-hand.md +9 -9
  38. package/docs/github/reference.md +4 -19
  39. package/docs/github/setup.md +3 -3
  40. package/docs/glossary.md +18 -9
  41. package/docs/limitations.md +4 -1
  42. package/docs/plugins.md +36 -24
  43. package/docs/presets.md +410 -0
  44. package/docs/quick-start.md +21 -18
  45. package/docs/removing.md +1 -1
  46. package/docs/skills.md +28 -23
  47. package/docs/updating.md +22 -14
  48. package/docs/workflow.md +13 -14
  49. package/package.json +1 -1
  50. package/rules.md +1 -1
  51. package/settings.schema.json +60 -11
  52. package/skills/factory-build/SKILL.md +1 -1
  53. package/skills/factory-deps/SKILL.md +23 -12
  54. package/skills/factory-design/SKILL.md +2 -2
  55. package/skills/factory-refine/SKILL.md +2 -2
  56. package/skills/factory-resolve-conflicts/SKILL.md +6 -0
  57. package/workflows/factory-claude-review.yml +8 -3
@@ -1,36 +1,84 @@
1
1
  # Configuration
2
2
 
3
- Everything you can change lives in one file, `.claude/factory.yaml`. This
4
- page explains every key, then shows three complete files.
3
+ This page is for changing what the factory does in your repository once it
4
+ is set up. Everything you can change is in one file,
5
+ `.claude/factory.yaml`, which [`factory init`](github/setup.md) writes when
6
+ you set the factory up. You don't need to read this page top to bottom:
7
+ start with
8
+ [the settings most repositories change](#the-settings-most-repositories-change),
9
+ and look up any other setting under [Every setting](#every-setting).
10
+
11
+ ## Words this page uses
12
+
13
+ - **Session:** one conversation with the coding agent, such as Claude
14
+ Code, working in your repository. A session on your own machine is a
15
+ local session. One that runs in the cloud with nobody at the keyboard is
16
+ an unattended session.
17
+ - **Build:** a session taking one approved ticket to a pull request.
18
+ - **The cloud runner:** where the factory's unattended work runs. Today
19
+ that is GitHub Actions.
20
+ - **The board:** a GitHub Project showing each ticket's state as a column.
21
+ It is optional.
22
+ - **The board sync:** a job on the cloud runner that moves each ticket to
23
+ its column on the board and fills in its fields. It is the only thing
24
+ that writes to the board.
25
+ - **`factory sync`:** a command you run. It copies the factory's skills,
26
+ agents, rules, and workflows into your repository, choosing which ones
27
+ from this file, and writes the settings in effect into
28
+ `.claude/factory.lock`. It has nothing to do with the board sync.
29
+ - **Skill and agent:** a skill is a set of instructions a session follows,
30
+ and an agent is a separate reviewer a session launches to read something
31
+ and report back.
32
+
33
+ The [glossary](glossary.md) has the rest.
5
34
 
6
35
  ## How the file works
7
36
 
8
- - **Every key has a default.** A key belongs in your file only when you
9
- change it. The shortest file that works is two lines.
10
- - **It holds only what a script must compute.** Anything that needs judgment,
11
- such as when a reviewer applies, stays as prose in the instructions your
12
- coding agent reads, such as `CLAUDE.md`, where sessions already read it.
13
- - **Paths are glob patterns.** `*` matches within one folder, `**` matches
14
- across folders, and both match names that start with a dot. A pattern with
15
- no wildcard matches that one path from the repository's root.
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:
37
+ - **Two settings are required, and a third before any build.** Every
38
+ file has [`version`](#version) and [`repository`](#repository), and a
39
+ session can't build a ticket until you set
40
+ [`commands.gate`](#commandsgate). Every other setting has a default, and
41
+ you write it only when you want something else.
42
+ - **It holds only what a script needs.** Anything that needs judgment,
43
+ such as when one of your reviewers should apply, goes in the
44
+ instructions your coding agent already reads, such as `CLAUDE.md`.
45
+ - **File patterns are globs.** `*` matches within one folder and `**`
46
+ matches across folders. Both match names that start with a dot. A
47
+ pattern with no wildcard matches that one path from the repository's
48
+ root.
49
+ - **A command is one line of shell.** Each runs with bash, from the
50
+ repository's root. Only the commands under [`site.checks`](#site) and
51
+ [`auto-merge.commands`](#auto-merge) are given anything on their
52
+ standard input, and their entries say what.
53
+ - **Some settings choose between tools, and name the tool with `type`.**
54
+ When `type` is the only thing in the block, you can write the tool's
55
+ name on the same line. These two mean the same:
20
56
 
21
57
  ```yaml
22
58
  specs: openspec
23
59
  ```
24
60
 
25
- means the same as:
26
-
27
61
  ```yaml
28
62
  specs:
29
63
  type: openspec
30
64
  ```
31
65
 
32
- - **Comments are kept.** Setup writes the same comment above a section in
33
- every repository, and updates never remove yours.
66
+ - **Your comments are kept.** `factory init` writes a comment above each
67
+ section, and updates never remove yours.
68
+ - **Every command reads the lock, not this file.** `factory sync` combines
69
+ the factory's defaults, any [`presets`](#presets) you list, and this
70
+ file, and writes every setting the factory will use, defaults included,
71
+ into `.claude/factory.lock`, which you commit and never edit. Until you
72
+ sync after a change, every command stops and says so, but the ones that
73
+ fix or report it: `factory sync`, `factory doctor`,
74
+ `factory config check`, and the `factory preset` commands.
75
+
76
+ ```text
77
+ .claude/factory.yaml changed since the last sync. Run: npx --no-install factory sync
78
+ ```
79
+
80
+ [`factory config explain`](cli.md) prints the settings in effect, each
81
+ marked with where its value came from.
34
82
 
35
83
  ## The shortest file
36
84
 
@@ -39,149 +87,91 @@ version: 2
39
87
  repository: your-name/your-repo
40
88
  ```
41
89
 
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.
90
+ With only this, the factory refines a ticket when you run `/factory-refine N` in a session,
91
+ nothing merges without you, and there is no board. Before a session can
92
+ build a ticket, you also need to tell it how to check a change:
93
+ [`commands.gate`](#commandsgate), below.
45
94
 
46
95
  ## The settings most repositories change
47
96
 
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.
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
97
+ - **How to check a change:** your tests, linter, and type check, under
98
+ [`commands.gate`](#commandsgate). A build cannot finish without it.
99
+ - **Quick checks before every commit:** your formatter and the other
100
+ checks that take a few seconds, under
57
101
  [`commands.before-commit`](#commandsbefore-commit).
58
- - **A board,** to see every ticket's state. Set `tickets.board` to your
59
- board's number, and when your columns have other names, map them under
60
- `tickets.columns`. [`tickets`](#tickets) has both. On GitHub,
61
- [Setting up on GitHub](github/setup.md) has the steps around
62
- them.
63
- - **What merges without you.** List the files that may under
64
- `auto-merge.allow`, such as your docs. [`auto-merge`](#auto-merge).
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.
68
-
69
- After any change, run `factory config check`, and
70
- `factory sync`, which rewrites the files a change of
71
- settings affects. A change under `plugins` alone needs no sync: plug-ins
72
- are read from the settings each time.
73
-
74
- ## Every key
102
+ - **A board:** your GitHub Project's number, under
103
+ [`tickets.board`](#tickets).
104
+ - **What may merge without you:** for example your docs, under
105
+ [`auto-merge.allow`](#auto-merge).
106
+ - **Reviewers of your own:** an agent you wrote, which reads a change that
107
+ touches certain files, under
108
+ [`plugins.build.reviewers`](#pluginsbuild). [Plugins](plugins.md) has a
109
+ worked example.
110
+
111
+ **After you change the file,** run:
112
+
113
+ ```bash
114
+ factory config check
115
+ factory sync
116
+ ```
117
+
118
+ `factory config check` prints nothing when the file is valid, and names
119
+ the setting when it is not. `factory sync` then rewrites the lock and the
120
+ copied files that depend on what you changed, and lists each file it
121
+ wrote. Every change needs it, one under `plugins` included, as
122
+ [How the file works](#how-the-file-works) says.
123
+
124
+ ## Every setting
75
125
 
76
126
  ### `version`
77
127
 
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.
128
+ Which layout of this file you are using. It is not the factory's version.
129
+ Write `2`.
83
130
 
84
- - **Default:** none. Setup writes it.
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.
131
+ - **Default:** none. `factory init` writes it.
132
+ - **If it is wrong,** every factory command that reads this file stops
133
+ with `version: must be 2`. For a version 1 file, it also says where
134
+ [Updating](updating.md#moving-to-settings-version-2) shows each setting
135
+ that moved.
88
136
 
89
137
  ### `repository`
90
138
 
91
- The repository on the code host, as `owner/name`.
139
+ Your repository, as `owner/name`, such as `harbor-goods/storefront`.
92
140
 
93
- - **Default:** none. Setup writes it once.
94
- - **If wrong:** commands read and write another repository's tickets, or
95
- fail because it does not exist.
141
+ - **Default:** none. `factory init` writes it.
142
+ - **If it is wrong,** commands read and write another repository's
143
+ tickets, or fail because it does not exist.
96
144
 
97
- It is a setting, not a lookup, so a command run outside a checkout, as the
98
- poller is, still knows which repository to read.
145
+ It is written down rather than worked out from your checkout, because the
146
+ [poller](#builds), which watches your board from outside any checkout,
147
+ needs it too.
99
148
 
100
- ### `tickets`
149
+ ### `presets`
101
150
 
102
- Where tickets live and how their state is shown.
151
+ Settings shared by several repositories, each an npm package your team
152
+ publishes, listed in the order they apply: a later preset wins over an
153
+ earlier one, and your own settings in this file win over every preset's.
103
154
 
104
155
  ```yaml
105
- tickets:
106
- type: github
107
- board: 1
156
+ presets:
157
+ - "@acme/factory-preset" # what every Acme repository shares
158
+ - "@acme/factory-preset/node" # extra settings for its Node repositories
108
159
  ```
109
160
 
110
- | Key | Meaning | Allowed | Default |
111
- | ------- | ------------------ | ---------------- | -------- |
112
- | `type` | The ticket system | `github` | `github` |
113
- | `board` | The board's number | A number, `none` | `none` |
114
-
115
- - **With `type: github`,** the board is a GitHub Project, and its number is
116
- the last part of its address.
117
- - **With no board,** a ticket's state lives in its comments,
118
- `factory status` still shows it, and builds start only
119
- when you tell a session.
120
- - **If `board` is wrong:** the board sync fails and names the board it could
121
- not read.
122
- - **One board can hold more than one repository's tickets.** Give each
123
- repository the same `board`: each one's sync, `status`, and poller read
124
- only the cards for its own issues, and GitHub's Repository field tells
125
- them apart on the board.
126
-
127
- A board shows the six states of [Workflow](workflow.md) as columns, and
128
- keeps three fields the factory writes. A repository that writes nothing
129
- below gets the factory's own board. `columns` and `fields` need a `board`.
130
-
131
- #### `tickets.columns`
132
-
133
- Which of your board's columns shows each state. Leave a key out to use the
134
- factory's own name for it. `none` means your board has no column for that
135
- state.
136
-
137
- | Key | State | Default column | May be `none` |
138
- | ---------- | -------- | -------------- | ------------- |
139
- | `backlog` | backlog | Backlog | No |
140
- | `refining` | refining | In refinement | Yes |
141
- | `ready` | ready | Ready | Yes |
142
- | `building` | building | In progress | Yes |
143
- | `review` | review | In review | Yes |
144
- | `done` | done | Done | Yes |
145
-
146
- - **A name matches whatever its capitals and the spaces around it,** so
147
- the default "In progress" finds a board's "In Progress".
148
- - **A ticket shows in its state's column. When that state has none, it
149
- shows in the column of the nearest earlier state that has one.** Nothing
150
- but an approved ticket shows in the `ready` column, so a state with no
151
- column passes over it.
152
- - **A card in a column no state names is left alone.** The sync writes none
153
- of its fields while it sits there, and nothing builds it.
154
- - **With `ready: none`,** no column approves a build. A build starts only
155
- when you tell a session to build the ticket or run
156
- `factory build N`, so
157
- `factory config check` requires `builds.trigger: manual`.
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.
161
- - `factory config get tickets.columns.ready` prints the
162
- name in effect, or `none`.
163
-
164
- #### `tickets.fields`
165
-
166
- Which of your board's fields the sync writes: `session`, `runs-in`, and
167
- `cost`, with the defaults Session, Runs in, and Cost. Each may be `none`.
168
- The board's own status field keeps its name, Status on a GitHub Project,
169
- and has to be a single select holding every column named above.
161
+ - **Default:** none.
162
+ - **Add or remove one** with `factory preset add NAME` or
163
+ `factory preset remove NAME`, which install or uninstall the package,
164
+ edit this list, and sync. A name that starts with `@` must be quoted.
165
+ - **A preset can't set** `repository`, `auto-merge.allow`, or
166
+ `auto-merge.commands`, and can't list other presets
167
+ ([why](presets.md#what-a-preset-cant-set)).
170
168
 
171
- | The settings | The board | The sync |
172
- | -------------- | ---------------------------------- | -------------------------------------------------------------- |
173
- | name the field | has it, with the right type | writes it |
174
- | name the field | lacks it, or it has the wrong type | fails, naming the field and its key |
175
- | leave default | has it, with the right type | writes it |
176
- | leave default | lacks it | skips it, with a note |
177
- | leave default | has it, with the wrong type | fails, and says to name another field or set the key to `none` |
178
- | say `none` | either | never writes it |
169
+ [Presets](presets.md) says how they combine, how to choose between two
170
+ that disagree, and how to write one.
179
171
 
180
- Session is Text, Runs in is a single select with the options Local and
181
- Actions, and Cost is a Number. `factory board check` reads
182
- your board and says what the factory will do with it.
172
+ ### `tickets`
183
173
 
184
- Two examples. The default, which needs nothing written:
174
+ Where your tickets live, and which board shows them.
185
175
 
186
176
  ```yaml
187
177
  tickets:
@@ -189,210 +179,269 @@ tickets:
189
179
  board: 1
190
180
  ```
191
181
 
192
- A board with only Todo, In Progress, and Done, as a new GitHub Project
193
- starts, and none of the factory's fields:
182
+ - **`type`** is the ticket system. Only `github` is built, and it is the
183
+ default.
184
+ - **`board`** is your GitHub Project's number: the last part of its
185
+ address, such as `1` in `github.com/users/your-name/projects/1`. The
186
+ default, `none`, means no board.
187
+
188
+ Without a board, `factory status` still shows every ticket's state, which
189
+ the factory keeps in comments on the ticket. Builds then start only when
190
+ you run `/factory-build N` in a session.
191
+
192
+ One board can show tickets from several repositories. Give each
193
+ repository the same `board`. Each repository's board sync,
194
+ `factory status`, and poller only touch that repository's own tickets.
195
+
196
+ `factory board check` reads your board and says what the factory will do
197
+ with it.
198
+
199
+ #### `tickets.columns`
200
+
201
+ The board has one column for each of the six
202
+ [states](workflow.md#the-six-states) a ticket goes through. If your
203
+ board's columns have the factory's names, write nothing here. If they have
204
+ other names, or your board has fewer columns, say which column shows each
205
+ state. A new GitHub Project starts with only Todo, In Progress, and Done,
206
+ so its settings would be:
194
207
 
195
208
  ```yaml
196
209
  tickets:
197
- type: github
198
210
  board: 7
199
211
  columns:
200
212
  backlog: Todo
213
+ building: In Progress
214
+ done: Done
201
215
  refining: none
202
216
  ready: none
203
- building: In Progress
204
217
  review: none
205
- done: Done
206
218
  builds:
207
219
  trigger: manual
208
220
  ```
209
221
 
210
- `factory config check` rejects, naming the key: a key it
211
- does not know;
212
- `backlog: none`; two states naming the same column; `columns` or `fields`
213
- with no `board`; and `ready: none` while `builds.trigger` is not `manual`.
214
- It reads no board.
222
+ The factory's own names, used for any state you leave out, are:
223
+
224
+ | State | Column the factory looks for |
225
+ | ---------- | ---------------------------- |
226
+ | `backlog` | Backlog |
227
+ | `refining` | In refinement |
228
+ | `ready` | Ready |
229
+ | `building` | In progress |
230
+ | `review` | In review |
231
+ | `done` | Done |
232
+
233
+ - **Capitals don't matter,** so "In progress" finds your "In Progress".
234
+ - **`none` means your board has no column for that state.** A ticket in
235
+ that state stays in the column of the state before it. With
236
+ `review: none`, a ticket whose pull request is in review stays in In
237
+ progress. Every state can be `none` except `backlog`.
238
+ - **A ticket never falls back into Ready,** since only a ticket you
239
+ approved goes there, so the fallback skips it. With `building: none`
240
+ alone, a ticket being built has no column of its own, the state before
241
+ building is ready, and Ready is skipped, so it shows in In refinement.
242
+ - **With `ready: none`, nothing on the board approves a build,** so you
243
+ need `builds.trigger: manual`, and you start each build by asking a
244
+ session.
245
+ - **A ticket in a column no state uses is left alone.** The board sync
246
+ doesn't move it or fill in its fields, and nothing builds it.
247
+ - **If you host your own poller** and rename the Ready column, the poller
248
+ needs the new name too: see `FACTORY_READY_COLUMN` in
249
+ [Builds](builds.md#what-it-reads-from-its-environment).
250
+
251
+ `factory config check` stops on a state it doesn't know, on
252
+ `backlog: none`, on two states sharing one column, on `columns` without a
253
+ `board`, and on `ready: none` when `builds.trigger` isn't `manual`. It
254
+ doesn't read your board: `factory board check` does.
215
255
 
216
- `type` exists so that another ticket system changes this block and nothing
217
- else. Only `github` is built. Any other value fails
218
- `factory config check` and every ticket command with:
219
- `tickets.type "X" is not supported. "github" is the only ticket system built.`
256
+ #### `tickets.fields`
220
257
 
221
- ### `code-host`
258
+ Besides moving a ticket between columns, the board sync fills in three
259
+ fields so you can see at a glance what is happening to it:
222
260
 
223
- Where the repository and its pull requests live.
261
+ - **Session:** which session is working on the ticket, or "Waiting on
262
+ you".
263
+ - **Runs in:** whether that session is on someone's machine or in the
264
+ cloud.
265
+ - **Cost:** roughly what refining and building the ticket has cost so far.
266
+
267
+ `factory init` adds these three fields to your board, so most repositories
268
+ write nothing here. Write this block only when your board already has a
269
+ field you want used instead, or to stop the board sync filling one in:
224
270
 
225
271
  ```yaml
226
- code-host:
227
- type: github
272
+ tickets:
273
+ board: 7
274
+ fields:
275
+ session: Agent # fill in your existing "Agent" field instead
276
+ cost: none # never fill in a cost
228
277
  ```
229
278
 
230
- | Key | Meaning | Allowed | Default |
231
- | ------ | ------------- | -------- | -------- |
232
- | `type` | The code host | `github` | `github` |
279
+ - **A field you name must exist,** holding the right kind of value: text
280
+ for Session, a single select with the options Local and Actions for Runs
281
+ in, and a number for Cost. If it doesn't, the board sync stops and says
282
+ which field is wrong.
283
+ - **When you name nothing,** the board sync looks for fields called
284
+ Session, Runs in, and Cost, fills in those it finds, and skips the rest
285
+ with a note.
286
+ - **It never overwrites a field of yours.** If your board has a field
287
+ called Cost that holds text, the board sync stops rather than write over
288
+ it, and asks you to name another field or write `cost: none`.
289
+ - **The column itself is the board's own Status field,** which has to be
290
+ a single select with an option for each column in
291
+ [`tickets.columns`](#ticketscolumns).
292
+
293
+ ### `code-host`
233
294
 
234
- `code-host: github` means the same, and most files leave the block out.
235
- It exists so that code kept somewhere else changes this block and nothing
236
- else. Only `github` is built. Any other value fails
237
- `factory config check`, and every command that reads the
238
- settings and reaches a pull request, with:
239
- `code-host.type "X" is not supported. "github" is the only code host built.`
295
+ Where your repository and its pull requests live. Only `github` is built,
296
+ and it is the default, so most files leave this out.
297
+
298
+ ```yaml
299
+ code-host: github
300
+ ```
240
301
 
241
302
  ### `builds`
242
303
 
304
+ What starts a build when you approve a ticket, and where the build runs.
305
+
243
306
  ```yaml
244
307
  builds:
245
308
  trigger: own-server
246
- runner: github-actions
247
309
  ```
248
310
 
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 |
254
-
255
- `trigger` is what notices a card moved to Ready, and `runner` is where the
256
- build it starts then runs: a poller on your own server still starts its
257
- builds on the cloud runner. Only `github-actions` is built. Any other value
258
- fails `factory config check`, and every command that reads
259
- the settings and reaches the runner, with:
260
- `builds.runner "X" is not supported. "github-actions" is the only runner built.`
261
-
262
- - **`manual`:** nothing watches the board. You tell a session "work 12".
263
- - **`own-server`:** a small poller you host reads the board once a minute.
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.
270
-
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`.
311
+ | Setting | What it sets | Choices | Default |
312
+ | -------------- | ----------------------------------------------------- | --------------------------------------- | ---------------- |
313
+ | `trigger` | What notices you moved a ticket to Ready on the board | `manual`, `own-server`, `github-action` | `manual` |
314
+ | `runner` | Where a build in the cloud runs | `github-actions` | `github-actions` |
315
+ | `poll-minutes` | With `github-action`, how often it checks the board | 5, 10, 15, 30, or 60 | 5 |
316
+
317
+ The three triggers:
318
+
319
+ - **`manual`:** nothing watches the board. You build a ticket by running
320
+ `/factory-build 12` in a session.
321
+ - **`own-server`:** a small program you host, the poller, checks the board
322
+ once a minute and starts a cloud build for each ticket in Ready.
323
+ [Hosting the poller](builds.md#hosting-the-poller-own-server) shows how
324
+ to run it.
325
+ - **`github-action`:** a schedule on GitHub Actions does the same every
326
+ `poll-minutes` minutes, with nothing for you to host. On a private
327
+ repository, each check is billed as at least one Actions minute.
328
+ `factory sync` adds its workflow.
329
+
330
+ Watch the spelling: the trigger is `github-action`, singular, and the
331
+ runner is `github-actions`, plural.
332
+
333
+ Whatever starts it, a cloud build runs on the cloud runner.
334
+ [Builds](builds.md) explains each trigger. **It worked when** a ticket you
335
+ move to Ready shows as In progress on the board within a few minutes. If
336
+ nothing is watching the board, a ticket you move to Ready just sits there, and `factory status`
337
+ marks it "not started": after 5 minutes with `own-server`, and after
338
+ `poll-minutes` plus 15 minutes with `github-action`.
339
+
340
+ `factory config check` stops on `poll-minutes` with any trigger but
341
+ `github-action`, and on any value but the five above.
275
342
 
276
343
  ### `specs`
277
344
 
278
- How the written spec for a change your users will see is kept, and the
279
- command that checks it.
345
+ Whether a change your users will see also gets a written spec, kept beside
346
+ your code.
280
347
 
281
348
  ```yaml
282
349
  specs: openspec
283
350
  ```
284
351
 
285
- | `type` | Meaning |
286
- | ---------- | ------------------------------------------------------------------------- |
287
- | `none` | The ticket's acceptance criteria are the only spec |
288
- | `openspec` | A visible, non-trivial change also adds its behavior to `openspec/specs/` |
289
-
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.
293
- - **If you set `openspec` without OpenSpec installed:** a build of a visible
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.
352
+ - **`none`,** the default: the ticket's acceptance criteria are the only
353
+ spec.
354
+ - **`openspec`:** a visible change that isn't
355
+ [small](workflow.md#sizing-the-work-to-the-change) also writes its new
356
+ behavior into `openspec/specs/`, using
357
+ [OpenSpec](https://github.com/Fission-AI/OpenSpec), so that folder
358
+ always describes what your project does. Install it first, with
359
+ `npm install -D @fission-ai/openspec`. Without it, a build stops at its
360
+ first spec step and says so.
297
361
 
298
362
  #### `specs.check`
299
363
 
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/`.
364
+ The command that checks your written specs are sound.
365
+ `factory specs check` runs it, and so does a build each time it writes a
366
+ spec.
303
367
 
304
368
  ```yaml
305
369
  specs:
306
370
  type: openspec
307
- # The command "factory specs check" runs. This is its default.
308
371
  check: npx --no-install openspec validate --all --strict --no-interactive
309
372
  ```
310
373
 
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`.
374
+ - **Default:** the command above,
375
+ `npx --no-install openspec validate --all --strict --no-interactive`,
376
+ with `type: openspec`, so most repositories leave it out.
377
+ - **It runs with `DO_NOT_TRACK=1` set,** so OpenSpec collects no usage
378
+ statistics.
379
+ - **With `specs: none`** there is nothing to check, and writing `check`
380
+ fails `factory config check`.
319
381
 
320
382
  ### `commands`
321
383
 
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.
384
+ The commands that are your project's own: how a session checks a change,
385
+ runs one test, and so on. The factory's skills never name a test runner or
386
+ a linter. They run `factory gate`, `factory test-one`, and the like, which
387
+ run what you write here.
326
388
 
327
389
  ```yaml
328
- # Every command a build runs, each from the repository's root.
329
390
  commands:
330
- # Before an unattended build starts work.
331
391
  build-setup:
332
392
  - npx playwright install --with-deps chromium
333
- # Before every commit a session makes.
334
393
  before-commit:
335
394
  - npm run -s format:check
336
395
  - npx tsc --noEmit
337
- # Before a session reports a task done. "factory gate" runs them in order.
338
396
  gate:
339
397
  - npm run check
340
- # One test alone. "factory test-one" sets $FILE and $NAME.
341
398
  test-one: npx vitest run $FILE -t "$NAME"
342
- # One end-to-end spec alone. "factory end-to-end" sets $FILE.
343
399
  end-to-end: npx playwright test $FILE
344
- # Coverage, and where its lcov report lands.
345
400
  coverage:
346
401
  run: npm run coverage
347
402
  report: coverage/lcov.info
348
- # Rebuilds the lock file after a conflict in it.
349
403
  relock: npm install
350
404
  ```
351
405
 
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
-
406
+ | Setting | Runs | Default |
407
+ | --------------- | ---------------------------------------------------------------- | -------------------------- |
408
+ | `build-setup` | Before a cloud build starts work | none |
409
+ | `before-commit` | Before every commit a session makes | none |
410
+ | `gate` | Before a session calls a task done | none, and a build needs it |
411
+ | `test-one` | When a session runs one test alone | none |
412
+ | `end-to-end` | When a session runs one end-to-end test file alone | none |
413
+ | `coverage` | When a session checks that a pull request's new lines are tested | none |
414
+ | `relock` | After a conflict in your lock file | `npm install` |
415
+
416
+ - **`$FILE` and `$NAME`** are set for you when a command runs one test.
417
+ [`commands.test-one`](#commandstest-one) says how.
362
418
  - **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.
419
+ something on, and its entry below says what happens without it.
364
420
  - **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
421
 
373
422
  #### `commands.build-setup`
374
423
 
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`.
424
+ Commands that run before a cloud build starts work, to install what the
425
+ session will need. Your npm dependencies are already installed by then,
426
+ with `npm ci`, but nothing else is.
377
427
 
378
428
  ```yaml
379
429
  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
430
  build-setup:
383
- - npx playwright install --with-deps chromium
431
+ - npx playwright install --with-deps chromium # a browser for end-to-end tests
384
432
  ```
385
433
 
434
+ In a project that isn't JavaScript, install its dependencies here too,
435
+ such as `composer install` or `pip install -r requirements.txt`.
436
+
386
437
  - **Default:** none.
387
- - **What goes here:** what a session needs that `npm ci` does not give it,
388
- such as a browser for end-to-end tests or a system package.
389
- - **If one fails:** the run stops before the session starts, with that
390
- command's output in its log.
438
+ - **If one fails,** the build stops before the session starts, and the
439
+ run's log shows that command's output.
391
440
 
392
441
  #### `commands.before-commit`
393
442
 
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.
443
+ Quick checks that run before every commit a session makes. If one fails,
444
+ the commit is blocked and the session sees why.
396
445
 
397
446
  ```yaml
398
447
  commands:
@@ -403,19 +452,20 @@ commands:
403
452
  ```
404
453
 
405
454
  - **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.
455
+ - **Keep them to a few seconds.** They run on every commit. Your tests
456
+ belong in [`commands.gate`](#commandsgate), which runs once per task.
457
+ - **They only apply to a session's commits,** not to commits you make
458
+ yourself.
413
459
 
414
460
  #### `commands.gate`
415
461
 
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.
462
+ The checks a change has to pass before a session calls it done or opens a
463
+ pull request. Think of it as what your CI runs on a pull request, minus
464
+ anything too slow for a session to sit and wait for. `factory gate` runs
465
+ them in order and stops at the first failure, so put the fastest first.
466
+
467
+ If you already have one command that runs every check, such as
468
+ `npm run check` or `make check`, the gate can be just that:
419
469
 
420
470
  ```yaml
421
471
  commands:
@@ -423,71 +473,117 @@ commands:
423
473
  - npm run check
424
474
  ```
425
475
 
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.
476
+ Otherwise, list each check. What that looks like in a few languages:
477
+
478
+ ```yaml
479
+ # JavaScript or TypeScript
480
+ gate:
481
+ - npm run format:check
482
+ - npm run lint
483
+ - npx tsc --noEmit
484
+ - npm test
485
+ ```
486
+
487
+ ```yaml
488
+ # Python
489
+ gate:
490
+ - ruff format --check .
491
+ - ruff check .
492
+ - mypy src
493
+ - pytest -q
494
+ ```
495
+
496
+ ```yaml
497
+ # Go
498
+ gate:
499
+ - test -z "$(gofmt -l .)"
500
+ - go vet ./...
501
+ - go test ./...
502
+ ```
503
+
504
+ ```yaml
505
+ # PHP
506
+ gate:
507
+ - composer validate --strict
508
+ - vendor/bin/php-cs-fixer fix --dry-run --diff
509
+ - vendor/bin/phpstan analyse
510
+ - vendor/bin/phpunit
511
+ ```
512
+
513
+ ```yaml
514
+ # Rust
515
+ gate:
516
+ - cargo fmt --check
517
+ - cargo clippy -- -D warnings
518
+ - cargo test
519
+ ```
520
+
521
+ Leave out:
522
+
523
+ - **Anything that changes files,** such as `prettier --write`. The gate
524
+ checks a change; it doesn't fix it.
525
+ - **A test suite that takes many minutes,** such as a full browser suite.
526
+ CI still runs it on the pull request.
527
+ - **Anything that needs production secrets, or deploys.**
528
+
529
+ There is no default. Without a gate, `factory gate` fails with
530
+ `commands.gate is not set`, and a build stops there, because an empty gate
531
+ would pass every change. `factory init` lists it under "Left to do".
532
+
533
+ When a command fails, `factory gate` prints `gate failed on:` and the
534
+ command, and runs none after it. The session fixes the cause and runs the
535
+ gate again.
536
+
537
+ **Check your gate yourself** before a session relies on it: run
538
+ `factory gate` on a clean checkout. It should print each command and exit 0. `factory config check` only checks that the file is valid, not that
539
+ your commands work.
439
540
 
440
541
  #### `commands.test-one`
441
542
 
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.
543
+ Runs one test file alone, or one test in it. A session uses it to watch a
544
+ new test fail before the change, and to narrow down a bug.
545
+ `factory test-one FILE NAME` runs your command with `$FILE` and `$NAME`
546
+ set. When only a file is given, `$NAME` is empty, so the command should
547
+ run the whole file then:
446
548
 
447
549
  ```yaml
448
550
  commands:
449
- # One test alone. An empty NAME runs the whole file.
450
- test-one: npx vitest run $FILE -t "$NAME"
551
+ test-one: npx vitest run $FILE -t "$NAME" # an empty -t runs every test
451
552
  ```
452
553
 
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.**
554
+ ```yaml
555
+ commands:
556
+ test-one: vendor/bin/phpunit $FILE ${NAME:+--filter "$NAME"} # --filter only with a name
557
+ ```
558
+
559
+ - **Default:** none. `factory test-one` then fails with
560
+ `commands.test-one is not set`, and a session finds its own way to run
561
+ one test.
460
562
 
461
563
  #### `commands.end-to-end`
462
564
 
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.
565
+ Runs one end-to-end test file alone, with `$FILE` set.
566
+ `factory end-to-end FILE --times 10` runs it ten times and stops at the
567
+ first failure, as `failed on run 3 of 10`. A build does that with each new
568
+ end-to-end test, since one that fails one run in ten will fail someone's
569
+ pull request.
468
570
 
469
571
  ```yaml
470
572
  commands:
471
573
  end-to-end: npx playwright test $FILE
472
574
  ```
473
575
 
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.**
576
+ - **Default:** none. Leave it out if you have no end-to-end tests.
577
+ - **Setting it makes `factory-e2e-reviewer` available,** the factory's
578
+ reviewer for browser tests. To use it, run `factory sync`, then list it
579
+ under [`plugins.test.reviewers`](#pluginstest). That list replaces the
580
+ default, so list `factory-test-reviewer` there too.
485
581
 
486
582
  #### `commands.coverage`
487
583
 
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.
584
+ The command that measures test coverage, and where it writes its lcov
585
+ report. A session working on a pull request's review runs it to find new
586
+ lines no test covers.
491
587
 
492
588
  ```yaml
493
589
  commands:
@@ -496,236 +592,252 @@ commands:
496
592
  report: coverage/lcov.info
497
593
  ```
498
594
 
499
- - **Default:** not set. A session then judges no coverage.
500
- - **Both keys are required** once `coverage` is written.
595
+ - **Default:** none, and a session doesn't check coverage.
596
+ - **Write both `run` and `report`,** or neither.
501
597
 
502
598
  #### `commands.relock`
503
599
 
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.
600
+ The command that rebuilds your package manager's lock file. When the lock
601
+ file conflicts with the default branch, a session takes the default
602
+ branch's copy and runs this, instead of merging the file by hand.
508
603
 
509
604
  ```yaml
510
605
  commands:
511
- relock: npm install
606
+ relock: composer update --lock
512
607
  ```
513
608
 
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).
609
+ - **Default:** `npm install`.
610
+ - **Another generated file that conflicts,** such as a generated API
611
+ client, needs a [resolver](#pluginsconflicts).
518
612
 
519
613
  ### `session-minutes`
520
614
 
521
- How long each kind of session that runs on its own in the cloud may run, in
522
- minutes. Raise one when your tests, your build, or your site's
523
- comparison take long enough that honest work is being cut off.
615
+ How long each kind of unattended session may run, in minutes, before the
616
+ cloud runner stops it. Raise one if your tests or your build are slow
617
+ enough that sessions are cut off mid-task.
524
618
 
525
619
  ```yaml
526
- # How long each unattended session may run, in minutes.
527
620
  session-minutes:
528
621
  build: 300
529
622
  ```
530
623
 
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` |
537
-
538
- - **Each is a whole number above zero.** A key you leave out keeps its
539
- default.
540
- - **The job around a session gets 10 minutes more,** so the steps after it,
541
- which release the ticket and post what happened, still run when the
542
- session is stopped.
543
- - **`factory sync` writes these where the cloud runner
544
- reads them,** and `factory sync --check` fails until it
545
- has run after a change.
546
- - **The cloud runner may stop a job sooner.** On GitHub, see
624
+ | Setting | Limits the session that is | Default |
625
+ | -------------- | --------------------------------------------------------- | ------- |
626
+ | `build` | Building a ticket | `230` |
627
+ | `conflicts` | Fixing a pull request's conflicts with the default branch | `110` |
628
+ | `review` | Answering your review of a pull request | `50` |
629
+ | `dependencies` | Working through dependency updates | `50` |
630
+
631
+ - **Each is a whole number above zero.**
632
+ - **Run `factory sync` after changing one,** since it writes them into the
633
+ workflows. `factory config check` fails until you do.
634
+ - **GitHub may stop a job sooner:** see
547
635
  [its limits](github/reference.md#limits).
548
- - The cloud jobs that run no session, such as the board's sync and who
549
- merges, keep fixed short limits.
550
- - `factory config get session-minutes.build` prints the
551
- value in effect.
552
636
 
553
637
  ### `plugins`
554
638
 
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.
639
+ Your own skills and agents, doing a job the factory would otherwise do
640
+ itself, or adding to it. Each job is a **role**. For example, an agent you
641
+ list in the `reviewers` role reads every change that touches its files,
642
+ alongside the factory's own reviewers. Roles are grouped by the part of
643
+ the work they belong to: `refine`, `build`, `test`, and `conflicts`.
644
+
645
+ ```yaml
646
+ plugins:
647
+ build:
648
+ reviewers:
649
+ - agent: migration-reviewer # .claude/agents/migration-reviewer.md
650
+ files:
651
+ - db/migrations/**
652
+ ```
653
+
654
+ Every role is optional. Leaving one out never turns a step off: the
655
+ factory does that step its own way. A reviewer is an agent, since it only
656
+ reads and reports. Every other role takes a skill, which the session
657
+ follows itself. [Plugins](plugins.md) says what each role is handed and
658
+ what it has to give back.
659
+
660
+ | Role | What you list | How many | When it is used | If you list none |
661
+ | --------------------- | ------------- | -------- | --------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------- |
662
+ | `refine.refiner` | A skill | One | Whenever a ticket is refined | `factory-refine` refines tickets |
663
+ | `refine.mockups` | A skill | One | Whenever a decision changes how something looks | `factory-design` draws mockups if you set [`site`](#site), and otherwise the session describes the choices in words |
664
+ | `build.builders` | Skills | A list | For a ticket with one of the builder's `labels`. Each builder needs at least one | The factory's own build builds every ticket |
665
+ | `build.reviewers` | Agents | A list | When a change touches one of the reviewer's `files`. Each reviewer needs at least one pattern | Only the factory's own reviewers read a change |
666
+ | `test.prover` | A skill | One | Whenever a new test needs proof that it can fail | `factory-mutate` proves each new test can fail |
667
+ | `test.reviewers` | Agents | A list | When a change touches tests. A reviewer given `files` reads only changes to those | `factory-test-reviewer` reads new tests |
668
+ | `conflicts.resolvers` | Skills | A list | When a conflict is in one of the resolver's `files`. Each resolver needs at least one pattern | The session merges conflicts by hand, and [`commands.relock`](#commandsrelock) rebuilds the lock file |
669
+
670
+ In Claude Code, a skill lives at `.claude/skills/NAME/SKILL.md` and an
671
+ agent at `.claude/agents/NAME.md`:
672
+ [Skills in Claude Code](github/reference.md#skills-in-claude-code).
673
+
674
+ - **`factory plugins`** prints every plugin the factory will use, its own
675
+ included, one per line: skill or agent, its name, its role, and its
676
+ files or labels. `factory plugins reviewer` prints one role's.
677
+ - **A plugin can come from a [preset](#presets),** which ships its agent
678
+ or skill too. To leave out one that a preset adds to a list, name it
679
+ here with `off: true`:
680
+
681
+ ```yaml
682
+ plugins:
683
+ build:
684
+ reviewers:
685
+ - agent: acme-security-reviewer
686
+ off: true
687
+ ```
688
+
689
+ - **`factory config check`** stops on an agent in a role that takes a
690
+ skill, or the other way round; on `files` or `labels` in a role that
691
+ doesn't take them; on a builder with no `labels`; on a build reviewer or
692
+ resolver with no `files`; on a skill or agent whose file doesn't
693
+ exist and no preset ships; and on `off: true` for a plugin no preset
694
+ names, where the fix is to delete that entry. It warns on a `files`
695
+ pattern that matches no file.
696
+
697
+ #### `plugins.refine`
698
+
699
+ - **`refiner`:** your own skill for refining a ticket, used instead of
700
+ `factory-refine`.
701
+ - **`mockups`:** your own skill for drawing the choices when a decision
702
+ changes how something looks.
703
+
704
+ A role that takes one plugin is a block, not a list:
561
705
 
562
706
  ```yaml
563
- # Your own skills and agents, by phase. Every slot is optional.
564
707
  plugins:
565
708
  refine:
566
- # Replaces factory-refine. Must deliver what the build reads.
567
709
  refiner:
568
- skill: acme-refine
569
- # Makes pictures when a decision changes the look. One only.
710
+ skill: acme-refine # .claude/skills/acme-refine/SKILL.md
570
711
  mockups:
571
712
  skill: design-mockups
713
+ ```
714
+
715
+ #### `plugins.build`
716
+
717
+ - **`builders`:** your own skill for building certain tickets, used
718
+ instead of the factory's build for any ticket with one of its `labels`.
719
+ If two builders share a label, the first one listed builds the ticket.
720
+ - **`reviewers`:** your own agents, each asked to read a change that
721
+ touches a file matching its `files`. The pattern only decides who is
722
+ asked: the agent's own description says when it really applies. One
723
+ that was asked but didn't apply gets a line in the pull request saying
724
+ why.
725
+
726
+ ```yaml
727
+ plugins:
572
728
  build:
573
- # Each builds a ticket that carries one of its labels.
574
729
  builders:
575
730
  - skill: add-endpoint
576
731
  labels:
577
732
  - new-endpoint
578
- # Each is considered when a change touches one of its files.
579
733
  reviewers:
580
734
  - agent: migration-reviewer
581
735
  files:
582
736
  - db/migrations/**
737
+ ```
738
+
739
+ #### `plugins.test`
740
+
741
+ - **`prover`:** your own skill for proving a new test can fail, used
742
+ instead of `factory-mutate`.
743
+ - **`reviewers`:** the agents that read new and changed tests. **This list
744
+ replaces the default,** so `factory-test-reviewer` runs only if you list
745
+ it, and `reviewers: []` means no test reviewer runs. Without `files`, a
746
+ reviewer reads every change to tests; with `files`, only changes to
747
+ matching files. `factory-e2e-reviewer` needs
748
+ [`commands.end-to-end`](#commandsend-to-end).
749
+
750
+ ```yaml
751
+ plugins:
583
752
  test:
584
- # Replaces factory-mutate: proves each new test can fail.
585
753
  prover:
586
754
  skill: acme-mutation
587
- # The whole list of test reviewers. Left out, it is factory-test-reviewer.
588
755
  reviewers:
589
756
  - agent: factory-test-reviewer
590
757
  - agent: factory-e2e-reviewer
591
758
  files:
592
759
  - e2e/**
760
+ ```
761
+
762
+ #### `plugins.conflicts`
763
+
764
+ - **`resolvers`:** your own skills for files that should be rebuilt rather
765
+ than merged by hand after a conflict, such as a generated API client.
766
+ Each handles the files matching its `files`. If two match one file, the
767
+ first one listed rebuilds it.
768
+ - **A new resolver is used once it has merged,** since conflicts are fixed
769
+ using the default branch's copy of this file, never a pull request's.
770
+
771
+ ```yaml
772
+ plugins:
593
773
  conflicts:
594
- # Each rebuilds its files after a conflict, in place of a hand merge.
595
774
  resolvers:
596
775
  - skill: regenerate-api-client
597
776
  files:
598
777
  - src/generated/**
599
778
  ```
600
779
 
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
616
- [Skills in Claude Code](github/reference.md#skills-in-claude-code).
617
-
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`
780
+ ### `site`
645
781
 
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.
782
+ How the factory looks at your website, if your repository is one. With
783
+ `site` set and `factory-ui-reviewer` listed under
784
+ [`plugins.build.reviewers`](#pluginsbuild), every change that alters how
785
+ the site looks is screenshotted before and after, and the difference is
786
+ reviewed. The screenshots are taken with Playwright, so install it in
787
+ your repository first, with `npm install -D playwright`. Until you do,
788
+ `factory config check` fails on a file with `site`.
655
789
 
656
- #### `plugins.test`
790
+ Most sites need only two lines:
657
791
 
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).
792
+ ```yaml
793
+ site:
794
+ start: npm run build && npx serve out -p $PORT
795
+ url: http://localhost:$PORT
796
+ ```
669
797
 
670
- #### `plugins.conflicts`
798
+ **It worked when** `factory site compare` builds your branch and the
799
+ default branch, takes the screenshots, and prints where it saved them.
800
+ [`factory site`](cli.md#factory-site) has the details.
671
801
 
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.
802
+ Every setting `site` takes:
680
803
 
681
- ### `site`
804
+ | Setting | What it sets | Default |
805
+ | --------------- | ----------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------- |
806
+ | `start` | A command that builds and serves the site, with `$PORT` set for it. Required | none |
807
+ | `url` | The address `start` serves the site at. Required | none |
808
+ | `design-guide` | A file of your own design rules, checked on top of the factory's | none |
809
+ | `pages` | A list of paths to look at | The pages in `/sitemap.xml`, or else the ones the home page links to |
810
+ | `widths` | A list of screen widths, in pixels | `[390, 1280]` |
811
+ | `hide` | A list of CSS selectors hidden before each screenshot, for something that floats over the page | none |
812
+ | `checks` | A list of your own measuring commands, described below | none |
813
+ | `max-pages` | How many changed pages the reviewer reads closely | `4` |
814
+ | `start-minutes` | How long to wait for the site to answer after `start` runs | `5` |
815
+ | `accessibility` | The WCAG level changed pages are checked against: `wcag22aa`, `wcag21aa`, `wcag2aa`, or `none` | `wcag22aa` |
816
+ | `new-values` | Whether the review points out font sizes, colors, spacing, and corner radii that the rest of the site doesn't use | `true` |
682
817
 
683
- How the factory looks at your website. Leave it out if the repository is not
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.
818
+ The optional ones that take a list are written like this:
687
819
 
688
820
  ```yaml
689
821
  site:
690
- # A command that builds and serves the site from the repository's root,
691
- # and the address it answers at. $PORT is set for you.
692
822
  start: npm run build && npx serve out -p $PORT
693
823
  url: http://localhost:$PORT
694
- # Optional. Your design rules, applied on top of the built-in ones.
695
- design-guide: docs/design.md
824
+ pages:
825
+ - /
826
+ - /pricing
827
+ hide:
828
+ - .chat-widget
829
+ checks:
830
+ - node scripts/check-tap-targets.mjs
696
831
  ```
697
832
 
698
- | Key | Default | Meaning |
699
- | --------------- | ------------- | ---------------------------------------------------------------------------------------------------- |
700
- | `start` | required | Builds and serves the site from the repository's root; `$PORT` is set |
701
- | `url` | required | The address `start` answers at |
702
- | `design-guide` | none | A file of your own design rules |
703
- | `pages` | found | The paths to look at. Otherwise from `/sitemap.xml`, or the home page's links |
704
- | `widths` | `[390, 1280]` | The widths, in pixels, each page is shot at |
705
- | `hide` | none | CSS selectors hidden before every picture, for something that floats |
706
- | `checks` | none | Your own measuring commands. Each gets one JSON object on its standard input |
707
- | `max-pages` | `4` | How many changed pages the agent reads closely |
708
- | `start-minutes` | `5` | How long to wait for the site to answer after `start` is run |
709
- | `accessibility` | `wcag22aa` | The WCAG level axe-core measures changed pages against: `wcag22aa`, `wcag21aa`, `wcag2aa`, or `none` |
710
- | `new-values` | `true` | `false` leaves out the font sizes, colors, spacing, and radii the base site does not use |
711
-
712
- - **`factory config get site`** prints every key in this
713
- order, defaults included, one `key: value` line each.
714
- `factory config get site.widths` prints one key, a list one item to a line, and `none` for a key that is not
715
- set; `site.pages` prints `found` when it is not set.
716
- - **`factory config check`** rejects a `site` with no `start` or `url`, a
717
- `design-guide` that is not a file, and `factory-ui-reviewer` listed with no
718
- `site`. It also fails when the `playwright` package is not found from the
719
- repository's root: `npm install -D playwright`. It looks for the package and
720
- never for a browser.
721
- - **A `checks` command** gets `{"before", "after", "pages", "report"}` on its
722
- standard input: the two addresses, the paths that changed, and the folder of
723
- pictures. Each non-empty line it prints is a finding; its exit code says
724
- nothing.
833
+ **A command under `checks`** is given one JSON object on its standard
834
+ input: `before` and `after`, the two sites' addresses; `pages`, the paths
835
+ that changed; and `report`, the folder of screenshots. Each line it prints
836
+ is reported as a finding. Its exit code is ignored.
725
837
 
726
838
  ### `auto-merge`
727
839
 
728
- Which pull requests may merge without you.
840
+ Which pull requests may merge without you reading them.
729
841
 
730
842
  ```yaml
731
843
  auto-merge:
@@ -741,108 +853,101 @@ auto-merge:
741
853
 
742
854
  A pull request merges itself only when **all** of these hold:
743
855
 
744
- 1. every changed file matches a pattern under `allow`;
745
- 2. no changed file matches a pattern under `deny`;
856
+ 1. every file it changes matches a pattern under `allow`;
857
+ 2. no file it changes matches a pattern under `deny`;
746
858
  3. every command under `commands` exits 0;
747
- 4. CI passes, including the automated review's verdict.
748
-
749
- Anything else waits for you, and the pull request says why.
750
-
751
- | Key | Meaning | Default |
752
- | ---------- | -------------------------------------------------------------------- | ------- |
753
- | `allow` | Patterns for files safe to merge unread | empty |
754
- | `deny` | Exceptions inside `allow`. `deny` always wins | empty |
755
- | `commands` | Your own checks. Each is run once for a pull request and can veto it | empty |
756
-
757
- - **With the default, nothing merges without you.**
758
- - **Always held for you, whatever you allow:** the factory's own files
759
- (`.claude/`, `.github/`, every `CLAUDE.md` and `AGENTS.md`, and
760
- `openspec/config.yaml`).
761
- - **A command** is run once for a pull request, from the root of a checkout
762
- of your default branch, never the pull request's. It is given one JSON
763
- object on its standard input:
764
-
765
- ```json
766
- {
767
- "repository": "harbor-goods/storefront",
768
- "pull": 42,
769
- "base": "the merge base's commit",
770
- "head": "the pull request's newest commit",
771
- "files": [
772
- {
773
- "filename": "src/a.ts",
774
- "previous_filename": "src/b.ts",
775
- "status": "renamed"
776
- }
777
- ]
778
- }
779
- ```
859
+ 4. CI passes. With [`pr-review`](#pr-review) on, that includes the
860
+ automated review finding it ready.
861
+
862
+ Otherwise it waits for you, and the pull request says why.
863
+
864
+ - **By default every list is empty, so nothing merges without you.**
865
+ - **`deny` carves exceptions out of `allow`,** and always wins.
866
+ - **Some files always wait for you,** whatever `allow` says: the
867
+ factory's own, which are everything under `.claude/` and `.github/`,
868
+ every `CLAUDE.md` and `AGENTS.md`, and `openspec/config.yaml`.
869
+ - **Start with a short `allow` list** and add to it. Too wide a list
870
+ merges changes you meant to read.
871
+ - **`factory config check` warns about a pattern that matches no file,**
872
+ since a stale pattern is how a policy quietly stops meaning anything.
873
+
874
+ **A command under `commands`** is your own check. It runs once for each
875
+ pull request, from a checkout of your default branch, never the pull
876
+ request's, and reads one JSON object on its standard input:
877
+
878
+ ```json
879
+ {
880
+ "repository": "harbor-goods/storefront",
881
+ "pull": 42,
882
+ "base": "the commit the pull request branched from",
883
+ "head": "the pull request's newest commit",
884
+ "files": [
885
+ {
886
+ "filename": "src/a.ts",
887
+ "previous_filename": "src/b.ts",
888
+ "status": "renamed"
889
+ }
890
+ ]
891
+ }
892
+ ```
893
+
894
+ It exits 0 to let the pull request merge, and anything else to hold it for
895
+ you. Each line it prints is shown as a reason.
896
+
897
+ What a held pull request says, one line for each file or command that held
898
+ it:
780
899
 
781
- It exits 0 to allow the merge, and anything else to hold the pull request
782
- for you. Each line it prints is shown as a reason; one that prints nothing
783
- is shown as "held by" and the command. A command that cannot be run
784
- counts as a hold.
785
-
786
- - **The reasons a held pull request shows**, one for each file or command
787
- that held it, in this order of checking:
788
-
789
- | Reason | Why |
790
- | -------------------------------------- | --------------------------------------------------- |
791
- | `PATH: the factory's own files` | One of the files below, whatever `allow` says |
792
- | `PATH: held by auto-merge.deny` | It matches `deny` |
793
- | `PATH: not in auto-merge.allow` | It matches nothing in `allow` |
794
- | What a command printed | A command exited with anything but 0 |
795
- | `held by COMMAND` | A command exited with anything but 0, printing none |
796
- | `held by COMMAND: it could not be run` | The command was not found or could not be started |
797
- | `no changed files` | The pull request changes nothing |
798
-
799
- A renamed file is checked under both its names.
800
-
801
- - **If a pattern matches no file:** `factory config check`
802
- warns, since a stale pattern is how a policy rots.
803
- - **If `allow` is too wide:** changes you meant to read merge unread.
804
- Start with a short list and add to it.
805
- - **If a `deny` pattern matches nothing inside `allow`:** it does nothing,
806
- and `factory config check` says so.
807
-
808
- ### `ci-review`
809
-
810
- The automated review of every pull request: Claude reads each one once it
811
- is marked ready, comments on what it finds, and posts a verdict. It is on
812
- while `ci-review` is written, even with nothing under it, and `factory
813
- sync` then writes its workflow, `.github/workflows/factory-claude-review.yml`.
814
- [Setting up on GitHub](github/setup.md) has what it needs on GitHub.
900
+ | The status says | Why |
901
+ | -------------------------------------- | ----------------------------------------------- |
902
+ | `PATH: the factory's own files` | The file is one of the factory's, listed above |
903
+ | `PATH: held by auto-merge.deny` | The file matches `deny` |
904
+ | `PATH: not in auto-merge.allow` | The file matches nothing in `allow` |
905
+ | What your command printed | Your command exited with something other than 0 |
906
+ | `held by COMMAND` | The same, and the command printed nothing |
907
+ | `held by COMMAND: it could not be run` | The command was not found or could not start |
908
+ | `no changed files` | The pull request changes nothing |
909
+
910
+ A renamed file is checked under both its old and new names.
911
+
912
+ ### `pr-review`
913
+
914
+ An AI code review of every pull request. Once a pull request is marked
915
+ ready, the coding agent reads it, comments on what it finds, and posts a
916
+ verdict that [`auto-merge`](#auto-merge) waits for. It is separate from
917
+ your own CI, which keeps running your tests as before.
815
918
 
816
919
  ```yaml
817
- # The automated review of every pull request, on while this is written.
818
- # "commands" are what it may run to confirm a finding, beside reading the
819
- # pull request and commenting on it.
820
- ci-review:
920
+ pr-review:
821
921
  commands:
822
922
  - npm test
823
923
  - npx tsc --noEmit
824
924
  ```
825
925
 
826
- - **Default:** off.
827
- - **`commands`:** each is a command prefix the reviewer may run, such as
828
- your tests, the type check, or lint. Without any, it reads the pull
829
- request, its history, and your instructions, and runs nothing of yours.
830
- A command may hold no comma, parenthesis, or quote.
831
- - **Read from the pull request's base commit,** so a change to the
832
- settings alone cannot widen what its own review may run.
833
- - **To turn it off,** delete `ci-review` and run
834
- `factory sync`, which deletes the workflow.
835
- - `factory review tools` prints every tool the review may
836
- use, as its workflow passes them on.
926
+ - **Default:** off. Writing `pr-review` turns it on, even with nothing
927
+ under it (`pr-review: {}`), and `factory sync` then adds its workflow,
928
+ `.github/workflows/factory-claude-review.yml`.
929
+ [Setting up on GitHub](github/setup.md) has what it needs there.
930
+ - **`commands` is what the reviewer may run** to confirm something it
931
+ suspects, beyond reading the code and commenting. It doesn't run them on
932
+ every pull request. Without any, it only reads. A command can't contain
933
+ a comma, a parenthesis, or a quote.
934
+ - **Each command you list runs the pull request's own code,** in a job
935
+ that holds the review's token. Only list commands you'd be comfortable
936
+ running on any pull request.
937
+ - **It reads this list from the branch the pull request merges into,** so
938
+ a pull request can't widen what its own review may run.
939
+ - **To turn it off,** delete `pr-review` and run `factory sync`, which
940
+ removes the workflow.
941
+ - `factory review tools` prints everything the reviewer may use.
837
942
 
838
943
  ### `approvers`
839
944
 
840
- _[Planned](developing.md#what-is-built)_: `factory config check`
841
- refuses this key until it is built.
945
+ _[Planned](developing.md#what-is-built)_: `factory config check` refuses
946
+ this setting until it is built.
842
947
 
843
- The people whose comments a session treats as instructions, and whose move
844
- of a ticket to Ready counts as approval. Everyone else's comments are
845
- information.
948
+ The people whose comments a session takes as instructions, and whose move
949
+ of a ticket to Ready counts as approving it. Everyone else's comments are
950
+ read as information.
846
951
 
847
952
  ```yaml
848
953
  approvers:
@@ -850,20 +955,16 @@ approvers:
850
955
  - a-teammate
851
956
  ```
852
957
 
853
- - **Default:** the repository's owner. One person never writes this key.
854
- - **If a name is wrong:** that person's comments are treated as
855
- information, and a ticket they move to Ready is not built.
856
- _[Planned](developing.md#what-is-built)_: `factory doctor`
857
- flags a name that is not an account with access to the repository.
858
-
859
- A session posts through a person's account too, so it marks its own comments
860
- and never takes one as an instruction.
958
+ - **Default:** the repository's owner, so a repository with one person
959
+ leaves it out.
960
+ - **If a name is wrong,** that person's comments are treated as
961
+ information, and a ticket they approve is not built.
861
962
 
862
963
  ### `rules`
863
964
 
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.
965
+ Two numbers the factory's rules use, for a repository that wants
966
+ different ones. Run `factory sync` after changing one, since it writes the
967
+ number into the rules and skills that use it.
867
968
 
868
969
  ```yaml
869
970
  rules:
@@ -871,105 +972,71 @@ rules:
871
972
  review-rounds: 2
872
973
  ```
873
974
 
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` |
878
-
879
- - **If a value is not a whole number above zero:**
880
- `factory config check` fails and names the key.
975
+ | Setting | What it sets | Default |
976
+ | -------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- |
977
+ | `small-change-lines` | How many changed lines, outside tests, specs, and content, a change can have and still count as [small](workflow.md#sizing-the-work-to-the-change), which skips the heavier steps | `30` |
978
+ | `review-rounds` | How many rounds of review comments a session answers before it hands what is left to you | `2` |
881
979
 
882
- Any rule that is prose, not a number, you change by saying otherwise in
883
- your own instructions for the agent, such as `CLAUDE.md`, which win over the
884
- factory's rules.
980
+ Each must be a whole number above zero. Any rule that isn't a number, you
981
+ change by saying so in your own instructions for the coding agent, such as
982
+ `CLAUDE.md`, which win over the factory's rules.
885
983
 
886
984
  ## Checking the file
887
985
 
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 |
986
+ | Command or tool | What it does |
987
+ | ------------------------ | ---------------------------------------------------------------------------------------------------- |
988
+ | Your editor | Flags a misspelled setting as you type, using the schema named on the file's first line |
989
+ | `factory config check` | Stops on anything the factory can't use, and warns about patterns that match nothing. CI runs it |
990
+ | `factory config explain` | Prints the whole file as the factory reads it, with every default written out and marked `# default` |
991
+ | `factory doctor` | Checks the file against your real board, and that each secret the factory needs is set |
894
992
 
895
- The first line of the file, which the three files below start with:
993
+ The first line `factory init` writes is optional. It points your editor at
994
+ the schema in the installed package:
896
995
 
897
996
  ```yaml
898
997
  # $schema: ../node_modules/@davidbyoung/software-factory/settings.schema.json
899
998
  ```
900
999
 
901
- Both editor families read it: JetBrains' editors and the YAML language server
902
- that Visual Studio Code's YAML extension uses. The path is relative to the
903
- settings file, so it finds the schema in the installed package, which matches
904
- the installed version and works offline. In a checkout with nothing installed
905
- the editor finds no schema and says so.
906
-
907
- The editor's check is a help. It accepts some files
908
- `factory config check` refuses, such as a plug-in whose
909
- file does not exist, and that command is the one that counts.
1000
+ JetBrains editors and Visual Studio Code's YAML extension both read it.
1001
+ The editor's check is only a help: it accepts some things
1002
+ `factory config check` refuses, such as a plugin whose file doesn't exist.
910
1003
 
911
1004
  ## Three complete files
912
1005
 
1006
+ The skills, agents, and scripts these files name are examples. Yours would
1007
+ have to exist in your repository for `factory config check` to pass.
1008
+
913
1009
  ### A web application with its own reviewers
914
1010
 
915
- An online store. It adds a skill that builds new API endpoints the way
916
- this project scaffolds them, and three reviewers of its own. It sets `site`,
917
- so the factory's design skill makes its mockups with no entry here. Changes to components, styles, docs, and tests merge
918
- unread; anything touching checkout or consent waits for a person.
1011
+ An online store with a board, a skill of its own for building new API
1012
+ endpoints, two reviewers of its own, and the factory's UI reviewer.
1013
+ Changes to components, styles, docs, and tests merge unread, except
1014
+ anything touching checkout or consent.
919
1015
 
920
1016
  ```yaml
921
1017
  # $schema: ../node_modules/@davidbyoung/software-factory/settings.schema.json
922
- # Settings for the software factory. Every key is explained in
923
- # docs/configuration.md in the factory's repository.
924
- #
925
- # Anything not listed here keeps its default: no pull request merges without
926
- # you, a build starts when you tell a session to work a ticket, and only the
927
- # built-in reviewers run.
928
- #
929
- # "version" is the shape of this file, not the factory's version.
930
1018
  version: 2
931
1019
  repository: harbor-goods/storefront
932
1020
 
933
- # Where tickets live. "board" is the number in your GitHub Project's address.
934
1021
  tickets:
935
- type: github
936
1022
  board: 1
937
1023
 
938
- # What starts a build once a ticket is moved to Ready on the board:
939
- # own-server (a small poller you host), github-action, or manual (you tell
940
- # a session to build it).
941
1024
  builds:
942
1025
  trigger: own-server
943
1026
 
944
- # How the written spec for a change your users will see is kept: openspec,
945
- # or none.
946
1027
  specs: openspec
947
1028
 
948
- # Every command a build runs, each from the repository's root.
949
1029
  commands:
950
- # Run on the session's machine before every commit it makes. If one
951
- # fails, the commit is blocked.
1030
+ build-setup:
1031
+ - npx playwright install --with-deps chromium
952
1032
  before-commit:
953
1033
  - npm run -s format:check
954
1034
  - npx tsc --noEmit
955
1035
  - npm run -s lint
956
- # Run before a session reports a task done, in order. A build cannot
957
- # finish until they pass.
958
1036
  gate:
959
1037
  - 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
1038
  test-one: npx vitest run $FILE -t "$NAME"
963
1039
 
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
973
1040
  plugins:
974
1041
  build:
975
1042
  builders:
@@ -980,24 +1047,18 @@ plugins:
980
1047
  - agent: migration-reviewer
981
1048
  files:
982
1049
  - db/migrations/**
983
- - agent: factory-ui-reviewer
1050
+ - agent: accessibility-reviewer
984
1051
  files:
985
1052
  - src/components/**
986
- - src/styles/**
987
- - agent: accessibility-reviewer
1053
+ - agent: factory-ui-reviewer
988
1054
  files:
989
1055
  - src/components/**
1056
+ - src/styles/**
990
1057
 
991
- # How the factory looks at this website, for factory-ui-reviewer.
992
1058
  site:
993
1059
  start: npm run build && npx serve out -p $PORT
994
1060
  url: http://localhost:$PORT
995
1061
 
996
- # Which pull requests may merge without you. Patterns are globs matched
997
- # against paths from the repository's root, and deny wins over allow. A pull
998
- # request merges itself only when every changed file matches "allow", none
999
- # matches "deny", every command under "commands" (if you list any) exits 0
1000
- # when CI runs it, and CI passes. Anything else waits for you.
1001
1062
  auto-merge:
1002
1063
  allow:
1003
1064
  - docs/**
@@ -1010,96 +1071,60 @@ auto-merge:
1010
1071
  - src/components/consent/**
1011
1072
  commands:
1012
1073
  - node scripts/public-api-changed.mjs
1074
+
1075
+ pr-review:
1076
+ commands:
1077
+ - npm test
1013
1078
  ```
1014
1079
 
1015
- ### A basic website
1080
+ ### A small website
1016
1081
 
1017
- A small marketing site with a board, no reviewers of its own, and nothing
1018
- merging unread. Everything not written here is a default.
1082
+ A marketing site with a board and nothing else changed. Builds start when
1083
+ someone asks a session, since `builds.trigger` defaults to `manual`.
1019
1084
 
1020
1085
  ```yaml
1021
1086
  # $schema: ../node_modules/@davidbyoung/software-factory/settings.schema.json
1022
- # Settings for the software factory. Every key is explained in
1023
- # docs/configuration.md in the factory's repository.
1024
- #
1025
- # Anything not listed here keeps its default: no pull request merges without
1026
- # you, a build starts when you tell a session to work a ticket, and only the
1027
- # built-in reviewers run.
1028
- #
1029
- # "version" is the shape of this file, not the factory's version.
1030
1087
  version: 2
1031
1088
  repository: riverbend-studio/site
1032
1089
 
1033
- # Where tickets live. "board" is the number in your GitHub Project's address.
1034
1090
  tickets:
1035
1091
  board: 4
1036
1092
 
1037
- # Every command a build runs, each from the repository's root.
1038
1093
  commands:
1039
- # Run on the session's machine before every commit it makes. If one
1040
- # fails, the commit is blocked.
1041
1094
  before-commit:
1042
1095
  - 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
1096
  gate:
1097
+ - npm run lint
1098
+ - npm run typecheck
1047
1099
  - npm test
1048
1100
  ```
1049
1101
 
1050
- Builds start when someone tells a session to work a ticket, since
1051
- `builds.trigger` defaults to `manual`.
1052
-
1053
- ### A repository that is not JavaScript
1102
+ ### A project that isn't JavaScript
1054
1103
 
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.
1104
+ A PHP library. Its commands are Composer's and PHPUnit's, and a cloud
1105
+ build installs its dependencies first. Docs merge unread, and one reviewer
1106
+ of its own reads changes to its public API.
1058
1107
 
1059
1108
  ```yaml
1060
1109
  # $schema: ../node_modules/@davidbyoung/software-factory/settings.schema.json
1061
- # Settings for the software factory. Every key is explained in
1062
- # docs/configuration.md in the factory's repository.
1063
- #
1064
- # Anything not listed here keeps its default: no pull request merges without
1065
- # you, a build starts when you tell a session to work a ticket, and only the
1066
- # built-in reviewers run.
1067
- #
1068
- # "version" is the shape of this file, not the factory's version.
1069
1110
  version: 2
1070
1111
  repository: northwind-php/ledger
1071
1112
 
1072
- # Where tickets live. "board" is the number in your GitHub Project's address.
1073
1113
  tickets:
1074
- type: github
1075
1114
  board: 2
1076
1115
 
1077
- # Every command a build runs, each from the repository's root.
1078
1116
  commands:
1079
- # Run on the session's machine before every commit it makes. If one
1080
- # fails, the commit is blocked.
1117
+ build-setup:
1118
+ - composer install --no-interaction
1081
1119
  before-commit:
1082
1120
  - 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
1121
  gate:
1087
1122
  - composer lint
1088
1123
  - composer analyse
1089
1124
  - 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
1125
  test-one: vendor/bin/phpunit $FILE ${NAME:+--filter "$NAME"}
1126
+ relock: composer update --lock
1093
1127
 
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
1103
1128
  plugins:
1104
1129
  build:
1105
1130
  reviewers:
@@ -1107,25 +1132,9 @@ plugins:
1107
1132
  files:
1108
1133
  - src/**
1109
1134
 
1110
- # Which pull requests may merge without you. Patterns are globs matched
1111
- # against paths from the repository's root, and deny wins over allow. A pull
1112
- # request merges itself only when every changed file matches "allow", none
1113
- # matches "deny", every command under "commands" (if you list any) exits 0
1114
- # when CI runs it, and CI passes. Anything else waits for you.
1115
1135
  auto-merge:
1116
1136
  allow:
1117
1137
  - docs/**
1118
1138
  deny:
1119
1139
  - docs/security/**
1120
1140
  ```
1121
-
1122
- If this team moved its tickets to Jira, only the `tickets` block would
1123
- change. **Only GitHub is built**; the block below shows the shape the
1124
- design leaves room for.
1125
-
1126
- ```yaml
1127
- tickets:
1128
- type: jira
1129
- site: northwind.atlassian.net
1130
- project: LEDGER
1131
- ```