@davidbyoung/software-factory 0.1.4 → 0.1.5

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