@davidbyoung/software-factory 0.1.4 → 0.1.6

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (57) hide show
  1. package/README.md +9 -8
  2. package/dist/cli.mjs +13 -1
  3. package/dist/code-host/github-setup.mjs +1 -1
  4. package/dist/config.d.mts +74 -20
  5. package/dist/config.mjs +326 -76
  6. package/dist/deps.d.mts +6 -4
  7. package/dist/deps.mjs +29 -7
  8. package/dist/doctor.d.mts +3 -0
  9. package/dist/doctor.mjs +7 -4
  10. package/dist/explain.d.mts +13 -2
  11. package/dist/explain.mjs +58 -43
  12. package/dist/init.mjs +9 -7
  13. package/dist/lib/default-branch.d.mts +1 -1
  14. package/dist/lib/default-branch.mjs +2 -2
  15. package/dist/lib/refined-check.mjs +1 -1
  16. package/dist/lib/work-status.d.mts +2 -2
  17. package/dist/lib/work-status.mjs +4 -4
  18. package/dist/parts.d.mts +1 -1
  19. package/dist/parts.mjs +2 -2
  20. package/dist/preset-commands.d.mts +65 -0
  21. package/dist/preset-commands.mjs +1148 -0
  22. package/dist/preset.d.mts +169 -0
  23. package/dist/preset.mjs +550 -0
  24. package/dist/remove.mjs +34 -1
  25. package/dist/review-cost.mjs +1 -1
  26. package/dist/review-tools.mjs +3 -3
  27. package/dist/session-start.d.mts +3 -0
  28. package/dist/session-start.mjs +12 -1
  29. package/dist/sync.d.mts +42 -7
  30. package/dist/sync.mjs +166 -32
  31. package/docs/builds.md +12 -11
  32. package/docs/cli.md +27 -8
  33. package/docs/configuration.md +723 -714
  34. package/docs/design.md +1 -1
  35. package/docs/developing.md +20 -8
  36. package/docs/existing-repo.md +1 -1
  37. package/docs/github/by-hand.md +9 -9
  38. package/docs/github/reference.md +4 -19
  39. package/docs/github/setup.md +3 -3
  40. package/docs/glossary.md +18 -9
  41. package/docs/limitations.md +4 -1
  42. package/docs/plugins.md +36 -24
  43. package/docs/presets.md +410 -0
  44. package/docs/quick-start.md +21 -18
  45. package/docs/removing.md +1 -1
  46. package/docs/skills.md +28 -23
  47. package/docs/updating.md +22 -14
  48. package/docs/workflow.md +13 -14
  49. package/package.json +1 -1
  50. package/rules.md +1 -1
  51. package/settings.schema.json +60 -11
  52. package/skills/factory-build/SKILL.md +1 -1
  53. package/skills/factory-deps/SKILL.md +23 -12
  54. package/skills/factory-design/SKILL.md +2 -2
  55. package/skills/factory-refine/SKILL.md +2 -2
  56. package/skills/factory-resolve-conflicts/SKILL.md +6 -0
  57. package/workflows/factory-claude-review.yml +8 -3
package/docs/updating.md CHANGED
@@ -23,7 +23,8 @@ settings file: [Moving to settings version 2](#moving-to-settings-version-2).
23
23
  ## What the pull request holds
24
24
 
25
25
  - **The new version**, in `package.json`, the lockfile, and
26
- `.claude/factory.lock`.
26
+ `.claude/factory.lock`. The lock also holds every setting in effect, so
27
+ a release that changes a default shows in its diff.
27
28
  - **The factory's files, rewritten.** Its skills, agents, rules, and CI
28
29
  workflows live in your repository, so the diff shows exactly which
29
30
  instruction changed.
@@ -33,6 +34,10 @@ settings file: [Moving to settings version 2](#moving-to-settings-version-2).
33
34
  An update changes the instructions your sessions follow and the code that
34
35
  runs with your tokens. Read it as carefully as you would read code.
35
36
 
37
+ A new version of a [preset](presets.md) arrives the same way, with a
38
+ comment saying what it changes in this repository:
39
+ [When a preset changes](presets.md#when-a-preset-changes).
40
+
36
41
  ## Doing it yourself
37
42
 
38
43
  To update now instead of waiting for Dependabot:
@@ -96,10 +101,11 @@ and its checks fail until the file is moved. On the pull request's branch:
96
101
  | `version: 1` | `version: 2` |
97
102
  | `before-commit`, at the top of the file | [`commands.before-commit`](configuration.md#commandsbefore-commit) |
98
103
  | `build-setup`, at the top of the file | [`commands.build-setup`](configuration.md#commandsbuild-setup) |
99
- | [`plugins`](configuration.md#plugins), one list, each item with a `role` | `plugins`, grouped by phase, each plug-in in a slot, with no `role` |
100
- | A plug-in with `role: mockups` | The one block [`plugins.refine.mockups`](configuration.md#pluginsrefine) |
101
- | A plug-in with `role: builder` | An item of the list [`plugins.build.builders`](configuration.md#pluginsbuild) |
102
- | A plug-in with `role: reviewer` | An item of the list `plugins.build.reviewers` |
104
+ | [`plugins`](configuration.md#plugins), one list, each item with a `role` | `plugins`, grouped by phase, each plugin listed under its role's key instead of a `role` field |
105
+ | A plugin with `role: mockups` | The one block [`plugins.refine.mockups`](configuration.md#pluginsrefine) |
106
+ | A plugin with `role: builder` | An item of the list [`plugins.build.builders`](configuration.md#pluginsbuild) |
107
+ | A plugin with `role: reviewer` | An item of the list `plugins.build.reviewers` |
108
+ | `ci-review` | [`pr-review`](configuration.md#pr-review), the same block under a new name |
103
109
  | [`specs`](configuration.md#specs), one word | Still one word. It is now also a block, with `type` and [`check`](configuration.md#specscheck) |
104
110
 
105
111
  Every other key keeps its name, its place, and its meaning.
@@ -195,8 +201,8 @@ needed, and the rest are worth a look while the file is open.
195
201
  - **Coverage, and the lock file:**
196
202
  [`commands.coverage`](configuration.md#commandscoverage) and
197
203
  [`commands.relock`](configuration.md#commandsrelock).
198
- - **Four more slots for plug-ins:** your own refiner, prover, test
199
- reviewers, and conflict resolvers ([Plug-ins](plugins.md#the-slots)).
204
+ - **Four more roles for plugins:** your own refiner, prover, test
205
+ reviewers, and conflict resolvers ([Plugins](plugins.md#the-roles)).
200
206
  - **The default branch is read, not assumed.** A repository whose default
201
207
  branch is not `main` needs no setting: `factory sync` writes the
202
208
  branch's name where the workflows need it.
@@ -223,12 +229,14 @@ not match `package-lock.json`.
223
229
 
224
230
  ## When something goes wrong
225
231
 
226
- | What you see | What happened | What to do |
227
- | --------------------------------------------------------------------------- | --------------------------------------------------------------------- | -------------------------------------------------------------------------- |
228
- | CI fails with "the factory's files are out of sync" | A factory file was edited by hand, or settings changed without a sync | Run `factory sync` and commit the result |
229
- | `factory doctor` says your installed version is older than the repository's | You pulled an update and have not installed it | Run `npm ci` |
230
- | A command stops with `version: must be 2` | The update changed the shape of the settings file | [Move the file](#moving-to-settings-version-2) |
231
- | The update pull request conflicts with your default branch | Something else changed the same file | `factory-deps` resolves it on its next run, or close it and update by hand |
232
+ | What you see | What happened | What to do |
233
+ | ------------------------------------------------------------------------------------- | --------------------------------------------------------------------- | -------------------------------------------------------------------------- |
234
+ | CI fails with "the factory's files are out of sync" | A factory file was edited by hand, or settings changed without a sync | Run `factory sync` and commit the result |
235
+ | `factory doctor` says your installed version is older than the repository's | You pulled an update and have not installed it | Run `npm ci` |
236
+ | A command stops with `version: must be 2` | The update changed the shape of the settings file | [Move the file](#moving-to-settings-version-2) |
237
+ | A command stops with `.claude/factory.lock is from an earlier version of the factory` | The update's sync has not run on this checkout | Run `factory sync` and commit the result |
238
+ | A command stops with `.claude/factory.yaml changed since the last sync` | The settings changed without a sync | Run `factory sync` and commit the result |
239
+ | The update pull request conflicts with your default branch | Something else changed the same file | `factory-deps` resolves it on its next run, or close it and update by hand |
232
240
 
233
241
  ## Never edit a factory file
234
242
 
@@ -241,7 +249,7 @@ To change what the factory does:
241
249
  - **For your repository only:** say so in your own instructions for the
242
250
  agent, which win over the factory's rules, change a number under
243
251
  [`rules`](configuration.md#rules) in your settings, or put a skill or
244
- an agent of your own in a [plug-in slot](plugins.md).
252
+ an agent of your own in a [plugin role](plugins.md).
245
253
  - **For everyone:** change it in the factory, and it reaches you as an
246
254
  update.
247
255
 
package/docs/workflow.md CHANGED
@@ -9,7 +9,7 @@ each step, and what the factory will not do on its own.
9
9
  | ----------------- | -------------------------------------------------- | -------------------------------------------------- | ----------------------------------------------------------------------------- |
10
10
  | Write a ticket | You | Your ticket system | A ticket saying what, why, and when it is done |
11
11
  | Refine it | A session you start | Your machine, in your coding agent | The ticket rewritten into acceptance criteria, after you answer its decisions |
12
- | Approve it | **You** | A session, or your board | Tell a session to build it, or move its card to Ready |
12
+ | Approve it | **You** | A session, or your board | Run `/factory-build N` in a session, or move its card to Ready |
13
13
  | Build it | A session | Your machine, or the cloud when started from Ready | A tested change in a pull request that closes the ticket |
14
14
  | Review it | The automated review, if you set it up | Your CI | Comments and a verdict on the pull request |
15
15
  | Answer the review | The session that built it | Where it was built | Each comment fixed, or rejected with evidence |
@@ -29,11 +29,10 @@ default names.
29
29
 
30
30
  A state with no column of its own shows in the column of the nearest earlier
31
31
  state that has one, and a ticket is shown in the `ready` column only when it
32
- is approved. A board without a `ready` column approves a build by telling a
33
- session to build the ticket, or by running
34
- `factory build N`.
32
+ is approved. A board without a `ready` column approves a build by running
33
+ `/factory-build N` in a session, or by running `factory build N`.
35
34
 
36
- | State | Board column | It means |
35
+ | State | Board column | What it means |
37
36
  | -------- | ------------- | ----------------------------------------------------------------------------- |
38
37
  | backlog | Backlog | Nothing is happening |
39
38
  | refining | In refinement | A session is turning it into a spec, or the spec is written and waits for you |
@@ -50,13 +49,13 @@ backlog → refining → ready → building → review → done
50
49
 
51
50
  ## Who moves a ticket
52
51
 
53
- | Move | Who |
54
- | ------------------ | ---------------------------------------------------------------- |
55
- | backlog → refining | The session you ask to refine it |
56
- | refining → ready | **You**, by moving the card, or by telling a session to build it |
57
- | ready → building | The session that claims it |
58
- | building → review | Opening the pull request |
59
- | review → done | The merge, which closes the ticket |
52
+ | Move | Who |
53
+ | ------------------ | -------------------------------------------------------------------------- |
54
+ | backlog → refining | The session you run `/factory-refine N` in |
55
+ | refining → ready | **You**, by moving the card, or by running `/factory-build N` in a session |
56
+ | ready → building | The session that claims it |
57
+ | building → review | Opening the pull request |
58
+ | review → done | The merge, which closes the ticket |
60
59
 
61
60
  Approving a ticket is the only move a person has to make. A session moves
62
61
  the card to Ready only when you ask it to, as your own move.
@@ -74,7 +73,7 @@ These hold in every repository. They are not settings.
74
73
  - **The order does not change.** A repository cannot add a state or reorder
75
74
  them. A team that wants a security review between building and review adds
76
75
  a [reviewer](plugins.md#reviewer), not a column. A
77
- [plug-in](plugins.md#the-slots) can take over a step, such as refining a
76
+ [plugin](plugins.md#the-roles) can take over a step, such as refining a
78
77
  ticket or proving a test, where the step stands.
79
78
  - **One session holds a ticket at a time.** The claim is a comment on the
80
79
  ticket. A second session that tries is told who holds it and stops.
@@ -149,7 +148,7 @@ small fixes on one checklist cost you one approval and one pull request.
149
148
 
150
149
  **What becomes a line, and what gets its own ticket.**
151
150
 
152
- | The session noticed | It becomes |
151
+ | What the session noticed | What it becomes |
153
152
  | -------------------------------------------------------- | ----------------------------------------------------- |
154
153
  | Something small that breaks a rule your guides state | A line |
155
154
  | Something that needs your call before it can be fixed | A line that says "Needs a decision:" and the question |
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@davidbyoung/software-factory",
3
- "version": "0.1.4",
3
+ "version": "0.1.6",
4
4
  "description": "Refines, builds, and reviews tickets with Claude Code sessions, from a board to a merged pull request.",
5
5
  "license": "MIT",
6
6
  "repository": {
package/rules.md CHANGED
@@ -64,7 +64,7 @@ here rather than restate it.
64
64
  - For a visible change, a UI reviewer read pointed at the states the change
65
65
  touched, not every size and scheme, and told the change is small. The UI
66
66
  reviewer is `factory-ui-reviewer` where the repository lists it, and
67
- otherwise the repository's own, among its reviewer plug-ins
67
+ otherwise the repository's own, among its reviewer plugins
68
68
  (`npx --no-install factory plugins reviewer`).
69
69
  - The gate and CI stay. The pull request says it took this path.
70
70
 
@@ -15,6 +15,15 @@
15
15
  "pattern": "^[\\w.-]+/[\\w.-]+$",
16
16
  "description": "The repository's owner and name, as owner/name."
17
17
  },
18
+ "presets": {
19
+ "type": "array",
20
+ "uniqueItems": true,
21
+ "items": {
22
+ "type": "string",
23
+ "minLength": 1
24
+ },
25
+ "description": "The presets this repository follows, each an npm package, or a folder of one, holding a factory-preset.yaml. Later ones win over earlier ones, and this file wins over them all."
26
+ },
18
27
  "tickets": {
19
28
  "description": "Where tickets live and how their state is shown.",
20
29
  "anyOf": [
@@ -60,8 +69,8 @@
60
69
  "auto-merge": {
61
70
  "$ref": "#/definitions/auto-merge"
62
71
  },
63
- "ci-review": {
64
- "$ref": "#/definitions/ci-review"
72
+ "pr-review": {
73
+ "$ref": "#/definitions/pr-review"
65
74
  },
66
75
  "site": {
67
76
  "$ref": "#/definitions/site"
@@ -277,7 +286,7 @@
277
286
  },
278
287
  "plugins": {
279
288
  "type": "object",
280
- "description": "Your own skills and agents, grouped by the phase they work in. Every slot is optional.",
289
+ "description": "Your own skills and agents, grouped by the phase they work in. Every role is optional.",
281
290
  "additionalProperties": false,
282
291
  "properties": {
283
292
  "refine": {
@@ -296,7 +305,7 @@
296
305
  },
297
306
  "plugins.refine": {
298
307
  "type": "object",
299
- "description": "Plug-ins for refining a ticket.",
308
+ "description": "Plugins for refining a ticket.",
300
309
  "additionalProperties": false,
301
310
  "properties": {
302
311
  "refiner": {
@@ -309,7 +318,7 @@
309
318
  },
310
319
  "plugins.build": {
311
320
  "type": "object",
312
- "description": "Plug-ins for building a ticket.",
321
+ "description": "Plugins for building a ticket.",
313
322
  "additionalProperties": false,
314
323
  "properties": {
315
324
  "builders": {
@@ -330,7 +339,7 @@
330
339
  },
331
340
  "plugins.test": {
332
341
  "type": "object",
333
- "description": "Plug-ins for a change's tests.",
342
+ "description": "Plugins for a change's tests.",
334
343
  "additionalProperties": false,
335
344
  "properties": {
336
345
  "prover": {
@@ -347,7 +356,7 @@
347
356
  },
348
357
  "plugins.conflicts": {
349
358
  "type": "object",
350
- "description": "Plug-ins for a conflict with the default branch.",
359
+ "description": "Plugins for a conflict with the default branch.",
351
360
  "additionalProperties": false,
352
361
  "properties": {
353
362
  "resolvers": {
@@ -403,9 +412,21 @@
403
412
  "minLength": 1
404
413
  },
405
414
  "description": "It builds a ticket carrying one of these labels."
415
+ },
416
+ "off": {
417
+ "const": true,
418
+ "description": "Leaves out the plugin of this name that a preset adds. Only this file can."
406
419
  }
407
420
  },
408
- "required": ["skill", "labels"]
421
+ "required": ["skill"],
422
+ "anyOf": [
423
+ {
424
+ "required": ["labels"]
425
+ },
426
+ {
427
+ "required": ["off"]
428
+ }
429
+ ]
409
430
  },
410
431
  "plugins.build.reviewers[]": {
411
432
  "type": "object",
@@ -425,9 +446,21 @@
425
446
  "minLength": 1
426
447
  },
427
448
  "description": "It is considered when a change touches one of these."
449
+ },
450
+ "off": {
451
+ "const": true,
452
+ "description": "Leaves out the plugin of this name that a preset adds. Only this file can."
428
453
  }
429
454
  },
430
- "required": ["agent", "files"]
455
+ "required": ["agent"],
456
+ "anyOf": [
457
+ {
458
+ "required": ["files"]
459
+ },
460
+ {
461
+ "required": ["off"]
462
+ }
463
+ ]
431
464
  },
432
465
  "plugins.test.prover": {
433
466
  "type": "object",
@@ -460,6 +493,10 @@
460
493
  "minLength": 1
461
494
  },
462
495
  "description": "It is considered only when a change touches one of these. Left out, it is considered whenever a change touches tests."
496
+ },
497
+ "off": {
498
+ "const": true,
499
+ "description": "Leaves out the plugin of this name that a preset adds. Only this file can."
463
500
  }
464
501
  },
465
502
  "required": ["agent"]
@@ -482,9 +519,21 @@
482
519
  "minLength": 1
483
520
  },
484
521
  "description": "It resolves a conflict in one of these."
522
+ },
523
+ "off": {
524
+ "const": true,
525
+ "description": "Leaves out the plugin of this name that a preset adds. Only this file can."
485
526
  }
486
527
  },
487
- "required": ["skill", "files"]
528
+ "required": ["skill"],
529
+ "anyOf": [
530
+ {
531
+ "required": ["files"]
532
+ },
533
+ {
534
+ "required": ["off"]
535
+ }
536
+ ]
488
537
  },
489
538
  "auto-merge": {
490
539
  "type": "object",
@@ -517,7 +566,7 @@
517
566
  }
518
567
  }
519
568
  },
520
- "ci-review": {
569
+ "pr-review": {
521
570
  "type": ["object", "null"],
522
571
  "additionalProperties": false,
523
572
  "description": "The automated review of every pull request: on when this is written, even with nothing under it.",
@@ -274,7 +274,7 @@ change on its own.
274
274
 
275
275
  Read the `CLAUDE.md` for the area first ("Rules by area" in `CLAUDE.md`).
276
276
 
277
- **A builder plug-in:** list them with
277
+ **A builder plugin:** list them with
278
278
  `npx --no-install factory plugins builder`, which prints each one's
279
279
  labels. When the issue carries one of a builder's labels, invoke that skill
280
280
  with the Skill tool to build it, in place of the steps below up to the
@@ -8,9 +8,10 @@ description: Move every open Dependabot pull request one step closer to merged:
8
8
  A minor or patch bump already has auto-merge on, set by
9
9
  `factory-deps-auto-merge.yml`, so it merges by itself once its checks are
10
10
  green. The job here is to get it there. A major bump never has
11
- auto-merge, and neither does a bump of the factory itself, and this skill
12
- never turns it on or merges anything: the owner reads a major's migration,
13
- and every update of the factory, before it lands.
11
+ auto-merge, and neither does a bump of the factory itself or of a preset
12
+ the settings list, and this skill never turns it on or merges anything:
13
+ the owner reads a major's migration, and every update of the factory or a
14
+ preset, before it lands.
14
15
 
15
16
  Every command below goes through `factory deps`, `factory ticket`, or
16
17
  `factory pr`. The default branch's name is what
@@ -70,7 +71,8 @@ take the default branch's lock file, run `commands.relock`, the command
70
71
  `npx --no-install factory config get commands.relock` prints, so the bump
71
72
  is reapplied on top of it, and commit the merge. Any other conflicted file
72
73
  that matches the `files` of a resolver
73
- (`npx --no-install factory plugins resolver`) is that resolver's, as
74
+ (`npx --no-install factory plugins resolver`) is that resolver's, and a
75
+ conflict in `.claude/factory.lock` is resolved first, by `factory sync`, as
74
76
  "Merge" in the `factory-resolve-conflicts` skill says.
75
77
 
76
78
  Then go on: a branch with a conflict can be failing as well.
@@ -131,27 +133,36 @@ running after 20 minutes: leave the bump for the next run.
131
133
  If one still fails, try once more in the same run. A second failure is the
132
134
  end for this run: comment what was tried and leave it for the next one.
133
135
 
134
- ## 4. An update of the factory
136
+ ## 4. An update of the factory or a preset
135
137
 
136
- A pull request that bumps `@davidbyoung/software-factory` gets steps 2 and
137
- 3, and the files the new version writes. After `npm ci` on its branch:
138
+ A pull request that bumps `@davidbyoung/software-factory`, or the package
139
+ of a preset `.claude/factory.lock` lists, gets steps 2 and 3, and the files
140
+ the new version writes. `factory deps` says `sync (step 4)` for each. Run
141
+ the sync right after `npm ci` on its branch, before step 3's gate: until it
142
+ runs, every `factory` command stops on the stale lock and names it.
138
143
 
139
144
  ```bash
140
145
  npx --no-install factory sync
141
146
  ```
142
147
 
143
- When the sync, or any other `factory` command, fails on the settings after
144
- the update, the release changed the settings' shape, as version 2 does.
148
+ When the sync itself fails on the settings after the update, the release
149
+ changed the settings' shape, as version 2 does.
145
150
  Stop (step 6), and say the settings are the owner's to move, as "Moving to
146
151
  settings version 2" in the factory's `docs/updating.md` says for that
147
152
  release. Never edit `.claude/factory.yaml`.
148
153
 
149
154
  Commit what the sync wrote as a second commit, "Sync the factory's files to
150
- VERSION", and push. The push changes workflows, so it needs a token with
155
+ VERSION" or "Sync the settings to PACKAGE VERSION", and push. The push changes workflows, so it needs a token with
151
156
  the `workflow` scope, such as the build token; a refused push is a stop
152
157
  (step 6), with GitHub's error. Until then CI's `factory sync --check` fails, which is
153
- the sign the commit is missing. Then comment on the pull request with the
154
- files the sync changed and the release notes' steps to do by hand, first.
158
+ the sign the commit is missing. Then comment on the pull request: for the
159
+ factory, the files the sync changed and the release notes' steps to do by
160
+ hand, first; for a preset, what this prints, as it stands:
161
+
162
+ ```bash
163
+ npx --no-install factory preset changes origin/DEFAULT
164
+ ```
165
+
155
166
  Never enable auto-merge, never approve and never merge: it waits for the
156
167
  owner, whatever its size.
157
168
 
@@ -1,6 +1,6 @@
1
1
  ---
2
2
  name: factory-design
3
- description: Design a visible change to a website, a new page or a redesign, as the designer rather than asking the owner to be one: real-content mockups built from the site itself, pictured at its widths in light and dark, reviewed before anyone sees them, and one recommended design. Use when asked to redesign, restyle, or rethink how a page looks or what it says, when an issue asks for renderings to approve, and as the `mockups` plug-in `factory-refine` calls.
3
+ description: Design a visible change to a website, a new page or a redesign, as the designer rather than asking the owner to be one: real-content mockups built from the site itself, pictured at its widths in light and dark, reviewed before anyone sees them, and one recommended design. Use when asked to redesign, restyle, or rethink how a page looks or what it says, when an issue asks for renderings to approve, and as the `mockups` plugin `factory-refine` calls.
4
4
  ---
5
5
 
6
6
  # Designing a change
@@ -10,7 +10,7 @@ them a recommendation, not a menu. Each round the owner has to spend
10
10
  catching a defect or making a design call is a round this skill exists to
11
11
  remove.
12
12
 
13
- It works on any site whose `.claude/factory.yaml` has a `site` block:
13
+ It works on any site whose settings have a `site` block:
14
14
  `site.start` says how to build and serve it, and `factory site compare`
15
15
  pictures it.
16
16
 
@@ -72,12 +72,12 @@ marker", it runs steps 4 and 5 only and posts none of these.
72
72
 
73
73
  ## 0. Read
74
74
 
75
- **A refiner plug-in replaces this skill.** Before anything else, run
75
+ **A refiner plugin replaces this skill.** Before anything else, run
76
76
  `npx --no-install factory plugins refiner`. When it prints a skill other
77
77
  than `factory-refine`, invoke that skill with the Skill tool, with the
78
78
  same ticket and words this one was given, and stop: the repository
79
79
  refines its own way, and what that skill must leave behind is in the
80
- factory's plug-ins guide.
80
+ factory's plugins guide.
81
81
 
82
82
  Post the `refining` marker first ("Labels and markers"), then:
83
83
 
@@ -153,6 +153,12 @@ area" in `CLAUDE.md`).
153
153
  line on one side and a real change on the other is not a contradiction:
154
154
  apply both. In content, that includes sweeps such as the serial
155
155
  comma.
156
+ - **`.claude/factory.lock`, first:** it is never merged by hand. Resolve
157
+ `.claude/factory.yaml` and `.claude/factory.choices.yaml`, take either
158
+ side's lock, and run `npx --no-install factory sync`, which writes it
159
+ from them. Do it before anything else that runs `factory`: every command
160
+ but the sync reads its settings from the lock, and stops while it is
161
+ conflicted or stale.
156
162
  - **The lock file `commands.relock` regenerates:** resolve the manifest
157
163
  it is generated from first, then take the default branch's copy of the
158
164
  lock file and run `commands.relock`, the command
@@ -1,7 +1,7 @@
1
1
  # The review that reads every pull request once it is marked ready, and
2
2
  # every push after that, with the instructions in .github/factory-review.md.
3
3
  # The commands it may run beyond reading and commenting are the settings'
4
- # `ci-review.commands`, read from the pull request's base commit
4
+ # `pr-review.commands`, read from the pull request's base commit
5
5
  # (`factory review tools`). Its credential is CLAUDE_CODE_OAUTH_TOKEN, or
6
6
  # ANTHROPIC_API_KEY when that is the one set, and
7
7
  # FACTORY_BUILD_MODEL, a repository variable, chooses the model as it does
@@ -85,14 +85,19 @@ jobs:
85
85
  done
86
86
 
87
87
  # From the base commit too, so a change to the settings alone cannot
88
- # widen the commands its own review may run.
88
+ # widen the commands its own review may run. Its lock holds them, from
89
+ # a preset as well; a lock written before presets holds no settings,
90
+ # and then the base commit's settings file does.
89
91
  - name: List the tools the review may use
90
92
  id: tools
91
93
  env:
92
94
  BASE: ${{ github.event.pull_request.base.sha }}
93
95
  FACTORY_SETTINGS: ${{ runner.temp }}/factory.yaml
94
96
  run: |
95
- if git cat-file -e "$BASE:.claude/factory.yaml" 2>/dev/null; then
97
+ if git show "$BASE:.claude/factory.lock" > "$RUNNER_TEMP/factory.lock" 2>/dev/null &&
98
+ grep -q '^settings:' "$RUNNER_TEMP/factory.lock"; then
99
+ export FACTORY_LOCK="$RUNNER_TEMP/factory.lock"
100
+ elif git cat-file -e "$BASE:.claude/factory.yaml" 2>/dev/null; then
96
101
  git show "$BASE:.claude/factory.yaml" > "$FACTORY_SETTINGS"
97
102
  else
98
103
  cp .claude/factory.yaml "$FACTORY_SETTINGS"