@davidbyoung/software-factory 0.0.0-stage → 0.1.1

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