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