@davidbyoung/software-factory 0.1.2 → 0.1.4

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (120) hide show
  1. package/README.md +20 -20
  2. package/actions/factory-agent/action.yml +1 -1
  3. package/agents/factory-e2e-reviewer.md +102 -0
  4. package/agents/factory-test-reviewer.md +26 -64
  5. package/agents/factory-ticket-readiness.md +14 -6
  6. package/dist/agent/claude-code.d.mts +3 -0
  7. package/dist/agent/claude-code.mjs +89 -0
  8. package/dist/agent/index.d.mts +2 -0
  9. package/dist/agent/index.mjs +5 -0
  10. package/dist/board.mjs +1 -1
  11. package/dist/cli.mjs +46 -4
  12. package/dist/code-host/github-setup.d.mts +5 -0
  13. package/dist/code-host/github-setup.mjs +133 -0
  14. package/dist/code-host/github.mjs +4 -0
  15. package/dist/code-host/index.d.mts +1 -1
  16. package/dist/code-host/index.mjs +2 -1
  17. package/dist/code-host/types.d.mts +2 -0
  18. package/dist/commands.d.mts +16 -0
  19. package/dist/commands.mjs +129 -0
  20. package/dist/config.d.mts +87 -20
  21. package/dist/config.mjs +344 -89
  22. package/dist/deps.d.mts +7 -4
  23. package/dist/deps.mjs +20 -9
  24. package/dist/doctor.d.mts +9 -16
  25. package/dist/doctor.mjs +71 -68
  26. package/dist/explain.d.mts +4 -0
  27. package/dist/explain.mjs +174 -0
  28. package/dist/guard-commit.d.mts +7 -2
  29. package/dist/guard-commit.mjs +58 -21
  30. package/dist/init.d.mts +12 -14
  31. package/dist/init.mjs +194 -136
  32. package/dist/lib/default-branch.d.mts +35 -0
  33. package/dist/lib/default-branch.mjs +117 -0
  34. package/dist/lib/has-command.d.mts +5 -0
  35. package/dist/lib/has-command.mjs +8 -0
  36. package/dist/lib/listed.d.mts +2 -0
  37. package/dist/lib/listed.mjs +4 -0
  38. package/dist/lib/refined-check.d.mts +7 -0
  39. package/dist/lib/refined-check.mjs +76 -0
  40. package/dist/lib/work-status.d.mts +12 -2
  41. package/dist/lib/work-status.mjs +14 -3
  42. package/dist/parts.d.mts +18 -15
  43. package/dist/parts.mjs +15 -43
  44. package/dist/patch-coverage.d.mts +13 -0
  45. package/dist/patch-coverage.mjs +73 -0
  46. package/dist/poller.d.mts +20 -3
  47. package/dist/poller.mjs +62 -15
  48. package/dist/pr-watch.d.mts +3 -2
  49. package/dist/pr-watch.mjs +22 -5
  50. package/dist/pr.mjs +34 -2
  51. package/dist/remove.d.mts +11 -0
  52. package/dist/remove.mjs +156 -0
  53. package/dist/runner/github-actions.d.mts +1 -1
  54. package/dist/runner/github-actions.mjs +12 -0
  55. package/dist/runner/index.d.mts +1 -1
  56. package/dist/runner/index.mjs +2 -1
  57. package/dist/runner/setup.d.mts +2 -0
  58. package/dist/runner/setup.mjs +22 -0
  59. package/dist/runner/types.d.mts +3 -0
  60. package/dist/runner/types.mjs +0 -2
  61. package/dist/session-start.d.mts +23 -13
  62. package/dist/session-start.mjs +56 -44
  63. package/dist/setup.d.mts +98 -0
  64. package/dist/setup.mjs +3 -0
  65. package/dist/site/servers.d.mts +6 -2
  66. package/dist/site/servers.mjs +14 -9
  67. package/dist/site.mjs +2 -2
  68. package/dist/status.d.mts +4 -4
  69. package/dist/status.mjs +8 -7
  70. package/dist/sync.d.mts +26 -2
  71. package/dist/sync.mjs +177 -13
  72. package/dist/ticket.mjs +19 -1
  73. package/dist/tickets/github-setup.d.mts +2 -0
  74. package/dist/tickets/github-setup.mjs +50 -0
  75. package/dist/tickets/github.mjs +0 -2
  76. package/dist/tickets/index.mjs +2 -1
  77. package/dist/tickets/transport.mjs +1 -3
  78. package/dist/tickets/types.mjs +0 -2
  79. package/dist/tool-names.d.mts +11 -0
  80. package/dist/tool-names.mjs +20 -0
  81. package/dist/tools.d.mts +56 -0
  82. package/dist/tools.mjs +76 -0
  83. package/docs/builds.md +111 -59
  84. package/docs/cli.md +106 -69
  85. package/docs/configuration.md +489 -171
  86. package/docs/design.md +18 -5
  87. package/docs/developing.md +179 -73
  88. package/docs/existing-repo.md +25 -12
  89. package/docs/github/by-hand.md +334 -0
  90. package/docs/github/reference.md +76 -67
  91. package/docs/github/setup.md +105 -286
  92. package/docs/glossary.md +18 -7
  93. package/docs/limitations.md +39 -12
  94. package/docs/plugins.md +305 -56
  95. package/docs/quick-start.md +85 -100
  96. package/docs/removing.md +37 -17
  97. package/docs/skills.md +121 -62
  98. package/docs/updating.md +150 -9
  99. package/docs/workflow.md +23 -19
  100. package/package.json +1 -1
  101. package/poller.Dockerfile +10 -18
  102. package/review.md +20 -11
  103. package/rules.md +36 -30
  104. package/settings.schema.json +313 -69
  105. package/skills/factory-address-review/SKILL.md +50 -30
  106. package/skills/factory-build/SKILL.md +76 -23
  107. package/skills/factory-deps/SKILL.md +46 -21
  108. package/skills/factory-design/SKILL.md +17 -8
  109. package/skills/factory-diagnose/SKILL.md +22 -20
  110. package/skills/factory-mutate/SKILL.md +38 -24
  111. package/skills/factory-refine/SKILL.md +55 -31
  112. package/skills/factory-resolve-conflicts/SKILL.md +76 -34
  113. package/skills/factory-trace/SKILL.md +80 -0
  114. package/workflows/factory-build.yml +6 -5
  115. package/workflows/factory-conflicts.yml +8 -8
  116. package/workflows/factory-deps-auto-merge.yml +3 -2
  117. package/workflows/factory-deps.yml +1 -1
  118. package/workflows/factory-poller.yml +46 -0
  119. package/workflows/factory-review.yml +1 -1
  120. package/skills/factory-address-review/patch-coverage.py +0 -68
package/docs/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` 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` | _[Planned](developing.md#what-is-built)_: 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
 
@@ -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 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,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. 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
 
123
- **Defaults you can change,** _[Planned](developing.md#what-is-built)_. `rules.small-change-lines`, default 30: a
124
- change under it takes the lighter path [Workflow](workflow.md) describes.
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, 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.
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`, _[Planned](developing.md#what-is-built)_), whatever
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 main branch, fixes failing checks,
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` _[Planned](developing.md#what-is-built)_
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, or an agent is
221
- marked ready, this has a fresh agent trace each kind of change your
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 main branch into a pull request that conflicts
232
- with it, runs the gate, and pushes the merge. It never rebases or forces a
233
- push. When the two sides of a conflict contradict each other, it pushes
234
- nothing, comments why, and opens a ticket, because which side wins is your
235
- 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.
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
- 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.
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 that
256
- changed, drives the states the change is about, and judges them against built-in
257
- rules, your `design-guide` when you wrote one, and what your `checks` printed.
258
- It is listed under `plugins` like a reviewer of your own, with the `files` that
259
- should trigger it, and is written only to a repository with `site` in its
260
- settings. Read-only, and slow.
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 reviews a pull request:
265
- one behavior per test, each able to fail, found the way a user would find
266
- it, with no waits on a timer. `factory-build` runs it. Read-only, and it
267
- 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.
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 _[Planned](developing.md#what-is-built)_
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
- | 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 |
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, or, _[Planned](developing.md#what-is-built)_, change the value under
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 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
 
@@ -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 within a minute of the blocker closing if the ticket is in Ready.
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, adding no new component and no
113
- new state, is **small**. It skips the heavier steps: no separate spec, no
114
- readiness read, and one test that reproduces the defect or checks the
115
- change. The first message of the work says which path it is taking, so you
116
- can overrule it before it starts.
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
- The number is `rules.small-change-lines` in your
119
- [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.
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
- main branch, that passes only when the automated
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 main branch's copy of the
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`, a change that adds or alters behavior someone can
189
- see, and is not small, carries the `spec` label. Its ticket holds a "Spec"
190
- section of plain "When this, then that" lines. The build turns those lines
191
- into an OpenSpec change, builds to them, and folds them into
192
- `openspec/specs/` in the same pull request, so that folder always describes
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
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@davidbyoung/software-factory",
3
- "version": "0.1.2",
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/poller.Dockerfile CHANGED
@@ -1,21 +1,13 @@
1
- # The poller's image. It copies only the poller and the modules it imports:
2
- # the shared work-status rules, the GitHub ticket adapter with its `fetch`
3
- # transport, GitHub as the code host, and GitHub Actions as the runner, each
4
- # with the interface it fills. No npm install and no build, so
5
- # the repository's build variables are not needed here, and the `factory`
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
- COPY src/poller.mts src/poller.mts
11
- COPY src/lib/work-status.mts src/lib/work-status.mts
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", "src/poller.mts"]
13
+ CMD ["node", "node_modules/@davidbyoung/software-factory/bin/factory.js", "poller"]