@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
@@ -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
 
@@ -203,5 +206,5 @@ optional, stands alone, and can come later.
203
206
  [`commands.before-commit`](configuration.md#commandsbefore-commit).
204
207
  - **Your own reviewers,** so a change to your content or your design is
205
208
  read by an expert agent: a few lines under
206
- [`plugins`](configuration.md#plugins), which [Plug-ins](plugins.md)
209
+ [`plugins`](configuration.md#plugins), which [Plugins](plugins.md)
207
210
  walks through.
package/docs/removing.md CHANGED
@@ -28,7 +28,7 @@ hook, label, and setting.
28
28
  ## What it never touches
29
29
 
30
30
  Your code, your tickets, and your pull requests. Your own skills, agents,
31
- plug-ins, and CI workflows, which the factory never writes to.
31
+ plugins, and CI workflows, which the factory never writes to.
32
32
 
33
33
  One file belongs to you, and removing the factory leaves it: the review
34
34
  notes you write for the automated review. The review's workflow is the
package/docs/skills.md CHANGED
@@ -5,10 +5,12 @@ it. An agent, in this page's sense, is a separate reviewer a session
5
5
  launches, which reads and reports and changes nothing. This page covers
6
6
  every skill and agent the factory brings.
7
7
 
8
- You call a skill by asking a session in plain words, such as "refine ticket
9
- 12". Your coding agent may also have a shorter way to call one by name; on
10
- Claude Code it is a slash command, as
11
- [the reference](github/reference.md#skills-in-claude-code) shows.
8
+ You call a skill by typing its name as a slash command in a session, with
9
+ the ticket or pull request number after it: `/factory-refine 12`. Slash
10
+ commands are how Claude Code, the one coding agent the factory supports
11
+ today, calls a skill. Asking in
12
+ plain words, such as "refine ticket 12", usually calls the same skill, but
13
+ the session decides which one fits, so the command is the sure way.
12
14
 
13
15
  ## Which ones a repository gets
14
16
 
@@ -39,22 +41,25 @@ commands such as `factory gate` and `factory test-one`
39
41
  `factory default-branch` for your default branch's name.
40
42
 
41
43
  Where a step below names a built-in skill or agent, a
42
- [plug-in](plugins.md#the-slots) of yours can stand in for it: your own
44
+ [plugin](plugins.md#the-roles) of yours can stand in for it: your own
43
45
  refiner, builder, prover, test reviewers, and conflict resolvers.
44
46
 
45
47
  ## At a glance
46
48
 
47
- | Ask a session | Skill | It does |
48
- | ---------------------------------- | --------------------------- | ------------------------------------------------------------------------ |
49
- | "refine ticket 12" | `factory-refine` | Turns a ticket into a spec a builder can start from |
50
- | "build ticket 12" | `factory-build` | Builds a ticket to a reviewed pull request |
51
- | "address the review on 280" | `factory-address-review` | Works a pull request's review until it can merge |
52
- | "resolve the conflicts on 280" | `factory-resolve-conflicts` | Merges your default branch into a pull request and settles the conflicts |
53
- | "diagnose this failing test" | `factory-diagnose` | Finds a bug's cause before any code changes |
54
- | "mutate this test" | `factory-mutate` | Proves a test can fail |
55
- | "fix the dependency pull requests" | `factory-deps` | Moves dependency pull requests toward merged |
56
- | "mock up a new about page" | `factory-design` | Designs a visible change to a website, with mockups |
57
- | "trace this rule change" | `factory-trace` | Traces a change to the rules through every kind of change |
49
+ | Slash command | Plain words that also work | What it does |
50
+ | -------------------------------- | ---------------------------------- | ------------------------------------------------------------------------ |
51
+ | `/factory-refine 12` | "refine ticket 12" | Turns a ticket into a spec a builder can start from |
52
+ | `/factory-build 12` | "build ticket 12" | Builds a ticket to a reviewed pull request |
53
+ | `/factory-address-review 280` | "address the review on 280" | Works a pull request's review until it can merge |
54
+ | `/factory-resolve-conflicts 280` | "resolve the conflicts on 280" | Merges your default branch into a pull request and settles the conflicts |
55
+ | `/factory-diagnose` | "diagnose this failing test" | Finds a bug's cause before any code changes |
56
+ | `/factory-mutate` | "mutate this test" | Proves a test can fail |
57
+ | `/factory-deps` | "fix the dependency pull requests" | Moves dependency pull requests toward merged |
58
+ | `/factory-design` | "mock up a new about page" | Designs a visible change to a website, with mockups |
59
+ | `/factory-trace` | "trace this rule change" | Traces a change to the rules through every kind of change |
60
+
61
+ Typing `/factory` in a session lists them, which is also how to check that
62
+ a session picked the factory up.
58
63
 
59
64
  ## `factory-refine`
60
65
 
@@ -79,7 +84,7 @@ spec when [`specs`](configuration.md#specs) is on.
79
84
  you.
80
85
  - A blocked-by relationship for each ticket that must be built first.
81
86
  - For a decision about the look, mockups from your
82
- [`mockups` plug-in](plugins.md), if you have one.
87
+ [`mockups` plugin](plugins.md), if you have one.
83
88
 
84
89
  **How it asks.** In the session if you are there: each decision as a
85
90
  choice, the recommended answer first. Otherwise as one comment on the
@@ -96,7 +101,7 @@ ask. Then `factory ticket refined` refuses to mark the ticket refined
96
101
  while its body lacks a section a build reads.
97
102
 
98
103
  **Your own in its place.** A skill of yours can refine tickets instead, as
99
- the [`refiner` plug-in](plugins.md#refiner), which lists what it has to
104
+ the [`refiner` plugin](plugins.md#refiner), which lists what it has to
100
105
  leave for the build. To add questions to this one, write them under
101
106
  "Refining: this repository" in your `CLAUDE.md`.
102
107
 
@@ -109,14 +114,14 @@ leave for the build. To add questions to this one, write them under
109
114
  3. Builds to the acceptance criteria: the test first where there is a
110
115
  defect to reproduce or a behavior to add, then the change. A ticket
111
116
  carrying a label of one of your
112
- [`builder` plug-ins](plugins.md#builder) is built by that skill
117
+ [`builder` plugins](plugins.md#builder) is built by that skill
113
118
  instead.
114
119
  4. Proves each new test can fail, by its failing run before the change or
115
120
  with the [prover](plugins.md#prover), which is `factory-mutate` unless
116
121
  you name your own, and has the
117
122
  [test reviewers](plugins.md#test-reviewer) read the tests:
118
123
  `factory-test-reviewer`, unless your settings list others.
119
- 5. Has each [`reviewer` plug-in](plugins.md#reviewer) that applies read the
124
+ 5. Has each [`reviewer` plugin](plugins.md#reviewer) that applies read the
120
125
  change, and fixes what they find.
121
126
  6. Runs the gate with `factory gate`: the commands under
122
127
  [`commands.gate`](configuration.md#commandsgate) in your settings.
@@ -126,7 +131,7 @@ leave for the build. To add questions to this one, write them under
126
131
  review with `factory-address-review`.
127
132
 
128
133
  **When to use it.** On a ticket that has acceptance criteria and your
129
- approval. Telling a session "build ticket 12" is approval. So is moving the ticket
134
+ approval. Running `/factory-build 12` in a session is approval. So is moving the ticket
130
135
  to Ready.
131
136
 
132
137
  **What it reads.** The ticket, its Decisions, and your project's
@@ -240,7 +245,7 @@ your visitors are from your project's own instructions.
240
245
  **When to use it.** When asked to redesign or restyle a page, and from
241
246
  `factory-refine` when a decision changes how something looks. A
242
247
  repository with `site` in its settings gets it as its
243
- [`mockups` plug-in](plugins.md) without listing it; one without `site`
248
+ [`mockups` plugin](plugins.md) without listing it; one without `site`
244
249
  does not get it at all.
245
250
 
246
251
  **What it never does.** Make a mockup of a change with no look to choose,
@@ -273,7 +278,7 @@ file's shape for you to write.
273
278
  conflicts with it, runs the gate, and pushes the merge. It never rebases or
274
279
  forces a push. A conflict in the lock file is settled by rebuilding it with
275
280
  [`commands.relock`](configuration.md#commandsrelock), and one in a file
276
- that a [`resolver` plug-in](plugins.md#resolver) of yours rebuilds, by
281
+ that a [`resolver` plugin](plugins.md#resolver) of yours rebuilds, by
277
282
  that skill. When the two sides of a conflict contradict each other, it
278
283
  pushes nothing, comments why, and opens a ticket, because which side wins
279
284
  is your decision.