@davidbyoung/software-factory 0.1.2 → 0.1.4

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 (120) hide show
  1. package/README.md +20 -20
  2. package/actions/factory-agent/action.yml +1 -1
  3. package/agents/factory-e2e-reviewer.md +102 -0
  4. package/agents/factory-test-reviewer.md +26 -64
  5. package/agents/factory-ticket-readiness.md +14 -6
  6. package/dist/agent/claude-code.d.mts +3 -0
  7. package/dist/agent/claude-code.mjs +89 -0
  8. package/dist/agent/index.d.mts +2 -0
  9. package/dist/agent/index.mjs +5 -0
  10. package/dist/board.mjs +1 -1
  11. package/dist/cli.mjs +46 -4
  12. package/dist/code-host/github-setup.d.mts +5 -0
  13. package/dist/code-host/github-setup.mjs +133 -0
  14. package/dist/code-host/github.mjs +4 -0
  15. package/dist/code-host/index.d.mts +1 -1
  16. package/dist/code-host/index.mjs +2 -1
  17. package/dist/code-host/types.d.mts +2 -0
  18. package/dist/commands.d.mts +16 -0
  19. package/dist/commands.mjs +129 -0
  20. package/dist/config.d.mts +87 -20
  21. package/dist/config.mjs +344 -89
  22. package/dist/deps.d.mts +7 -4
  23. package/dist/deps.mjs +20 -9
  24. package/dist/doctor.d.mts +9 -16
  25. package/dist/doctor.mjs +71 -68
  26. package/dist/explain.d.mts +4 -0
  27. package/dist/explain.mjs +174 -0
  28. package/dist/guard-commit.d.mts +7 -2
  29. package/dist/guard-commit.mjs +58 -21
  30. package/dist/init.d.mts +12 -14
  31. package/dist/init.mjs +194 -136
  32. package/dist/lib/default-branch.d.mts +35 -0
  33. package/dist/lib/default-branch.mjs +117 -0
  34. package/dist/lib/has-command.d.mts +5 -0
  35. package/dist/lib/has-command.mjs +8 -0
  36. package/dist/lib/listed.d.mts +2 -0
  37. package/dist/lib/listed.mjs +4 -0
  38. package/dist/lib/refined-check.d.mts +7 -0
  39. package/dist/lib/refined-check.mjs +76 -0
  40. package/dist/lib/work-status.d.mts +12 -2
  41. package/dist/lib/work-status.mjs +14 -3
  42. package/dist/parts.d.mts +18 -15
  43. package/dist/parts.mjs +15 -43
  44. package/dist/patch-coverage.d.mts +13 -0
  45. package/dist/patch-coverage.mjs +73 -0
  46. package/dist/poller.d.mts +20 -3
  47. package/dist/poller.mjs +62 -15
  48. package/dist/pr-watch.d.mts +3 -2
  49. package/dist/pr-watch.mjs +22 -5
  50. package/dist/pr.mjs +34 -2
  51. package/dist/remove.d.mts +11 -0
  52. package/dist/remove.mjs +156 -0
  53. package/dist/runner/github-actions.d.mts +1 -1
  54. package/dist/runner/github-actions.mjs +12 -0
  55. package/dist/runner/index.d.mts +1 -1
  56. package/dist/runner/index.mjs +2 -1
  57. package/dist/runner/setup.d.mts +2 -0
  58. package/dist/runner/setup.mjs +22 -0
  59. package/dist/runner/types.d.mts +3 -0
  60. package/dist/runner/types.mjs +0 -2
  61. package/dist/session-start.d.mts +23 -13
  62. package/dist/session-start.mjs +56 -44
  63. package/dist/setup.d.mts +98 -0
  64. package/dist/setup.mjs +3 -0
  65. package/dist/site/servers.d.mts +6 -2
  66. package/dist/site/servers.mjs +14 -9
  67. package/dist/site.mjs +2 -2
  68. package/dist/status.d.mts +4 -4
  69. package/dist/status.mjs +8 -7
  70. package/dist/sync.d.mts +26 -2
  71. package/dist/sync.mjs +177 -13
  72. package/dist/ticket.mjs +19 -1
  73. package/dist/tickets/github-setup.d.mts +2 -0
  74. package/dist/tickets/github-setup.mjs +50 -0
  75. package/dist/tickets/github.mjs +0 -2
  76. package/dist/tickets/index.mjs +2 -1
  77. package/dist/tickets/transport.mjs +1 -3
  78. package/dist/tickets/types.mjs +0 -2
  79. package/dist/tool-names.d.mts +11 -0
  80. package/dist/tool-names.mjs +20 -0
  81. package/dist/tools.d.mts +56 -0
  82. package/dist/tools.mjs +76 -0
  83. package/docs/builds.md +111 -59
  84. package/docs/cli.md +106 -69
  85. package/docs/configuration.md +489 -171
  86. package/docs/design.md +18 -5
  87. package/docs/developing.md +179 -73
  88. package/docs/existing-repo.md +25 -12
  89. package/docs/github/by-hand.md +334 -0
  90. package/docs/github/reference.md +76 -67
  91. package/docs/github/setup.md +105 -286
  92. package/docs/glossary.md +18 -7
  93. package/docs/limitations.md +39 -12
  94. package/docs/plugins.md +305 -56
  95. package/docs/quick-start.md +85 -100
  96. package/docs/removing.md +37 -17
  97. package/docs/skills.md +121 -62
  98. package/docs/updating.md +150 -9
  99. package/docs/workflow.md +23 -19
  100. package/package.json +1 -1
  101. package/poller.Dockerfile +10 -18
  102. package/review.md +20 -11
  103. package/rules.md +36 -30
  104. package/settings.schema.json +313 -69
  105. package/skills/factory-address-review/SKILL.md +50 -30
  106. package/skills/factory-build/SKILL.md +76 -23
  107. package/skills/factory-deps/SKILL.md +46 -21
  108. package/skills/factory-design/SKILL.md +17 -8
  109. package/skills/factory-diagnose/SKILL.md +22 -20
  110. package/skills/factory-mutate/SKILL.md +38 -24
  111. package/skills/factory-refine/SKILL.md +55 -31
  112. package/skills/factory-resolve-conflicts/SKILL.md +76 -34
  113. package/skills/factory-trace/SKILL.md +80 -0
  114. package/workflows/factory-build.yml +6 -5
  115. package/workflows/factory-conflicts.yml +8 -8
  116. package/workflows/factory-deps-auto-merge.yml +3 -2
  117. package/workflows/factory-deps.yml +1 -1
  118. package/workflows/factory-poller.yml +46 -0
  119. package/workflows/factory-review.yml +1 -1
  120. package/skills/factory-address-review/patch-coverage.py +0 -68
package/docs/plugins.md CHANGED
@@ -1,5 +1,10 @@
1
1
  # Plug-ins
2
2
 
3
+ For someone who wants the factory to use a skill or an agent of their own:
4
+ a reviewer for one part of the code, a builder for one kind of ticket, or
5
+ their own way of refining a ticket. At the end, the factory calls it at a
6
+ set moment of every build, and `factory plugins` lists it.
7
+
3
8
  The factory knows how to refine, build, and review a ticket. It does not
4
9
  know your project. A plug-in is one of your own skills or agents that the
5
10
  factory calls at a set moment, so what only your project knows is part of
@@ -10,28 +15,188 @@ every build.
10
15
  You write a skill or an agent the way your coding agent expects one, in
11
16
  the folder it reads them from
12
17
  ([on Claude Code](github/reference.md#skills-in-claude-code)). Then you add
13
- a few lines to `.claude/factory.yaml` saying what job it does:
18
+ a few lines to `.claude/factory.yaml` saying where the factory calls it:
14
19
 
15
20
  ```yaml
16
21
  plugins:
17
- - agent: migration-reviewer
18
- role: reviewer
19
- files:
20
- - db/migrations/**
22
+ build:
23
+ reviewers:
24
+ - agent: migration-reviewer
25
+ files:
26
+ - db/migrations/**
21
27
  ```
22
28
 
23
29
  That is the whole of it. The factory never copies over your files, and an
24
30
  update never touches them.
25
31
 
26
- ## The three roles
32
+ ## The slots
33
+
34
+ A slot is a moment in the work where the factory hands off. There are
35
+ seven, grouped under [`plugins`](configuration.md#plugins) by the phase
36
+ each belongs to. Every slot is optional, and leaving one out never turns a
37
+ step off: the last column says what does the work then.
38
+
39
+ A slot has two names. The settings key, in the second column, is what you
40
+ write in `.claude/factory.yaml`. The slot's own name, in the first column,
41
+ is what `factory plugins` prints, and the headings below use it: `builder`
42
+ is the slot you write as
43
+ [`plugins.build.builders`](configuration.md#pluginsbuild), and no key is
44
+ called `builder`.
45
+
46
+ | Slot | Settings key | It | Left out |
47
+ | --------------- | ------------------------------------------------------------------ | ---------------------------------------------- | ----------------------------------------- |
48
+ | `refiner` | [`plugins.refine.refiner`](configuration.md#pluginsrefine) | Refines a ticket, in place of `factory-refine` | `factory-refine` |
49
+ | `mockups` | [`plugins.refine.mockups`](configuration.md#pluginsrefine) | Makes pictures for a decision about the look | `factory-design` on a website, else words |
50
+ | `builder` | [`plugins.build.builders`](configuration.md#pluginsbuild) | Builds a ticket that carries one of its labels | The built-in build |
51
+ | `reviewer` | [`plugins.build.reviewers`](configuration.md#pluginsbuild) | Reads a finished change that touches its files | No reviewers of your own |
52
+ | `prover` | [`plugins.test.prover`](configuration.md#pluginstest) | Proves a new test can fail | `factory-mutate` |
53
+ | `test-reviewer` | [`plugins.test.reviewers`](configuration.md#pluginstest) | Reads new and changed tests | `factory-test-reviewer` |
54
+ | `resolver` | [`plugins.conflicts.resolvers`](configuration.md#pluginsconflicts) | Rebuilds its files after a merge conflict | A merge by hand |
55
+
56
+ [Configuration](configuration.md#plugins) has the shape of each key:
57
+ whether it takes a skill or an agent, one or a list, and `files` or
58
+ `labels`.
59
+
60
+ A reviewer is an agent: a session launches it, and it reads and changes
61
+ nothing. Every other slot is a skill, which the session follows itself.
62
+
63
+ ## Refining
64
+
65
+ ### `refiner`
66
+
67
+ Refines a ticket your own way, in place of `factory-refine`.
68
+
69
+ ```yaml
70
+ plugins:
71
+ refine:
72
+ refiner:
73
+ skill: acme-refine
74
+ ```
75
+
76
+ | Step | What happens |
77
+ | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
78
+ | **Called** | When you ask a session to refine a ticket: `factory-refine` hands over to it before doing anything. By `factory-build`, on a ticket that has no criteria yet, or one you approved while its questions waited |
79
+ | **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 |
80
+ | **Returns** | A ticket a build can start from: everything in the list below |
81
+ | **Then** | The ticket waits for your approval, and the build reads what the refiner left |
82
+
83
+ **What a refiner must deliver.** The board and the build read these, so a
84
+ refiner that leaves one out leaves a ticket that cannot be built.
85
+
86
+ - **The three markers,** each posted with a command, so the board shows
87
+ where the ticket stands: `factory ticket refining N` when it starts,
88
+ `factory ticket waiting N` when it has posted questions for you, and
89
+ `factory ticket refined N` when the ticket is ready for your approval.
90
+ - **The `spec` label, decided.** With
91
+ [`specs: openspec`](configuration.md#specs), a change your users will
92
+ see that is not small gets the label, with
93
+ `factory ticket label N --add spec`. A refiner never removes it, and
94
+ never adds it back once you took it off.
95
+ - **Each ticket this one waits on,** recorded with
96
+ `factory ticket block N --by M`. A build order written only in prose is
97
+ one nothing reads.
98
+ - **The body,** written with `factory ticket edit`, with your text kept
99
+ first and these sections after it:
100
+
101
+ | The ticket | Its body has |
102
+ | --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
103
+ | Without `spec` | `## Decisions`, and `## Acceptance criteria` with at least one list item |
104
+ | With `spec` | `## Decisions`; `## Spec`, with a `### NAME (new)` or `### NAME (modified)` heading for each capability and numbered lines under it; and `## For the builder`, with `### Design` and `### Tasks` |
105
+ | The follow-ups ticket | Its checklist. The check passes it whatever else its body holds |
106
+
107
+ On a `spec` ticket the build copies these into an OpenSpec change, so
108
+ they keep its shape: each numbered Spec line is one "When this, then
109
+ that" sentence, which becomes one requirement, and Tasks are numbered
110
+ groups of checkboxes, as OpenSpec's `tasks.md` has them.
111
+
112
+ **The check is a script's.** `factory ticket refined N` refuses to post
113
+ its marker on a body missing one of those sections, for the factory's own
114
+ refiner as for yours. It prints one line for each, such as
115
+ `missing: ### Tasks under ## For the builder`, and exits 1.
116
+ `factory ticket refined N --check` makes the same check and posts nothing:
117
+ it prints `sound` when the body passes. The check is that each section is
118
+ there, not that what it says is right. For that,
119
+ `factory-ticket-readiness`, the built-in agent that reads a refined ticket
120
+ cold, reads any refiner's result against this same list: have your refiner
121
+ launch it, as `factory-refine` does.
122
+
123
+ `factory-refine` stays in your repository beside your refiner, so ask a
124
+ session for yours by its own name. The surest way to write one is to start
125
+ from a copy of `factory-refine` under your own name.
126
+
127
+ **To add questions, not replace the refiner,** write them in your own
128
+ instructions for the agent, under a heading "Refining: this repository" in
129
+ `CLAUDE.md`. The refining session reads `CLAUDE.md`, and it wins over the
130
+ factory's rules, so no plug-in is needed for that.
131
+
132
+ ### `mockups`
133
+
134
+ Makes pictures to choose from when a decision changes how something looks.
135
+
136
+ A repository with [`site`](configuration.md#site) in its settings has one
137
+ already: the factory's own `factory-design` skill, which `factory sync`
138
+ writes, is its `mockups` plug-in unless you name one of your own.
139
+
140
+ ```yaml
141
+ plugins:
142
+ refine:
143
+ mockups:
144
+ skill: design-mockups
145
+ ```
146
+
147
+ | Step | What happens |
148
+ | --------------- | ------------------------------------------------------------------------------ |
149
+ | **Called** | By the refiner, when one of the decisions it would bring you is about the look |
150
+ | **Handed** | The ticket and the decision |
151
+ | **Returns** | Pictures of each option, with one recommended |
152
+ | **Then** | You choose, and the choice goes into the ticket |
153
+ | **Without one** | The decision is described in words |
154
+
155
+ ## Building
156
+
157
+ ### `builder`
158
+
159
+ Builds a kind of ticket the general build would do badly.
160
+
161
+ ```yaml
162
+ plugins:
163
+ build:
164
+ builders:
165
+ - skill: add-endpoint
166
+ labels:
167
+ - new-endpoint
168
+ ```
169
+
170
+ | Step | What happens |
171
+ | ------------- | --------------------------------------------------------------------------------------------------- |
172
+ | **Called** | By `factory-build`, in place of its own build step |
173
+ | **Used when** | The ticket carries one of its `labels`. When two builders share a label, the first listed is used |
174
+ | **Handed** | The ticket, already claimed, on its branch |
175
+ | **Returns** | The change, and a report for the pull request body |
176
+ | **Then** | `factory-build` carries on as usual: the test reviewers, your reviewers, the gate, the pull request |
177
+
178
+ **Reviewers still run after a builder.** The test reviewers and your own
179
+ read what it built, and so does everything after them. A reviewer the
180
+ builder's report shows it already ran is not run twice: its line in the
181
+ pull request reads "already run by the builder".
27
182
 
28
- A role is a moment in the workflow where the factory hands off. There are
29
- three. A repository can have several plug-ins in one role, or none.
183
+ Good candidates: work your project always does the same way, such as a new
184
+ API endpoint with its route, handler, schema, and docs, or a new
185
+ translation added to every locale file.
30
186
 
31
187
  ### `reviewer`
32
188
 
33
189
  Reads a finished change and reports problems.
34
190
 
191
+ ```yaml
192
+ plugins:
193
+ build:
194
+ reviewers:
195
+ - agent: migration-reviewer
196
+ files:
197
+ - db/migrations/**
198
+ ```
199
+
35
200
  | Step | What happens |
36
201
  | ------------------- | -------------------------------------------------------------------------------------------- |
37
202
  | **Called** | By `factory-build`, after the change is built and before the pull request opens |
@@ -44,37 +209,109 @@ Good candidates: database migrations, anything touching authentication or
44
209
  payments, a public API that must stay backward compatible, accessibility
45
210
  of your components, copy that has to follow a style guide.
46
211
 
47
- ### `mockups`
212
+ ## Testing
48
213
 
49
- Makes pictures to choose from when a decision changes how something looks.
214
+ ### `prover`
50
215
 
51
- A repository with `site` in its settings has one already: the factory's
52
- own `factory-design` skill, which `factory sync` writes, is its `mockups`
53
- plug-in unless you list one of your own with this role.
216
+ Proves a new test can fail, in place of `factory-mutate`. A test that
217
+ passes whether or not the code works locks nothing in.
54
218
 
55
- | Step | What happens |
56
- | --------------- | ----------------------------------------------------------------------------------- |
57
- | **Called** | By `factory-refine`, when one of the decisions it would bring you is about the look |
58
- | **Handed** | The ticket and the decision |
59
- | **Returns** | Screenshots of each option, with one recommended |
60
- | **Then** | You choose, and the choice goes into the ticket |
61
- | **Without one** | The decision is described in words |
219
+ ```yaml
220
+ plugins:
221
+ test:
222
+ prover:
223
+ skill: acme-mutation
224
+ ```
62
225
 
63
- ### `builder`
226
+ | Step | What happens |
227
+ | ----------- | ------------------------------------------------------------------------------------------------------------ |
228
+ | **Called** | By `factory-build` and `factory-address-review`, for a new or changed test nobody saw fail before the change |
229
+ | **Handed** | The new or changed tests |
230
+ | **Returns** | For each test, what made it fail, and the code put back as it was |
231
+ | **Then** | The pull request records each proof. A test that stays green is the one that needs work |
64
232
 
65
- Builds a kind of ticket the general build would do badly.
233
+ **What a prover must report.** For each new or changed test, one of two
234
+ things, as a line the pull request body takes:
66
235
 
67
- | Step | What happens |
68
- | ------------- | -------------------------------------------------------------------------- |
69
- | **Called** | By `factory-build`, in place of its own build step |
70
- | **Used when** | The ticket carries one of its `labels` |
71
- | **Handed** | The ticket, already claimed, on its branch |
72
- | **Returns** | The change, and a report for the pull request body |
73
- | **Then** | `factory-build` carries on as usual: reviewers, the gate, the pull request |
236
+ - **its red run:** the test failing before the change was made; or
237
+ - **the one mutation that made it fail:** the edit to the code under test
238
+ that turned the test red, for a test written after the code.
74
239
 
75
- Good candidates: work your project always does the same way, such as a new
76
- API endpoint with its route, handler, schema, and docs, or a new
77
- translation added to every locale file.
240
+ One proof for each test is the rule, and it stays a rule whichever prover
241
+ runs: the slot cannot be set to nothing. No script checks a prover's
242
+ report. The pull request records it, where you read it.
243
+
244
+ ### `test-reviewer`
245
+
246
+ Reads new and changed tests, the way `factory-test-reviewer` does.
247
+
248
+ ```yaml
249
+ plugins:
250
+ test:
251
+ reviewers:
252
+ - agent: factory-test-reviewer
253
+ - agent: factory-e2e-reviewer
254
+ files:
255
+ - e2e/**
256
+ ```
257
+
258
+ | Step | What happens |
259
+ | ------------------- | ------------------------------------------------------------------------------------------------------- |
260
+ | **Called** | By `factory-build`, once the tests are written and proved, and before your own reviewers |
261
+ | **Considered when** | The change adds or changes tests. One listed with `files`, only when the change touches a matching file |
262
+ | **Handed** | The new and changed tests |
263
+ | **Returns** | Findings, each with where it is and why it matters. It changes nothing |
264
+ | **Then** | The building session fixes what holds up, and the pull request says what each one found |
265
+
266
+ - **[`plugins.test.reviewers`](configuration.md#pluginstest), once
267
+ written, is the whole list.** Left out, `factory-test-reviewer` reads
268
+ the tests. Written, only the agents you list do, so list
269
+ `factory-test-reviewer` to keep it, and leave it off to remove it.
270
+ - **A small change gets no test reviewer,** whichever are listed
271
+ ([Workflow](workflow.md#sizing-the-work-to-the-change)), with two
272
+ exceptions that run every one listed, one with `files` only when the
273
+ change touches a matching file: a change to tests alone, and code that
274
+ builds what is sent to an outside service.
275
+ - **`factory-e2e-reviewer`** ships with the factory and reads browser
276
+ end-to-end tests. `factory sync` writes it once
277
+ [`commands.end-to-end`](configuration.md#commandsend-to-end) is set, and
278
+ it runs only where it is listed, as above.
279
+
280
+ ## Conflicts
281
+
282
+ ### `resolver`
283
+
284
+ Rebuilds a file after a merge conflict, in place of merging it by hand: a
285
+ generated API client, a compiled schema, a lock file of a package manager
286
+ other than npm.
287
+
288
+ ```yaml
289
+ plugins:
290
+ conflicts:
291
+ resolvers:
292
+ - skill: regenerate-api-client
293
+ files:
294
+ - src/generated/**
295
+ ```
296
+
297
+ | Step | What happens |
298
+ | ------------- | -------------------------------------------------------------------------------------------------------------- |
299
+ | **Called** | By `factory-resolve-conflicts` and `factory-deps`, during a merge of your default branch into a pull request |
300
+ | **Used when** | A conflicted file matches one of its `files`. When two resolvers match one file, the first listed is used |
301
+ | **Handed** | The conflicted files that match, with the merge still in progress |
302
+ | **Returns** | Each file resolved and staged, or word that it cannot |
303
+ | **Then** | The session runs the gate and pushes the merge. "It cannot" is a stop: nothing is pushed, and you are told why |
304
+
305
+ - **The conflict sweep reads a resolver from your default branch's
306
+ copy,** both the list in the settings and the skill's text, never from
307
+ the pull request's branch. The sweep runs with a token, and a pull
308
+ request could otherwise change what runs with it. So a new or changed
309
+ resolver is used once it has merged.
310
+ - **A contradiction is still a stop.** When the two sides of a conflict
311
+ disagree about what the file should say, a resolver does not settle it:
312
+ the session pushes nothing, comments why, and opens a ticket.
313
+ - **npm's lock file needs no resolver.**
314
+ [`commands.relock`](configuration.md#commandsrelock) rebuilds it.
78
315
 
79
316
  ## `files` filters; the agent decides
80
317
 
@@ -123,10 +360,11 @@ runs.
123
360
 
124
361
  ```yaml
125
362
  plugins:
126
- - agent: migration-reviewer
127
- role: reviewer
128
- files:
129
- - db/migrations/**
363
+ build:
364
+ reviewers:
365
+ - agent: migration-reviewer
366
+ files:
367
+ - db/migrations/**
130
368
  ```
131
369
 
132
370
  **3. A session builds a ticket** that removes an unused column.
@@ -150,10 +388,21 @@ instructions for the agent and in the agent itself. The factory holds none of th
150
388
 
151
389
  1. Write the skill or agent, and try it by hand until it does its job.
152
390
  2. Give it a description that states when it applies.
153
- 3. Add it under `plugins` with its `role`, and `files` or `labels`.
154
- 4. Run `factory config check`. It fails if the file is missing or the
155
- role is not one of the three.
156
- 5. Run `factory plugins` to see the list the factory will use.
391
+ 3. Add it under [`plugins`](configuration.md#plugins), in its slot, with
392
+ `files` or `labels` where the slot takes them.
393
+ 4. Run `factory config check`. It fails, naming the slot, if the file is
394
+ missing, or the slot takes a skill and you named an agent.
395
+ 5. Run `factory plugins` to see the list the factory will use, the
396
+ built-in ones included:
397
+
398
+ ```text
399
+ skill factory-refine refiner
400
+ agent migration-reviewer reviewer db/migrations/**
401
+ skill factory-mutate prover
402
+ agent factory-test-reviewer test-reviewer
403
+ ```
404
+
405
+ **It worked when** your plug-in is in that list, in its slot.
157
406
 
158
407
  No sync is needed. Plug-ins are read from your settings each time.
159
408
 
@@ -163,10 +412,16 @@ No sync is needed. Plug-ins are read from your settings each time.
163
412
  reviewing a ticket should call it, it needs no entry. It stays an
164
413
  ordinary skill.
165
414
  - **A skill another of your skills calls.** A reviewer that only your own
166
- `builder` launches is that builder's business.
167
- - **A rule.** "Migrations always wait for me" is `auto-merge`. "Every
168
- migration needs a rollback" is a sentence in your project's instructions
169
- for the agent.
415
+ builder launches is that builder's business.
416
+ - **A rule.** "Migrations always wait for me" is
417
+ [`auto-merge`](configuration.md#auto-merge). "Every migration needs a
418
+ rollback" is a sentence in your project's instructions for the agent.
419
+ - **A question you want every refinement to ask.** That is a line under
420
+ "Refining: this repository" in `CLAUDE.md`, as [`refiner`](#refiner)
421
+ says.
422
+ - **A step in another order.** A plug-in replaces a step where it stands.
423
+ It cannot add a state or move one
424
+ ([Why it works this way](design.md#the-order-of-the-workflow-is-fixed)).
170
425
 
171
426
  ## The UI reviewer
172
427
 
@@ -175,18 +430,12 @@ with `site` in its settings, but runs only where it is listed:
175
430
 
176
431
  ```yaml
177
432
  plugins:
178
- - agent: factory-ui-reviewer
179
- role: reviewer
180
- files:
181
- - src/**
182
- - public/**
433
+ build:
434
+ reviewers:
435
+ - agent: factory-ui-reviewer
436
+ files:
437
+ - src/**
438
+ - public/**
183
439
  ```
184
440
 
185
441
  It needs the `site` settings, which say how to start the website.
186
-
187
- ## Sharing plug-ins between repositories
188
-
189
- Not planned. A plug-in lives in the repository that uses it. A way to
190
- package a set of them, such as a design skill and a visual reviewer for
191
- any website, and install it in several repositories is designed for but
192
- not scheduled.