@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.
- package/README.md +9 -8
- package/dist/cli.mjs +12 -0
- package/dist/config.d.mts +57 -3
- package/dist/config.mjs +268 -18
- 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 +12 -1
- package/dist/explain.mjs +47 -32
- package/dist/init.mjs +6 -4
- package/dist/lib/default-branch.d.mts +1 -1
- package/dist/lib/default-branch.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/session-start.d.mts +3 -0
- package/dist/session-start.mjs +12 -1
- package/dist/sync.d.mts +42 -7
- package/dist/sync.mjs +165 -31
- package/docs/builds.md +12 -11
- package/docs/cli.md +21 -2
- package/docs/configuration.md +65 -13
- package/docs/developing.md +9 -2
- package/docs/github/by-hand.md +5 -5
- package/docs/github/reference.md +2 -17
- package/docs/github/setup.md +1 -1
- package/docs/glossary.md +12 -2
- package/docs/limitations.md +3 -0
- package/docs/plugins.md +16 -5
- package/docs/presets.md +410 -0
- package/docs/quick-start.md +20 -17
- package/docs/skills.md +21 -16
- package/docs/updating.md +14 -7
- package/docs/workflow.md +12 -13
- package/package.json +1 -1
- package/settings.schema.json +52 -3
- package/skills/factory-deps/SKILL.md +23 -12
- package/skills/factory-design/SKILL.md +1 -1
- package/skills/factory-resolve-conflicts/SKILL.md +6 -0
- package/workflows/factory-claude-review.yml +7 -2
package/docs/github/setup.md
CHANGED
|
@@ -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
|
-
|
|
|
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
|
|
109
|
-
such as
|
|
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
|
package/docs/limitations.md
CHANGED
|
@@ -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
|
|
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 |
|
|
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
|
|
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
|
|
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
|
-
|
|
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
|
|
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
|
|