@davidbyoung/software-factory 0.0.0-stage → 0.1.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/.claude-plugin/plugin.json +5 -0
- package/LICENSE +21 -0
- package/README.md +135 -2
- package/actions/factory-agent/action.yml +218 -0
- package/agents/factory-test-reviewer.md +129 -0
- package/agents/factory-ticket-readiness.md +107 -0
- package/agents/factory-ui-reviewer.md +160 -0
- package/bin/factory.js +45 -0
- package/bin/launch.js +67 -0
- package/dist/board.d.mts +128 -0
- package/dist/board.mjs +456 -0
- package/dist/build.d.mts +18 -0
- package/dist/build.mjs +60 -0
- package/dist/cli.d.mts +17 -0
- package/dist/cli.mjs +264 -0
- package/dist/code-host/github.d.mts +118 -0
- package/dist/code-host/github.mjs +419 -0
- package/dist/code-host/index.d.mts +9 -0
- package/dist/code-host/index.mjs +18 -0
- package/dist/code-host/types.d.mts +205 -0
- package/dist/code-host/types.mjs +12 -0
- package/dist/config.d.mts +166 -0
- package/dist/config.mjs +548 -0
- package/dist/deps.d.mts +32 -0
- package/dist/deps.mjs +126 -0
- package/dist/doctor.d.mts +34 -0
- package/dist/doctor.mjs +188 -0
- package/dist/guard-commit.d.mts +41 -0
- package/dist/guard-commit.mjs +209 -0
- package/dist/guard-permission.d.mts +15 -0
- package/dist/guard-permission.mjs +52 -0
- package/dist/guard-ticket-text.d.mts +27 -0
- package/dist/guard-ticket-text.mjs +288 -0
- package/dist/guard.d.mts +4 -0
- package/dist/guard.mjs +37 -0
- package/dist/init.d.mts +58 -0
- package/dist/init.mjs +556 -0
- package/dist/lib/clock.d.mts +14 -0
- package/dist/lib/clock.mjs +36 -0
- package/dist/lib/gh.d.mts +28 -0
- package/dist/lib/gh.mjs +92 -0
- package/dist/lib/glob.d.mts +2 -0
- package/dist/lib/glob.mjs +41 -0
- package/dist/lib/pricing.d.mts +25 -0
- package/dist/lib/pricing.mjs +77 -0
- package/dist/lib/usage.d.mts +34 -0
- package/dist/lib/usage.mjs +128 -0
- package/dist/lib/work-status.d.mts +251 -0
- package/dist/lib/work-status.mjs +510 -0
- package/dist/merge-policy.d.mts +66 -0
- package/dist/merge-policy.mjs +146 -0
- package/dist/parts.d.mts +39 -0
- package/dist/parts.mjs +138 -0
- package/dist/poller.d.mts +61 -0
- package/dist/poller.mjs +247 -0
- package/dist/pr-watch.d.mts +45 -0
- package/dist/pr-watch.mjs +244 -0
- package/dist/pr.d.mts +65 -0
- package/dist/pr.mjs +571 -0
- package/dist/review-cost.d.mts +18 -0
- package/dist/review-cost.mjs +95 -0
- package/dist/review-tools.d.mts +5 -0
- package/dist/review-tools.mjs +46 -0
- package/dist/review-verdict.d.mts +50 -0
- package/dist/review-verdict.mjs +171 -0
- package/dist/reviewers.d.mts +54 -0
- package/dist/reviewers.mjs +312 -0
- package/dist/runner/github-actions.d.mts +12 -0
- package/dist/runner/github-actions.mjs +97 -0
- package/dist/runner/index.d.mts +9 -0
- package/dist/runner/index.mjs +22 -0
- package/dist/runner/types.d.mts +60 -0
- package/dist/runner/types.mjs +7 -0
- package/dist/session-start.d.mts +20 -0
- package/dist/session-start.mjs +115 -0
- package/dist/site/capture.d.mts +44 -0
- package/dist/site/capture.mjs +114 -0
- package/dist/site/measure.d.mts +83 -0
- package/dist/site/measure.mjs +225 -0
- package/dist/site/pages.d.mts +10 -0
- package/dist/site/pages.mjs +71 -0
- package/dist/site/pixels.d.mts +47 -0
- package/dist/site/pixels.mjs +157 -0
- package/dist/site/servers.d.mts +47 -0
- package/dist/site/servers.mjs +141 -0
- package/dist/site.d.mts +60 -0
- package/dist/site.mjs +341 -0
- package/dist/status.d.mts +100 -0
- package/dist/status.mjs +514 -0
- package/dist/sync.d.mts +59 -0
- package/dist/sync.mjs +292 -0
- package/dist/ticket.d.mts +61 -0
- package/dist/ticket.mjs +562 -0
- package/dist/tickets/github.d.mts +128 -0
- package/dist/tickets/github.mjs +491 -0
- package/dist/tickets/index.d.mts +15 -0
- package/dist/tickets/index.mjs +27 -0
- package/dist/tickets/transport.d.mts +42 -0
- package/dist/tickets/transport.mjs +158 -0
- package/dist/tickets/types.d.mts +191 -0
- package/dist/tickets/types.mjs +76 -0
- package/docs/builds.md +227 -0
- package/docs/cli.md +221 -0
- package/docs/configuration.md +809 -0
- package/docs/design.md +106 -0
- package/docs/developing.md +400 -0
- package/docs/existing-repo.md +138 -0
- package/docs/github/reference.md +288 -0
- package/docs/github/setup.md +312 -0
- package/docs/glossary.md +106 -0
- package/docs/limitations.md +115 -0
- package/docs/plugins.md +192 -0
- package/docs/quick-start.md +222 -0
- package/docs/removing.md +76 -0
- package/docs/skills.md +270 -0
- package/docs/updating.md +108 -0
- package/docs/workflow.md +195 -0
- package/package.json +67 -4
- package/poller.Dockerfile +21 -0
- package/review.md +170 -0
- package/rules.md +313 -0
- package/settings.schema.json +411 -0
- package/skills/factory-address-review/SKILL.md +547 -0
- package/skills/factory-address-review/patch-coverage.py +68 -0
- package/skills/factory-build/SKILL.md +412 -0
- package/skills/factory-deps/SKILL.md +185 -0
- package/skills/factory-design/SKILL.md +159 -0
- package/skills/factory-diagnose/SKILL.md +93 -0
- package/skills/factory-mutate/SKILL.md +76 -0
- package/skills/factory-refine/SKILL.md +417 -0
- package/skills/factory-resolve-conflicts/SKILL.md +235 -0
- package/workflows/factory-board-sync.yml +91 -0
- package/workflows/factory-build.yml +72 -0
- package/workflows/factory-check.yml +37 -0
- package/workflows/factory-claude-review.yml +133 -0
- package/workflows/factory-conflicts.yml +69 -0
- package/workflows/factory-deps-auto-merge.yml +43 -0
- package/workflows/factory-deps.yml +59 -0
- package/workflows/factory-merge-policy.yml +121 -0
- package/workflows/factory-review-verdict.yml +54 -0
- 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.
|