@davidbyoung/software-factory 0.1.3 → 0.1.4

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (72) hide show
  1. package/README.md +12 -11
  2. package/actions/factory-agent/action.yml +1 -1
  3. package/agents/factory-e2e-reviewer.md +102 -0
  4. package/agents/factory-test-reviewer.md +26 -64
  5. package/agents/factory-ticket-readiness.md +14 -6
  6. package/dist/cli.mjs +29 -2
  7. package/dist/commands.d.mts +16 -0
  8. package/dist/commands.mjs +129 -0
  9. package/dist/config.d.mts +61 -13
  10. package/dist/config.mjs +267 -65
  11. package/dist/deps.d.mts +7 -4
  12. package/dist/deps.mjs +20 -9
  13. package/dist/doctor.d.mts +3 -2
  14. package/dist/doctor.mjs +19 -4
  15. package/dist/explain.d.mts +4 -2
  16. package/dist/explain.mjs +66 -19
  17. package/dist/guard-commit.d.mts +7 -2
  18. package/dist/guard-commit.mjs +58 -21
  19. package/dist/init.d.mts +4 -2
  20. package/dist/init.mjs +15 -5
  21. package/dist/lib/default-branch.d.mts +35 -0
  22. package/dist/lib/default-branch.mjs +117 -0
  23. package/dist/lib/refined-check.d.mts +7 -0
  24. package/dist/lib/refined-check.mjs +76 -0
  25. package/dist/patch-coverage.d.mts +13 -0
  26. package/dist/patch-coverage.mjs +73 -0
  27. package/dist/pr-watch.d.mts +3 -2
  28. package/dist/pr-watch.mjs +22 -5
  29. package/dist/pr.mjs +34 -2
  30. package/dist/session-start.d.mts +23 -13
  31. package/dist/session-start.mjs +56 -44
  32. package/dist/site/servers.d.mts +6 -2
  33. package/dist/site/servers.mjs +14 -9
  34. package/dist/site.mjs +2 -2
  35. package/dist/sync.d.mts +8 -2
  36. package/dist/sync.mjs +40 -6
  37. package/dist/ticket.mjs +19 -1
  38. package/docs/builds.md +8 -8
  39. package/docs/cli.md +82 -45
  40. package/docs/configuration.md +455 -139
  41. package/docs/design.md +17 -4
  42. package/docs/developing.md +37 -6
  43. package/docs/existing-repo.md +8 -6
  44. package/docs/github/by-hand.md +23 -10
  45. package/docs/github/reference.md +19 -14
  46. package/docs/github/setup.md +12 -9
  47. package/docs/glossary.md +13 -3
  48. package/docs/limitations.md +27 -2
  49. package/docs/plugins.md +302 -48
  50. package/docs/quick-start.md +36 -8
  51. package/docs/removing.md +1 -1
  52. package/docs/skills.md +101 -52
  53. package/docs/updating.md +148 -3
  54. package/docs/workflow.md +13 -10
  55. package/package.json +1 -1
  56. package/review.md +20 -11
  57. package/rules.md +22 -18
  58. package/settings.schema.json +289 -69
  59. package/skills/factory-address-review/SKILL.md +50 -30
  60. package/skills/factory-build/SKILL.md +75 -22
  61. package/skills/factory-deps/SKILL.md +46 -21
  62. package/skills/factory-design/SKILL.md +17 -8
  63. package/skills/factory-diagnose/SKILL.md +22 -20
  64. package/skills/factory-mutate/SKILL.md +38 -24
  65. package/skills/factory-refine/SKILL.md +55 -31
  66. package/skills/factory-resolve-conflicts/SKILL.md +76 -34
  67. package/skills/factory-trace/SKILL.md +3 -2
  68. package/workflows/factory-build.yml +1 -1
  69. package/workflows/factory-conflicts.yml +8 -8
  70. package/workflows/factory-deps.yml +1 -1
  71. package/workflows/factory-review.yml +1 -1
  72. 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-ticket-readiness` | Always |
28
- | `factory-test-reviewer` | Always |
29
- | `factory-design` | With [`site`](configuration.md#site) in your settings |
30
- | `factory-ui-reviewer` | With `site` in your settings |
31
- | `factory-deps` | With a `.github/dependabot.yml` file |
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 main branch into a pull request and settles the conflicts |
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
 
@@ -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 main branch, named for the ticket.
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
- 4. Proves each new test can fail, and has `factory-test-reviewer` read the
94
- tests.
95
- 5. Has each [`reviewer` plug-in](plugins.md) that applies read the change,
96
- and fixes what they find.
97
- 6. Runs the checks your project's instructions name.
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,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. It releases the ticket
117
- and says why. The ticket stays in "building", waiting on you.
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 main branch. Merge. Turn auto-merge
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, patch coverage, and a conflict with your main branch.
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 main branch, fixes failing checks,
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
 
@@ -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 main branch into a pull request that conflicts
241
- with it, runs the gate, and pushes the merge. It never rebases or forces a
242
- push. When the two sides of a conflict contradict each other, it pushes
243
- nothing, comments why, and opens a ticket, because which side wins is your
244
- decision.
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.
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
- Read-only.
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#plugins) like a reviewer of your own, with
269
- the `files` that should trigger it, and is written only to a repository
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 reviews a pull request:
275
- one behavior per test, each able to fail, found the way a user would find
276
- it, with no waits on a timer. `factory-build` runs it. Read-only, and it
277
- does not run the suite.
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,146 @@ 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 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
+
61
204
  ## The commands
62
205
 
63
206
  | Command | When |
@@ -84,7 +227,8 @@ not match `package-lock.json`.
84
227
  | --------------------------------------------------------------------------- | --------------------------------------------------------------------- | -------------------------------------------------------------------------- |
85
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 |
86
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` |
87
- | The update pull request conflicts with your main branch | Something else changed the same file | `factory-deps` resolves it on its next run, or close it and update by hand |
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 |
88
232
 
89
233
  ## Never edit a factory file
90
234
 
@@ -95,8 +239,9 @@ fails when one differs from what the installed version would write.
95
239
  To change what the factory does:
96
240
 
97
241
  - **For your repository only:** say so in your own instructions for the
98
- agent, which win over the factory's rules, or, _[Planned](developing.md#what-is-built)_, change the value under
99
- [`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).
100
245
  - **For everyone:** change it in the factory, and it reaches you as an
101
246
  update.
102
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 main branch, and the ticket closed |
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
 
@@ -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, and one test that reproduces the defect
116
- or checks the change. The first message of the work says which path it is
117
- taking, so you can overrule it before it starts.
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
- The number is `rules.small-change-lines` in your
120
- [settings](configuration.md), _[Planned](developing.md#what-is-built)_; until it is built, it is 30.
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
- main branch, that passes only when the automated
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 main branch's copy of the
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
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@davidbyoung/software-factory",
3
- "version": "0.1.3",
3
+ "version": "0.1.4",
4
4
  "description": "Refines, builds, and reviews tickets with Claude Code sessions, from a board to a merged pull request.",
5
5
  "license": "MIT",
6
6
  "repository": {
package/review.md CHANGED
@@ -9,8 +9,8 @@ defend.
9
9
 
10
10
  ## Before you review
11
11
 
12
- 1. Read `CLAUDE.md`, `AGENTS.md`, and every area guide "Rules by area" in
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/main` with `git merge-base HEAD origin/main`.
31
- If they differ, main was merged in since that review, so review
32
- `git diff origin/main...HEAD`, the pull request's own changes as they
33
- now stand. If they match, review only `git diff SHA...HEAD`. Otherwise
34
- review the whole pull request, `git diff origin/main...HEAD`. Use
35
- `origin/main` rather than the base SHA you were given, which comes from
36
- the event and can be older than a merge from main.
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/main...HEAD`, does not meet, or
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 visitor would see the gap, Medium otherwise. Behavior
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