@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.
- package/README.md +9 -8
- package/dist/cli.mjs +13 -1
- package/dist/code-host/github-setup.mjs +1 -1
- package/dist/config.d.mts +74 -20
- package/dist/config.mjs +326 -76
- package/dist/deps.d.mts +6 -4
- package/dist/deps.mjs +29 -7
- package/dist/doctor.d.mts +3 -0
- package/dist/doctor.mjs +7 -4
- package/dist/explain.d.mts +13 -2
- package/dist/explain.mjs +58 -43
- package/dist/init.mjs +9 -7
- package/dist/lib/default-branch.d.mts +1 -1
- package/dist/lib/default-branch.mjs +2 -2
- package/dist/lib/refined-check.mjs +1 -1
- package/dist/lib/work-status.d.mts +2 -2
- package/dist/lib/work-status.mjs +4 -4
- package/dist/parts.d.mts +1 -1
- package/dist/parts.mjs +2 -2
- package/dist/preset-commands.d.mts +65 -0
- package/dist/preset-commands.mjs +1148 -0
- package/dist/preset.d.mts +169 -0
- package/dist/preset.mjs +550 -0
- package/dist/remove.mjs +34 -1
- package/dist/review-cost.mjs +1 -1
- package/dist/review-tools.mjs +3 -3
- package/dist/session-start.d.mts +3 -0
- package/dist/session-start.mjs +12 -1
- package/dist/sync.d.mts +42 -7
- package/dist/sync.mjs +166 -32
- package/docs/builds.md +12 -11
- package/docs/cli.md +27 -8
- package/docs/configuration.md +723 -714
- package/docs/design.md +1 -1
- package/docs/developing.md +20 -8
- package/docs/existing-repo.md +1 -1
- package/docs/github/by-hand.md +9 -9
- package/docs/github/reference.md +4 -19
- package/docs/github/setup.md +3 -3
- package/docs/glossary.md +18 -9
- package/docs/limitations.md +4 -1
- package/docs/plugins.md +36 -24
- package/docs/presets.md +410 -0
- package/docs/quick-start.md +21 -18
- package/docs/removing.md +1 -1
- package/docs/skills.md +28 -23
- package/docs/updating.md +22 -14
- package/docs/workflow.md +13 -14
- package/package.json +1 -1
- package/rules.md +1 -1
- package/settings.schema.json +60 -11
- package/skills/factory-build/SKILL.md +1 -1
- package/skills/factory-deps/SKILL.md +23 -12
- package/skills/factory-design/SKILL.md +2 -2
- package/skills/factory-refine/SKILL.md +2 -2
- package/skills/factory-resolve-conflicts/SKILL.md +6 -0
- package/workflows/factory-claude-review.yml +8 -3
package/docs/presets.md
ADDED
|
@@ -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
|
+
```
|
package/docs/quick-start.md
CHANGED
|
@@ -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
|
|
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,
|
|
126
|
+
In the session, type:
|
|
127
127
|
|
|
128
128
|
```text
|
|
129
|
-
refine
|
|
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
|
|
152
|
+
/factory-build 12
|
|
150
153
|
```
|
|
151
154
|
|
|
152
|
-
|
|
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
|
|
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
|
|
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
|
|
183
|
-
| The build stops on `commands.gate is not set` | Add your test and lint commands, as in step 2, then
|
|
184
|
-
| The session was closed or crashed partway |
|
|
185
|
-
| You want to change what was decided |
|
|
186
|
-
| CI fails on the pull request |
|
|
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 [
|
|
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
|
-
|
|
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
|
|
9
|
-
|
|
10
|
-
Claude Code
|
|
11
|
-
|
|
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
|
-
[
|
|
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
|
-
|
|
|
48
|
-
|
|
|
49
|
-
| "refine ticket 12" |
|
|
50
|
-
| "build ticket 12" |
|
|
51
|
-
| "address the review on 280" |
|
|
52
|
-
| "resolve the conflicts on 280" |
|
|
53
|
-
| "diagnose this failing test" |
|
|
54
|
-
| "mutate this test" |
|
|
55
|
-
| "fix the dependency pull requests" |
|
|
56
|
-
| "mock up a new about page" |
|
|
57
|
-
| "trace this rule 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`
|
|
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`
|
|
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`
|
|
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`
|
|
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.
|
|
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`
|
|
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`
|
|
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.
|