@davidbyoung/software-factory 0.1.3 → 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.
Files changed (80) hide show
  1. package/README.md +12 -11
  2. package/actions/factory-agent/action.yml +1 -1
  3. package/agents/factory-e2e-reviewer.md +102 -0
  4. package/agents/factory-test-reviewer.md +26 -64
  5. package/agents/factory-ticket-readiness.md +14 -6
  6. package/dist/cli.mjs +28 -1
  7. package/dist/code-host/github-setup.mjs +1 -1
  8. package/dist/commands.d.mts +16 -0
  9. package/dist/commands.mjs +129 -0
  10. package/dist/config.d.mts +61 -13
  11. package/dist/config.mjs +271 -69
  12. package/dist/deps.d.mts +7 -4
  13. package/dist/deps.mjs +20 -9
  14. package/dist/doctor.d.mts +3 -2
  15. package/dist/doctor.mjs +19 -4
  16. package/dist/explain.d.mts +4 -2
  17. package/dist/explain.mjs +70 -23
  18. package/dist/guard-commit.d.mts +7 -2
  19. package/dist/guard-commit.mjs +58 -21
  20. package/dist/init.d.mts +4 -2
  21. package/dist/init.mjs +18 -8
  22. package/dist/lib/default-branch.d.mts +35 -0
  23. package/dist/lib/default-branch.mjs +117 -0
  24. package/dist/lib/refined-check.d.mts +7 -0
  25. package/dist/lib/refined-check.mjs +76 -0
  26. package/dist/lib/work-status.d.mts +2 -2
  27. package/dist/lib/work-status.mjs +4 -4
  28. package/dist/parts.d.mts +1 -1
  29. package/dist/parts.mjs +2 -2
  30. package/dist/patch-coverage.d.mts +13 -0
  31. package/dist/patch-coverage.mjs +73 -0
  32. package/dist/pr-watch.d.mts +3 -2
  33. package/dist/pr-watch.mjs +22 -5
  34. package/dist/pr.mjs +34 -2
  35. package/dist/review-cost.mjs +1 -1
  36. package/dist/review-tools.mjs +3 -3
  37. package/dist/session-start.d.mts +23 -13
  38. package/dist/session-start.mjs +56 -44
  39. package/dist/site/servers.d.mts +6 -2
  40. package/dist/site/servers.mjs +14 -9
  41. package/dist/site.mjs +2 -2
  42. package/dist/sync.d.mts +8 -2
  43. package/dist/sync.mjs +41 -7
  44. package/dist/ticket.mjs +19 -1
  45. package/docs/builds.md +8 -8
  46. package/docs/cli.md +82 -45
  47. package/docs/configuration.md +838 -565
  48. package/docs/design.md +17 -4
  49. package/docs/developing.md +44 -8
  50. package/docs/existing-repo.md +9 -7
  51. package/docs/github/by-hand.md +27 -14
  52. package/docs/github/reference.md +21 -16
  53. package/docs/github/setup.md +14 -11
  54. package/docs/glossary.md +14 -5
  55. package/docs/limitations.md +27 -2
  56. package/docs/plugins.md +307 -52
  57. package/docs/quick-start.md +37 -9
  58. package/docs/removing.md +2 -2
  59. package/docs/skills.md +103 -54
  60. package/docs/updating.md +149 -3
  61. package/docs/workflow.md +13 -10
  62. package/package.json +1 -1
  63. package/review.md +20 -11
  64. package/rules.md +23 -19
  65. package/settings.schema.json +292 -72
  66. package/skills/factory-address-review/SKILL.md +50 -30
  67. package/skills/factory-build/SKILL.md +76 -23
  68. package/skills/factory-deps/SKILL.md +46 -21
  69. package/skills/factory-design/SKILL.md +18 -9
  70. package/skills/factory-diagnose/SKILL.md +22 -20
  71. package/skills/factory-mutate/SKILL.md +38 -24
  72. package/skills/factory-refine/SKILL.md +55 -31
  73. package/skills/factory-resolve-conflicts/SKILL.md +76 -34
  74. package/skills/factory-trace/SKILL.md +3 -2
  75. package/workflows/factory-build.yml +1 -1
  76. package/workflows/factory-claude-review.yml +1 -1
  77. package/workflows/factory-conflicts.yml +8 -8
  78. package/workflows/factory-deps.yml +1 -1
  79. package/workflows/factory-review.yml +1 -1
  80. package/skills/factory-address-review/patch-coverage.py +0 -68
@@ -1,95 +1,139 @@
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 part you can swap is a block with a `type`.** Today each has one type.
17
- When a part has no settings of its own, you may write it as one word:
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:
18
55
 
19
56
  ```yaml
20
57
  specs: openspec
21
58
  ```
22
59
 
23
- means the same as:
24
-
25
60
  ```yaml
26
61
  specs:
27
62
  type: openspec
28
63
  ```
29
64
 
30
- - **Comments are kept.** Setup writes the same comment above a section in
31
- 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.
32
67
 
33
68
  ## The shortest file
34
69
 
35
70
  ```yaml
36
- version: 1
71
+ version: 2
37
72
  repository: your-name/your-repo
38
73
  ```
39
74
 
40
- With this, sessions refine and build tickets when you tell them to, nothing
41
- merges without you, and there is no board.
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.
42
79
 
43
80
  ## The settings most repositories change
44
81
 
45
- Most repositories change three things, and leave every other key at its
46
- default.
47
-
48
- - **A board,** to see every ticket's state. Set `tickets.board` to your
49
- board's number, and when your columns have other names, map them under
50
- `tickets.columns`. [`tickets`](#tickets) has both. On GitHub,
51
- [Setting up on GitHub](github/setup.md) has the steps around
52
- them.
53
- - **What merges without you.** List the files that may under
54
- `auto-merge.allow`, such as your docs. [`auto-merge`](#auto-merge).
55
- - **Your own reviewers.** An agent of yours, listed under `plugins` with
56
- the files it reads. [`plugins`](#plugins), and
57
- [Plug-ins](plugins.md) for a worked example.
58
-
59
- The commands to run before each commit, [`before-commit`](#before-commit),
60
- are the fourth most repositories set.
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
86
+ [`commands.before-commit`](#commandsbefore-commit).
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
+ ```
61
102
 
62
- After any change, run `factory config check`, and
63
- `factory sync`, which rewrites the files a change of
64
- settings affects. A change under `plugins` alone needs no sync: plug-ins
65
- are read from the settings each time.
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.
66
108
 
67
- ## Every key
109
+ ## Every setting
68
110
 
69
111
  ### `version`
70
112
 
71
- The shape of this file, not the factory's version. It is `1`. It changes
72
- only when keys are renamed or moved, and an [update](updating.md) converts
73
- your file when it does.
113
+ Which layout of this file you are using. It is not the factory's version.
114
+ Write `2`.
74
115
 
75
- - **Default:** none. Setup writes it.
76
- - **If wrong:** every command of the factory stops and says which versions it
77
- understands.
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.
78
121
 
79
122
  ### `repository`
80
123
 
81
- The repository on the code host, as `owner/name`.
124
+ Your repository, as `owner/name`, such as `harbor-goods/storefront`.
82
125
 
83
- - **Default:** none. Setup writes it once.
84
- - **If wrong:** commands read and write another repository's tickets, or
85
- 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.
86
129
 
87
- It is a setting, not a lookup, so a command run outside a checkout, as the
88
- 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.
89
133
 
90
134
  ### `tickets`
91
135
 
92
- Where tickets live and how their state is shown.
136
+ Where your tickets live, and which board shows them.
93
137
 
94
138
  ```yaml
95
139
  tickets:
@@ -97,346 +141,651 @@ tickets:
97
141
  board: 1
98
142
  ```
99
143
 
100
- | Key | Meaning | Allowed | Default |
101
- | ------- | ------------------ | ---------------- | -------- |
102
- | `type` | The ticket system | `github` | `github` |
103
- | `board` | The board's number | A number, `none` | `none` |
104
-
105
- - **With `type: github`,** the board is a GitHub Project, and its number is
106
- the last part of its address.
107
- - **With no board,** a ticket's state lives in its comments,
108
- `factory status` still shows it, and builds start only
109
- when you tell a session.
110
- - **If `board` is wrong:** the board sync fails and names the board it could
111
- not read.
112
- - **One board can hold more than one repository's tickets.** Give each
113
- repository the same `board`: each one's sync, `status`, and poller read
114
- only the cards for its own issues, and GitHub's Repository field tells
115
- them apart on the board.
116
-
117
- A board shows the six states of [Workflow](workflow.md) as columns, and
118
- keeps three fields the factory writes. A repository that writes nothing
119
- below gets the factory's own board. `columns` and `fields` need a `board`.
120
-
121
- #### `tickets.columns`
122
-
123
- Which of your board's columns shows each state. Leave a key out to use the
124
- factory's own name for it. `none` means your board has no column for that
125
- state.
126
-
127
- | Key | State | Default column | May be `none` |
128
- | ---------- | -------- | -------------- | ------------- |
129
- | `backlog` | backlog | Backlog | No |
130
- | `refining` | refining | In refinement | Yes |
131
- | `ready` | ready | Ready | Yes |
132
- | `building` | building | In progress | Yes |
133
- | `review` | review | In review | Yes |
134
- | `done` | done | Done | Yes |
135
-
136
- - **A name matches whatever its capitals and the spaces around it,** so
137
- the default "In progress" finds a board's "In Progress".
138
- - **A ticket shows in its state's column. When that state has none, it
139
- shows in the column of the nearest earlier state that has one.** Nothing
140
- but an approved ticket shows in the `ready` column, so a state with no
141
- column passes over it.
142
- - **A card in a column no state names is left alone.** The sync writes none
143
- of its fields while it sits there, and nothing builds it.
144
- - **With `ready: none`,** no column approves a build. A build starts only
145
- when you tell a session to build the ticket or run
146
- `factory build N`, so
147
- `factory config check` requires `builds.trigger: manual`.
148
- - **If a repository's `ready` column has another name,** a poller you host
149
- needs it too: see `FACTORY_READY_COLUMN` in [Builds](builds.md). A
150
- scheduled one reads it from here.
151
- - `factory config get tickets.columns.ready` prints the
152
- name in effect, or `none`.
153
-
154
- #### `tickets.fields`
155
-
156
- Which of your board's fields the sync writes: `session`, `runs-in`, and
157
- `cost`, with the defaults Session, Runs in, and Cost. Each may be `none`.
158
- The board's own status field keeps its name, Status on a GitHub Project,
159
- 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.
160
149
 
161
- | The settings | The board | The sync |
162
- | -------------- | ---------------------------------- | -------------------------------------------------------------- |
163
- | name the field | has it, with the right type | writes it |
164
- | name the field | lacks it, or it has the wrong type | fails, naming the field and its key |
165
- | leave default | has it, with the right type | writes it |
166
- | leave default | lacks it | skips it, with a note |
167
- | leave default | has it, with the wrong type | fails, and says to name another field or set the key to `none` |
168
- | 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.
169
153
 
170
- Session is Text, Runs in is a single select with the options Local and
171
- Actions, and Cost is a Number. `factory board check` reads
172
- 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.
173
157
 
174
- 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.
175
160
 
176
- ```yaml
177
- tickets:
178
- type: github
179
- board: 1
180
- ```
161
+ #### `tickets.columns`
181
162
 
182
- A board with only Todo, In Progress, and Done, as a new GitHub Project
183
- 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:
184
169
 
185
170
  ```yaml
186
171
  tickets:
187
- type: github
188
172
  board: 7
189
173
  columns:
190
174
  backlog: Todo
175
+ building: In Progress
176
+ done: Done
191
177
  refining: none
192
178
  ready: none
193
- building: In Progress
194
179
  review: none
195
- done: Done
196
180
  builds:
197
181
  trigger: manual
198
182
  ```
199
183
 
200
- `factory config check` rejects, naming the key: a key it
201
- does not know;
202
- `backlog: none`; two states naming the same column; `columns` or `fields`
203
- with no `board`; and `ready: none` while `builds.trigger` is not `manual`.
204
- 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.
205
217
 
206
- `type` exists so that another ticket system changes this block and nothing
207
- else. Only `github` is built. Any other value fails
208
- `factory config check` and every ticket command with:
209
- `tickets.type "X" is not supported. "github" is the only ticket system built.`
218
+ #### `tickets.fields`
210
219
 
211
- ### `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:
212
222
 
213
- 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:
214
232
 
215
233
  ```yaml
216
- code-host:
217
- 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
218
239
  ```
219
240
 
220
- | Key | Meaning | Allowed | Default |
221
- | ------ | ------------- | -------- | -------- |
222
- | `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`
256
+
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.
223
259
 
224
- `code-host: github` means the same, and most files leave the block out.
225
- It exists so that code kept somewhere else changes this block and nothing
226
- else. Only `github` is built. Any other value fails
227
- `factory config check`, and every command that reads the
228
- settings and reaches a pull request, with:
229
- `code-host.type "X" is not supported. "github" is the only code host built.`
260
+ ```yaml
261
+ code-host: github
262
+ ```
230
263
 
231
264
  ### `builds`
232
265
 
266
+ What starts a build when you approve a ticket, and where the build runs.
267
+
233
268
  ```yaml
234
269
  builds:
235
270
  trigger: own-server
236
- runner: github-actions
237
271
  ```
238
272
 
239
- | Key | Meaning | Allowed | Default |
240
- | -------------- | -------------------------------------------------------------------- | --------------------------------------- | ---------------- |
241
- | `trigger` | What starts a build for a ticket you moved to Ready | `own-server`, `github-action`, `manual` | `manual` |
242
- | `runner` | Where a build in the cloud runs | `github-actions` | `github-actions` |
243
- | `poll-minutes` | How often the scheduled poller reads the board, with `github-action` | 5, 10, 15, 30, or 60 | 5 |
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.
244
304
 
245
- `trigger` is what notices a card moved to Ready, and `runner` is where the
246
- build it starts then runs: a poller on your own server still starts its
247
- builds on the cloud runner. Only `github-actions` is built. Any other value
248
- fails `factory config check`, and every command that reads
249
- the settings and reaches the runner, with:
250
- `builds.runner "X" is not supported. "github-actions" is the only runner built.`
305
+ ### `specs`
251
306
 
252
- - **`manual`:** nothing watches the board. You tell a session "work 12".
253
- - **`own-server`:** a small poller you host reads the board once a minute.
254
- - **`github-action`:** a schedule on the cloud runner does the same every
255
- `poll-minutes` minutes, with nothing to host. On a private repository,
256
- each pass is billed as at least an Actions minute.
307
+ Whether a change your users will see also gets a written spec, kept beside
308
+ your code.
257
309
 
258
- `factory config check` fails on `poll-minutes` beside any other trigger,
259
- and on any value but the five above.
310
+ ```yaml
311
+ specs: openspec
312
+ ```
260
313
 
261
- [Builds](builds.md) explains each. **If no poller is running,** a ticket
262
- moved to Ready sits there, and `factory status` flags it "not started":
263
- after 5 minutes with `own-server`, and after `poll-minutes` and 15 more
264
- with `github-action`.
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.
265
323
 
266
- ### `specs`
324
+ #### `specs.check`
267
325
 
268
- How the written spec for a change your visitors or users will see is kept.
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.
269
329
 
270
330
  ```yaml
271
- specs: openspec
331
+ specs:
332
+ type: openspec
333
+ check: npx --no-install openspec validate --all --strict --no-interactive
334
+ ```
335
+
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`.
343
+
344
+ ### `commands`
345
+
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.
350
+
351
+ ```yaml
352
+ commands:
353
+ build-setup:
354
+ - npx playwright install --with-deps chromium
355
+ before-commit:
356
+ - npm run -s format:check
357
+ - npx tsc --noEmit
358
+ gate:
359
+ - npm run check
360
+ test-one: npx vitest run $FILE -t "$NAME"
361
+ end-to-end: npx playwright test $FILE
362
+ coverage:
363
+ run: npm run coverage
364
+ report: coverage/lcov.info
365
+ relock: npm install
272
366
  ```
273
367
 
274
- | Allowed | Meaning |
275
- | ---------- | ------------------------------------------------------------------------- |
276
- | `none` | The ticket's acceptance criteria are the only spec |
277
- | `openspec` | A visible, non-trivial change also adds its behavior to `openspec/specs/` |
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` |
278
377
 
279
- - **Default:** `none`.
280
- - **If you set `openspec` without OpenSpec installed:** a build of a visible
281
- change stops at its first spec step and says so.
378
+ - **`$FILE` and `$NAME`** are set for you when a command runs one test.
379
+ [`commands.test-one`](#commandstest-one) says how.
380
+ - **Only `gate` is needed for a build.** Each of the others turns
381
+ something on, and its entry below says what happens without it.
382
+ - **A list runs in order and stops at the first command that fails.**
282
383
 
283
- ### `before-commit`
384
+ #### `commands.build-setup`
284
385
 
285
- Commands run, in order, before every commit a session makes. If one fails,
286
- the commit is blocked and the session is shown the output.
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.
287
389
 
288
390
  ```yaml
289
- before-commit:
290
- - npm run -s format:check
291
- - npx tsc --noEmit
292
- - npm run -s lint
391
+ commands:
392
+ build-setup:
393
+ - npx playwright install --with-deps chromium # a browser for end-to-end tests
293
394
  ```
294
395
 
295
- - **Default:** none. Setup proposes some from your `package.json`,
296
- `composer.json`, or Makefile, and asks.
297
- - **Keep them fast.** They run on every commit. Your full test suite belongs
298
- in the gate your agent's instructions name, which a session runs before it
299
- reports a task done, and in CI.
300
- - **If one is wrong:** every commit is blocked with that command's error.
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
+
399
+ - **Default:** none.
400
+ - **If one fails,** the build stops before the session starts, and the
401
+ run's log shows that command's output.
301
402
 
302
- ### `build-setup`
403
+ #### `commands.before-commit`
303
404
 
304
- Commands run, in order, from the repository's root before a build in the
305
- cloud starts work. Your npm dependencies are already installed by then,
306
- with `npm ci`.
405
+ Quick checks that run before every commit a session makes. If one fails,
406
+ the commit is blocked and the session sees why.
307
407
 
308
408
  ```yaml
309
- # Commands run from the repository's root before an unattended build starts
310
- # work. Your npm dependencies are already installed by then.
311
- build-setup:
312
- - npx playwright install --with-deps chromium
409
+ commands:
410
+ before-commit:
411
+ - npm run -s format:check
412
+ - npx tsc --noEmit
413
+ - npm run -s lint
313
414
  ```
314
415
 
315
416
  - **Default:** none.
316
- - **What goes here:** what a session needs that `npm ci` does not give it,
317
- such as a browser for end-to-end tests or a system package.
318
- - **If one fails:** the run stops before the session starts, with that
319
- command's output in its log.
320
- - `factory config get build-setup` prints one command per
321
- line.
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.
421
+
422
+ #### `commands.gate`
423
+
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:
431
+
432
+ ```yaml
433
+ commands:
434
+ gate:
435
+ - npm run check
436
+ ```
437
+
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.
502
+
503
+ #### `commands.test-one`
504
+
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:
510
+
511
+ ```yaml
512
+ commands:
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
519
+ ```
520
+
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.
524
+
525
+ #### `commands.end-to-end`
526
+
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.
532
+
533
+ ```yaml
534
+ commands:
535
+ end-to-end: npx playwright test $FILE
536
+ ```
537
+
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.
543
+
544
+ #### `commands.coverage`
545
+
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.
549
+
550
+ ```yaml
551
+ commands:
552
+ coverage:
553
+ run: npm run coverage
554
+ report: coverage/lcov.info
555
+ ```
556
+
557
+ - **Default:** none, and a session doesn't check coverage.
558
+ - **Write both `run` and `report`,** or neither.
559
+
560
+ #### `commands.relock`
561
+
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.
565
+
566
+ ```yaml
567
+ commands:
568
+ relock: composer update --lock
569
+ ```
570
+
571
+ - **Default:** `npm install`.
572
+ - **Another generated file that conflicts,** such as a generated API
573
+ client, needs a [resolver](#pluginsconflicts).
322
574
 
323
575
  ### `session-minutes`
324
576
 
325
- How long each kind of session that runs on its own in the cloud may run, in
326
- minutes. Raise one when your tests, your build, or your site's
327
- 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.
328
580
 
329
581
  ```yaml
330
- # How long each unattended session may run, in minutes.
331
582
  session-minutes:
332
583
  build: 300
333
584
  ```
334
585
 
335
- | Key | The session | Default |
336
- | -------------- | --------------------------------------------- | ------- |
337
- | `build` | A build of a ticket | `230` |
338
- | `conflicts` | A fix of a pull request's conflicts with main | `110` |
339
- | `review` | An answer to your review of a pull request | `50` |
340
- | `dependencies` | Work on the dependency pull requests | `50` |
341
-
342
- - **Each is a whole number above zero.** A key you leave out keeps its
343
- default.
344
- - **The job around a session gets 10 minutes more,** so the steps after it,
345
- which release the ticket and post what happened, still run when the
346
- session is stopped.
347
- - **`factory sync` writes these where the cloud runner
348
- reads them,** and `factory sync --check` fails until it
349
- has run after a change.
350
- - **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
351
597
  [its limits](github/reference.md#limits).
352
- - The cloud jobs that run no session, such as the board's sync and who
353
- merges, keep fixed short limits.
354
- - `factory config get session-minutes.build` prints the
355
- value in effect.
356
598
 
357
599
  ### `plugins`
358
600
 
359
- Your own skills and agents, and the job each does. Refining, building, and
360
- reviewing tests are built in; these add to them.
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`.
361
606
 
362
607
  ```yaml
363
608
  plugins:
364
- - skill: design-mockups
365
- role: mockups
366
- - skill: add-endpoint
367
- role: builder
368
- labels:
369
- - new-endpoint
370
- - agent: migration-reviewer
371
- role: reviewer
372
- files:
373
- - db/migrations/**
374
- ```
375
-
376
- | Key | Meaning |
377
- | ---------------- | --------------------------------------------------------------------- |
378
- | `skill`, `agent` | The name of one of your own skills or agents |
379
- | `role` | `mockups`, `builder`, or `reviewer` |
380
- | `labels` | For a `builder`: it builds a ticket carrying one of these labels |
381
- | `files` | For a `reviewer`: it is considered when a change touches one of these |
382
-
383
- Where your coding agent keeps them: in Claude Code, see
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`:
384
634
  [Skills in Claude Code](github/reference.md#skills-in-claude-code).
385
635
 
386
- - **Default:** none.
387
- - **`files` is a filter, not the whole rule.** When a reviewer really
388
- applies is in that agent's own description. A reviewer whose files matched
389
- but which did not apply gets one line in the pull request saying why.
390
- - **If a name is wrong:** `factory config check` fails and
391
- names the missing file.
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:
653
+
654
+ ```yaml
655
+ plugins:
656
+ refine:
657
+ refiner:
658
+ skill: acme-refine # .claude/skills/acme-refine/SKILL.md
659
+ mockups:
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:
676
+ build:
677
+ builders:
678
+ - skill: add-endpoint
679
+ labels:
680
+ - new-endpoint
681
+ reviewers:
682
+ - agent: migration-reviewer
683
+ files:
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:
700
+ test:
701
+ prover:
702
+ skill: acme-mutation
703
+ reviewers:
704
+ - agent: factory-test-reviewer
705
+ - agent: factory-e2e-reviewer
706
+ files:
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:
721
+ conflicts:
722
+ resolvers:
723
+ - skill: regenerate-api-client
724
+ files:
725
+ - src/generated/**
726
+ ```
392
727
 
393
728
  ### `site`
394
729
 
395
- How the factory looks at your website. Leave it out if the repository is not
396
- one. With it, and `factory-ui-reviewer` listed under `plugins`, a visible
397
- change is pictured before and after, and the difference is reviewed.
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`.
737
+
738
+ Most sites need only two lines:
398
739
 
399
740
  ```yaml
400
741
  site:
401
- # A command that builds and serves the site from the repository's root,
402
- # and the address it answers at. $PORT is set for you.
403
742
  start: npm run build && npx serve out -p $PORT
404
743
  url: http://localhost:$PORT
405
- # Optional. Your design rules, applied on top of the built-in ones.
406
- design-guide: docs/design.md
407
- ```
408
-
409
- | Key | Default | Meaning |
410
- | --------------- | ------------- | ---------------------------------------------------------------------------------------------------- |
411
- | `start` | required | Builds and serves the site from the repository's root; `$PORT` is set |
412
- | `url` | required | The address `start` answers at |
413
- | `design-guide` | none | A file of your own design rules |
414
- | `pages` | found | The paths to look at. Otherwise from `/sitemap.xml`, or the home page's links |
415
- | `widths` | `[390, 1280]` | The widths, in pixels, each page is shot at |
416
- | `hide` | none | CSS selectors hidden before every picture, for something that floats |
417
- | `checks` | none | Your own measuring commands. Each gets one JSON object on its standard input |
418
- | `max-pages` | `4` | How many changed pages the agent reads closely |
419
- | `start-minutes` | `5` | How long to wait for the site to answer after `start` is run |
420
- | `accessibility` | `wcag22aa` | The WCAG level axe-core measures changed pages against: `wcag22aa`, `wcag21aa`, `wcag2aa`, or `none` |
421
- | `new-values` | `true` | `false` leaves out the font sizes, colors, spacing, and radii the base site does not use |
422
-
423
- - **`factory config get site`** prints every key in this
424
- order, defaults included, one `key: value` line each.
425
- `factory config get site.widths` prints one key, a list one item to a line, and `none` for a key that is not
426
- set; `site.pages` prints `found` when it is not set.
427
- - **`factory config check`** rejects a `site` with no `start` or `url`, a
428
- `design-guide` that is not a file, and `factory-ui-reviewer` listed with no
429
- `site`. It also fails when the `playwright` package is not found from the
430
- repository's root: `npm install -D playwright`. It looks for the package and
431
- never for a browser.
432
- - **A `checks` command** gets `{"before", "after", "pages", "report"}` on its
433
- standard input: the two addresses, the paths that changed, and the folder of
434
- pictures. Each non-empty line it prints is a finding; its exit code says
435
- nothing.
744
+ ```
745
+
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.
749
+
750
+ Every setting `site` takes:
751
+
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` |
765
+
766
+ The optional ones that take a list are written like this:
767
+
768
+ ```yaml
769
+ site:
770
+ start: npm run build && npx serve out -p $PORT
771
+ url: http://localhost:$PORT
772
+ pages:
773
+ - /
774
+ - /pricing
775
+ hide:
776
+ - .chat-widget
777
+ checks:
778
+ - node scripts/check-tap-targets.mjs
779
+ ```
780
+
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.
436
785
 
437
786
  ### `auto-merge`
438
787
 
439
- Which pull requests may merge without you.
788
+ Which pull requests may merge without you reading them.
440
789
 
441
790
  ```yaml
442
791
  auto-merge:
@@ -452,108 +801,101 @@ auto-merge:
452
801
 
453
802
  A pull request merges itself only when **all** of these hold:
454
803
 
455
- 1. every changed file matches a pattern under `allow`;
456
- 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`;
457
806
  3. every command under `commands` exits 0;
458
- 4. CI passes, including the automated review's verdict.
459
-
460
- Anything else waits for you, and the pull request says why.
461
-
462
- | Key | Meaning | Default |
463
- | ---------- | -------------------------------------------------------------------- | ------- |
464
- | `allow` | Patterns for files safe to merge unread | empty |
465
- | `deny` | Exceptions inside `allow`. `deny` always wins | empty |
466
- | `commands` | Your own checks. Each is run once for a pull request and can veto it | empty |
467
-
468
- - **With the default, nothing merges without you.**
469
- - **Always held for you, whatever you allow:** the factory's own files
470
- (`.claude/`, `.github/`, every `CLAUDE.md` and `AGENTS.md`, and
471
- `openspec/config.yaml`).
472
- - **A command** is run once for a pull request, from the root of a checkout
473
- of your default branch, never the pull request's. It is given one JSON
474
- object on its standard input:
475
-
476
- ```json
477
- {
478
- "repository": "harbor-goods/storefront",
479
- "pull": 42,
480
- "base": "the merge base's commit",
481
- "head": "the pull request's newest commit",
482
- "files": [
483
- {
484
- "filename": "src/a.ts",
485
- "previous_filename": "src/b.ts",
486
- "status": "renamed"
487
- }
488
- ]
489
- }
490
- ```
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:
491
847
 
492
- It exits 0 to allow the merge, and anything else to hold the pull request
493
- for you. Each line it prints is shown as a reason; one that prints nothing
494
- is shown as "held by" and the command. A command that cannot be run
495
- counts as a hold.
496
-
497
- - **The reasons a held pull request shows**, one for each file or command
498
- that held it, in this order of checking:
499
-
500
- | Reason | Why |
501
- | -------------------------------------- | --------------------------------------------------- |
502
- | `PATH: the factory's own files` | One of the files below, whatever `allow` says |
503
- | `PATH: held by auto-merge.deny` | It matches `deny` |
504
- | `PATH: not in auto-merge.allow` | It matches nothing in `allow` |
505
- | What a command printed | A command exited with anything but 0 |
506
- | `held by COMMAND` | A command exited with anything but 0, printing none |
507
- | `held by COMMAND: it could not be run` | The command was not found or could not be started |
508
- | `no changed files` | The pull request changes nothing |
509
-
510
- A renamed file is checked under both its names.
511
-
512
- - **If a pattern matches no file:** `factory config check`
513
- warns, since a stale pattern is how a policy rots.
514
- - **If `allow` is too wide:** changes you meant to read merge unread.
515
- Start with a short list and add to it.
516
- - **If a `deny` pattern matches nothing inside `allow`:** it does nothing,
517
- and `factory config check` says so.
518
-
519
- ### `ci-review`
520
-
521
- The automated review of every pull request: Claude reads each one once it
522
- is marked ready, comments on what it finds, and posts a verdict. It is on
523
- while `ci-review` is written, even with nothing under it, and `factory
524
- sync` then writes its workflow, `.github/workflows/factory-claude-review.yml`.
525
- [Setting up on GitHub](github/setup.md) has what it needs on GitHub.
526
-
527
- ```yaml
528
- # The automated review of every pull request, on while this is written.
529
- # "commands" are what it may run to confirm a finding, beside reading the
530
- # pull request and commenting on it.
531
- ci-review:
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.
859
+
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.
866
+
867
+ ```yaml
868
+ pr-review:
532
869
  commands:
533
870
  - npm test
534
871
  - npx tsc --noEmit
535
872
  ```
536
873
 
537
- - **Default:** off.
538
- - **`commands`:** each is a command prefix the reviewer may run, such as
539
- your tests, the type check, or lint. Without any, it reads the pull
540
- request, its history, and your instructions, and runs nothing of yours.
541
- A command may hold no comma, parenthesis, or quote.
542
- - **Read from the pull request's base commit,** so a change to the
543
- settings alone cannot widen what its own review may run.
544
- - **To turn it off,** delete `ci-review` and run
545
- `factory sync`, which deletes the workflow.
546
- - `factory review tools` prints every tool the review may
547
- 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.
548
890
 
549
891
  ### `approvers`
550
892
 
551
- _[Planned](developing.md#what-is-built)_: `factory config check`
552
- 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.
553
895
 
554
- The people whose comments a session treats as instructions, and whose move
555
- of a ticket to Ready counts as approval. Everyone else's comments are
556
- 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.
557
899
 
558
900
  ```yaml
559
901
  approvers:
@@ -561,20 +903,16 @@ approvers:
561
903
  - a-teammate
562
904
  ```
563
905
 
564
- - **Default:** the repository's owner. One person never writes this key.
565
- - **If a name is wrong:** that person's comments are treated as
566
- information, and a ticket they move to Ready is not built.
567
- _[Planned](developing.md#what-is-built)_: `factory doctor`
568
- flags a name that is not an account with access to the repository.
569
-
570
- A session posts through a person's account too, so it marks its own comments
571
- 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.
572
910
 
573
911
  ### `rules`
574
912
 
575
- Numbers the process rules use, for a repository that wants different ones.
576
- `factory sync` writes each into the copies of the rules and skills that
577
- 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.
578
916
 
579
917
  ```yaml
580
918
  rules:
@@ -582,125 +920,93 @@ rules:
582
920
  review-rounds: 2
583
921
  ```
584
922
 
585
- | Key | Meaning | Default |
586
- | -------------------- | -------------------------------------------------------------------------------------------------------------------------- | ------- |
587
- | `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` |
588
- | `review-rounds` | Rounds a session works a review before it hands what is left to you | `2` |
589
-
590
- - **If a value is not a whole number above zero:**
591
- `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` |
592
927
 
593
- Any rule that is prose, not a number, you change by saying otherwise in
594
- your own instructions for the agent, such as `CLAUDE.md`, which win over the
595
- 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.
596
931
 
597
932
  ## Checking the file
598
933
 
599
- | Command | What it does |
600
- | ------------------------ | ---------------------------------------------------------------------------------------------------------------------- |
601
- | Your editor | The first line of the file points at the factory's schema, which flags a misspelled key as you type it |
602
- | `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 |
603
- | `factory config explain` | Prints every setting in effect, as the file would read with every default written out, each default marked `# default` |
604
- | `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 |
605
940
 
606
- 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:
607
943
 
608
944
  ```yaml
609
945
  # $schema: ../node_modules/@davidbyoung/software-factory/settings.schema.json
610
946
  ```
611
947
 
612
- Both editor families read it: JetBrains' editors and the YAML language server
613
- that Visual Studio Code's YAML extension uses. The path is relative to the
614
- settings file, so it finds the schema in the installed package, which matches
615
- the installed version and works offline. In a checkout with nothing installed
616
- the editor finds no schema and says so.
617
-
618
- The editor's check is a help. It accepts some files
619
- `factory config check` refuses, such as a plug-in whose
620
- 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.
621
951
 
622
952
  ## Three complete files
623
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
+
624
957
  ### A web application with its own reviewers
625
958
 
626
- An online store. It adds a skill that builds new API endpoints the way
627
- this project scaffolds them, and three reviewers of its own. It sets `site`,
628
- so the factory's design skill makes its mockups with no entry here. Changes to components, styles, docs, and tests merge
629
- 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.
630
963
 
631
964
  ```yaml
632
965
  # $schema: ../node_modules/@davidbyoung/software-factory/settings.schema.json
633
- # Settings for the software factory. Every key is explained in
634
- # docs/configuration.md in the factory's repository.
635
- #
636
- # Anything not listed here keeps its default: no pull request merges without
637
- # you, a build starts when you tell a session to work a ticket, and only the
638
- # built-in reviewers run.
639
- #
640
- # "version" is the shape of this file, not the factory's version.
641
- version: 1
966
+ version: 2
642
967
  repository: harbor-goods/storefront
643
968
 
644
- # Where tickets live. "board" is the number in your GitHub Project's address.
645
969
  tickets:
646
- type: github
647
970
  board: 1
648
971
 
649
- # What starts a build once a ticket is moved to Ready on the board:
650
- # own-server (a small poller you host), github-action, or manual (you tell
651
- # a session to build it).
652
972
  builds:
653
973
  trigger: own-server
654
974
 
655
- # How the written spec for a change your users will see is kept: openspec,
656
- # or none.
657
975
  specs: openspec
658
976
 
659
- # Commands run on the session's machine, from the repository's root, before
660
- # every commit it makes. If one fails, the commit is blocked.
661
- before-commit:
662
- - npm run -s format:check
663
- - npx tsc --noEmit
664
- - npm run -s lint
665
-
666
- # Your own skills and agents. A skill is a set of instructions a session
667
- # follows; an agent is a separate reviewer a session launches. Refining,
668
- # building, and reviewing tests are built in; these add to them. "role" is
669
- # one of:
670
- # mockups makes pictures to choose from when a decision changes the look
671
- # builder builds a ticket that carries one of "labels" (label names),
672
- # in place of the built-in build
673
- # reviewer is asked to read a finished change when it touches a path
674
- # matching "files", and reports problems; it edits nothing
977
+ commands:
978
+ build-setup:
979
+ - npx playwright install --with-deps chromium
980
+ before-commit:
981
+ - npm run -s format:check
982
+ - npx tsc --noEmit
983
+ - npm run -s lint
984
+ gate:
985
+ - npm run check
986
+ test-one: npx vitest run $FILE -t "$NAME"
987
+
675
988
  plugins:
676
- - skill: add-endpoint
677
- role: builder
678
- labels:
679
- - new-endpoint
680
- - agent: migration-reviewer
681
- role: reviewer
682
- files:
683
- - db/migrations/**
684
- - agent: factory-ui-reviewer
685
- role: reviewer
686
- files:
687
- - src/components/**
688
- - src/styles/**
689
- - agent: accessibility-reviewer
690
- role: reviewer
691
- files:
692
- - src/components/**
693
-
694
- # How the factory looks at this website, for factory-ui-reviewer.
989
+ build:
990
+ builders:
991
+ - skill: add-endpoint
992
+ labels:
993
+ - new-endpoint
994
+ reviewers:
995
+ - agent: migration-reviewer
996
+ files:
997
+ - db/migrations/**
998
+ - agent: accessibility-reviewer
999
+ files:
1000
+ - src/components/**
1001
+ - agent: factory-ui-reviewer
1002
+ files:
1003
+ - src/components/**
1004
+ - src/styles/**
1005
+
695
1006
  site:
696
1007
  start: npm run build && npx serve out -p $PORT
697
1008
  url: http://localhost:$PORT
698
1009
 
699
- # Which pull requests may merge without you. Patterns are globs matched
700
- # against paths from the repository's root, and deny wins over allow. A pull
701
- # request merges itself only when every changed file matches "allow", none
702
- # matches "deny", every command under "commands" (if you list any) exits 0
703
- # when CI runs it, and CI passes. Anything else waits for you.
704
1010
  auto-merge:
705
1011
  allow:
706
1012
  - docs/**
@@ -713,103 +1019,70 @@ auto-merge:
713
1019
  - src/components/consent/**
714
1020
  commands:
715
1021
  - node scripts/public-api-changed.mjs
1022
+
1023
+ pr-review:
1024
+ commands:
1025
+ - npm test
716
1026
  ```
717
1027
 
718
- ### A basic website
1028
+ ### A small website
719
1029
 
720
- A small marketing site with a board, no reviewers of its own, and nothing
721
- 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`.
722
1032
 
723
1033
  ```yaml
724
1034
  # $schema: ../node_modules/@davidbyoung/software-factory/settings.schema.json
725
- # Settings for the software factory. Every key is explained in
726
- # docs/configuration.md in the factory's repository.
727
- #
728
- # Anything not listed here keeps its default: no pull request merges without
729
- # you, a build starts when you tell a session to work a ticket, and only the
730
- # built-in reviewers run.
731
- #
732
- # "version" is the shape of this file, not the factory's version.
733
- version: 1
1035
+ version: 2
734
1036
  repository: riverbend-studio/site
735
1037
 
736
- # Where tickets live. "board" is the number in your GitHub Project's address.
737
1038
  tickets:
738
1039
  board: 4
739
1040
 
740
- # Commands run on the session's machine, from the repository's root, before
741
- # every commit it makes. If one fails, the commit is blocked.
742
- before-commit:
743
- - npm run lint
744
- - npm run typecheck
1041
+ commands:
1042
+ before-commit:
1043
+ - npm run lint
1044
+ gate:
1045
+ - npm run lint
1046
+ - npm run typecheck
1047
+ - npm test
745
1048
  ```
746
1049
 
747
- Builds start when someone tells a session to work a ticket, since
748
- `builds.trigger` defaults to `manual`.
749
-
750
- ### A repository that is not JavaScript
1050
+ ### A project that isn't JavaScript
751
1051
 
752
- A PHP library. Its commands are Composer's. It lets documentation merge
753
- unread and has one reviewer of its own for its public API.
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.
754
1055
 
755
1056
  ```yaml
756
1057
  # $schema: ../node_modules/@davidbyoung/software-factory/settings.schema.json
757
- # Settings for the software factory. Every key is explained in
758
- # docs/configuration.md in the factory's repository.
759
- #
760
- # Anything not listed here keeps its default: no pull request merges without
761
- # you, a build starts when you tell a session to work a ticket, and only the
762
- # built-in reviewers run.
763
- #
764
- # "version" is the shape of this file, not the factory's version.
765
- version: 1
1058
+ version: 2
766
1059
  repository: northwind-php/ledger
767
1060
 
768
- # Where tickets live. "board" is the number in your GitHub Project's address.
769
1061
  tickets:
770
- type: github
771
1062
  board: 2
772
1063
 
773
- # Commands run on the session's machine, from the repository's root, before
774
- # every commit it makes. If one fails, the commit is blocked.
775
- before-commit:
776
- - composer lint
777
- - composer analyse
778
-
779
- # Your own skills and agents. A skill is a set of instructions a session
780
- # follows; an agent is a separate reviewer a session launches. Refining,
781
- # building, and reviewing tests are built in; these add to them. "role" is
782
- # one of:
783
- # mockups makes pictures to choose from when a decision changes the look
784
- # builder builds a ticket that carries one of "labels" (label names),
785
- # in place of the built-in build
786
- # reviewer is asked to read a finished change when it touches a path
787
- # matching "files", and reports problems; it edits nothing
1064
+ commands:
1065
+ build-setup:
1066
+ - composer install --no-interaction
1067
+ before-commit:
1068
+ - composer lint
1069
+ gate:
1070
+ - composer lint
1071
+ - composer analyse
1072
+ - composer test
1073
+ test-one: vendor/bin/phpunit $FILE ${NAME:+--filter "$NAME"}
1074
+ relock: composer update --lock
1075
+
788
1076
  plugins:
789
- - agent: api-compatibility-reviewer
790
- role: reviewer
791
- files:
792
- - src/**
793
-
794
- # Which pull requests may merge without you. Patterns are globs matched
795
- # against paths from the repository's root, and deny wins over allow. A pull
796
- # request merges itself only when every changed file matches "allow", none
797
- # matches "deny", every command under "commands" (if you list any) exits 0
798
- # when CI runs it, and CI passes. Anything else waits for you.
1077
+ build:
1078
+ reviewers:
1079
+ - agent: api-compatibility-reviewer
1080
+ files:
1081
+ - src/**
1082
+
799
1083
  auto-merge:
800
1084
  allow:
801
1085
  - docs/**
802
1086
  deny:
803
1087
  - docs/security/**
804
1088
  ```
805
-
806
- If this team moved its tickets to Jira, only the `tickets` block would
807
- change. **Only GitHub is built**; the block below shows the shape the
808
- design leaves room for.
809
-
810
- ```yaml
811
- tickets:
812
- type: jira
813
- site: northwind.atlassian.net
814
- project: LEDGER
815
- ```