@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
@@ -0,0 +1,334 @@
1
+ # Setting up on GitHub by hand
2
+
3
+ Every step [`factory init`](setup.md) takes, for someone who cannot run it
4
+ or wants to see what it does. If you can run `init`, do that: it does all
5
+ of this for you. Here you do [the basics](#the-basics), then only the
6
+ parts you want, in the order they appear.
7
+
8
+ ## Choose what you want
9
+
10
+ The basics are all the [quick start](../quick-start.md) needs. Everything
11
+ else is optional, and each part stands alone. You need the tools under
12
+ [What you need](setup.md#what-you-need), and the package
13
+ [installed](../quick-start.md#1-install).
14
+
15
+ | Part | What it takes |
16
+ | --------------------------------------------------------------------------- | ------------------------------------------------------------------ |
17
+ | [The basics](#the-basics) | A settings file and one command |
18
+ | [The automated review](#the-automated-review) | The Claude GitHub App, a workflow file, and your Claude token |
19
+ | [A board](#a-board) | A Project, one setting, and a GitHub token |
20
+ | [Builds in the cloud](#builds-in-the-cloud) | Your Claude token and a GitHub token |
21
+ | [Pull requests that merge themselves](#pull-requests-that-merge-themselves) | A list of files, one repository setting, and a second GitHub token |
22
+ | [Signed commits from cloud builds](#signed-commits-from-cloud-builds) | A signing key |
23
+
24
+ [Run `factory init`](setup.md#run-factory-init) says what each part gives
25
+ you. Every part's secrets are gathered in [Secrets](#secrets), so you can
26
+ make them all at once.
27
+
28
+ ## The basics
29
+
30
+ If you followed the quick start, this is done.
31
+
32
+ 1. Write `.claude/factory.yaml`, with your repository's owner and name:
33
+
34
+ ```yaml
35
+ version: 2
36
+ repository: your-name/your-repo
37
+ ```
38
+
39
+ 2. Write the factory's files:
40
+
41
+ ```bash
42
+ factory sync
43
+ ```
44
+
45
+ It writes the skills, agents, and rules Claude Code loads, under
46
+ `.claude/`; adds hook entries to `.claude/settings.json`; adds one line
47
+ to `CLAUDE.md`; and writes the workflows under `.github/workflows/`.
48
+ [What lives where](reference.md) names each.
49
+
50
+ 3. List the commands that check a change, such as your tests and linter,
51
+ under [`commands.gate`](../configuration.md#commandsgate). A build runs
52
+ them, and cannot finish without them:
53
+
54
+ ```yaml
55
+ commands:
56
+ gate:
57
+ - npm test
58
+ - npm run lint
59
+ ```
60
+
61
+ 4. Optionally, list commands to run before every commit a session makes,
62
+ under
63
+ [`commands.before-commit`](../configuration.md#commandsbefore-commit),
64
+ in the same block:
65
+
66
+ ```yaml
67
+ commands:
68
+ before-commit:
69
+ - npm run lint
70
+ ```
71
+
72
+ 5. Check, commit, and merge:
73
+
74
+ ```bash
75
+ factory sync --check
76
+ factory config check
77
+ git switch -c set-up-factory && git add -A
78
+ git commit -m "Set up the software factory"
79
+ git push -u origin set-up-factory
80
+ gh pr create --fill
81
+ ```
82
+
83
+ Merge the pull request on GitHub, then switch to your default branch
84
+ and pull, such as `git switch main && git pull`, and start a new Claude
85
+ Code session.
86
+
87
+ **It worked when** typing `/factory` in the new session offers
88
+ `/factory-refine` and `/factory-build`.
89
+
90
+ Every part below is turned on the same way: add its settings to
91
+ `.claude/factory.yaml`, run `factory sync`, do the steps
92
+ the part lists, and merge what `sync` wrote.
93
+
94
+ ## The automated review
95
+
96
+ Claude reads every pull request once it is marked ready, comments on what
97
+ it finds, and posts a verdict. The session that built the pull request
98
+ answers each comment, fixing it or rejecting it with evidence.
99
+
100
+ It is on while `.claude/factory.yaml` has
101
+ [`ci-review`](../configuration.md#ci-review). Three files have similar
102
+ names, and `sync` writes all three:
103
+
104
+ | File | What it is |
105
+ | ---------------------------------------------- | ---------------------------------------------------------- |
106
+ | `.github/workflows/factory-claude-review.yml` | The workflow that runs the review |
107
+ | `.github/factory-review.md` | The review's instructions |
108
+ | `.github/workflows/factory-review-verdict.yml` | Turns each review's summary into a "Review verdict" status |
109
+
110
+ 1. **Install the Claude GitHub App** on the repository, from
111
+ <https://github.com/apps/claude>. The review posts its comments through
112
+ it. Or run `/install-github-app` in Claude Code, which installs the app
113
+ and also stores the Claude token for you.
114
+ 2. **Store your Claude token** as `CLAUDE_CODE_OAUTH_TOKEN`
115
+ ([Secrets](#secrets)), unless step 1 did.
116
+ 3. **Write `ci-review` in `.claude/factory.yaml`,** and run
117
+ `factory sync`, which writes the three files above:
118
+
119
+ ```yaml
120
+ ci-review:
121
+ commands:
122
+ - npm test
123
+ - npx tsc --noEmit
124
+ ```
125
+
126
+ Each command under it is one the reviewer may run to confirm a finding,
127
+ such as your tests. To let it run nothing of yours, write the key
128
+ alone, and it reads the pull request and comments:
129
+
130
+ ```yaml
131
+ ci-review:
132
+ ```
133
+
134
+ The workflow installs your project with `npm ci`, and chooses the
135
+ model from `FACTORY_BUILD_MODEL` ([Variables](reference.md#workflows))
136
+ when it is set.
137
+
138
+ 4. **Optionally, write `.github/review-notes.md`:** what a reviewer must
139
+ know about your project that your `CLAUDE.md` does not say. The
140
+ reviewer reads it when it exists.
141
+ 5. **To make the verdict count,** add "Review verdict" to the required
142
+ status checks of your default branch: Settings, then Rules or Branches.
143
+ Until you do, it is information only.
144
+
145
+ **It worked when** a pull request you mark ready gets Claude's comments
146
+ and a "Review verdict" status in its checks.
147
+
148
+ ## A board
149
+
150
+ A GitHub Project that shows each ticket's state as a column, which session
151
+ has it, and what it has cost. [Workflow](../workflow.md#the-board) says
152
+ what each column means.
153
+
154
+ 1. **Create a Project** under the account or the organization that owns the
155
+ repository: its Projects tab, "New project", Board layout. Link it to
156
+ the repository from the Project's menu, so it shows on the repository's
157
+ Projects tab. Its number is the last part of its address.
158
+ 2. **Give it the factory's columns:** Backlog, In refinement, Ready, In
159
+ progress, In review, and Done, in its Status field. A new Project starts
160
+ with Todo, In Progress, and Done. To keep columns of your own, map them
161
+ under [`tickets.columns`](../configuration.md#ticketscolumns) instead.
162
+ 3. **Give it the three fields the sync writes:** Session, a Text field;
163
+ Runs in, a single select with the options Local and Actions; and Cost, a
164
+ Number. A field the sync does not find, it skips.
165
+ 4. **Point the settings at it,** with the Project's number under
166
+ [`tickets`](../configuration.md#tickets):
167
+
168
+ ```yaml
169
+ tickets:
170
+ board: 7
171
+ ```
172
+
173
+ Then `factory board check` shows how it reads your
174
+ columns.
175
+
176
+ 5. **Store a GitHub token** as `FACTORY_BOARD_TOKEN` ([Secrets](#secrets)).
177
+ 6. **Run `factory sync`.** It writes the board-sync
178
+ workflow, the only thing that writes to the board. It never creates,
179
+ renames, or removes a column or field.
180
+
181
+ ## Builds in the cloud
182
+
183
+ `factory build 12` builds ticket 12 in GitHub Actions and
184
+ prints the run's link, with no session open on your machine.
185
+
186
+ `sync` already wrote the workflows these use, and each does nothing until
187
+ it has work and its secrets:
188
+
189
+ | Workflow | Runs a Claude Code session that |
190
+ | ----------------------- | ------------------------------------------------------------------------------------ |
191
+ | `factory-build.yml` | builds a ticket |
192
+ | `factory-review.yml` | answers a review you submit on a pull request |
193
+ | `factory-conflicts.yml` | resolves a conflict between a pull request and your default branch |
194
+ | `factory-deps.yml` | moves Dependabot's pull requests along, written once `.github/dependabot.yml` exists |
195
+
196
+ 1. **Store your Claude token** as `CLAUDE_CODE_OAUTH_TOKEN`.
197
+ 2. **Store a GitHub token that can push**, as `FACTORY_BUILD_TOKEN`. With
198
+ a board, `FACTORY_BOARD_TOKEN` stands in for it when it has the
199
+ `workflow` scope, so one token does both ([Secrets](#secrets)).
200
+
201
+ **It worked when** `factory build 12`, with the number of a refined
202
+ ticket, prints a run's link, and the run opens a pull request.
203
+
204
+ A build may run for 230 minutes, which
205
+ [`session-minutes`](../configuration.md#session-minutes) changes; GitHub
206
+ stops any job at six hours.
207
+
208
+ ### Starting builds from the board
209
+
210
+ To have a ticket build when you move its card to Ready on
211
+ [a board](#a-board), a small program, the poller, watches the board and
212
+ starts each build. Set
213
+ [`builds.trigger: github-action`](../configuration.md#builds) to run it on
214
+ a schedule in GitHub Actions, with nothing to host, or `own-server` to
215
+ host it yourself.
216
+ [Builds in the cloud](../builds.md) explains each and what it costs.
217
+
218
+ ## Pull requests that merge themselves
219
+
220
+ A pull request that touches only files you listed as safe merges once
221
+ every check passes. Everything else still waits for you. Turn this on
222
+ last: it is only as safe as your tests and the review. Start with a short
223
+ list, such as documentation.
224
+
225
+ 1. **List the files** under
226
+ [`auto-merge.allow`](../configuration.md#auto-merge), with exceptions
227
+ under `deny`:
228
+
229
+ ```yaml
230
+ auto-merge:
231
+ allow:
232
+ - docs/**
233
+ ```
234
+
235
+ Then run `factory sync`, which writes the merge-policy workflow. It
236
+ labels each pull request `merge: automatic` or `merge: manual` and
237
+ says why.
238
+
239
+ 2. **Allow auto-merge** on the repository: Settings, General, "Allow
240
+ auto-merge".
241
+ 3. **Store a GitHub token** as `FACTORY_AUTOMERGE_TOKEN` ([Secrets](#secrets)).
242
+
243
+ **It worked when** a pull request that touches only files you listed gets
244
+ the `merge: automatic` label.
245
+
246
+ ## Signed commits from cloud builds
247
+
248
+ Without a key, a build's commits are unsigned.
249
+
250
+ 1. Make a key for this and nothing else, with no passphrase:
251
+
252
+ ```bash
253
+ ssh-keygen -t ed25519 -N "" -C "factory builds" -f factory-signing-key
254
+ ```
255
+
256
+ 2. Add `factory-signing-key.pub` to the GitHub account whose token the
257
+ builds use: Settings, "SSH and GPG keys", "New SSH key", key type
258
+ "Signing Key".
259
+ 3. Store the private half, then delete both files:
260
+
261
+ ```bash
262
+ gh secret set FACTORY_SIGNING_KEY < factory-signing-key
263
+ rm factory-signing-key factory-signing-key.pub
264
+ ```
265
+
266
+ Anything that can run a workflow in the repository can read the key, as
267
+ it can the build token. Removing the public key from the account ends its
268
+ use.
269
+
270
+ **It worked when** the commits of the next build's pull request show as
271
+ "Verified".
272
+
273
+ ## Secrets
274
+
275
+ Everything here is stored on the repository with `gh secret set NAME`,
276
+ which asks for the value. Nothing the factory runs on your machine needs
277
+ one; each is for something that runs in GitHub Actions.
278
+
279
+ | Secret | Needed for | Make it |
280
+ | ------------------------- | -------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
281
+ | `CLAUDE_CODE_OAUTH_TOKEN` | The automated review, and builds in the cloud | `claude setup-token`, on your machine. It bills your Claude subscription |
282
+ | `FACTORY_BOARD_TOKEN` | A board. Also builds in the cloud, when `FACTORY_BUILD_TOKEN` is not set | [A classic token](https://github.com/settings/tokens/new?scopes=repo,project,workflow&description=factory%20board) with `repo`, `project`, and `workflow` |
283
+ | `FACTORY_BUILD_TOKEN` | Builds in the cloud. Optional with a board token; used instead of it when both are set | [A classic token](https://github.com/settings/tokens/new?scopes=repo,workflow&description=factory%20builds) with `repo` and `workflow` |
284
+ | `FACTORY_AUTOMERGE_TOKEN` | Pull requests that merge themselves | [A classic token](https://github.com/settings/tokens/new?scopes=repo&description=factory%20auto-merge) with `repo` |
285
+ | `FACTORY_SIGNING_KEY` | Signed commits from cloud builds | [The steps above](#signed-commits-from-cloud-builds) |
286
+
287
+ Each token link opens GitHub's page with the scopes checked; choose an
288
+ expiry date and generate it. The account that makes a token is the one
289
+ its work is done as, and must be able to write the repository, and the
290
+ Project for the board token.
291
+
292
+ **One GitHub token is enough for everything.** Make one classic token with
293
+ `repo` and `workflow`, and `project` when you have a board, and store it
294
+ under each name your parts read; `init` does the same. Any workflow a pull
295
+ request from the repository adds can read every secret, so separate tokens
296
+ protect little.
297
+
298
+ Builds and auto-merge also take a fine-grained token instead: read and
299
+ write access to Contents, Pull requests, Issues, and Workflows for builds,
300
+ and to Contents and Pull requests for auto-merge. The board token must be
301
+ classic.
302
+
303
+ To set them in one go, run the lines for your parts and paste each value
304
+ when asked. `claude setup-token` prints the first value, and the other
305
+ three lines can all take the same GitHub token:
306
+
307
+ ```bash
308
+ claude setup-token
309
+ gh secret set CLAUDE_CODE_OAUTH_TOKEN # the review, or builds in the cloud
310
+ gh secret set FACTORY_BOARD_TOKEN # a board
311
+ gh secret set FACTORY_BUILD_TOKEN # builds in the cloud, with no board
312
+ gh secret set FACTORY_AUTOMERGE_TOKEN # pull requests that merge themselves
313
+ ```
314
+
315
+ Two optional settings:
316
+
317
+ - **Paying by the token instead of a subscription:** store an API key from
318
+ the [Claude Console](https://platform.claude.com) as `ANTHROPIC_API_KEY`.
319
+ A workflow uses it when `CLAUDE_CODE_OAUTH_TOKEN` is not set.
320
+ - **The model a cloud session uses:** `gh variable set FACTORY_BUILD_MODEL`.
321
+ This is a variable, not a secret.
322
+
323
+ Everything the factory owns starts with `FACTORY_`. The other two keep the
324
+ names Claude's GitHub Action gives them, since your other workflows may
325
+ use them too.
326
+
327
+ ## Checking it
328
+
329
+ ```bash
330
+ factory doctor
331
+ ```
332
+
333
+ **It worked when** every check shows ✓, or `-` for a part you left off.
334
+ [Changing it later](setup.md#changing-it-later) says what it checks.
@@ -20,33 +20,32 @@ Everything the factory adds, and what
20
20
  | `.claude/factory/`, the rules | Setup | Deletes it |
21
21
  | `.claude/skills/factory-*/` | Setup | Deletes them |
22
22
  | `.claude/agents/factory-*.md` | Setup | Deletes them |
23
- | Five hook entries in `.claude/settings.json` | Setup | Removes those five, keeps the rest |
23
+ | Five hook entries in `.claude/settings.json` | Setup | Removes those five, keeps the rest, and deletes an emptied file |
24
24
  | `attribution` in `.claude/settings.json`, when the file had none | Setup | Leaves it: delete the key to get Claude Code's lines back |
25
- | One line in `CLAUDE.md` | Setup | Removes that line |
25
+ | One line in `CLAUDE.md` | Setup | Removes that line, and deletes an emptied file |
26
26
  | `.github/workflows/factory-check.yml` | Setup | Deletes them |
27
27
  | Other `.github/workflows/factory-*.yml` | Setup, and each part you turned on | Deletes them |
28
- | `.github/factory-review.md` | The automated review | Deletes it |
28
+ | `.github/factory-review.md` | Setup | Deletes it |
29
+ | `.github/actions/factory-*/`, the step the workflows share | Setup | Deletes them |
29
30
  | `.github/review-notes.md` | You, if you wrote one. It is yours | Leaves it |
30
31
  | The `@davidbyoung/software-factory` entry in `package.json`, and `package-lock.json` | `npm install` | Left for `npm uninstall` |
31
- | `package.json` itself, if you had none | Setup | Leaves it. Delete it and its lockfile if nothing else uses them |
32
+ | `package.json` itself, if you had none | You, before installing | Leaves it. Delete it and its lockfile if nothing else uses them |
32
33
  | `node_modules/` in `.gitignore` | Setup, if it was missing | Leaves it. Remove the line if you deleted `package.json` |
33
34
 
34
- The "Removing it" column says what `factory remove`
35
- (_[Planned](../developing.md#what-is-built)_) does with each; until it is
36
- built, do the same by hand.
35
+ The "Removing it" column says what `factory remove` does with each.
37
36
 
38
37
  ### On GitHub
39
38
 
40
- | What | Added when | To undo |
41
- | ------------------------------------------------------------------------------------- | --------------------------------------------------------------- | ----------------------------------------------------------------------- |
42
- | Secrets and variables named `FACTORY_...` | You create them | Delete them |
43
- | `CLAUDE_CODE_OAUTH_TOKEN` | You create it, for the automated review and builds in the cloud | Delete it, unless another workflow uses it |
44
- | Labels: `merge: automatic`, `merge: manual`, `verdict: override`, `follow-up`, `spec` | First use | Delete them. Deleting a label removes it from every ticket |
45
- | A CI check that the factory's files are in step | Setup | Goes with `factory-check.yml` |
46
- | A "Review verdict" required check | You add it to your branch rules | Remove it from the rules **first**, or pull requests wait on it forever |
47
- | Statuses on pull requests: "Who merges", "Review verdict" | Each pull request | They stay in history |
48
- | One open ticket titled "Follow-ups" | The first follow-up | Close it |
49
- | Comments on tickets the factory worked | Each refinement and build | They stay. They hold the ticket's history |
39
+ | What | Added when | To undo |
40
+ | ------------------------------------------------------------------------------------- | --------------------------------------------------------------- | ----------------------------------------------------------------------------------------- |
41
+ | Secrets and variables named `FACTORY_...` | You create them | Delete them |
42
+ | `CLAUDE_CODE_OAUTH_TOKEN` | You create it, for the automated review and builds in the cloud | Delete it, unless another workflow uses it |
43
+ | Labels: `merge: automatic`, `merge: manual`, `verdict: override`, `follow-up`, `spec` | First use | Delete them. Deleting a label removes it from every ticket |
44
+ | A CI check that the factory's files are in step | Setup | Goes with `factory-check.yml` |
45
+ | A "Review verdict" required check, as the ruleset "Software factory" | `init`, when the review is on; or you, in your branch rules | Delete the ruleset, under Settings, Rules, **first**, or pull requests wait on it forever |
46
+ | Statuses on pull requests: "Who merges", "Review verdict" | Each pull request | They stay in history |
47
+ | One open ticket titled "Follow-ups" | The first follow-up | Close it |
48
+ | Comments on tickets the factory worked | Each refinement and build | They stay. They hold the ticket's history |
50
49
 
51
50
  ### On your board
52
51
 
@@ -55,16 +54,16 @@ built, do the same by hand.
55
54
  | Up to six columns, if yours lacked them and `factory init` added them | Delete the ones you do not want |
56
55
  | Three fields, Session, Runs in, and Cost, if yours lacked them and `init` added them. The sync also sets the board's own Status field | Delete the three |
57
56
  | A Project `init` created, linked to the repository | Delete it, or keep it as an ordinary Project |
58
- | The "Software factory" ruleset, requiring "Review verdict" | Delete the ruleset, under Settings, Rules |
59
57
 
60
58
  A board the factory created for you is an ordinary GitHub Project. Keep
61
59
  it or delete it.
62
60
 
63
61
  ### Outside GitHub
64
62
 
65
- Only if you turned on builds that start from the board: **the poller**,
66
- wherever you host it, with the four `FACTORY_` variables you gave it. Stop
67
- and delete it.
63
+ Only if you host the poller
64
+ ([`builds.trigger: own-server`](../configuration.md#builds)): **the
65
+ poller**, wherever you host it, with the four `FACTORY_` variables you
66
+ gave it. Stop and delete it.
68
67
 
69
68
  ## Workflows
70
69
 
@@ -72,18 +71,19 @@ and delete it.
72
71
  Each one that runs a Claude Code session first checks whether there is
73
72
  anything to do, and stops there when there is not.
74
73
 
75
- | Workflow | Starts on | What it does |
76
- | ----------------------------- | --------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
77
- | `factory-check.yml` | Every pull request | Fails when the factory's files differ from what your settings and version would write |
78
- | `factory-build.yml` | The poller, `factory build N`, or by hand | Runs a session that builds the ticket |
79
- | `factory-review.yml` | A review you submit on a pull request | Runs a session that answers it, when `factory pr review-pending N REVIEW` exits 0 |
80
- | `factory-conflicts.yml` | A push to the default branch, nightly at 09:00 UTC, or by hand | Runs the conflict sweep, when `factory pr conflicts` exits 0 |
81
- | `factory-deps.yml` | 01:00, 13:00, and 19:00 UTC, or by hand | Runs a session that moves Dependabot's pull requests along, when `factory deps --any` exits 0. Written once `.github/dependabot.yml` exists |
82
- | `factory-deps-auto-merge.yml` | Dependabot's pull requests | Lets one merge itself when your `auto-merge` settings allow its files. Written once `.github/dependabot.yml` exists |
83
- | `factory-board-sync.yml` | Ticket and pull request events, and nightly | Sets the board's columns and fields from the tickets' marker comments. Written once `tickets.board` is set |
84
- | `factory-merge-policy.yml` | Every pull request | Labels it `merge: automatic` or `merge: manual`, and turns auto-merge on for the first. Written once `auto-merge.allow` is set |
85
- | `factory-review-verdict.yml` | Each automated review | Posts the "Review verdict" status from the review's summary |
86
- | `factory-claude-review.yml` | Every pull request once it is marked ready, and each push after | Runs the automated review. Written once `ci-review` is set |
74
+ | Workflow | Starts on | What it does |
75
+ | ----------------------------- | --------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
76
+ | `factory-check.yml` | Every pull request, and a push to the default branch | Fails when the factory's files differ from what your settings and version would write |
77
+ | `factory-build.yml` | The poller, `factory build N`, or by hand | Runs a session that builds the ticket |
78
+ | `factory-review.yml` | A review you submit on a pull request | Runs a session that answers it, when `factory pr review-pending N REVIEW` exits 0 |
79
+ | `factory-conflicts.yml` | A push to the default branch, nightly at 09:00 UTC, or by hand | Runs the conflict sweep, when `factory pr conflicts` exits 0 |
80
+ | `factory-deps.yml` | 01:00, 13:00, and 19:00 UTC, or by hand | Runs a session that moves Dependabot's pull requests along, when `factory deps --any` exits 0. Written once `.github/dependabot.yml` exists |
81
+ | `factory-deps-auto-merge.yml` | Dependabot's pull requests | Lets one merge itself when your [`auto-merge`](../configuration.md#auto-merge) settings allow its files. Written once `.github/dependabot.yml` exists |
82
+ | `factory-board-sync.yml` | Ticket and pull request events, and nightly | Sets the board's columns and fields from the tickets' marker comments. Written once [`tickets.board`](../configuration.md#tickets) is set |
83
+ | `factory-merge-policy.yml` | Every pull request | Labels it `merge: automatic` or `merge: manual`, and turns auto-merge on for the first. Written once `auto-merge.allow` is set |
84
+ | `factory-review-verdict.yml` | Each automated review | Posts the "Review verdict" status from the review's summary |
85
+ | `factory-claude-review.yml` | Every pull request once it is marked ready, and each push after | Runs the automated review. Written once [`ci-review`](../configuration.md#ci-review) is set |
86
+ | `factory-poller.yml` | Every `builds.poll-minutes` minutes, or by hand | Runs one pass of the poller, starting a build for each Ready ticket. Written once `builds.trigger` is `github-action` |
87
87
 
88
88
  **Starting a build by hand.** The Actions tab, "Factory build", "Run
89
89
  workflow", and the ticket's number. The board's "Runs in" field then shows
@@ -91,7 +91,8 @@ workflow", and the ticket's number. The board's "Runs in" field then shows
91
91
  tool call the session was denied, with the reason.
92
92
 
93
93
  The poller starts `factory-build.yml` on the repository's default branch,
94
- which it reads once when it starts. The run does no start check of its
94
+ which a poller you host reads once when it starts, and a scheduled pass on
95
+ each run. The run does no start check of its
95
96
  own: only someone with write access can start a workflow.
96
97
 
97
98
  A review on a pull request that conflicts with the default branch starts
@@ -125,7 +126,7 @@ committer are then that account's.
125
126
 
126
127
  When a build cannot start, the poller's comment on the ticket reads "Could
127
128
  not start a build in GitHub Actions ... answered 403": give the token the
128
- scopes [Secrets](setup.md#secrets) names. A failed board sync arrives as
129
+ scopes [Secrets](by-hand.md#secrets) names. A failed board sync arrives as
129
130
  an email from GitHub.
130
131
 
131
132
  ## The board
@@ -147,28 +148,28 @@ number, the last part of its address, is `tickets.board` in your settings.
147
148
 
148
149
  ## Labels and statuses
149
150
 
150
- | Name | Kind | Set by |
151
- | ------------------- | ------------------------ | ------------------------------------------------------------------------------ |
152
- | `merge: automatic` | Label on a pull request | The merge policy, when every file is allowed |
153
- | `merge: manual` | Label on a pull request | The merge policy, otherwise |
154
- | `verdict: override` | Label on a pull request | Only a person: passes the review verdict for one commit. Sessions never add it |
155
- | `follow-up` | Label on a ticket | The first follow-up line, on the one follow-ups ticket |
156
- | `spec` | Label on a ticket | Refinement, for a change your users will see, when `specs: openspec` |
157
- | Who merges | Status on a pull request | The merge policy: which way it goes, and why |
158
- | Review verdict | Status on a pull request | The review-verdict workflow: success only when the review said ready |
151
+ | Name | Kind | Set by |
152
+ | ------------------- | ------------------------ | ------------------------------------------------------------------------------------------------- |
153
+ | `merge: automatic` | Label on a pull request | The merge policy, when every file is allowed |
154
+ | `merge: manual` | Label on a pull request | The merge policy, otherwise |
155
+ | `verdict: override` | Label on a pull request | Only a person: passes the review verdict for one commit. Sessions never add it |
156
+ | `follow-up` | Label on a ticket | The first follow-up line, on the one follow-ups ticket |
157
+ | `spec` | Label on a ticket | Refinement, for a change your users will see, when [`specs: openspec`](../configuration.md#specs) |
158
+ | Who merges | Status on a pull request | The merge policy: which way it goes, and why |
159
+ | Review verdict | Status on a pull request | The review-verdict workflow: success only when the review said ready |
159
160
 
160
161
  ## Hooks
161
162
 
162
163
  `sync` adds five hooks to `.claude/settings.json`. They run inside Claude
163
164
  Code sessions in this repository, not in your own terminal.
164
165
 
165
- | Hook | What it does |
166
- | --------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
167
- | Before a shell command | Blocks a commit on your main branch, a push to it, and a force push. Runs your `before-commit` commands before a commit |
168
- | Before posting ticket text | Refuses text with a bare `<tag>`, which GitHub would silently drop |
169
- | When a reviewer starts or stops | Records the run on the ticket, so its cost is counted |
170
- | Before an unattended build writes a file under `.claude/` | Approves the write, when the run is one the factory started and the file is not `.claude/settings.json` or `.claude/settings.local.json` |
171
- | When a session starts | Shows unfinished branches and where each ticket stands |
166
+ | Hook | What it does |
167
+ | --------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
168
+ | Before a shell command | Blocks a commit on your default branch, a push to it, and a force push. Runs your [`commands.before-commit`](../configuration.md#commandsbefore-commit) commands before a commit |
169
+ | Before posting ticket text | Refuses text with a bare `<tag>`, which GitHub would silently drop |
170
+ | When a reviewer starts or stops | Records the run on the ticket, so its cost is counted |
171
+ | Before an unattended build writes a file under `.claude/` | Approves the write, when the run is one the factory started and the file is not `.claude/settings.json` or `.claude/settings.local.json` |
172
+ | When a session starts | Shows unfinished branches and where each ticket stands |
172
173
 
173
174
  Claude Code protects `.claude/`, and an unattended run denies a write
174
175
  there that nothing approves. The fourth hook approves, only in a run the
@@ -205,12 +206,14 @@ Typing `/factory` in a session lists them, which is also how to check that
205
206
  a session picked the factory up.
206
207
 
207
208
  **Where the files live.** `sync` writes the factory's skills to
208
- `.claude/skills/factory-*/` and its agents to `.claude/agents/factory-*.md`.
209
- Your own skills go in `.claude/skills/NAME/SKILL.md` and your own agents
210
- in `.claude/agents/NAME.md`, as for any Claude Code project. A plug-in
211
- names one under `plugins` in `.claude/factory.yaml`, with `skill:` for a
212
- folder in `.claude/skills/` and `agent:` for a file in `.claude/agents/`.
213
- An agent's description is the `description` in its file's front matter.
209
+ `.claude/skills/factory-*/` and its agents to
210
+ `.claude/agents/factory-*.md`. Your own skills go in
211
+ `.claude/skills/NAME/SKILL.md` and your own agents in
212
+ `.claude/agents/NAME.md`, as for any Claude Code project. A plug-in names
213
+ one under [`plugins`](../configuration.md#plugins) in
214
+ `.claude/factory.yaml`, with `skill:` for a folder in `.claude/skills/`
215
+ and `agent:` for a file in `.claude/agents/`. An agent's description is
216
+ the `description` in its file's front matter.
214
217
 
215
218
  A colon, as in `/factory:refine`, is something Claude Code adds to a
216
219
  skill that comes from a plugin. Plain skill files get plain names, so the
@@ -220,9 +223,11 @@ still laid out as a valid Claude Code plugin, so loading the skills from
220
223
  it instead of copying them stays possible.
221
224
 
222
225
  **Your project's instructions** are its `CLAUDE.md` files: the one at the
223
- root, and any beside the code they govern. The skills read how to check a
224
- change, and the rules for each area, from them. `sync` adds one line to
225
- the root `CLAUDE.md`, which loads the factory's rules.
226
+ root, and any beside the code they govern. The skills read the rules for
227
+ each area from them. How to check a change is not there: it is
228
+ [`commands.gate`](../configuration.md#commandsgate) in your settings.
229
+ `sync` adds one line to the root `CLAUDE.md`, which loads the factory's
230
+ rules.
226
231
 
227
232
  ## Dependency bots
228
233
 
@@ -256,19 +261,23 @@ These come from GitHub, GitHub Actions, or Claude Code, not from the
256
261
  factory.
257
262
 
258
263
  - **GitHub's own runners stop any job at 6 hours.** A cloud session's job
259
- is given its `session-minutes` plus 10, so the step that releases the
260
- claim still runs; a value above 350 does nothing there. A self-hosted
261
- runner allows longer. `sync` writes each `session-minutes` value into
262
- the session workflows as the session step's timeout.
264
+ is given its [`session-minutes`](../configuration.md#session-minutes)
265
+ plus 10, so the step that releases the claim still runs; a value above
266
+ 350 does nothing there. A self-hosted runner allows longer. `sync`
267
+ writes each `session-minutes` value into the session workflows as the
268
+ session step's timeout.
263
269
  - GitHub's shortest schedule is every five minutes, and scheduled runs can
264
270
  start late.
265
271
  - Public repositories are not billed for Actions minutes.
266
272
  - GitHub switches off scheduled workflows in a public repository with no
267
273
  activity for 60 days.
268
274
  - GitHub limits how many jobs an account runs at the same time.
269
- - **A default branch not named `main` or `master` gets no conflict sweep
270
- on a push.** A copied workflow cannot ask for the default branch's name.
271
- It gets the nightly sweep, and can start one by hand.
275
+ - **A workflow's trigger cannot ask for the default branch's name,** so
276
+ `factory sync` writes the name into the push triggers of
277
+ `factory-check.yml` and `factory-conflicts.yml`. After you rename the
278
+ default branch, `factory sync --check` fails until you run
279
+ `factory sync` again, and until then the conflict sweep runs nightly and
280
+ by hand, not on a push.
272
281
  - **Every review event costs a minute of Actions,** including the
273
282
  factory's own replies, which start runs that find nothing to do.
274
283
  - **A token from a GitHub App is not supported** for a build. The run asks