@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.
- package/README.md +20 -20
- 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/agent/claude-code.d.mts +3 -0
- package/dist/agent/claude-code.mjs +89 -0
- package/dist/agent/index.d.mts +2 -0
- package/dist/agent/index.mjs +5 -0
- package/dist/board.mjs +1 -1
- package/dist/cli.mjs +46 -4
- package/dist/code-host/github-setup.d.mts +5 -0
- package/dist/code-host/github-setup.mjs +133 -0
- package/dist/code-host/github.mjs +4 -0
- package/dist/code-host/index.d.mts +1 -1
- package/dist/code-host/index.mjs +2 -1
- package/dist/code-host/types.d.mts +2 -0
- package/dist/commands.d.mts +16 -0
- package/dist/commands.mjs +129 -0
- package/dist/config.d.mts +87 -20
- package/dist/config.mjs +344 -89
- package/dist/deps.d.mts +7 -4
- package/dist/deps.mjs +20 -9
- package/dist/doctor.d.mts +9 -16
- package/dist/doctor.mjs +71 -68
- package/dist/explain.d.mts +4 -0
- package/dist/explain.mjs +174 -0
- package/dist/guard-commit.d.mts +7 -2
- package/dist/guard-commit.mjs +58 -21
- package/dist/init.d.mts +12 -14
- package/dist/init.mjs +194 -136
- package/dist/lib/default-branch.d.mts +35 -0
- package/dist/lib/default-branch.mjs +117 -0
- package/dist/lib/has-command.d.mts +5 -0
- package/dist/lib/has-command.mjs +8 -0
- package/dist/lib/listed.d.mts +2 -0
- package/dist/lib/listed.mjs +4 -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 +12 -2
- package/dist/lib/work-status.mjs +14 -3
- package/dist/parts.d.mts +18 -15
- package/dist/parts.mjs +15 -43
- package/dist/patch-coverage.d.mts +13 -0
- package/dist/patch-coverage.mjs +73 -0
- package/dist/poller.d.mts +20 -3
- package/dist/poller.mjs +62 -15
- package/dist/pr-watch.d.mts +3 -2
- package/dist/pr-watch.mjs +22 -5
- package/dist/pr.mjs +34 -2
- package/dist/remove.d.mts +11 -0
- package/dist/remove.mjs +156 -0
- package/dist/runner/github-actions.d.mts +1 -1
- package/dist/runner/github-actions.mjs +12 -0
- package/dist/runner/index.d.mts +1 -1
- package/dist/runner/index.mjs +2 -1
- package/dist/runner/setup.d.mts +2 -0
- package/dist/runner/setup.mjs +22 -0
- package/dist/runner/types.d.mts +3 -0
- package/dist/runner/types.mjs +0 -2
- package/dist/session-start.d.mts +23 -13
- package/dist/session-start.mjs +56 -44
- package/dist/setup.d.mts +98 -0
- package/dist/setup.mjs +3 -0
- package/dist/site/servers.d.mts +6 -2
- package/dist/site/servers.mjs +14 -9
- package/dist/site.mjs +2 -2
- package/dist/status.d.mts +4 -4
- package/dist/status.mjs +8 -7
- package/dist/sync.d.mts +26 -2
- package/dist/sync.mjs +177 -13
- package/dist/ticket.mjs +19 -1
- package/dist/tickets/github-setup.d.mts +2 -0
- package/dist/tickets/github-setup.mjs +50 -0
- package/dist/tickets/github.mjs +0 -2
- package/dist/tickets/index.mjs +2 -1
- package/dist/tickets/transport.mjs +1 -3
- package/dist/tickets/types.mjs +0 -2
- package/dist/tool-names.d.mts +11 -0
- package/dist/tool-names.mjs +20 -0
- package/dist/tools.d.mts +56 -0
- package/dist/tools.mjs +76 -0
- package/docs/builds.md +111 -59
- package/docs/cli.md +106 -69
- package/docs/configuration.md +489 -171
- package/docs/design.md +18 -5
- package/docs/developing.md +179 -73
- package/docs/existing-repo.md +25 -12
- package/docs/github/by-hand.md +334 -0
- package/docs/github/reference.md +76 -67
- package/docs/github/setup.md +105 -286
- package/docs/glossary.md +18 -7
- package/docs/limitations.md +39 -12
- package/docs/plugins.md +305 -56
- package/docs/quick-start.md +85 -100
- package/docs/removing.md +37 -17
- package/docs/skills.md +121 -62
- package/docs/updating.md +150 -9
- package/docs/workflow.md +23 -19
- package/package.json +1 -1
- package/poller.Dockerfile +10 -18
- package/review.md +20 -11
- package/rules.md +36 -30
- package/settings.schema.json +313 -69
- 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 +17 -8
- 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 +80 -0
- package/workflows/factory-build.yml +6 -5
- package/workflows/factory-conflicts.yml +8 -8
- package/workflows/factory-deps-auto-merge.yml +3 -2
- package/workflows/factory-deps.yml +1 -1
- package/workflows/factory-poller.yml +46 -0
- 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
|
+
[plug-in](plugins.md#the-slots) 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` |
|
|
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
|
|
|
@@ -57,7 +69,7 @@ acceptance criteria cannot be built; `factory-build` sends it here.
|
|
|
57
69
|
**What it reads.** The ticket and its comments, the open tickets that touch
|
|
58
70
|
the same code, the code itself, your project's instructions for the agent
|
|
59
71
|
(`CLAUDE.md` files, on Claude Code), and the existing
|
|
60
|
-
spec when `specs` is on.
|
|
72
|
+
spec when [`specs`](configuration.md#specs) is on.
|
|
61
73
|
|
|
62
74
|
**What it writes.**
|
|
63
75
|
|
|
@@ -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` plug-in](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` plug-ins](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` plug-in](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,21 +138,25 @@ 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
|
|
|
123
|
-
**Defaults you can change
|
|
124
|
-
change
|
|
149
|
+
**Defaults you can change.**
|
|
150
|
+
[`rules.small-change-lines`](configuration.md#rules), default 30: a change
|
|
151
|
+
under it takes the lighter path [Workflow](workflow.md) describes.
|
|
125
152
|
|
|
126
153
|
## `factory-address-review`
|
|
127
154
|
|
|
128
155
|
**What it does.** Works everything standing between a pull request and its
|
|
129
156
|
merge: the threads from the automated review, your own comments, failed
|
|
130
|
-
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.
|
|
131
160
|
|
|
132
161
|
**When to use it.** After every push to a branch with an open pull request.
|
|
133
162
|
The session that built the pull request runs it without being asked.
|
|
@@ -148,7 +177,7 @@ something to do, and starts no session when there is not.
|
|
|
148
177
|
**What it writes.** Commits on the branch, a reply on each thread, and one
|
|
149
178
|
report.
|
|
150
179
|
|
|
151
|
-
**When it stops.** After two rounds (`rules.review-rounds
|
|
180
|
+
**When it stops.** After two rounds (`rules.review-rounds`), whatever
|
|
152
181
|
is still in dispute goes to you instead of through another round.
|
|
153
182
|
|
|
154
183
|
**What it never does.** Resolve a thread it neither fixed nor disproved.
|
|
@@ -159,7 +188,8 @@ Dismiss a failing test as flaky without reproducing it. Merge.
|
|
|
159
188
|
**What it does.** Finds the cause of a bug, a failing or flaky test, or a
|
|
160
189
|
slowdown, before changing any code. It starts by building one command that
|
|
161
190
|
fails on the exact symptom, shrinks it, ranks the possible causes, and
|
|
162
|
-
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`.
|
|
163
193
|
|
|
164
194
|
**When to use it.** When something is broken, failing, flaky, or slow, and
|
|
165
195
|
the cause is not already known.
|
|
@@ -179,10 +209,13 @@ locks nothing in.
|
|
|
179
209
|
|
|
180
210
|
**What it never does.** Leave a mutation in place.
|
|
181
211
|
|
|
212
|
+
It is the [prover](plugins.md#prover) a build calls, unless your settings
|
|
213
|
+
name one of your own.
|
|
214
|
+
|
|
182
215
|
## `factory-deps`
|
|
183
216
|
|
|
184
217
|
**What it does.** Moves every open dependency pull request one step closer
|
|
185
|
-
to merged: resolves a conflict with your
|
|
218
|
+
to merged: resolves a conflict with your default branch, fixes failing checks,
|
|
186
219
|
does the migration a major version asks for, and opens a ticket for
|
|
187
220
|
anything it cannot fix.
|
|
188
221
|
|
|
@@ -214,11 +247,12 @@ does not get it at all.
|
|
|
214
247
|
or one made by editing a running page instead of building it. Leave a
|
|
215
248
|
scratch worktree behind.
|
|
216
249
|
|
|
217
|
-
## `factory-trace`
|
|
250
|
+
## `factory-trace`
|
|
218
251
|
|
|
219
252
|
**What it does.** A rule written for one kind of change can be wrong for
|
|
220
|
-
every other kind. Before a change to the rules, a skill,
|
|
221
|
-
|
|
253
|
+
every other kind. Before a change to the rules, a skill, an agent, or a
|
|
254
|
+
workflow that alters what triggers a step, who runs, or when is marked
|
|
255
|
+
ready, this has a fresh agent trace each kind of change your
|
|
222
256
|
repository gets through the rules as they would stand, and report any kind
|
|
223
257
|
that got heavier, lighter, or ambiguous, and any two rules that now
|
|
224
258
|
disagree.
|
|
@@ -226,13 +260,23 @@ disagree.
|
|
|
226
260
|
**What it reads.** `.claude/change-types.md`, your list of the kinds of
|
|
227
261
|
change your repository gets, each with a real example.
|
|
228
262
|
|
|
263
|
+
**What it writes.** The fresh agent's report: on the pull request when the
|
|
264
|
+
branch has one, and otherwise in the session.
|
|
265
|
+
|
|
266
|
+
**When it stops.** Before starting an agent, when `.claude/change-types.md`
|
|
267
|
+
is missing. The pull request stays a draft, and a comment on it shows the
|
|
268
|
+
file's shape for you to write.
|
|
269
|
+
|
|
229
270
|
## `factory-resolve-conflicts`
|
|
230
271
|
|
|
231
|
-
**What it does.** Merges your
|
|
232
|
-
with it, runs the gate, and pushes the merge. It never rebases or
|
|
233
|
-
push.
|
|
234
|
-
|
|
235
|
-
|
|
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` plug-in](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.
|
|
236
280
|
|
|
237
281
|
**When to use it.** Ask it for one pull request ("resolve the conflicts on
|
|
238
282
|
280"). `factory-address-review` calls it when the pull request it is
|
|
@@ -246,25 +290,40 @@ no session when there is not.
|
|
|
246
290
|
### `factory-ticket-readiness`
|
|
247
291
|
|
|
248
292
|
Reads a refined ticket cold, as the session that will build it, and lists
|
|
249
|
-
every question it would still have to ask. `factory-refine` runs it
|
|
250
|
-
|
|
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.
|
|
251
296
|
|
|
252
297
|
### `factory-ui-reviewer`
|
|
253
298
|
|
|
254
299
|
Reads a change to how a website looks or responds. It runs
|
|
255
|
-
`factory site compare`, reads the before and after pictures of the pages
|
|
256
|
-
changed, drives the states the change is about, and judges them
|
|
257
|
-
rules, your `design-guide` when you wrote one, and what
|
|
258
|
-
|
|
259
|
-
|
|
260
|
-
|
|
300
|
+
`factory site compare`, reads the before and after pictures of the pages
|
|
301
|
+
that changed, drives the states the change is about, and judges them
|
|
302
|
+
against built-in rules, your `design-guide` when you wrote one, and what
|
|
303
|
+
your `checks` printed. It is listed under
|
|
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.
|
|
261
307
|
|
|
262
308
|
### `factory-test-reviewer`
|
|
263
309
|
|
|
264
|
-
Reads new or changed tests the way a test engineer
|
|
265
|
-
one behavior per test, each able to fail
|
|
266
|
-
|
|
267
|
-
|
|
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.
|
|
268
316
|
|
|
269
317
|
It takes its specifics from your project's instructions beside your tests. Without one,
|
|
270
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
|
@@ -1,12 +1,11 @@
|
|
|
1
|
-
# Updating
|
|
2
|
-
|
|
3
|
-
Nothing on this page works until the package is published. Until then, a
|
|
4
|
-
new version reaches your repository the way it was installed, and
|
|
5
|
-
`factory sync` applies it.
|
|
1
|
+
# Updating
|
|
6
2
|
|
|
7
3
|
**When a new version is released, a pull request appears in your
|
|
8
4
|
repository. You read it and merge it.** That is all you have to do.
|
|
9
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
|
+
|
|
10
9
|
## What happens
|
|
11
10
|
|
|
12
11
|
1. Dependabot's weekly run finds the new version and opens one pull
|
|
@@ -17,7 +16,7 @@ repository. You read it and merge it.** That is all you have to do.
|
|
|
17
16
|
runs `factory sync` on its branch and adds what it wrote as a second
|
|
18
17
|
commit. Until it has, CI's `factory sync --check` fails.
|
|
19
18
|
3. You read it and merge it. It never merges itself, whatever your
|
|
20
|
-
`auto-merge` settings allow.
|
|
19
|
+
[`auto-merge`](configuration.md#auto-merge) settings allow.
|
|
21
20
|
4. Everyone working on the repository, you included, pulls and runs
|
|
22
21
|
`npm ci`, as after any dependency change.
|
|
23
22
|
|
|
@@ -62,6 +61,146 @@ factory doctor
|
|
|
62
61
|
Update by hand as above. `factory-deps` and its workflows are written only
|
|
63
62
|
once `.github/dependabot.yml` exists.
|
|
64
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 plug-in in a slot, with no `role` |
|
|
100
|
+
| A plug-in with `role: mockups` | The one block [`plugins.refine.mockups`](configuration.md#pluginsrefine) |
|
|
101
|
+
| A plug-in with `role: builder` | An item of the list [`plugins.build.builders`](configuration.md#pluginsbuild) |
|
|
102
|
+
| A plug-in with `role: reviewer` | An item of the list `plugins.build.reviewers` |
|
|
103
|
+
| [`specs`](configuration.md#specs), one word | Still one word. It is now also a block, with `type` and [`check`](configuration.md#specscheck) |
|
|
104
|
+
|
|
105
|
+
Every other key keeps its name, its place, and its meaning.
|
|
106
|
+
|
|
107
|
+
`factory-test-reviewer` still runs by default, with nothing to write. Once
|
|
108
|
+
you write [`plugins.test.reviewers`](configuration.md#pluginstest), that
|
|
109
|
+
list is the whole list, so `factory-test-reviewer` runs only when you list
|
|
110
|
+
it there.
|
|
111
|
+
|
|
112
|
+
Before:
|
|
113
|
+
|
|
114
|
+
```yaml
|
|
115
|
+
version: 1
|
|
116
|
+
repository: your-name/your-repo
|
|
117
|
+
|
|
118
|
+
specs: openspec
|
|
119
|
+
|
|
120
|
+
before-commit:
|
|
121
|
+
- npm run -s format:check
|
|
122
|
+
- npx tsc --noEmit
|
|
123
|
+
|
|
124
|
+
build-setup:
|
|
125
|
+
- npx playwright install --with-deps chromium
|
|
126
|
+
|
|
127
|
+
plugins:
|
|
128
|
+
- skill: design-mockups
|
|
129
|
+
role: mockups
|
|
130
|
+
- skill: add-endpoint
|
|
131
|
+
role: builder
|
|
132
|
+
labels:
|
|
133
|
+
- new-endpoint
|
|
134
|
+
- agent: migration-reviewer
|
|
135
|
+
role: reviewer
|
|
136
|
+
files:
|
|
137
|
+
- db/migrations/**
|
|
138
|
+
```
|
|
139
|
+
|
|
140
|
+
After:
|
|
141
|
+
|
|
142
|
+
```yaml
|
|
143
|
+
version: 2
|
|
144
|
+
repository: your-name/your-repo
|
|
145
|
+
|
|
146
|
+
specs: openspec
|
|
147
|
+
|
|
148
|
+
commands:
|
|
149
|
+
before-commit:
|
|
150
|
+
- npm run -s format:check
|
|
151
|
+
- npx tsc --noEmit
|
|
152
|
+
build-setup:
|
|
153
|
+
- npx playwright install --with-deps chromium
|
|
154
|
+
# New, and needed: what a build runs to check its change.
|
|
155
|
+
gate:
|
|
156
|
+
- npm run check
|
|
157
|
+
|
|
158
|
+
plugins:
|
|
159
|
+
refine:
|
|
160
|
+
mockups:
|
|
161
|
+
skill: design-mockups
|
|
162
|
+
build:
|
|
163
|
+
builders:
|
|
164
|
+
- skill: add-endpoint
|
|
165
|
+
labels:
|
|
166
|
+
- new-endpoint
|
|
167
|
+
reviewers:
|
|
168
|
+
- agent: migration-reviewer
|
|
169
|
+
files:
|
|
170
|
+
- db/migrations/**
|
|
171
|
+
```
|
|
172
|
+
|
|
173
|
+
A file moved only partway says which key is left:
|
|
174
|
+
`before-commit: moved to commands.before-commit`, or
|
|
175
|
+
`plugins: must be grouped by phase: refine, build, test, conflicts`.
|
|
176
|
+
|
|
177
|
+
### What version 2 adds
|
|
178
|
+
|
|
179
|
+
Nothing here was in a version 1 file, so nothing moves. The first is
|
|
180
|
+
needed, and the rest are worth a look while the file is open.
|
|
181
|
+
|
|
182
|
+
- **The gate.** A build used to check its change with the commands your
|
|
183
|
+
agent's instructions named. It now runs `factory gate`, which runs
|
|
184
|
+
`commands.gate`. Copy those commands there, or a build stops with
|
|
185
|
+
`commands.gate is not set`.
|
|
186
|
+
- **One test alone, and one end-to-end spec alone:**
|
|
187
|
+
[`commands.test-one`](configuration.md#commandstest-one) and
|
|
188
|
+
[`commands.end-to-end`](configuration.md#commandsend-to-end), which the
|
|
189
|
+
skills run in place of naming a test runner.
|
|
190
|
+
- **The checks for browser end-to-end tests moved** out of
|
|
191
|
+
`factory-test-reviewer` into a second built-in agent,
|
|
192
|
+
`factory-e2e-reviewer`. A repository with such tests keeps them by
|
|
193
|
+
setting `commands.end-to-end` and listing both agents under
|
|
194
|
+
[`plugins.test.reviewers`](configuration.md#pluginstest).
|
|
195
|
+
- **Coverage, and the lock file:**
|
|
196
|
+
[`commands.coverage`](configuration.md#commandscoverage) and
|
|
197
|
+
[`commands.relock`](configuration.md#commandsrelock).
|
|
198
|
+
- **Four more slots for plug-ins:** your own refiner, prover, test
|
|
199
|
+
reviewers, and conflict resolvers ([Plug-ins](plugins.md#the-slots)).
|
|
200
|
+
- **The default branch is read, not assumed.** A repository whose default
|
|
201
|
+
branch is not `main` needs no setting: `factory sync` writes the
|
|
202
|
+
branch's name where the workflows need it.
|
|
203
|
+
|
|
65
204
|
## The commands
|
|
66
205
|
|
|
67
206
|
| Command | When |
|
|
@@ -88,7 +227,8 @@ not match `package-lock.json`.
|
|
|
88
227
|
| --------------------------------------------------------------------------- | --------------------------------------------------------------------- | -------------------------------------------------------------------------- |
|
|
89
228
|
| 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 |
|
|
90
229
|
| `factory doctor` says your installed version is older than the repository's | You pulled an update and have not installed it | Run `npm ci` |
|
|
91
|
-
|
|
|
230
|
+
| 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) |
|
|
231
|
+
| 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 |
|
|
92
232
|
|
|
93
233
|
## Never edit a factory file
|
|
94
234
|
|
|
@@ -99,8 +239,9 @@ fails when one differs from what the installed version would write.
|
|
|
99
239
|
To change what the factory does:
|
|
100
240
|
|
|
101
241
|
- **For your repository only:** say so in your own instructions for the
|
|
102
|
-
agent, which win over the factory's rules,
|
|
103
|
-
[`rules`](configuration.md#rules) in your settings
|
|
242
|
+
agent, which win over the factory's rules, change a number under
|
|
243
|
+
[`rules`](configuration.md#rules) in your settings, or put a skill or
|
|
244
|
+
an agent of your own in a [plug-in slot](plugins.md).
|
|
104
245
|
- **For everyone:** change it in the factory, and it reaches you as an
|
|
105
246
|
update.
|
|
106
247
|
|
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
|
+
[plug-in](plugins.md#the-slots) 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
|
|
|
@@ -102,21 +104,23 @@ That is why a ticket's history survives even if the board is rebuilt.
|
|
|
102
104
|
When building one ticket first would break another, or mean redoing work,
|
|
103
105
|
the second is recorded as blocked by the first, using the ticket system's
|
|
104
106
|
own relationship between tickets. A build never starts on a ticket with an open blocker, and
|
|
105
|
-
starts
|
|
107
|
+
starts at the poller's first pass after the blocker closes if the ticket is in Ready.
|
|
106
108
|
|
|
107
109
|
Two tickets touching the same file is not a blocker. That is a merge
|
|
108
110
|
conflict, and the session that owns the pull request resolves it.
|
|
109
111
|
|
|
110
112
|
## Sizing the work to the change
|
|
111
113
|
|
|
112
|
-
A change under about 30 lines outside tests
|
|
113
|
-
|
|
114
|
-
|
|
115
|
-
|
|
116
|
-
|
|
114
|
+
A change under about 30 lines outside tests (30 by default,
|
|
115
|
+
[`rules.small-change-lines`](configuration.md#rules)), adding no new
|
|
116
|
+
component and no new state, is **small**. It skips the heavier steps: no
|
|
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.
|
|
117
121
|
|
|
118
|
-
|
|
119
|
-
|
|
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.
|
|
120
124
|
|
|
121
125
|
## Follow-ups
|
|
122
126
|
|
|
@@ -171,25 +175,25 @@ Every pull request gets one of two labels:
|
|
|
171
175
|
Two more things guard a merge:
|
|
172
176
|
|
|
173
177
|
- **"Review verdict"** is a status, which you can make required on your
|
|
174
|
-
|
|
178
|
+
default branch, that passes only when the automated
|
|
175
179
|
review of the newest commit said it is ready, or an approver overrode it
|
|
176
180
|
with the `verdict: override` label. Sessions never add that label.
|
|
177
181
|
- **Every review thread must be resolved.** A session answers each one,
|
|
178
182
|
fixed or rejected with evidence, before resolving it.
|
|
179
183
|
|
|
180
|
-
Both the labeling and the verdict run from your
|
|
181
|
-
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.
|
|
182
186
|
|
|
183
187
|
A session never merges, never turns auto-merge on, and never overrides a
|
|
184
188
|
verdict.
|
|
185
189
|
|
|
186
190
|
## A change your users will see
|
|
187
191
|
|
|
188
|
-
With `specs: openspec
|
|
189
|
-
see, and is not small, carries the `spec`
|
|
190
|
-
section of plain "When this, then that"
|
|
191
|
-
into an OpenSpec change, builds to
|
|
192
|
-
`openspec/specs/` in the same pull request, so
|
|
193
|
-
what the project does now.
|
|
192
|
+
With [`specs: openspec`](configuration.md#specs), a change that adds or
|
|
193
|
+
alters behavior someone can see, and is not small, carries the `spec`
|
|
194
|
+
label. Its ticket holds a "Spec" section of plain "When this, then that"
|
|
195
|
+
lines. The build turns those lines into an OpenSpec change, builds to
|
|
196
|
+
them, and folds them into `openspec/specs/` in the same pull request, so
|
|
197
|
+
that folder always describes what the project does now.
|
|
194
198
|
|
|
195
199
|
With `specs: none`, the ticket's acceptance criteria are the whole spec.
|
package/package.json
CHANGED
package/poller.Dockerfile
CHANGED
|
@@ -1,21 +1,13 @@
|
|
|
1
|
-
# The poller's image
|
|
2
|
-
#
|
|
3
|
-
#
|
|
4
|
-
#
|
|
5
|
-
# the
|
|
6
|
-
# launcher is not used. A test fails when the poller imports a file not
|
|
7
|
-
# copied below.
|
|
1
|
+
# The poller's image: one published version of the factory, installed from
|
|
2
|
+
# npm, and nothing else. The release workflow builds it with VERSION set to
|
|
3
|
+
# the version it has just published, and pushes it to GitHub's container
|
|
4
|
+
# registry. It runs outside any checkout, so the `factory` launcher runs
|
|
5
|
+
# the installed copy itself.
|
|
8
6
|
FROM node:22-slim
|
|
7
|
+
ARG VERSION
|
|
8
|
+
LABEL org.opencontainers.image.source="https://github.com/davidbyoung/software-factory"
|
|
9
9
|
WORKDIR /app
|
|
10
|
-
|
|
11
|
-
|
|
12
|
-
COPY src/lib/gh.mts src/lib/gh.mts
|
|
13
|
-
COPY src/tickets/types.mts src/tickets/types.mts
|
|
14
|
-
COPY src/tickets/transport.mts src/tickets/transport.mts
|
|
15
|
-
COPY src/tickets/github.mts src/tickets/github.mts
|
|
16
|
-
COPY src/code-host/types.mts src/code-host/types.mts
|
|
17
|
-
COPY src/code-host/github.mts src/code-host/github.mts
|
|
18
|
-
COPY src/runner/types.mts src/runner/types.mts
|
|
19
|
-
COPY src/runner/github-actions.mts src/runner/github-actions.mts
|
|
10
|
+
RUN npm install --omit=dev --no-audit --no-fund --no-save \
|
|
11
|
+
"@davidbyoung/software-factory@${VERSION}"
|
|
20
12
|
USER node
|
|
21
|
-
CMD ["node", "
|
|
13
|
+
CMD ["node", "node_modules/@davidbyoung/software-factory/bin/factory.js", "poller"]
|