@davidbyoung/software-factory 0.0.0-stage → 0.1.0

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 (141) hide show
  1. package/.claude-plugin/plugin.json +5 -0
  2. package/LICENSE +21 -0
  3. package/README.md +135 -2
  4. package/actions/factory-agent/action.yml +218 -0
  5. package/agents/factory-test-reviewer.md +129 -0
  6. package/agents/factory-ticket-readiness.md +107 -0
  7. package/agents/factory-ui-reviewer.md +160 -0
  8. package/bin/factory.js +45 -0
  9. package/bin/launch.js +67 -0
  10. package/dist/board.d.mts +128 -0
  11. package/dist/board.mjs +456 -0
  12. package/dist/build.d.mts +18 -0
  13. package/dist/build.mjs +60 -0
  14. package/dist/cli.d.mts +17 -0
  15. package/dist/cli.mjs +264 -0
  16. package/dist/code-host/github.d.mts +118 -0
  17. package/dist/code-host/github.mjs +419 -0
  18. package/dist/code-host/index.d.mts +9 -0
  19. package/dist/code-host/index.mjs +18 -0
  20. package/dist/code-host/types.d.mts +205 -0
  21. package/dist/code-host/types.mjs +12 -0
  22. package/dist/config.d.mts +166 -0
  23. package/dist/config.mjs +548 -0
  24. package/dist/deps.d.mts +32 -0
  25. package/dist/deps.mjs +126 -0
  26. package/dist/doctor.d.mts +34 -0
  27. package/dist/doctor.mjs +188 -0
  28. package/dist/guard-commit.d.mts +41 -0
  29. package/dist/guard-commit.mjs +205 -0
  30. package/dist/guard-permission.d.mts +15 -0
  31. package/dist/guard-permission.mjs +52 -0
  32. package/dist/guard-ticket-text.d.mts +27 -0
  33. package/dist/guard-ticket-text.mjs +288 -0
  34. package/dist/guard.d.mts +4 -0
  35. package/dist/guard.mjs +37 -0
  36. package/dist/init.d.mts +58 -0
  37. package/dist/init.mjs +556 -0
  38. package/dist/lib/clock.d.mts +14 -0
  39. package/dist/lib/clock.mjs +36 -0
  40. package/dist/lib/gh.d.mts +28 -0
  41. package/dist/lib/gh.mjs +92 -0
  42. package/dist/lib/glob.d.mts +2 -0
  43. package/dist/lib/glob.mjs +41 -0
  44. package/dist/lib/pricing.d.mts +25 -0
  45. package/dist/lib/pricing.mjs +77 -0
  46. package/dist/lib/usage.d.mts +34 -0
  47. package/dist/lib/usage.mjs +128 -0
  48. package/dist/lib/work-status.d.mts +251 -0
  49. package/dist/lib/work-status.mjs +510 -0
  50. package/dist/merge-policy.d.mts +66 -0
  51. package/dist/merge-policy.mjs +146 -0
  52. package/dist/parts.d.mts +39 -0
  53. package/dist/parts.mjs +138 -0
  54. package/dist/poller.d.mts +61 -0
  55. package/dist/poller.mjs +247 -0
  56. package/dist/pr-watch.d.mts +45 -0
  57. package/dist/pr-watch.mjs +244 -0
  58. package/dist/pr.d.mts +65 -0
  59. package/dist/pr.mjs +571 -0
  60. package/dist/review-cost.d.mts +18 -0
  61. package/dist/review-cost.mjs +95 -0
  62. package/dist/review-tools.d.mts +5 -0
  63. package/dist/review-tools.mjs +46 -0
  64. package/dist/review-verdict.d.mts +50 -0
  65. package/dist/review-verdict.mjs +171 -0
  66. package/dist/reviewers.d.mts +54 -0
  67. package/dist/reviewers.mjs +312 -0
  68. package/dist/runner/github-actions.d.mts +12 -0
  69. package/dist/runner/github-actions.mjs +97 -0
  70. package/dist/runner/index.d.mts +9 -0
  71. package/dist/runner/index.mjs +22 -0
  72. package/dist/runner/types.d.mts +60 -0
  73. package/dist/runner/types.mjs +7 -0
  74. package/dist/session-start.d.mts +20 -0
  75. package/dist/session-start.mjs +115 -0
  76. package/dist/site/capture.d.mts +44 -0
  77. package/dist/site/capture.mjs +114 -0
  78. package/dist/site/measure.d.mts +83 -0
  79. package/dist/site/measure.mjs +225 -0
  80. package/dist/site/pages.d.mts +10 -0
  81. package/dist/site/pages.mjs +71 -0
  82. package/dist/site/pixels.d.mts +47 -0
  83. package/dist/site/pixels.mjs +157 -0
  84. package/dist/site/servers.d.mts +47 -0
  85. package/dist/site/servers.mjs +141 -0
  86. package/dist/site.d.mts +60 -0
  87. package/dist/site.mjs +341 -0
  88. package/dist/status.d.mts +100 -0
  89. package/dist/status.mjs +514 -0
  90. package/dist/sync.d.mts +59 -0
  91. package/dist/sync.mjs +292 -0
  92. package/dist/ticket.d.mts +61 -0
  93. package/dist/ticket.mjs +562 -0
  94. package/dist/tickets/github.d.mts +128 -0
  95. package/dist/tickets/github.mjs +491 -0
  96. package/dist/tickets/index.d.mts +15 -0
  97. package/dist/tickets/index.mjs +27 -0
  98. package/dist/tickets/transport.d.mts +42 -0
  99. package/dist/tickets/transport.mjs +158 -0
  100. package/dist/tickets/types.d.mts +191 -0
  101. package/dist/tickets/types.mjs +76 -0
  102. package/docs/builds.md +227 -0
  103. package/docs/cli.md +221 -0
  104. package/docs/configuration.md +809 -0
  105. package/docs/design.md +106 -0
  106. package/docs/developing.md +400 -0
  107. package/docs/existing-repo.md +138 -0
  108. package/docs/github/reference.md +288 -0
  109. package/docs/github/setup.md +312 -0
  110. package/docs/glossary.md +106 -0
  111. package/docs/limitations.md +115 -0
  112. package/docs/plugins.md +192 -0
  113. package/docs/quick-start.md +222 -0
  114. package/docs/removing.md +76 -0
  115. package/docs/skills.md +270 -0
  116. package/docs/updating.md +108 -0
  117. package/docs/workflow.md +195 -0
  118. package/package.json +67 -4
  119. package/poller.Dockerfile +21 -0
  120. package/review.md +170 -0
  121. package/rules.md +313 -0
  122. package/settings.schema.json +411 -0
  123. package/skills/factory-address-review/SKILL.md +547 -0
  124. package/skills/factory-address-review/patch-coverage.py +68 -0
  125. package/skills/factory-build/SKILL.md +412 -0
  126. package/skills/factory-deps/SKILL.md +185 -0
  127. package/skills/factory-design/SKILL.md +159 -0
  128. package/skills/factory-diagnose/SKILL.md +93 -0
  129. package/skills/factory-mutate/SKILL.md +76 -0
  130. package/skills/factory-refine/SKILL.md +417 -0
  131. package/skills/factory-resolve-conflicts/SKILL.md +235 -0
  132. package/workflows/factory-board-sync.yml +91 -0
  133. package/workflows/factory-build.yml +72 -0
  134. package/workflows/factory-check.yml +37 -0
  135. package/workflows/factory-claude-review.yml +133 -0
  136. package/workflows/factory-conflicts.yml +69 -0
  137. package/workflows/factory-deps-auto-merge.yml +43 -0
  138. package/workflows/factory-deps.yml +59 -0
  139. package/workflows/factory-merge-policy.yml +121 -0
  140. package/workflows/factory-review-verdict.yml +54 -0
  141. package/workflows/factory-review.yml +75 -0
@@ -0,0 +1,412 @@
1
+ ---
2
+ name: factory-build
3
+ description: Build a ticket: take an approved GitHub issue to a reviewed pull request: claim it, branch, build it to its spec with the area's reviewers, run the gate, open a draft with Closes #N, and work the review. Use when asked to build, work, pick up, take, or fix a ticket by number, and as the run `factory build N` starts in GitHub Actions.
4
+ ---
5
+
6
+ # Working an issue
7
+
8
+ The issue is the spec. Everything a conversation would have settled has to
9
+ be in it or in the repository's rules, so read it as one and stop when it
10
+ is not.
11
+
12
+ Every ticket is read and written through `npx --no-install factory ticket`,
13
+ and every pull request's conversation through `factory pr`, so the skill
14
+ works whatever the ticket system. A command that cannot read exits
15
+ nonzero with the error: that is a failed read, never an empty answer.
16
+
17
+ ## How a build starts
18
+
19
+ - **Local:** the owner tells a session to work an issue by number. The
20
+ card stays where it is until the claim moves it.
21
+
22
+ - **GitHub Actions:** the owner moves the issue's card to Ready on the
23
+ board, and the `ready-poller` worker posts a start comment and dispatches
24
+ "Factory build" with the issue's number; or a person runs
25
+ `npx --no-install factory build N`, or "Run workflow" on the Actions
26
+ tab. The two are the same run. The run's prompt says so. There is no
27
+ start check, since only someone with write access can dispatch a
28
+ workflow: go straight to the claim, which names the run and who started
29
+ it. The run cannot be woken later, and nobody can answer
30
+ its questions: every stop ends it with a report. If it ends without a
31
+ pull request, its last step, `factory ticket end`, releases the claim.
32
+
33
+ There is no queue: each build takes the one issue it was given.
34
+
35
+ ## The claim
36
+
37
+ The claim comment is the lock. As soon as step 0 finds the issue
38
+ approved, and before setup, a branch, or any other work, including the
39
+ rest of step 0:
40
+
41
+ ```bash
42
+ npx --no-install factory ticket claim N
43
+ ```
44
+
45
+ It checks the issue's blockers, posts the claim, waits 5 seconds, reads
46
+ the comments back, and prints one line:
47
+
48
+ - **`claimed`:** go on.
49
+ - **`held by SESSION`:** another session holds the issue. Stop and post
50
+ nothing; the script has already deleted this session's claim.
51
+ - **`blocked by: #M`:** stop. In a run in GitHub Actions the script has posted the
52
+ stopped comment, which leaves the card In progress, waiting on you.
53
+ The report is:
54
+
55
+ > **Waiting on #M, so I did not start this.** #M is still open and has
56
+ > to merge first. To build it anyway, remove the relationship from this
57
+ > issue's sidebar, then move its card to Ready again or ask a session to
58
+ > work it.
59
+
60
+ - **`could not read`** (exit 1, with the error): stop. In a run in GitHub Actions
61
+ the script has tried to post the stopped comment; if that failed too,
62
+ the nightly sync clears the start. Say so in the report, with the error.
63
+
64
+ **Every stop after `claimed` and before a pull request** releases the
65
+ issue, whatever the reason: a question only the owner can answer, a
66
+ missing owner step, "already done", or a gate that would not pass.
67
+
68
+ ```bash
69
+ npx --no-install factory ticket stop N "one-line reason"
70
+ ```
71
+
72
+ It posts the stopped comment only while this session's claim is still
73
+ live, and prints `not live; posted nothing` otherwise, so it never ends a
74
+ newer session's claim. A dirty tree in step 1 is a pause for a live user,
75
+ not a stop.
76
+
77
+ **Before opening the pull request,** check the claim once more:
78
+
79
+ ```bash
80
+ npx --no-install factory ticket still-live N
81
+ ```
82
+
83
+ `not live` means something ended the claim, such as the nightly sync
84
+ clearing it. Push the branch, open no pull request, post no comment, and
85
+ say so in the report.
86
+
87
+ A build that opened its pull request leaves the claim in place through
88
+ the review and the merge: the pull request puts the card In review.
89
+
90
+ ## Follow-ups
91
+
92
+ "Follow-ups" in `.claude/factory/rules.md` says what a follow-up is and what the
93
+ follow-ups issue holds. This skill does two things with them.
94
+
95
+ **A follow-up noticed during a build** goes on the open follow-ups issue,
96
+ as one line in the format that section gives, before the report. A reviewer
97
+ finding left for the owner, a defect outside the issue's scope, and a
98
+ check deferred to later are each a line. A line that needs a decision
99
+ from the owner says "Needs a decision:" with the question and stays a
100
+ line. A follow-up gets its own issue only when it would need the `spec`
101
+ label or would make a line of `openspec/specs/` false, as that section
102
+ says.
103
+
104
+ ```bash
105
+ npx --no-install factory follow-up FILE "What is wrong. Found by WHO while building #N. The rule it breaks."
106
+ ```
107
+
108
+ FILE is the file or page the follow-up is about, and leads its line. The
109
+ script appends the line to the open follow-ups issue, or opens the issue
110
+ when none is open, and prints which.
111
+
112
+ **The follow-ups issue** is built here like any issue, with these
113
+ differences. Its unchecked lines are the criteria; there is no `spec`
114
+ label, so steps 2 and 4 are skipped. Every unchecked line is built on the
115
+ one branch, in order, one commit per line, and the line is checked off in
116
+ the body (`- [ ]` to `- [x]`) once its commit is in:
117
+
118
+ ```bash
119
+ npx --no-install factory ticket view N --field body > body.md # check the line, then
120
+ npx --no-install factory ticket edit N --body-file body.md
121
+ ```
122
+
123
+ A line that says "Needs a decision" is built only when the issue's
124
+ Decisions answer it; otherwise it stays unchecked and the pull request
125
+ names it. A line the guides do not determine and that lacks the phrase
126
+ gets it added, and stays unchecked the same way. Step 3's reviewers run
127
+ once, on the whole branch, sized as "Small changes" in
128
+ `.claude/factory/rules.md` sizes
129
+ a follow-ups build. The pull request lists each line with its commit. It
130
+ starts with `Closes #N` only when every line is checked; otherwise it
131
+ starts with `Part of #N`, and the unchecked lines wait there for the next
132
+ build. The sync reads `Part of #N` as a partial build of the follow-ups,
133
+ so a pull request that only links a line it added there names the issue
134
+ any other way.
135
+
136
+ ## 0. Read the issue
137
+
138
+ ```bash
139
+ npx --no-install factory ticket view N
140
+ ```
141
+
142
+ It prints the title, state, labels, body, and each comment with its ID
143
+ and author.
144
+
145
+ The owner's approval is moving the card to Ready, telling a local
146
+ session to build the issue, or starting a build of it in GitHub Actions,
147
+ which anyone with write access can do and whose claim names who did. Each
148
+ counts only for an issue that has:
149
+
150
+ - a "Spec" or "Acceptance criteria" section in its body; or
151
+ - the `follow-up` label, since the follow-ups issue's unchecked lines are
152
+ its criteria.
153
+
154
+ Without either, run `factory-refine` and stop: no claim, and nothing to
155
+ release. Do not guess at what content should say or how a page
156
+ should behave.
157
+
158
+ Otherwise, claim it now ("The claim"), then read on.
159
+
160
+ - **Approved:** its "Spec" (or "Acceptance criteria") section is what to
161
+ build, and its "Decisions" are settled. On the `spec` track, "For the
162
+ builder" is the plan. Without that label there is none: the plan is the
163
+ criteria, the Decisions, and the area's `CLAUDE.md`, which already says
164
+ where logic goes, how tests are written, and what a page must look like.
165
+ Build to them without reopening them. If the code makes a design note
166
+ wrong, depart from it and say so in the pull request, with the reason.
167
+ If a step under "Dependencies", or under "Decisions" on an issue without
168
+ `spec`, that only the owner can do has not happened, such as a form or
169
+ key with no value given, release the claim and say so.
170
+ - **Approved while a comment round waits on the owner:** the newest
171
+ refinement marker on the issue is `<!-- work-status: waiting -->`.
172
+ Approval means the round's defaults stand, along with the owner's
173
+ replies. After the claim, run `factory-refine` steps 4 and 5 first, posting
174
+ no refinement marker: fold the replies in and read the result for
175
+ readiness. If a reply raises a new decision, or the read finds a
176
+ question only the owner can answer, comment it on the issue, release
177
+ the claim, and stop.
178
+ - **Already done, or no longer true:** say so with the evidence, release
179
+ the claim, and leave the issue open for the owner to close.
180
+
181
+ The spec track applies only when `npx --no-install factory config get specs`
182
+ prints `openspec`; otherwise skip steps 2 and 4. When it does, the `spec`
183
+ label decides the track, per "Spec track" in `.claude/factory/rules.md`.
184
+ Never change it. Without it, skip steps 2 and 4, unless the issue has a
185
+ "Spec" section: a small change that makes a spec line false. That one runs
186
+ step 2 with the proposal and spec delta only, and step 4.
187
+
188
+ ## 1. Branch
189
+
190
+ First, `git status --short`. If it shows anything, stop and ask the user
191
+ whether to commit it, on the current branch or on a new branch of its own if
192
+ the current one is `main`, or to stash it with `git stash -u`. A plain
193
+ `git stash` leaves untracked files behind. A switch carries
194
+ uncommitted changes onto the new branch, where the issue's commit would sweep
195
+ them into its PR, and refuses outright when a changed file differs between
196
+ the branches.
197
+
198
+ Then, from the latest origin/main, named for the issue:
199
+
200
+ ```bash
201
+ git fetch origin
202
+ git switch -c issue-N-short-slug origin/main
203
+ ```
204
+
205
+ If the branch you left has commits not on origin/main, name it in the
206
+ report, so that work is not lost.
207
+
208
+ ## 2. Create the change from the issue (`spec`, or a Spec section)
209
+
210
+ The change is the issue's body in OpenSpec's shape, as the branch's first
211
+ commit. Nothing in it is new; the thinking was done at refinement.
212
+
213
+ ```bash
214
+ export DO_NOT_TRACK=1
215
+ npx --no-install openspec new change issue-N-short-slug
216
+ npx --no-install openspec status --change issue-N-short-slug
217
+ ```
218
+
219
+ For each artifact `status` lists, run `npx --no-install openspec instructions <artifact>
220
+ --change issue-N-short-slug` and fill it from the issue. An issue without
221
+ the `spec` label fills `proposal.md` and the spec delta only; OpenSpec
222
+ validates and archives a change without `design.md` or `tasks.md`.
223
+
224
+ - `proposal.md` from §1, the owner's request, and "Decisions", linking the
225
+ issue.
226
+ - `specs/<capability>/spec.md`, one per capability heading under "Spec":
227
+ `## ADDED Requirements` for a new capability, `## MODIFIED Requirements`
228
+ for a modified one, and `## REMOVED Requirements` for each "No longer"
229
+ line. Each numbered Spec line becomes one requirement, named after it,
230
+ whose SHALL sentence restates it, with one scenario in the line's own
231
+ words: its "When" clause is the WHEN and the rest is the THEN. A
232
+ MODIFIED requirement copies the current spec's requirement and changes
233
+ only what the line changes.
234
+ - `design.md` from "Design".
235
+ - `tasks.md` from "Tasks".
236
+
237
+ Then check that every Spec line is exactly one scenario and every
238
+ scenario is a Spec line. If one does not map, stop and comment on the
239
+ issue with the line and why, rather than rewording it to fit. Run the
240
+ spec check ("After every code change" in `CLAUDE.md`), and commit the
241
+ change on its own.
242
+
243
+ ## 3. Build it
244
+
245
+ Read the `CLAUDE.md` for the area first ("Rules by area" in `CLAUDE.md`).
246
+
247
+ **A builder plug-in:** list them with
248
+ `npx --no-install factory plugins builder`, which prints each one's
249
+ labels. When the issue carries one of a builder's labels, invoke that skill
250
+ with the Skill tool to build it, in place of the steps below. What its
251
+ report says goes in the pull request body at step 6, where the owner reads
252
+ it before merging.
253
+
254
+ **Content the repository reviews by what changed:** when `CLAUDE.md` gives
255
+ a kind of content its own path by what changed in it, an edit to that
256
+ content follows that path.
257
+
258
+ **Code:**
259
+
260
+ - On the `spec` track, work through the change's `tasks.md` and tick each
261
+ task as it lands. If the code makes the design wrong, update `design.md`
262
+ and say why in the pull request.
263
+ - Write the test first, where there is a defect to reproduce or a behavior
264
+ to add, and watch it fail before making the change, as the area's rules
265
+ for tests say ("Rules by area" in `CLAUDE.md`).
266
+ - A small change takes the path in "Small changes" in
267
+ `.claude/factory/rules.md` instead of the next two items.
268
+ - Prove each new test can fail, by its red run or the `factory-mutate`
269
+ skill, and have `factory-test-reviewer` read them.
270
+ - **The repository's own reviewers** are listed by
271
+ `npx --no-install factory plugins reviewer`, each with its
272
+ `files`. A reviewer is considered when a file the branch changed matches
273
+ one of its `files`. Whether it applies is decided from the agent's own
274
+ description. Each considered reviewer ends with either a run, its
275
+ findings fixed before going on, or one line in the pull request saying
276
+ why it was skipped.
277
+ - **When the issue's body has a mockup,** render the result in each of
278
+ the mockup's states, from the mockup's data where the code can take it,
279
+ at its widths and color schemes, before opening the pull request. On a
280
+ site page, the UI reviewer's screenshots are the result. Anything else,
281
+ such as terminal output, an email, or a comment, is rendered however
282
+ fits the surface, such as running the formatter on the mockup's rows. The
283
+ acceptance criteria may not name every style the mockup shows, so the
284
+ comparison is the check, and step 6 puts it in the pull request.
285
+
286
+ ## 4. Verify and archive the change (`spec`, or a Spec section)
287
+
288
+ Verify before archiving: for every scenario in the change's specs, name
289
+ the test that exercises it, in which file, and run it. A scenario with no
290
+ test gets one now; a scenario whose test cannot fail (its red run before
291
+ the change shows, or `factory-mutate`) is not verified. Record the mapping in the pull request.
292
+
293
+ Then fold the change into the specs, as the last commit before the pull
294
+ request:
295
+
296
+ ```bash
297
+ DO_NOT_TRACK=1 npx --no-install openspec archive issue-N-short-slug --yes
298
+ ```
299
+
300
+ Then run the spec check ("After every code change" in `CLAUDE.md`).
301
+
302
+ ## 5. Gate, commit, push
303
+
304
+ Run the gate ("After every code change" in `CLAUDE.md`).
305
+
306
+ Run the end-to-end specs the change added or changed, with
307
+ `--repeat-each=10` for a new one, with the command "After every code
308
+ change" in `CLAUDE.md` gives; CI runs the full suite on the draft (step 6).
309
+ Commit and push as "Branching, pushing, and review" in
310
+ `.claude/factory/rules.md` describes: one commit per coherent change,
311
+ describing the defect or the feature, not the issue number alone.
312
+
313
+ ## 6. Open the pull request
314
+
315
+ The issue is the request for this PR, so open it without asking, as a
316
+ draft: a draft gets no automated review, so the pushes that follow cost
317
+ nothing until it is ready. Run `still-live` first ("The claim").
318
+
319
+ ```bash
320
+ npx --no-install factory pr open --title "..." --body-file pr-N.md
321
+ ```
322
+
323
+ It opens a draft from the current branch into the default branch and
324
+ prints the pull request's number.
325
+
326
+ Start the body with the link text
327
+ `npx --no-install factory ticket link N` prints (`Closes #N` on GitHub),
328
+ then what changed and how it was
329
+ verified, including each new test's red run or mutation check, and what
330
+ each reviewer found and what was done about it.
331
+ On the `spec` track, or with a Spec section, name the spec it changed under `openspec/specs/` and
332
+ include the scenario-to-test mapping from step 4.
333
+
334
+ When the issue has a mockup, the body has a "Mockup and result" section:
335
+ a table with the mockup beside the result for each state, then each
336
+ difference on its own line, ending "fixed" or the reason it stands, or
337
+ "No differences." when there are none. Check it by reading the two
338
+ images side by side, element by element, not the criteria. The failure it
339
+ prevents is a build that met its ticket's criteria and dropped the
340
+ mockup's colors, dimming, count format, and underline until the owner ran
341
+ it. When the images cannot be attached,
342
+ still list every difference, and say in the
343
+ section that the images are missing; the build does not stop for them.
344
+
345
+ ```bash
346
+ npx --no-install factory pr closes PR
347
+ ```
348
+
349
+ That has to print N. If it does not, GitHub did not register the link; fix
350
+ the body.
351
+
352
+ Then note what the build cost, on the pull request:
353
+
354
+ ```bash
355
+ npx --no-install factory ticket cost PR
356
+ ```
357
+
358
+ The claim started the session's cost clock; this posts what the session
359
+ and its reviewers spent at API list prices since then, and restarts it.
360
+ The board sync adds it to the issue's Cost. `factory-address-review` notes each later
361
+ round the same way. It exits 0 even when the cost cannot be measured.
362
+
363
+ Two cases change the body. When the build made a layout or style choice
364
+ in a small change, the UI reviewer's screenshots go in the body and the
365
+ pull request stays a draft: the owner marks it ready once they have seen
366
+ it ("Small changes" in `.claude/factory/rules.md`), so skip the ready step below. The
367
+ same holds when the owner has said they want to see the pull request
368
+ before it is marked ready. Someone
369
+ still works the review that click starts. A local session starts the
370
+ watcher now, as the paragraph after the ready step says, and works the
371
+ review when it lands. A run in GitHub Actions
372
+ cannot wait that long, so its step 7
373
+ report tells the owner the review is theirs to start and work, with
374
+ `factory-address-review` in a session they open, as a skill that runs as parallel
375
+ slices does. When it changes a line the repository's rules leave for the
376
+ owner to write, say the owner wrote it and link where they did, or the
377
+ review holds it as High.
378
+
379
+ When the gate passes and everything is pushed, mark it ready for review,
380
+ once GitHub shows the pushed commit as its head and every CI run on it has
381
+ passed or been skipped. A "ready" sent sooner can carry the
382
+ previous commit, or a suite that is about to fail. A failure is fixed on
383
+ the draft first, where a push costs no review.
384
+
385
+ ```bash
386
+ npx --no-install factory pr wait-checks PR # prints the conclusion
387
+ npx --no-install factory pr ready PR # only after success or no checks
388
+ ```
389
+
390
+ `factory pr ready` enforces commit signatures: when git is set to sign, it
391
+ refuses while GitHub shows a commit on the pull request as not verified.
392
+
393
+ That triggers the review. In a local session, start the watcher "Branching,
394
+ pushing, and review" in `.claude/factory/rules.md` describes. A run in GitHub Actions, which nothing
395
+ can wake later, waits for the review with
396
+ `npx --no-install factory pr state PR --wait` instead, and does not start
397
+ `factory pr watch`. Work the review with the `factory-address-review` skill.
398
+
399
+ The merge-policy workflow labels the pull request `merge: automatic` or `merge: manual` from
400
+ the files it changes, and turns auto-merge on for `merge: automatic` ones, which
401
+ then merge themselves once every gate passes. Never enable auto-merge,
402
+ merge, or add the `verdict: override` label yourself. In the report, say which
403
+ label the pull request got, so the owner knows whether it waits for them.
404
+
405
+ ## 7. Report
406
+
407
+ The issue, the PR, what each reviewer found, the review rounds and their
408
+ outcome, any claim or release that failed, and anything left for the
409
+ user: a question, a deferred follow-up, or
410
+ a decision. Anything agreed but not done is recorded as "Follow-ups"
411
+ above says: a line on the follow-ups issue, or its own issue only when it
412
+ would need the `spec` label, either way linked from the PR.
@@ -0,0 +1,185 @@
1
+ ---
2
+ name: factory-deps
3
+ description: Move every open Dependabot pull request one step closer to merged: resolve conflicts with main, fix failing CI, do a major bump's migration, and open an issue for anything it cannot fix. Use when asked to look after, unstick, or fix Dependabot pull requests, and from the workflow that runs it.
4
+ ---
5
+
6
+ # Shepherding Dependabot pull requests
7
+
8
+ A minor or patch bump already has auto-merge on, set by
9
+ `factory-deps-auto-merge.yml`, so it merges by itself once its checks are
10
+ green. The job here is to get it there. A major bump never has
11
+ auto-merge, and neither does a bump of the factory itself, and this skill
12
+ never turns it on or merges anything: the owner reads a major's migration,
13
+ and every update of the factory, before it lands.
14
+
15
+ Every command below goes through `factory deps`, `factory ticket`, or
16
+ `factory pr`.
17
+
18
+ ## 0. The queue, and each one's state
19
+
20
+ A run started by the workflow ran `factory deps --any` first, which exits
21
+ 0 when a Dependabot pull request is open, and starts a session only then.
22
+ Read the list again, since time has passed.
23
+
24
+ ```bash
25
+ npx --no-install factory deps
26
+ ```
27
+
28
+ It lists the open Dependabot pull requests, oldest first, and for each
29
+ one: whether it is a major, its head branch and commit, its mergeable
30
+ state, whether auto-merge is on, the newest run of each gate, how many
31
+ earlier shepherd comments it has, and the next step this skill takes. A
32
+ failed read exits nonzero with the error; it never reports an empty
33
+ queue it could not read.
34
+
35
+ Work each one through the steps below, oldest first. One that stops goes
36
+ in the report and the next one starts.
37
+
38
+ ## 1. What the state means
39
+
40
+ - **Major or not:** the title's "from X to Y". A different leading number
41
+ is a major. A grouped pull request ("Bump the npm group") is minor and
42
+ patch only.
43
+ - **Checks still running, or whether it can merge is still `unknown`:** leave it for
44
+ the next run.
45
+ - **Two earlier shepherd comments already report a fix that did not turn
46
+ CI green:** stop on it. Open an issue (step 6) if none is linked yet.
47
+
48
+ ## 2. Conflicts with main
49
+
50
+ The ruleset does not require a branch to be up to date with main, so a
51
+ pull request that is only `behind` merges as it is; leave it. Updating it
52
+ would only start CI again.
53
+
54
+ A `dirty` state is a conflict, almost always in `package-lock.json`, and
55
+ blocks the merge. Check the branch out (step 3), merge `origin/main`, take
56
+ main's lock file, run `npm install` so the bump is reapplied on top of it,
57
+ and commit the merge.
58
+
59
+ Then go on: a branch with a conflict can be failing as well.
60
+
61
+ ## 3. Failing checks
62
+
63
+ Check out the branch and reproduce the failure before changing anything:
64
+
65
+ ```bash
66
+ git fetch origin HEAD_REF && git switch HEAD_REF
67
+ npm ci
68
+ ```
69
+
70
+ Then run the gate's check and the end-to-end suite, with its browser
71
+ installed first, by the commands "After every code change" in `CLAUDE.md`
72
+ gives.
73
+
74
+ Read the failing job's log too, since a failure can be specific to CI:
75
+
76
+ ```bash
77
+ npx --no-install factory pr failed N
78
+ ```
79
+
80
+ It prints what a failed check wrote about itself, and each failed job's
81
+ name and the end of its log.
82
+
83
+ Fix what the new version broke, in the code, tests or config that use it,
84
+ following `CLAUDE.md`, `AGENTS.md` and `tests/CLAUDE.md`. The fix adapts
85
+ the project to the new version. It never:
86
+
87
+ - pins or downgrades the dependency back, or adds an override for it;
88
+ - skips, deletes or loosens a test, or lowers a coverage threshold;
89
+ - relaxes a lint rule or type setting to make an error go away;
90
+ - makes a CI step non-blocking, for example with `continue-on-error`.
91
+
92
+ If the only fix is one of those, or needs a decision about how the site
93
+ should look or behave, stop and open an issue (step 6).
94
+
95
+ Run the gate again ("After every code change" in `CLAUDE.md`), then commit one coherent
96
+ change whose message describes the defect, and push to the same branch.
97
+ No attribution trailer naming an AI assistant. Never push to main and
98
+ never force push.
99
+
100
+ Wait for the checks of the new head, up to 20 minutes:
101
+
102
+ ```bash
103
+ timeout 1200 npx --no-install factory pr wait-checks N
104
+ ```
105
+
106
+ It waits until GitHub shows the pushed commit as the pull request's head,
107
+ then until every workflow run on it has finished. It prints `success` when
108
+ each passed or was skipped, or `failure:` with the name of each check that
109
+ failed, and exits 3. A `timeout` exit of 124 means the checks were still
110
+ running after 20 minutes: leave the bump for the next run.
111
+
112
+ If one still fails, try once more in the same run. A second failure is the
113
+ end for this run: comment what was tried and leave it for the next one.
114
+
115
+ ## 4. An update of the factory
116
+
117
+ A pull request that bumps `@davidbyoung/software-factory` gets steps 2 and
118
+ 3, and the files the new version writes. After `npm ci` on its branch:
119
+
120
+ ```bash
121
+ npx --no-install factory sync
122
+ ```
123
+
124
+ Commit what it wrote as a second commit, "Sync the factory's files to
125
+ VERSION", and push. The push changes workflows, so it needs a token with
126
+ the `workflow` scope, such as the build token; a refused push is a stop
127
+ (step 6), with GitHub's error. Until then CI's `factory sync --check` fails, which is
128
+ the sign the commit is missing. Then comment on the pull request with the
129
+ files the sync changed and the release notes' steps to do by hand, first.
130
+ Never enable auto-merge, never approve and never merge: it waits for the
131
+ owner, whatever its size.
132
+
133
+ ## 5. Majors
134
+
135
+ A major gets steps 2 and 3, plus the migration:
136
+
137
+ - Read the release notes and migration guide between the two versions,
138
+ from the package's GitHub releases or its changelog in `node_modules`.
139
+ - Make every change the guide calls for, not only the ones CI caught.
140
+ - Update instruction files that name the version: the "Stack" section of
141
+ `CLAUDE.md`, and `AGENTS.md`. For a framework, read the new docs under
142
+ `node_modules/` that `AGENTS.md` points to and correct any rule they
143
+ contradict.
144
+ - Never enable auto-merge, never approve and never merge.
145
+
146
+ Then comment on the pull request with what the migration changed, what
147
+ the guide called for that did not apply, and anything the owner should
148
+ check before merging.
149
+
150
+ ## 6. Opening an issue
151
+
152
+ For anything stopped on, open one issue per pull request, written so it
153
+ can be started without this run, and link it from the pull request:
154
+
155
+ ```bash
156
+ TITLE="Dependabot #N: what fails"
157
+ EXISTING=$(npx --no-install factory ticket list --title "$TITLE" | cut -f1 | head -1)
158
+ if [ -n "$EXISTING" ]; then
159
+ npx --no-install factory ticket comment "$EXISTING" --body-file issue.md
160
+ else
161
+ npx --no-install factory ticket open --title "$TITLE" --body-file issue.md
162
+ fi
163
+ ```
164
+
165
+ One already open with that title gets a comment rather than a second
166
+ issue.
167
+
168
+ The body names the pull request, the failing check, the error, what was
169
+ tried, and why it stopped.
170
+
171
+ ## 7. Report
172
+
173
+ Comment on every pull request this run changed, starting the body with
174
+ `<!-- factory-deps -->` so the next run can find it:
175
+
176
+ ```bash
177
+ npx --no-install factory pr comment N --body-file comment.md
178
+ ```
179
+
180
+ Say what was done (updated, fixed and how, migrated), the state of its
181
+ checks, and what it now waits on: its own auto-merge, the owner's merge
182
+ of a major, or an issue. Pull requests left untouched get no comment.
183
+
184
+ Finish with one summary of every pull request in the queue and its state.
185
+ Use American English and the Oxford comma.