@davidbyoung/software-factory 0.1.5 → 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 (43) hide show
  1. package/README.md +9 -8
  2. package/dist/cli.mjs +12 -0
  3. package/dist/config.d.mts +57 -3
  4. package/dist/config.mjs +268 -18
  5. package/dist/deps.d.mts +6 -4
  6. package/dist/deps.mjs +29 -7
  7. package/dist/doctor.d.mts +3 -0
  8. package/dist/doctor.mjs +7 -4
  9. package/dist/explain.d.mts +12 -1
  10. package/dist/explain.mjs +47 -32
  11. package/dist/init.mjs +6 -4
  12. package/dist/lib/default-branch.d.mts +1 -1
  13. package/dist/lib/default-branch.mjs +2 -2
  14. package/dist/preset-commands.d.mts +65 -0
  15. package/dist/preset-commands.mjs +1148 -0
  16. package/dist/preset.d.mts +169 -0
  17. package/dist/preset.mjs +550 -0
  18. package/dist/remove.mjs +34 -1
  19. package/dist/session-start.d.mts +3 -0
  20. package/dist/session-start.mjs +12 -1
  21. package/dist/sync.d.mts +42 -7
  22. package/dist/sync.mjs +165 -31
  23. package/docs/builds.md +12 -11
  24. package/docs/cli.md +21 -2
  25. package/docs/configuration.md +65 -13
  26. package/docs/developing.md +9 -2
  27. package/docs/github/by-hand.md +5 -5
  28. package/docs/github/reference.md +2 -17
  29. package/docs/github/setup.md +1 -1
  30. package/docs/glossary.md +12 -2
  31. package/docs/limitations.md +3 -0
  32. package/docs/plugins.md +16 -5
  33. package/docs/presets.md +410 -0
  34. package/docs/quick-start.md +20 -17
  35. package/docs/skills.md +21 -16
  36. package/docs/updating.md +14 -7
  37. package/docs/workflow.md +12 -13
  38. package/package.json +1 -1
  39. package/settings.schema.json +52 -3
  40. package/skills/factory-deps/SKILL.md +23 -12
  41. package/skills/factory-design/SKILL.md +1 -1
  42. package/skills/factory-resolve-conflicts/SKILL.md +6 -0
  43. package/workflows/factory-claude-review.yml +7 -2
@@ -42,7 +42,7 @@ machine, which is all the [quick start](../quick-start.md) needs.
42
42
 
43
43
  It then asks only what your parts need:
44
44
 
45
- | It asks | For | What you do |
45
+ | Question | Asked when you chose | What you do |
46
46
  | ------------------------------------- | --------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------- |
47
47
  | Which board | A board | Choose a new one, made with the factory's columns, or a Project you already have |
48
48
  | Which files may merge without you | Pull requests that merge themselves | Type their patterns, such as `docs/**`. Start with a short list |
package/docs/glossary.md CHANGED
@@ -78,6 +78,11 @@ commits.
78
78
 
79
79
  **Local session.** A session on your own machine.
80
80
 
81
+ **Lock.** The file `.claude/factory.lock`, which `factory sync` writes:
82
+ the factory's version, the presets, every setting in effect, and the files
83
+ it copied. Every command reads its settings from it. You commit it and
84
+ never edit it.
85
+
81
86
  **Marker.** A hidden line in a comment the factory posts on a ticket,
82
87
  recording what happened. The board is worked out from these.
83
88
 
@@ -90,6 +95,11 @@ does, in the repository. Optional.
90
95
  build for each ticket moved to Ready, on a server you host or on a
91
96
  schedule in the cloud.
92
97
 
98
+ **Preset.** An npm package of settings, and of any agents and skills they
99
+ name, that several repositories share. A repository lists it under
100
+ [`presets`](configuration.md#presets), and `factory sync` combines it with
101
+ the repository's own settings. [Presets](presets.md) says how.
102
+
93
103
  **Refine.** To turn a ticket into acceptance criteria, settling the
94
104
  decisions with you along the way.
95
105
 
@@ -105,8 +115,8 @@ that refines a ticket in place of the factory's own. There are seven.
105
115
  your machine or in the cloud.
106
116
 
107
117
  **Skill.** A set of instructions a session follows, named `factory-...`
108
- for the factory's own. You call one by asking a session in plain words,
109
- such as "refine ticket 12".
118
+ for the factory's own. You call one by typing its name as a slash command,
119
+ such as `/factory-refine 12`.
110
120
 
111
121
  **Spec.** A written statement of what a change must do. For most tickets
112
122
  that is the acceptance criteria. With OpenSpec turned on, a change your
@@ -48,6 +48,9 @@ as a code host's billing or what its workflows can see, are in
48
48
  then guards the old branch and not the new one. After the rename, run
49
49
  that command in each checkout, then `factory sync`, which writes the
50
50
  name into two workflows.
51
+ - **A private [preset](presets.md) works on your machine, not yet in the
52
+ factory's workflows.** _[Planned](developing.md#what-is-built)_: the
53
+ workflows can't install a private package yet.
51
54
  - **One lock file is rebuilt for you after a conflict,** the one
52
55
  [`commands.relock`](configuration.md#commandsrelock) rebuilds, npm's by
53
56
  default. A second, such as another package manager's beside the
package/docs/plugins.md CHANGED
@@ -35,7 +35,7 @@ A role is a job in the work that your own skill or agent can take on, such
35
35
  as reviewing a change or refining a ticket. There are
36
36
  seven, grouped under [`plugins`](configuration.md#plugins) by the phase
37
37
  each belongs to. Every role is optional, and leaving one out never turns a
38
- step off: the last column says what does the work then.
38
+ step off: the last column says what does the work when you have none.
39
39
 
40
40
  A role has two names. The settings key, in the second column, is what you
41
41
  write in `.claude/factory.yaml`. The role's own name, in the first column,
@@ -44,7 +44,7 @@ is the role you write as
44
44
  [`plugins.build.builders`](configuration.md#pluginsbuild), and no key is
45
45
  called `builder`.
46
46
 
47
- | Role | Settings key | It | Left out |
47
+ | Role | Settings key | What it does | Without one |
48
48
  | --------------- | ------------------------------------------------------------------ | ---------------------------------------------- | ----------------------------------------- |
49
49
  | `refiner` | [`plugins.refine.refiner`](configuration.md#pluginsrefine) | Refines a ticket, in place of `factory-refine` | `factory-refine` |
50
50
  | `mockups` | [`plugins.refine.mockups`](configuration.md#pluginsrefine) | Makes pictures for a decision about the look | `factory-design` on a website, else words |
@@ -76,7 +76,7 @@ plugins:
76
76
 
77
77
  | Step | What happens |
78
78
  | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
79
- | **Called** | When you ask a session to refine a ticket: `factory-refine` hands over to it before doing anything. By `factory-build`, on a ticket that has no criteria yet, or one you approved while its questions waited |
79
+ | **Called** | When you run `/factory-refine N` in a session: `factory-refine` hands over to it before doing anything. By `factory-build`, on a ticket that has no criteria yet, or one you approved while its questions waited |
80
80
  | **Handed** | The ticket's number. From `factory-build`, for a round of questions you approved while it waited on your answers, also the words "approved while waiting: fold the owner's replies into the body, post no marker". They tell the refiner to write your replies into the ticket's body and to post no [marker](glossary.md), the hidden comment line the board reads |
81
81
  | **Returns** | A ticket a build can start from: everything in the list below |
82
82
  | **Then** | The ticket waits for your approval, and the build reads what the refiner left |
@@ -393,7 +393,9 @@ instructions for the agent and in the agent itself. The factory holds none of th
393
393
  `files` or `labels` where the role takes them.
394
394
  4. Run `factory config check`. It fails, naming the role, if the file is
395
395
  missing, or the role takes a skill and you named an agent.
396
- 5. Run `factory plugins` to see the list the factory will use, the
396
+ 5. Run `factory sync`. Every command reads your settings from
397
+ `.claude/factory.lock`, which the sync writes.
398
+ 6. Run `factory plugins` to see the list the factory will use, the
397
399
  built-in ones included:
398
400
 
399
401
  ```text
@@ -405,7 +407,16 @@ instructions for the agent and in the agent itself. The factory holds none of th
405
407
 
406
408
  **It worked when** your plugin is in that list, in its role.
407
409
 
408
- No sync is needed. Plugins are read from your settings each time.
410
+ ## Plugins from a preset
411
+
412
+ A [preset](presets.md) your repository follows can add plugins too, and
413
+ ship their agents and skills, which `factory sync` copies into
414
+ `.claude/agents/` and `.claude/skills/`. They are in the list
415
+ `factory plugins` prints, beside your own. To leave one out, name it in
416
+ your own settings with `off: true`, as
417
+ [`plugins`](configuration.md#plugins) shows, then run `factory sync`.
418
+
419
+ **It worked when** `factory plugins` no longer lists it.
409
420
 
410
421
  ## What is not a plugin
411
422
 
@@ -0,0 +1,410 @@
1
+ # Presets
2
+
3
+ This page is for a team that sets the factory up the same way in several
4
+ repositories. A preset is an npm package that holds the settings those
5
+ repositories share, along with any reviewers of your own that the
6
+ settings name.
7
+
8
+ It has two readers:
9
+
10
+ - **If you look after a repository,** [Using a preset](#using-a-preset)
11
+ ends with your repository following the shared settings, and a pull
12
+ request whenever they change.
13
+ - **If you maintain the shared settings,** [Writing a preset](#writing-a-preset)
14
+ ends with a published preset that every repository can add.
15
+
16
+ ## The idea
17
+
18
+ Without a preset, every repository's
19
+ [`.claude/factory.yaml`](configuration.md) repeats the same lines, such as
20
+ the board's number in [`tickets.board`](configuration.md#tickets), the
21
+ size limit in [`rules.small-change-lines`](configuration.md#rules), and
22
+ the same [reviewer plugins](plugins.md#reviewer), your own agents that
23
+ read every change. Changing one of them means a pull request in every
24
+ repository, and nothing shows which ones have fallen behind.
25
+
26
+ With a preset, a repository names it under
27
+ [`presets`](configuration.md#presets) and keeps only what is its own:
28
+
29
+ ```yaml
30
+ version: 2
31
+ repository: acme/billing
32
+ presets:
33
+ - "@acme/factory-preset" # what every Acme repository shares
34
+ - "@acme/factory-preset/node" # extra settings for Acme's Node repositories
35
+ commands:
36
+ gate:
37
+ - npm run check # this repository's own
38
+ ```
39
+
40
+ A name that starts with `@` must be quoted in YAML. Those are
41
+ [scoped npm packages](https://docs.npmjs.com/about-scopes), which is how
42
+ most companies publish their own, but any package name works.
43
+
44
+ `factory sync`, the command that writes the factory's files into your
45
+ repository, combines the factory's defaults, each preset in the order
46
+ listed, and your own settings. It writes the result into
47
+ `.claude/factory.lock`, which you commit and never edit. Every command
48
+ reads its settings from the lock, so it has to be up to date: after you
49
+ change a setting, a command stops until you sync, and tells you so:
50
+
51
+ ```text
52
+ .claude/factory.yaml changed since the last sync. Run: npx --no-install factory sync
53
+ ```
54
+
55
+ ## Using a preset
56
+
57
+ ### Adding a preset
58
+
59
+ You need the factory already set up in the repository, which it is when
60
+ `.claude/factory.yaml` exists ([Quick start](quick-start.md)). A preset on
61
+ the public npm registry needs nothing else. For a private one, see
62
+ [Private presets](#private-presets).
63
+
64
+ In this example the repository already uses `@acme/factory-preset` and
65
+ adds the Node one. Run:
66
+
67
+ ```bash
68
+ factory preset add @acme/factory-preset/node
69
+ ```
70
+
71
+ Before it changes anything, it shows what the preset would change in this
72
+ repository:
73
+
74
+ ```text
75
+ @acme/factory-preset/node 1.4.0 would change these settings here:
76
+
77
+ added
78
+ plugins.build.reviewers + node-deps-reviewer
79
+ pr-review.commands + npm audit
80
+ replaces the default
81
+ rules.review-rounds 2 → 3
82
+ disagrees with @acme/factory-preset
83
+ rules.small-change-lines @acme/factory-preset: 40 this preset: 30
84
+ replaced by your .claude/factory.yaml
85
+ commands.gate yours: npm run check this preset's: npm test
86
+
87
+ writes .claude/agents/node-deps-reviewer.md
88
+
89
+ Choose:
90
+ rules.small-change-lines: 30 from this preset, or 40 from @acme/factory-preset? [30/40]
91
+ commands.gate: keep yours, or drop it and use this preset's? [keep/drop]
92
+
93
+ Apply? [y/N]
94
+ ```
95
+
96
+ The summary groups each change by what happens to it:
97
+
98
+ - **Added** is a plugin or a value the preset adds to a list. It needs no
99
+ answer.
100
+ - **Replaces the default** is a setting nothing else sets. The preset's
101
+ value applies, with no answer needed.
102
+ - **Disagrees with** is a setting another of your presets sets
103
+ differently. You choose which one this repository follows, and
104
+ [Your choices](#your-choices) says how that answer is kept.
105
+ - **Replaced by your `.claude/factory.yaml`** is a setting your own file
106
+ sets. Answering `keep` changes nothing. Answering `drop` deletes that
107
+ line from your `factory.yaml`, so the preset's value applies.
108
+
109
+ Answering `N` at `Apply?` leaves everything as it was.
110
+
111
+ The questions appear only when you run the command in a terminal. A
112
+ [session](glossary.md) or a CI job gets the summary and nothing changes,
113
+ unless it adds `--yes`. With `--yes` nothing is asked: where presets
114
+ disagree the later one in your list applies, and your own settings always
115
+ stay. To see the summary without changing anything, add `--dry-run`.
116
+
117
+ **It worked when**
118
+ [`factory config explain`](cli.md), which prints every
119
+ setting in effect, shows the preset's values marked with its name:
120
+
121
+ ```yaml
122
+ rules:
123
+ small-change-lines: 30 # @acme/factory-preset/node, chosen over @acme/factory-preset
124
+ review-rounds: 3 # @acme/factory-preset/node
125
+ ```
126
+
127
+ Commit what the command changed: `package.json`, `package-lock.json`,
128
+ `.claude/factory.yaml`, `.claude/factory.lock`,
129
+ `.claude/factory.choices.yaml` if you made a choice, and the agents and
130
+ skills the summary listed under "writes".
131
+
132
+ ### Your choices
133
+
134
+ Each answer you give where two presets disagree is kept in
135
+ `.claude/factory.choices.yaml`. The `preset` commands create and write it,
136
+ so you commit it but don't edit it by hand. Each line is a setting, or a
137
+ file two presets both ship, and the preset this repository follows for it:
138
+
139
+ ```yaml
140
+ rules.small-change-lines: "@acme/factory-preset/node"
141
+ .claude/agents/security-reviewer.md: "@acme/factory-preset"
142
+ ```
143
+
144
+ A choice names the preset, not its value. When
145
+ `@acme/factory-preset/node` later changes 30 to 25, the repository gets 25
146
+ and you aren't asked again. You're asked only when something about the
147
+ choice itself changes:
148
+
149
+ | What happens | What you see |
150
+ | ------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------- |
151
+ | You add a preset | A question for each setting it disagrees with another preset on |
152
+ | You remove a preset | A question for each setting that would go back to a preset you chose against |
153
+ | A preset update makes two presets disagree for the first time | A line in [the update's pull request](#when-a-preset-changes). The later preset applies until you choose |
154
+ | The preset you chose stops setting a value | A line in the update's pull request saying which value applies now |
155
+ | A preset you chose against changes its value | Nothing, since your choice stands |
156
+
157
+ To see every choice and change any of them, run:
158
+
159
+ ```bash
160
+ factory preset choices
161
+ ```
162
+
163
+ It lists each setting two presets disagree on, what each preset would set,
164
+ and which applies now, then asks which to follow. Outside a terminal it
165
+ prints the list without asking. To record one choice without questions,
166
+ from a session or a script:
167
+
168
+ ```bash
169
+ factory preset choose rules.review-rounds @acme/factory-preset/node
170
+ ```
171
+
172
+ **It worked when** `factory config explain` marks the setting
173
+ `chosen over` the other preset.
174
+
175
+ ### When a preset changes
176
+
177
+ A new version of a preset reaches each repository the way a new version
178
+ of the factory does ([Updating](updating.md#what-happens)):
179
+
180
+ 1. Your [dependency bot](glossary.md), such as Dependabot, opens a pull
181
+ request for the new version.
182
+ 2. `factory-deps`, the factory's job for those pull requests, runs
183
+ `factory sync` on it and comments what changed in this repository:
184
+
185
+ ```text
186
+ @acme/factory-preset 1.4.0 → 1.5.0
187
+
188
+ Changes here:
189
+ - plugins.build.reviewers: + acme-a11y-reviewer,
190
+ which wrote .claude/agents/acme-a11y-reviewer.md
191
+
192
+ Needs a choice:
193
+ - rules.review-rounds: @acme/factory-preset now sets 2, and
194
+ @acme/factory-preset/node sets 3. 3 applies, from the later
195
+ preset, until you choose.
196
+
197
+ Doesn't apply here:
198
+ - rules.small-change-lines: 40 → 35, but you chose
199
+ @acme/factory-preset/node's 30
200
+ - commands.gate, which your .claude/factory.yaml sets
201
+ ```
202
+
203
+ 3. Anything under "Needs a choice" is safe to merge as it stands: the
204
+ value it names is the one in effect. To choose differently, check out
205
+ the pull request's branch, run `factory preset choices`,
206
+ and push the `.claude/factory.choices.yaml` and `.claude/factory.lock`
207
+ it wrote.
208
+ 4. Read the pull request and merge it. A preset update never merges
209
+ itself, whatever your [`auto-merge`](configuration.md#auto-merge)
210
+ settings allow.
211
+
212
+ The diff of `.claude/factory.lock` in that pull request is the whole
213
+ change to this repository, setting by setting. Without a dependency bot,
214
+ update as [Updating](updating.md#without-dependabot) describes for the
215
+ factory, then run `factory sync`.
216
+
217
+ ### Removing a preset
218
+
219
+ ```bash
220
+ factory preset remove @acme/factory-preset/node
221
+ ```
222
+
223
+ It shows a summary first, as `preset add` does, and asks about any
224
+ setting that would go back to the value of a preset you chose against:
225
+
226
+ ```text
227
+ Removing @acme/factory-preset/node would change these settings here:
228
+
229
+ removed
230
+ plugins.build.reviewers − node-deps-reviewer
231
+ back to the default
232
+ rules.review-rounds 3 → 2
233
+ back to a value you chose against
234
+ rules.small-change-lines 30 → 40, from @acme/factory-preset
235
+
236
+ deletes .claude/agents/node-deps-reviewer.md
237
+
238
+ Choose:
239
+ rules.small-change-lines: use 40 from @acme/factory-preset, or keep 30 in your .claude/factory.yaml? [40/30]
240
+
241
+ Apply? [y/N]
242
+ ```
243
+
244
+ Keeping 30 writes `small-change-lines: 30` into your `factory.yaml`, since
245
+ no preset provides it anymore. Then the command uninstalls the package,
246
+ takes it out of `presets`, deletes the agents and skills the preset
247
+ shipped, and syncs. A file your repository wrote itself is never deleted.
248
+
249
+ **It worked when** `factory config explain` no longer names the preset.
250
+
251
+ ### How presets combine
252
+
253
+ The factory's defaults come first, then each preset in the order
254
+ `presets` lists them, then your own `factory.yaml`. When more than one of
255
+ them sets the same thing, what applies depends on its kind:
256
+
257
+ | Kind of setting | Examples | What applies when more than one sets it |
258
+ | ----------------------------------------- | ---------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
259
+ | A single value | [`rules.small-change-lines`](configuration.md#rules) | The later preset's value, unless you [chose](#your-choices) another. Your own `factory.yaml` wins over every preset |
260
+ | A list of commands run in order | [`commands.gate`](configuration.md#commandsgate) | One whole list, the same way as a single value, since running two lists would run steps twice |
261
+ | A list of plugins | [`plugins.build.reviewers`](configuration.md#pluginsbuild) | Every plugin from every list. A plugin named in two lists is treated as a single value |
262
+ | A list of values | [`pr-review.commands`](configuration.md#pr-review), [`auto-merge.deny`](configuration.md#auto-merge) | Every value from every list, each once |
263
+ | A setting that names its tool with `type` | [`tickets`](configuration.md#tickets), [`specs`](configuration.md#specs) | The whole setting from one place, when two places name different tools, so a Jira setup never inherits a GitHub board number |
264
+ | An agent or skill file a preset ships | `.claude/agents/security-reviewer.md` | The later preset's file, unless you chose another. A file your repository wrote itself always stays |
265
+
266
+ To leave out one plugin a preset adds, name it in your own
267
+ `factory.yaml` with `off: true`:
268
+
269
+ ```yaml
270
+ plugins:
271
+ build:
272
+ reviewers:
273
+ - agent: acme-security-reviewer
274
+ off: true
275
+ ```
276
+
277
+ **It worked when** [`factory plugins`](plugins.md) no
278
+ longer lists it.
279
+
280
+ A value a preset adds to a list of values, such as a command in
281
+ `pr-review.commands`, can't be left out by one repository. Ask whoever
282
+ maintains the preset.
283
+
284
+ ## Writing a preset
285
+
286
+ ### Making the package
287
+
288
+ 1. **Create an npm package** as you would any other, with `npm init`. If
289
+ its `package.json` has a `files` list, include `factory-preset.yaml`,
290
+ `agents/`, `skills/`, and any subfolder presets in it, or npm leaves
291
+ them out of what it publishes.
292
+ 2. **Write `factory-preset.yaml` at the package's root.** It takes the
293
+ same settings as `.claude/factory.yaml` ([Configuration](configuration.md#every-setting)),
294
+ so a line moves between the two unchanged:
295
+
296
+ ```yaml
297
+ version: 2 # the settings version, as in .claude/factory.yaml
298
+ tickets:
299
+ type: github
300
+ board: 7
301
+ rules:
302
+ small-change-lines: 40
303
+ plugins:
304
+ build:
305
+ reviewers:
306
+ - agent: acme-security-reviewer
307
+ files:
308
+ - src/**
309
+ ```
310
+
311
+ 3. **Add the agents and skills its settings name** in `agents/` and
312
+ `skills/`, beside `factory-preset.yaml`, written the way your coding
313
+ agent expects them ([Plugins](plugins.md)). `factory sync` copies them
314
+ into each repository that uses the preset.
315
+ 4. **For a second preset in the same package,** such as one for Node
316
+ repositories, add a folder with its own `factory-preset.yaml`, and its
317
+ own `agents/` and `skills/` if it needs them. Its name is the package's
318
+ name and the folder's, `@acme/factory-preset/node`:
319
+
320
+ ```text
321
+ acme-factory-preset/
322
+ ├── package.json # "name": "@acme/factory-preset"
323
+ ├── factory-preset.yaml # the preset @acme/factory-preset
324
+ ├── agents/
325
+ │ └── acme-security-reviewer.md
326
+ ├── skills/
327
+ │ └── acme-refine/SKILL.md
328
+ └── node/
329
+ └── factory-preset.yaml # the preset @acme/factory-preset/node
330
+ ```
331
+
332
+ 5. **Say which versions of the factory it works with,** in `package.json`,
333
+ so npm warns a repository that has another. Start from the version you
334
+ tested with, which `npm ls @davidbyoung/software-factory` prints:
335
+
336
+ ```json
337
+ "peerDependencies": {
338
+ "@davidbyoung/software-factory": "^0.5.0"
339
+ }
340
+ ```
341
+
342
+ ### What a preset can't set
343
+
344
+ Three settings belong to each repository:
345
+ [`repository`](configuration.md#repository), and
346
+ [`auto-merge.allow` and `auto-merge.commands`](configuration.md#auto-merge).
347
+ Each one decides who a session takes instructions from or what merges
348
+ without a person. If a preset could set `auto-merge.allow`, one update
349
+ could let changes merge themselves in every repository at once.
350
+
351
+ A preset also can't name another preset. Each repository lists every
352
+ preset it uses, so the order is in one place.
353
+
354
+ ### Checking and publishing
355
+
356
+ In the package's folder, run:
357
+
358
+ ```bash
359
+ factory preset check
360
+ ```
361
+
362
+ It prints each preset it found and what it ships, so you can see a
363
+ subfolder preset was picked up:
364
+
365
+ ```text
366
+ @acme/factory-preset 1 agent, 1 skill
367
+ @acme/factory-preset/node no agents or skills
368
+ ```
369
+
370
+ **It worked when** it lists every preset and nothing else. A problem gets
371
+ a line saying what to change, and the command fails:
372
+
373
+ ```text
374
+ node/factory-preset.yaml: auto-merge.allow: a preset can't set this. Remove it, and set it in each repository that wants it
375
+ ```
376
+
377
+ A plugin that names an agent or a skill the package doesn't ship gets a
378
+ note, not a failure, since a repository that uses the preset can provide
379
+ it:
380
+
381
+ ```text
382
+ factory-preset.yaml: plugins.build.reviewers: acme-docs-reader: not shipped here, so each repository that uses this preset must provide it
383
+ ```
384
+
385
+ Then publish it with `npm publish`, to the public npm registry or to
386
+ your company's private one. Each repository that uses
387
+ it gets a pull request at its dependency bot's next run, as
388
+ [When a preset changes](#when-a-preset-changes) describes.
389
+
390
+ ## Private presets
391
+
392
+ A preset is an npm package, so a private one installs on your machine the
393
+ way any other private package does, from whichever registry your company
394
+ uses, through your repository's `.npmrc`. Give the preset a Dependabot
395
+ group of its own, the way
396
+ [Dependency bots](github/reference.md#dependency-bots) does for the
397
+ factory, and add its registry under `registries` in
398
+ `.github/dependabot.yml`, so Dependabot sees its new versions.
399
+ `factory preset add` names either one that's missing.
400
+
401
+ _[Planned](developing.md#what-is-built)_: the factory's workflows can't
402
+ install a private package yet, so a private preset works on your machine
403
+ and not yet in the factory's workflows.
404
+
405
+ **It worked when** `factory doctor` shows:
406
+
407
+ ```text
408
+ ✓ @acme/factory-preset 1.4.0 is installed, as the lock records
409
+ ✓ @acme/factory-preset has a Dependabot group of its own
410
+ ```
@@ -103,7 +103,7 @@ git pull
103
103
  Start a new session of your coding agent, which loads the factory from the
104
104
  files now in your repository.
105
105
 
106
- **It worked when** the new session, asked which skills it has, lists
106
+ **It worked when** typing `/factory` in the new session lists
107
107
  `factory-refine` and `factory-build`.
108
108
 
109
109
  ## 4. Open a ticket
@@ -123,12 +123,15 @@ Done when: every page's footer shows the same hours the contact page does.
123
123
 
124
124
  ## 5. Refine it
125
125
 
126
- In the session, say:
126
+ In the session, type:
127
127
 
128
128
  ```text
129
- refine ticket 12
129
+ /factory-refine 12
130
130
  ```
131
131
 
132
+ That runs the `factory-refine` skill on ticket 12.
133
+ [Skills](skills.md#at-a-glance) lists the other commands.
134
+
132
135
  The session reads the ticket and the code it touches, then asks you the
133
136
  decisions that are yours, each as a choice with its recommendation first:
134
137
 
@@ -146,10 +149,10 @@ of exactly what "done" means, and the session says it is ready to build.
146
149
  In the same session, or a new one:
147
150
 
148
151
  ```text
149
- build ticket 12
152
+ /factory-build 12
150
153
  ```
151
154
 
152
- Telling a session to build a ticket is how you approve it. The session
155
+ Running `factory-build` on a ticket is how you approve it. The session
153
156
  makes a branch, writes a test and then the change, and opens a pull
154
157
  request that closes the ticket. Expect minutes, not seconds.
155
158
  [Workflow](workflow.md#from-a-ticket-to-a-merge) has each step.
@@ -164,11 +167,11 @@ Open the pull request. Its description says what changed, how it was
164
167
  verified, and anything the session noticed and left alone. Nothing merges
165
168
  without you.
166
169
 
167
- To ask for changes, comment on the pull request, then tell a session to
170
+ To ask for changes, comment on the pull request, then have a session
168
171
  answer your comments:
169
172
 
170
173
  ```text
171
- address the review on pull request 15
174
+ /factory-address-review 15
172
175
  ```
173
176
 
174
177
  **It worked when** the pull request is merged and ticket 12 is closed.
@@ -176,16 +179,16 @@ That is the whole loop: **ticket, refine, build, read, merge.**
176
179
 
177
180
  ## If something goes wrong
178
181
 
179
- | What happened | What to do |
180
- | ---------------------------------------------- | ------------------------------------------------------------------------------------------- |
181
- | A test or a check fails during the build | Nothing. The session sees the output, fixes the cause, and tries again |
182
- | The session stops and says it needs you | It says why, in the session and on the ticket. Answer, then ask it to build ticket 12 again |
183
- | The build stops on `commands.gate is not set` | Add your test and lint commands, as in step 2, then ask it to build ticket 12 again |
184
- | The session was closed or crashed partway | Ask a new session to build ticket 12. It picks up the branch it made |
185
- | You want to change what was decided | Ask a session to refine ticket 12 again, or edit the ticket |
186
- | CI fails on the pull request | Ask a session to address the review on pull request 15. It reads the failure and fixes it |
187
- | The session does not know the factory's skills | The setup is not merged, or the session started before it was. See step 3 |
188
- | Anything else | Run `factory doctor`. It says what is wrong, and what to do about it |
182
+ | What happened | What to do |
183
+ | ---------------------------------------------- | ----------------------------------------------------------------------------------------- |
184
+ | A test or a check fails during the build | Nothing. The session sees the output, fixes the cause, and tries again |
185
+ | The session stops and says it needs you | It says why, in the session and on the ticket. Answer, then run `/factory-build 12` again |
186
+ | The build stops on `commands.gate is not set` | Add your test and lint commands, as in step 2, then run `/factory-build 12` again |
187
+ | The session was closed or crashed partway | Run `/factory-build 12` in a new session. It picks up the branch it made |
188
+ | You want to change what was decided | Run `/factory-refine 12` again, or edit the ticket |
189
+ | CI fails on the pull request | Run `/factory-address-review 15`. It reads the failure and fixes it |
190
+ | The session does not know the factory's skills | The setup is not merged, or the session started before it was. See step 3 |
191
+ | Anything else | Run `factory doctor`. It says what is wrong, and what to do about it |
189
192
 
190
193
  ## What to add next
191
194