@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/skills.md
CHANGED
|
@@ -16,33 +16,45 @@ The factory's core is what its own steps call, and every repository gets
|
|
|
16
16
|
it. Everything else is written only when a setting or a file turns it on,
|
|
17
17
|
and `factory sync` removes it again when that is undone.
|
|
18
18
|
|
|
19
|
-
| Skill or agent | Written
|
|
20
|
-
| --------------------------- |
|
|
21
|
-
| `factory-refine` | Always
|
|
22
|
-
| `factory-build` | Always
|
|
23
|
-
| `factory-address-review` | Always
|
|
24
|
-
| `factory-resolve-conflicts` | Always
|
|
25
|
-
| `factory-diagnose` | Always
|
|
26
|
-
| `factory-mutate` | Always
|
|
27
|
-
| `factory-
|
|
28
|
-
| `factory-
|
|
29
|
-
| `factory-
|
|
30
|
-
| `factory-
|
|
31
|
-
| `factory-
|
|
19
|
+
| Skill or agent | Written |
|
|
20
|
+
| --------------------------- | ---------------------------------------------------------------------------------- |
|
|
21
|
+
| `factory-refine` | Always |
|
|
22
|
+
| `factory-build` | Always |
|
|
23
|
+
| `factory-address-review` | Always |
|
|
24
|
+
| `factory-resolve-conflicts` | Always |
|
|
25
|
+
| `factory-diagnose` | Always |
|
|
26
|
+
| `factory-mutate` | Always |
|
|
27
|
+
| `factory-trace` | Always |
|
|
28
|
+
| `factory-ticket-readiness` | Always |
|
|
29
|
+
| `factory-test-reviewer` | Always |
|
|
30
|
+
| `factory-design` | With [`site`](configuration.md#site) in your settings |
|
|
31
|
+
| `factory-ui-reviewer` | With `site` in your settings |
|
|
32
|
+
| `factory-e2e-reviewer` | With [`commands.end-to-end`](configuration.md#commandsend-to-end) in your settings |
|
|
33
|
+
| `factory-deps` | With a `.github/dependabot.yml` file |
|
|
34
|
+
|
|
35
|
+
No skill names a test runner, a linter, or a branch. Each runs what your
|
|
36
|
+
settings list under [`commands`](configuration.md#commands), through
|
|
37
|
+
commands such as `factory gate` and `factory test-one`
|
|
38
|
+
([The CLI](cli.md#your-repositorys-commands)), and asks
|
|
39
|
+
`factory default-branch` for your default branch's name.
|
|
40
|
+
|
|
41
|
+
Where a step below names a built-in skill or agent, a
|
|
42
|
+
[plugin](plugins.md#the-roles) of yours can stand in for it: your own
|
|
43
|
+
refiner, builder, prover, test reviewers, and conflict resolvers.
|
|
32
44
|
|
|
33
45
|
## At a glance
|
|
34
46
|
|
|
35
|
-
| Ask a session | Skill | It does
|
|
36
|
-
| ---------------------------------- | --------------------------- |
|
|
37
|
-
| "refine ticket 12" | `factory-refine` | Turns a ticket into a spec a builder can start from
|
|
38
|
-
| "build ticket 12" | `factory-build` | Builds a ticket to a reviewed pull request
|
|
39
|
-
| "address the review on 280" | `factory-address-review` | Works a pull request's review until it can merge
|
|
40
|
-
| "resolve the conflicts on 280" | `factory-resolve-conflicts` | Merges your
|
|
41
|
-
| "diagnose this failing test" | `factory-diagnose` | Finds a bug's cause before any code changes
|
|
42
|
-
| "mutate this test" | `factory-mutate` | Proves a test can fail
|
|
43
|
-
| "fix the dependency pull requests" | `factory-deps` | Moves dependency pull requests toward merged
|
|
44
|
-
| "mock up a new about page" | `factory-design` | Designs a visible change to a website, with mockups
|
|
45
|
-
| "trace this rule change" | `factory-trace` | Traces a change to the rules through every kind of change
|
|
47
|
+
| Ask a session | Skill | It does |
|
|
48
|
+
| ---------------------------------- | --------------------------- | ------------------------------------------------------------------------ |
|
|
49
|
+
| "refine ticket 12" | `factory-refine` | Turns a ticket into a spec a builder can start from |
|
|
50
|
+
| "build ticket 12" | `factory-build` | Builds a ticket to a reviewed pull request |
|
|
51
|
+
| "address the review on 280" | `factory-address-review` | Works a pull request's review until it can merge |
|
|
52
|
+
| "resolve the conflicts on 280" | `factory-resolve-conflicts` | Merges your default branch into a pull request and settles the conflicts |
|
|
53
|
+
| "diagnose this failing test" | `factory-diagnose` | Finds a bug's cause before any code changes |
|
|
54
|
+
| "mutate this test" | `factory-mutate` | Proves a test can fail |
|
|
55
|
+
| "fix the dependency pull requests" | `factory-deps` | Moves dependency pull requests toward merged |
|
|
56
|
+
| "mock up a new about page" | `factory-design` | Designs a visible change to a website, with mockups |
|
|
57
|
+
| "trace this rule change" | `factory-trace` | Traces a change to the rules through every kind of change |
|
|
46
58
|
|
|
47
59
|
## `factory-refine`
|
|
48
60
|
|
|
@@ -67,7 +79,7 @@ spec when [`specs`](configuration.md#specs) is on.
|
|
|
67
79
|
you.
|
|
68
80
|
- A blocked-by relationship for each ticket that must be built first.
|
|
69
81
|
- For a decision about the look, mockups from your
|
|
70
|
-
[`mockups`
|
|
82
|
+
[`mockups` plugin](plugins.md), if you have one.
|
|
71
83
|
|
|
72
84
|
**How it asks.** In the session if you are there: each decision as a
|
|
73
85
|
choice, the recommended answer first. Otherwise as one comment on the
|
|
@@ -80,21 +92,34 @@ several tickets, and it proposes the split.
|
|
|
80
92
|
|
|
81
93
|
**Its check.** The built-in `factory-ticket-readiness` agent reads the
|
|
82
94
|
result cold, at most twice, and lists what a builder would still have to
|
|
83
|
-
ask.
|
|
95
|
+
ask. Then `factory ticket refined` refuses to mark the ticket refined
|
|
96
|
+
while its body lacks a section a build reads.
|
|
97
|
+
|
|
98
|
+
**Your own in its place.** A skill of yours can refine tickets instead, as
|
|
99
|
+
the [`refiner` plugin](plugins.md#refiner), which lists what it has to
|
|
100
|
+
leave for the build. To add questions to this one, write them under
|
|
101
|
+
"Refining: this repository" in your `CLAUDE.md`.
|
|
84
102
|
|
|
85
103
|
## `factory-build`
|
|
86
104
|
|
|
87
105
|
**What it does.** Takes an approved ticket to a reviewed pull request.
|
|
88
106
|
|
|
89
107
|
1. Claims the ticket, so no other session builds it.
|
|
90
|
-
2. Makes a branch from your
|
|
108
|
+
2. Makes a branch from your default branch, named for the ticket.
|
|
91
109
|
3. Builds to the acceptance criteria: the test first where there is a
|
|
92
|
-
defect to reproduce or a behavior to add, then the change.
|
|
93
|
-
|
|
94
|
-
|
|
95
|
-
|
|
96
|
-
|
|
97
|
-
|
|
110
|
+
defect to reproduce or a behavior to add, then the change. A ticket
|
|
111
|
+
carrying a label of one of your
|
|
112
|
+
[`builder` plugins](plugins.md#builder) is built by that skill
|
|
113
|
+
instead.
|
|
114
|
+
4. Proves each new test can fail, by its failing run before the change or
|
|
115
|
+
with the [prover](plugins.md#prover), which is `factory-mutate` unless
|
|
116
|
+
you name your own, and has the
|
|
117
|
+
[test reviewers](plugins.md#test-reviewer) read the tests:
|
|
118
|
+
`factory-test-reviewer`, unless your settings list others.
|
|
119
|
+
5. Has each [`reviewer` plugin](plugins.md#reviewer) that applies read the
|
|
120
|
+
change, and fixes what they find.
|
|
121
|
+
6. Runs the gate with `factory gate`: the commands under
|
|
122
|
+
[`commands.gate`](configuration.md#commandsgate) in your settings.
|
|
98
123
|
7. Opens a draft pull request that closes the ticket, saying what changed,
|
|
99
124
|
how it was checked, and what each reviewer found.
|
|
100
125
|
8. Marks it ready once CI passes on the pushed commit, then works the
|
|
@@ -113,10 +138,11 @@ comment on the ticket, a note of what the build cost, and a line on the
|
|
|
113
138
|
and did not fix.
|
|
114
139
|
|
|
115
140
|
**When it stops.** On a question only you can answer, a step only you can
|
|
116
|
-
do, an open blocker, or a gate that will not pass
|
|
117
|
-
and says why. The ticket stays in "building", waiting
|
|
141
|
+
do, an open blocker, or a gate that will not pass or is not set. It
|
|
142
|
+
releases the ticket and says why. The ticket stays in "building", waiting
|
|
143
|
+
on you.
|
|
118
144
|
|
|
119
|
-
**What it never does.** Commit on your
|
|
145
|
+
**What it never does.** Commit on your default branch. Merge. Turn auto-merge
|
|
120
146
|
on. Add the label that overrides a review's verdict. Guess at a decision
|
|
121
147
|
the ticket left open. Reopen a decision the ticket settled.
|
|
122
148
|
|
|
@@ -128,7 +154,9 @@ under it takes the lighter path [Workflow](workflow.md) describes.
|
|
|
128
154
|
|
|
129
155
|
**What it does.** Works everything standing between a pull request and its
|
|
130
156
|
merge: the threads from the automated review, your own comments, failed
|
|
131
|
-
checks,
|
|
157
|
+
checks, a conflict with your default branch, and, when
|
|
158
|
+
[`commands.coverage`](configuration.md#commandscoverage) is set, the
|
|
159
|
+
changed lines no test covers.
|
|
132
160
|
|
|
133
161
|
**When to use it.** After every push to a branch with an open pull request.
|
|
134
162
|
The session that built the pull request runs it without being asked.
|
|
@@ -160,7 +188,8 @@ Dismiss a failing test as flaky without reproducing it. Merge.
|
|
|
160
188
|
**What it does.** Finds the cause of a bug, a failing or flaky test, or a
|
|
161
189
|
slowdown, before changing any code. It starts by building one command that
|
|
162
190
|
fails on the exact symptom, shrinks it, ranks the possible causes, and
|
|
163
|
-
tests them one change at a time.
|
|
191
|
+
tests them one change at a time. It runs one test or one end-to-end spec
|
|
192
|
+
alone with `factory test-one` and `factory end-to-end`.
|
|
164
193
|
|
|
165
194
|
**When to use it.** When something is broken, failing, flaky, or slow, and
|
|
166
195
|
the cause is not already known.
|
|
@@ -180,10 +209,13 @@ locks nothing in.
|
|
|
180
209
|
|
|
181
210
|
**What it never does.** Leave a mutation in place.
|
|
182
211
|
|
|
212
|
+
It is the [prover](plugins.md#prover) a build calls, unless your settings
|
|
213
|
+
name one of your own.
|
|
214
|
+
|
|
183
215
|
## `factory-deps`
|
|
184
216
|
|
|
185
217
|
**What it does.** Moves every open dependency pull request one step closer
|
|
186
|
-
to merged: resolves a conflict with your
|
|
218
|
+
to merged: resolves a conflict with your default branch, fixes failing checks,
|
|
187
219
|
does the migration a major version asks for, and opens a ticket for
|
|
188
220
|
anything it cannot fix.
|
|
189
221
|
|
|
@@ -208,7 +240,7 @@ your visitors are from your project's own instructions.
|
|
|
208
240
|
**When to use it.** When asked to redesign or restyle a page, and from
|
|
209
241
|
`factory-refine` when a decision changes how something looks. A
|
|
210
242
|
repository with `site` in its settings gets it as its
|
|
211
|
-
[`mockups`
|
|
243
|
+
[`mockups` plugin](plugins.md) without listing it; one without `site`
|
|
212
244
|
does not get it at all.
|
|
213
245
|
|
|
214
246
|
**What it never does.** Make a mockup of a change with no look to choose,
|
|
@@ -237,11 +269,14 @@ file's shape for you to write.
|
|
|
237
269
|
|
|
238
270
|
## `factory-resolve-conflicts`
|
|
239
271
|
|
|
240
|
-
**What it does.** Merges your
|
|
241
|
-
with it, runs the gate, and pushes the merge. It never rebases or
|
|
242
|
-
push.
|
|
243
|
-
|
|
244
|
-
|
|
272
|
+
**What it does.** Merges your default branch into a pull request that
|
|
273
|
+
conflicts with it, runs the gate, and pushes the merge. It never rebases or
|
|
274
|
+
forces a push. A conflict in the lock file is settled by rebuilding it with
|
|
275
|
+
[`commands.relock`](configuration.md#commandsrelock), and one in a file
|
|
276
|
+
that a [`resolver` plugin](plugins.md#resolver) of yours rebuilds, by
|
|
277
|
+
that skill. When the two sides of a conflict contradict each other, it
|
|
278
|
+
pushes nothing, comments why, and opens a ticket, because which side wins
|
|
279
|
+
is your decision.
|
|
245
280
|
|
|
246
281
|
**When to use it.** Ask it for one pull request ("resolve the conflicts on
|
|
247
282
|
280"). `factory-address-review` calls it when the pull request it is
|
|
@@ -255,8 +290,9 @@ no session when there is not.
|
|
|
255
290
|
### `factory-ticket-readiness`
|
|
256
291
|
|
|
257
292
|
Reads a refined ticket cold, as the session that will build it, and lists
|
|
258
|
-
every question it would still have to ask. `factory-refine` runs it
|
|
259
|
-
|
|
293
|
+
every question it would still have to ask. `factory-refine` runs it, and
|
|
294
|
+
a refiner of your own can: it reads any refiner's ticket against the same
|
|
295
|
+
list. Read-only.
|
|
260
296
|
|
|
261
297
|
### `factory-ui-reviewer`
|
|
262
298
|
|
|
@@ -265,16 +301,29 @@ Reads a change to how a website looks or responds. It runs
|
|
|
265
301
|
that changed, drives the states the change is about, and judges them
|
|
266
302
|
against built-in rules, your `design-guide` when you wrote one, and what
|
|
267
303
|
your `checks` printed. It is listed under
|
|
268
|
-
[`plugins`](configuration.md#
|
|
269
|
-
the `files` that should trigger it, and is written only
|
|
270
|
-
with `site` in its settings. Read-only, and slow.
|
|
304
|
+
[`plugins.build.reviewers`](configuration.md#pluginsbuild) like a reviewer
|
|
305
|
+
of your own, with the `files` that should trigger it, and is written only
|
|
306
|
+
to a repository with `site` in its settings. Read-only, and slow.
|
|
271
307
|
|
|
272
308
|
### `factory-test-reviewer`
|
|
273
309
|
|
|
274
|
-
Reads new or changed tests the way a test engineer
|
|
275
|
-
one behavior per test, each able to fail
|
|
276
|
-
|
|
277
|
-
|
|
310
|
+
Reads new or changed tests, whatever their kind, the way a test engineer
|
|
311
|
+
reviews a pull request: one behavior per test, each able to fail and
|
|
312
|
+
earning its place, with no waits on a timer. `factory-build` runs it,
|
|
313
|
+
unless your settings list other
|
|
314
|
+
[test reviewers](plugins.md#test-reviewer). Read-only, and it does not run
|
|
315
|
+
the suite.
|
|
278
316
|
|
|
279
317
|
It takes its specifics from your project's instructions beside your tests. Without one,
|
|
280
318
|
it applies only those general rules.
|
|
319
|
+
|
|
320
|
+
### `factory-e2e-reviewer`
|
|
321
|
+
|
|
322
|
+
Reads new or changed browser end-to-end and smoke tests for what only such
|
|
323
|
+
a test can get wrong: specs that go around their page objects, elements
|
|
324
|
+
not found the way a user finds them, waits on a timer, and a check that
|
|
325
|
+
needs no real browser. It is written only to a repository with
|
|
326
|
+
`commands.end-to-end` in its settings, and runs where it is listed under
|
|
327
|
+
[`plugins.test.reviewers`](configuration.md#pluginstest), beside
|
|
328
|
+
`factory-test-reviewer`, since that list, once written, is the whole list.
|
|
329
|
+
Read-only, and it does not run the suite.
|
package/docs/updating.md
CHANGED
|
@@ -3,6 +3,9 @@
|
|
|
3
3
|
**When a new version is released, a pull request appears in your
|
|
4
4
|
repository. You read it and merge it.** That is all you have to do.
|
|
5
5
|
|
|
6
|
+
One release asks more of you, because it changes the shape of your
|
|
7
|
+
settings file: [Moving to settings version 2](#moving-to-settings-version-2).
|
|
8
|
+
|
|
6
9
|
## What happens
|
|
7
10
|
|
|
8
11
|
1. Dependabot's weekly run finds the new version and opens one pull
|
|
@@ -58,6 +61,147 @@ factory doctor
|
|
|
58
61
|
Update by hand as above. `factory-deps` and its workflows are written only
|
|
59
62
|
once `.github/dependabot.yml` exists.
|
|
60
63
|
|
|
64
|
+
## Moving to settings version 2
|
|
65
|
+
|
|
66
|
+
One release changes the shape of `.claude/factory.yaml`, from version 1 to
|
|
67
|
+
version 2, and no command converts the file: you move it by hand, once.
|
|
68
|
+
Until you do, every command that reads the settings stops with:
|
|
69
|
+
|
|
70
|
+
```text
|
|
71
|
+
.claude/factory.yaml: version: must be 2: this file is version 1, see "Moving to settings version 2" in docs/updating.md
|
|
72
|
+
```
|
|
73
|
+
|
|
74
|
+
So `factory-deps` cannot run `factory sync` on that release's pull request,
|
|
75
|
+
and its checks fail until the file is moved. On the pull request's branch:
|
|
76
|
+
|
|
77
|
+
1. Edit `.claude/factory.yaml` as the table and the example below show.
|
|
78
|
+
A row applies only when your file has that key.
|
|
79
|
+
2. Add [`commands.gate`](configuration.md#commandsgate), which is new and
|
|
80
|
+
which a build cannot finish without. Put in it the commands your
|
|
81
|
+
`CLAUDE.md` names as the check before a task is done, usually what CI
|
|
82
|
+
runs, such as `npm run check`.
|
|
83
|
+
3. Once `commands.gate` holds the gate, change the gate's prose in your
|
|
84
|
+
`CLAUDE.md` to point at `npx --no-install factory gate`, so the two
|
|
85
|
+
cannot differ.
|
|
86
|
+
4. Run `factory config check`, then `factory sync`, and commit what
|
|
87
|
+
changed.
|
|
88
|
+
|
|
89
|
+
**It worked when** `factory config check` prints nothing, and
|
|
90
|
+
`factory sync --check` passes.
|
|
91
|
+
|
|
92
|
+
### Each key that moved or changed shape
|
|
93
|
+
|
|
94
|
+
| Version 1 | Version 2 |
|
|
95
|
+
| ------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------- |
|
|
96
|
+
| `version: 1` | `version: 2` |
|
|
97
|
+
| `before-commit`, at the top of the file | [`commands.before-commit`](configuration.md#commandsbefore-commit) |
|
|
98
|
+
| `build-setup`, at the top of the file | [`commands.build-setup`](configuration.md#commandsbuild-setup) |
|
|
99
|
+
| [`plugins`](configuration.md#plugins), one list, each item with a `role` | `plugins`, grouped by phase, each plugin listed under its role's key instead of a `role` field |
|
|
100
|
+
| A plugin with `role: mockups` | The one block [`plugins.refine.mockups`](configuration.md#pluginsrefine) |
|
|
101
|
+
| A plugin with `role: builder` | An item of the list [`plugins.build.builders`](configuration.md#pluginsbuild) |
|
|
102
|
+
| A plugin with `role: reviewer` | An item of the list `plugins.build.reviewers` |
|
|
103
|
+
| `ci-review` | [`pr-review`](configuration.md#pr-review), the same block under a new name |
|
|
104
|
+
| [`specs`](configuration.md#specs), one word | Still one word. It is now also a block, with `type` and [`check`](configuration.md#specscheck) |
|
|
105
|
+
|
|
106
|
+
Every other key keeps its name, its place, and its meaning.
|
|
107
|
+
|
|
108
|
+
`factory-test-reviewer` still runs by default, with nothing to write. Once
|
|
109
|
+
you write [`plugins.test.reviewers`](configuration.md#pluginstest), that
|
|
110
|
+
list is the whole list, so `factory-test-reviewer` runs only when you list
|
|
111
|
+
it there.
|
|
112
|
+
|
|
113
|
+
Before:
|
|
114
|
+
|
|
115
|
+
```yaml
|
|
116
|
+
version: 1
|
|
117
|
+
repository: your-name/your-repo
|
|
118
|
+
|
|
119
|
+
specs: openspec
|
|
120
|
+
|
|
121
|
+
before-commit:
|
|
122
|
+
- npm run -s format:check
|
|
123
|
+
- npx tsc --noEmit
|
|
124
|
+
|
|
125
|
+
build-setup:
|
|
126
|
+
- npx playwright install --with-deps chromium
|
|
127
|
+
|
|
128
|
+
plugins:
|
|
129
|
+
- skill: design-mockups
|
|
130
|
+
role: mockups
|
|
131
|
+
- skill: add-endpoint
|
|
132
|
+
role: builder
|
|
133
|
+
labels:
|
|
134
|
+
- new-endpoint
|
|
135
|
+
- agent: migration-reviewer
|
|
136
|
+
role: reviewer
|
|
137
|
+
files:
|
|
138
|
+
- db/migrations/**
|
|
139
|
+
```
|
|
140
|
+
|
|
141
|
+
After:
|
|
142
|
+
|
|
143
|
+
```yaml
|
|
144
|
+
version: 2
|
|
145
|
+
repository: your-name/your-repo
|
|
146
|
+
|
|
147
|
+
specs: openspec
|
|
148
|
+
|
|
149
|
+
commands:
|
|
150
|
+
before-commit:
|
|
151
|
+
- npm run -s format:check
|
|
152
|
+
- npx tsc --noEmit
|
|
153
|
+
build-setup:
|
|
154
|
+
- npx playwright install --with-deps chromium
|
|
155
|
+
# New, and needed: what a build runs to check its change.
|
|
156
|
+
gate:
|
|
157
|
+
- npm run check
|
|
158
|
+
|
|
159
|
+
plugins:
|
|
160
|
+
refine:
|
|
161
|
+
mockups:
|
|
162
|
+
skill: design-mockups
|
|
163
|
+
build:
|
|
164
|
+
builders:
|
|
165
|
+
- skill: add-endpoint
|
|
166
|
+
labels:
|
|
167
|
+
- new-endpoint
|
|
168
|
+
reviewers:
|
|
169
|
+
- agent: migration-reviewer
|
|
170
|
+
files:
|
|
171
|
+
- db/migrations/**
|
|
172
|
+
```
|
|
173
|
+
|
|
174
|
+
A file moved only partway says which key is left:
|
|
175
|
+
`before-commit: moved to commands.before-commit`, or
|
|
176
|
+
`plugins: must be grouped by phase: refine, build, test, conflicts`.
|
|
177
|
+
|
|
178
|
+
### What version 2 adds
|
|
179
|
+
|
|
180
|
+
Nothing here was in a version 1 file, so nothing moves. The first is
|
|
181
|
+
needed, and the rest are worth a look while the file is open.
|
|
182
|
+
|
|
183
|
+
- **The gate.** A build used to check its change with the commands your
|
|
184
|
+
agent's instructions named. It now runs `factory gate`, which runs
|
|
185
|
+
`commands.gate`. Copy those commands there, or a build stops with
|
|
186
|
+
`commands.gate is not set`.
|
|
187
|
+
- **One test alone, and one end-to-end spec alone:**
|
|
188
|
+
[`commands.test-one`](configuration.md#commandstest-one) and
|
|
189
|
+
[`commands.end-to-end`](configuration.md#commandsend-to-end), which the
|
|
190
|
+
skills run in place of naming a test runner.
|
|
191
|
+
- **The checks for browser end-to-end tests moved** out of
|
|
192
|
+
`factory-test-reviewer` into a second built-in agent,
|
|
193
|
+
`factory-e2e-reviewer`. A repository with such tests keeps them by
|
|
194
|
+
setting `commands.end-to-end` and listing both agents under
|
|
195
|
+
[`plugins.test.reviewers`](configuration.md#pluginstest).
|
|
196
|
+
- **Coverage, and the lock file:**
|
|
197
|
+
[`commands.coverage`](configuration.md#commandscoverage) and
|
|
198
|
+
[`commands.relock`](configuration.md#commandsrelock).
|
|
199
|
+
- **Four more roles for plugins:** your own refiner, prover, test
|
|
200
|
+
reviewers, and conflict resolvers ([Plugins](plugins.md#the-roles)).
|
|
201
|
+
- **The default branch is read, not assumed.** A repository whose default
|
|
202
|
+
branch is not `main` needs no setting: `factory sync` writes the
|
|
203
|
+
branch's name where the workflows need it.
|
|
204
|
+
|
|
61
205
|
## The commands
|
|
62
206
|
|
|
63
207
|
| Command | When |
|
|
@@ -84,7 +228,8 @@ not match `package-lock.json`.
|
|
|
84
228
|
| --------------------------------------------------------------------------- | --------------------------------------------------------------------- | -------------------------------------------------------------------------- |
|
|
85
229
|
| CI fails with "the factory's files are out of sync" | A factory file was edited by hand, or settings changed without a sync | Run `factory sync` and commit the result |
|
|
86
230
|
| `factory doctor` says your installed version is older than the repository's | You pulled an update and have not installed it | Run `npm ci` |
|
|
87
|
-
|
|
|
231
|
+
| A command stops with `version: must be 2` | The update changed the shape of the settings file | [Move the file](#moving-to-settings-version-2) |
|
|
232
|
+
| The update pull request conflicts with your default branch | Something else changed the same file | `factory-deps` resolves it on its next run, or close it and update by hand |
|
|
88
233
|
|
|
89
234
|
## Never edit a factory file
|
|
90
235
|
|
|
@@ -95,8 +240,9 @@ fails when one differs from what the installed version would write.
|
|
|
95
240
|
To change what the factory does:
|
|
96
241
|
|
|
97
242
|
- **For your repository only:** say so in your own instructions for the
|
|
98
|
-
agent, which win over the factory's rules,
|
|
99
|
-
[`rules`](configuration.md#rules) in your settings
|
|
243
|
+
agent, which win over the factory's rules, change a number under
|
|
244
|
+
[`rules`](configuration.md#rules) in your settings, or put a skill or
|
|
245
|
+
an agent of your own in a [plugin role](plugins.md).
|
|
100
246
|
- **For everyone:** change it in the factory, and it reaches you as an
|
|
101
247
|
update.
|
|
102
248
|
|
package/docs/workflow.md
CHANGED
|
@@ -13,7 +13,7 @@ each step, and what the factory will not do on its own.
|
|
|
13
13
|
| Build it | A session | Your machine, or the cloud when started from Ready | A tested change in a pull request that closes the ticket |
|
|
14
14
|
| Review it | The automated review, if you set it up | Your CI | Comments and a verdict on the pull request |
|
|
15
15
|
| Answer the review | The session that built it | Where it was built | Each comment fixed, or rejected with evidence |
|
|
16
|
-
| Merge it | **You**, or the merge policy for files you allowed | Your code host | The change on your
|
|
16
|
+
| Merge it | **You**, or the merge policy for files you allowed | Your code host | The change on your default branch, and the ticket closed |
|
|
17
17
|
|
|
18
18
|
Everything a session does, it does as you: through your account on the
|
|
19
19
|
code host and your coding agent's subscription, on your machine or in the
|
|
@@ -73,7 +73,9 @@ These hold in every repository. They are not settings.
|
|
|
73
73
|
it to Ready again retries it.
|
|
74
74
|
- **The order does not change.** A repository cannot add a state or reorder
|
|
75
75
|
them. A team that wants a security review between building and review adds
|
|
76
|
-
a [reviewer](plugins.md), not a column.
|
|
76
|
+
a [reviewer](plugins.md#reviewer), not a column. A
|
|
77
|
+
[plugin](plugins.md#the-roles) can take over a step, such as refining a
|
|
78
|
+
ticket or proving a test, where the step stands.
|
|
77
79
|
- **One session holds a ticket at a time.** The claim is a comment on the
|
|
78
80
|
ticket. A second session that tries is told who holds it and stops.
|
|
79
81
|
|
|
@@ -112,12 +114,13 @@ conflict, and the session that owns the pull request resolves it.
|
|
|
112
114
|
A change under about 30 lines outside tests (30 by default,
|
|
113
115
|
[`rules.small-change-lines`](configuration.md#rules)), adding no new
|
|
114
116
|
component and no new state, is **small**. It skips the heavier steps: no
|
|
115
|
-
separate spec, no readiness read,
|
|
116
|
-
or checks the change. The first message of
|
|
117
|
-
taking, so you can overrule it before it
|
|
117
|
+
separate spec, no readiness read, no read by the test reviewers, and one
|
|
118
|
+
test that reproduces the defect or checks the change. The first message of
|
|
119
|
+
the work says which path it is taking, so you can overrule it before it
|
|
120
|
+
starts.
|
|
118
121
|
|
|
119
|
-
|
|
120
|
-
|
|
122
|
+
Two kinds of small change keep the test reviewers: a change to tests
|
|
123
|
+
alone, and code that builds what is sent to an outside service.
|
|
121
124
|
|
|
122
125
|
## Follow-ups
|
|
123
126
|
|
|
@@ -172,14 +175,14 @@ Every pull request gets one of two labels:
|
|
|
172
175
|
Two more things guard a merge:
|
|
173
176
|
|
|
174
177
|
- **"Review verdict"** is a status, which you can make required on your
|
|
175
|
-
|
|
178
|
+
default branch, that passes only when the automated
|
|
176
179
|
review of the newest commit said it is ready, or an approver overrode it
|
|
177
180
|
with the `verdict: override` label. Sessions never add that label.
|
|
178
181
|
- **Every review thread must be resolved.** A session answers each one,
|
|
179
182
|
fixed or rejected with evidence, before resolving it.
|
|
180
183
|
|
|
181
|
-
Both the labeling and the verdict run from your
|
|
182
|
-
rules, so a pull request cannot change how it is judged.
|
|
184
|
+
Both the labeling and the verdict run from your default branch's copy of
|
|
185
|
+
the rules, so a pull request cannot change how it is judged.
|
|
183
186
|
|
|
184
187
|
A session never merges, never turns auto-merge on, and never overrides a
|
|
185
188
|
verdict.
|
package/package.json
CHANGED
package/review.md
CHANGED
|
@@ -9,8 +9,8 @@ defend.
|
|
|
9
9
|
|
|
10
10
|
## Before you review
|
|
11
11
|
|
|
12
|
-
1. Read `CLAUDE.md`,
|
|
13
|
-
`CLAUDE.md` lists, in full. They are the project's rules, and most
|
|
12
|
+
1. Read `CLAUDE.md`, the files it imports, and every area guide "Rules by
|
|
13
|
+
area" in `CLAUDE.md` lists, in full. They are the project's rules, and most
|
|
14
14
|
findings worth raising break one of them. Then read
|
|
15
15
|
`.github/review-notes.md` when it exists: what this repository's review
|
|
16
16
|
checks beyond this file.
|
|
@@ -24,16 +24,25 @@ defend.
|
|
|
24
24
|
gh api repos/REPO/pulls/PR_NUMBER/comments --paginate
|
|
25
25
|
```
|
|
26
26
|
|
|
27
|
+
The commands below write the default branch's name as DEFAULT. This
|
|
28
|
+
prints it:
|
|
29
|
+
|
|
30
|
+
```bash
|
|
31
|
+
gh api repos/REPO --jq .default_branch
|
|
32
|
+
```
|
|
33
|
+
|
|
27
34
|
Your earlier summaries contain `<!-- claude-review sha=SHA -->`. If one
|
|
28
35
|
exists and that SHA is an ancestor of the head
|
|
29
36
|
(`git merge-base --is-ancestor SHA HEAD`), compare
|
|
30
|
-
`git merge-base SHA origin/
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
37
|
+
`git merge-base SHA origin/DEFAULT` with
|
|
38
|
+
`git merge-base HEAD origin/DEFAULT`.
|
|
39
|
+
If they differ, the default branch was merged in since that review, so
|
|
40
|
+
review `git diff origin/DEFAULT...HEAD`, the pull request's own changes
|
|
41
|
+
as they now stand. If they match, review only `git diff SHA...HEAD`.
|
|
42
|
+
Otherwise review the whole pull request,
|
|
43
|
+
`git diff origin/DEFAULT...HEAD`. Use `origin/DEFAULT` rather than the
|
|
44
|
+
base SHA you were given, which comes from the event and can be older
|
|
45
|
+
than a merge from the default branch.
|
|
37
46
|
|
|
38
47
|
If that SHA is the head itself, this is a re-run after the author
|
|
39
48
|
replied without pushing. There is no new code: read the replies since
|
|
@@ -69,9 +78,9 @@ defend.
|
|
|
69
78
|
- **Correctness.** A defect a user would hit, a regression, a race, data
|
|
70
79
|
that is silently dropped.
|
|
71
80
|
- **What it was asked to do.** A Spec line or criterion from step 4 that
|
|
72
|
-
the whole pull request, `git diff origin/
|
|
81
|
+
the whole pull request, `git diff origin/DEFAULT...HEAD`, does not meet, or
|
|
73
82
|
meets only in part, is a finding, since the merge closes the issue as
|
|
74
|
-
done: High when a
|
|
83
|
+
done: High when a user would see the gap, Medium otherwise. Behavior
|
|
75
84
|
no line asked for is Medium, unless the body or the owner's comments on
|
|
76
85
|
the pull request explain it. Quote the line either way.
|
|
77
86
|
- **Tests that cannot fail.** A test whose name and body disagree, a
|