@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,288 @@
1
+ # GitHub and Claude Code reference
2
+
3
+ Where each part of the factory lives when the code host is GitHub, the
4
+ tickets are GitHub Issues, the board is a GitHub Project, builds in the
5
+ cloud run in GitHub Actions, and the coding agent is Claude Code.
6
+ [Setting up on GitHub](setup.md) says how to turn each part on; this page
7
+ says what you will find once it is on.
8
+
9
+ ## What setup adds
10
+
11
+ Everything the factory adds, and what
12
+ [removing it](../removing.md) does with each.
13
+
14
+ ### In your repository
15
+
16
+ | What | Added by | Removing it |
17
+ | ------------------------------------------------------------------------------------ | ---------------------------------- | --------------------------------------------------------------- |
18
+ | `.claude/factory.yaml`, your settings | Setup | Deletes it |
19
+ | `.claude/factory.lock` | Setup | Deletes it |
20
+ | `.claude/factory/`, the rules | Setup | Deletes it |
21
+ | `.claude/skills/factory-*/` | Setup | Deletes them |
22
+ | `.claude/agents/factory-*.md` | Setup | Deletes them |
23
+ | Five hook entries in `.claude/settings.json` | Setup | Removes those five, keeps the rest |
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 |
26
+ | `.github/workflows/factory-check.yml` | Setup | Deletes them |
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 |
29
+ | `.github/review-notes.md` | You, if you wrote one. It is yours | Leaves it |
30
+ | 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
+ | `node_modules/` in `.gitignore` | Setup, if it was missing | Leaves it. Remove the line if you deleted `package.json` |
33
+
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.
37
+
38
+ ### On GitHub
39
+
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 |
50
+
51
+ ### On your board
52
+
53
+ | What | To undo |
54
+ | ------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------- |
55
+ | Up to six columns, if yours lacked them and `factory init` added them | Delete the ones you do not want |
56
+ | 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
+ | 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
+
60
+ A board the factory created for you is an ordinary GitHub Project. Keep
61
+ it or delete it.
62
+
63
+ ### Outside GitHub
64
+
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.
68
+
69
+ ## Workflows
70
+
71
+ `factory sync` writes these under `.github/workflows/`.
72
+ Each one that runs a Claude Code session first checks whether there is
73
+ anything to do, and stops there when there is not.
74
+
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 |
87
+
88
+ **Starting a build by hand.** The Actions tab, "Factory build", "Run
89
+ workflow", and the ticket's number. The board's "Runs in" field then shows
90
+ "Actions", and "Session" the run's link. The run's log also shows each
91
+ tool call the session was denied, with the reason.
92
+
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
95
+ own: only someone with write access can start a workflow.
96
+
97
+ A review on a pull request that conflicts with the default branch starts
98
+ no run, since GitHub starts no workflow for a pull request it cannot
99
+ merge. The conflict sweep clears the conflict and works the review in the
100
+ same run, and `factory-review.yml` can be started by hand with the pull
101
+ request's and the review's numbers.
102
+
103
+ **Which token a cloud session uses.** The access token is
104
+ `FACTORY_BUILD_TOKEN`, or `FACTORY_BOARD_TOKEN` when that is not set. The
105
+ workflow's own token is never used for a build, since GitHub starts no CI
106
+ on a pull request that token opened. The token must be allowed to push a
107
+ change under `.github/workflows/` (the `workflow` scope), or such a push is
108
+ refused and the build stops there. The agent's token is
109
+ `CLAUDE_CODE_OAUTH_TOKEN`, or `ANTHROPIC_API_KEY`; with both set, the
110
+ first is used. `FACTORY_BUILD_MODEL`, a repository variable, chooses the
111
+ model.
112
+
113
+ **Who a build's commits name.** Their author is Claude,
114
+ `Claude <noreply@anthropic.com>`, which GitHub links to its `claude` user.
115
+ Their committer is the token's owner, by the account's no-reply address,
116
+ which is what lets that account's signing key show them as verified. When
117
+ a pull request is squash merged, the commit on your default branch names
118
+ the person who opened it as its author, and GitHub adds a
119
+ `Co-authored-by: Claude` line for the build's commits.
120
+
121
+ A team that wants its builds to act as an account of their own creates a
122
+ GitHub account, gives it write access, and stores that account's token as
123
+ `FACTORY_BUILD_TOKEN`. The build's pull requests, comments, and commits'
124
+ committer are then that account's.
125
+
126
+ When a build cannot start, the poller's comment on the ticket reads "Could
127
+ 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
+ an email from GitHub.
130
+
131
+ ## The board
132
+
133
+ A GitHub Project, owned by the account or the organization that owns the
134
+ repository. The sync sets its Status field to the ticket's column and
135
+ writes three fields of its own, which `init` adds when the board lacks
136
+ them:
137
+
138
+ | Field | Shows |
139
+ | ------- | ------------------------------------------------------------------------ |
140
+ | Status | The column |
141
+ | Session | Which session is on the ticket, "actions, starting", or "Waiting on you" |
142
+ | Runs in | "local" or "Actions" |
143
+ | Cost | An estimate of what refining and building the ticket used |
144
+
145
+ Anything typed into the last three is overwritten on the next sync. Its
146
+ number, the last part of its address, is `tickets.board` in your settings.
147
+
148
+ ## Labels and statuses
149
+
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 |
159
+
160
+ ## Hooks
161
+
162
+ `sync` adds five hooks to `.claude/settings.json`. They run inside Claude
163
+ Code sessions in this repository, not in your own terminal.
164
+
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 |
172
+
173
+ Claude Code protects `.claude/`, and an unattended run denies a write
174
+ there that nothing approves. The fourth hook approves, only in a run the
175
+ factory's action started, a write to the repository's own files under
176
+ `.claude/`: its skills, its agents, `.claude/factory.yaml`, and
177
+ `.claude/change-types.md`. It never approves a write to the two settings
178
+ files, which hold the hooks that guard the run. A session a person starts
179
+ is asked as before. A change under `.claude/` still waits for your merge,
180
+ since no `auto-merge` rule allows it.
181
+
182
+ `sync` also sets `attribution` in `.claude/settings.json` to leave out
183
+ Claude Code's own "Co-Authored-By" and "Generated with" lines, so a
184
+ session's commits and pull requests carry only the person's name. It leaves an `attribution`
185
+ you set yourself alone.
186
+
187
+ ## Skills in Claude Code
188
+
189
+ In Claude Code a skill is also a slash command: type `/` and its name,
190
+ with the ticket or pull request number after it. Asking in plain words
191
+ calls the same skill.
192
+
193
+ | Type | Same as asking |
194
+ | -------------------------------- | ---------------------------------- |
195
+ | `/factory-refine 12` | "refine ticket 12" |
196
+ | `/factory-build 12` | "build ticket 12" |
197
+ | `/factory-address-review 280` | "address the review on 280" |
198
+ | `/factory-resolve-conflicts 280` | "resolve the conflicts on 280" |
199
+ | `/factory-diagnose` | "diagnose this failing test" |
200
+ | `/factory-mutate` | "mutate this test" |
201
+ | `/factory-deps` | "fix the dependency pull requests" |
202
+ | `/factory-design` | "mock up a new about page" |
203
+
204
+ Typing `/factory` in a session lists them, which is also how to check that
205
+ a session picked the factory up.
206
+
207
+ **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.
214
+
215
+ A colon, as in `/factory:refine`, is something Claude Code adds to a
216
+ skill that comes from a plugin. Plain skill files get plain names, so the
217
+ prefix `factory-` is part of the name. It also shows, in `.claude/skills/`,
218
+ which files an update will overwrite and which are yours. The package is
219
+ still laid out as a valid Claude Code plugin, so loading the skills from
220
+ it instead of copying them stays possible.
221
+
222
+ **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
+
227
+ ## Dependency bots
228
+
229
+ Dependabot opens each new version of the factory as a pull request of its
230
+ own, and `factory-deps` adds the files that version writes
231
+ ([Updating](../updating.md)). Give the package a group of its own, and keep
232
+ it out of any group that takes every package, so its pull request holds
233
+ nothing else. In `.github/dependabot.yml`:
234
+
235
+ ```yaml
236
+ updates:
237
+ - package-ecosystem: npm
238
+ directory: /
239
+ schedule:
240
+ interval: weekly
241
+ groups:
242
+ factory:
243
+ patterns: ["@davidbyoung/software-factory"]
244
+ npm:
245
+ patterns: ["*"]
246
+ exclude-patterns: ["@davidbyoung/software-factory"]
247
+ update-types: [minor, patch]
248
+ ```
249
+
250
+ `factory-deps-auto-merge.yml` never turns auto-merge on for it, so it
251
+ waits for you whatever its size.
252
+
253
+ ## Limits
254
+
255
+ These come from GitHub, GitHub Actions, or Claude Code, not from the
256
+ factory.
257
+
258
+ - **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.
263
+ - GitHub's shortest schedule is every five minutes, and scheduled runs can
264
+ start late.
265
+ - Public repositories are not billed for Actions minutes.
266
+ - GitHub switches off scheduled workflows in a public repository with no
267
+ activity for 60 days.
268
+ - 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.
272
+ - **Every review event costs a minute of Actions,** including the
273
+ factory's own replies, which start runs that find nothing to do.
274
+ - **A token from a GitHub App is not supported** for a build. The run asks
275
+ GitHub who owns the token to name its commits' committer, and an App's
276
+ token has no user.
277
+ - **The squash merge on your default branch is signed by GitHub,** whether
278
+ or not the build's own commits were.
279
+ - **The factory does not work inside a Claude cloud session.** Its
280
+ commands need GitHub's GraphQL API, which is closed there.
281
+ `factory build N` still works from such a session,
282
+ since it only asks GitHub to start a workflow.
283
+ - **Untested against a real organization: a board one owns.** It is read
284
+ the same way as a person's. The token needs access to the
285
+ organization's projects, which an organization's settings can refuse a
286
+ classic token.
287
+ - **Untested: GitHub's built-in board automations,** such as moving a
288
+ closed issue to Done. They may fight the board sync.
@@ -0,0 +1,312 @@
1
+ # Setting up on GitHub, with Claude Code
2
+
3
+ Every step to set the factory up with GitHub as the code host, GitHub
4
+ Issues for tickets, a GitHub Project for the board, GitHub Actions for
5
+ builds in the cloud, and Claude Code as the coding agent. One command does
6
+ all of it; the rest of the page is the same setup by hand.
7
+
8
+ ## What you need
9
+
10
+ | Tool | Check it with | If it is not ready |
11
+ | ----------------------------------- | ------------------ | ----------------------------------------------------------------------- |
12
+ | A GitHub repository, with Issues on | Its Issues tab | On GitHub: Settings, General, Features, check "Issues" |
13
+ | The GitHub CLI, signed in | `gh auth status` | `gh auth login` |
14
+ | Claude Code, signed in | `claude --version` | [Install it](https://claude.com/claude-code), run `claude`, and sign in |
15
+ | Node 22.18 or later | `node --version` | [nodejs.org](https://nodejs.org) |
16
+
17
+ ## Setting it up with one command
18
+
19
+ In your repository, with the package installed:
20
+
21
+ ```bash
22
+ factory init
23
+ ```
24
+
25
+ It says what it found, asks which parts you want, and shows everything it
26
+ will do before it does any of it. Told to go ahead, it writes the settings
27
+ and the factory's files, makes or connects the board with its columns and
28
+ fields, stores every secret your parts need, and turns on the repository
29
+ settings they need. It commits nothing, and ends with what is left for you
30
+ and the checks `factory doctor` runs.
31
+
32
+ Run it again to turn a part on or off. It starts from what you already
33
+ have, and does not ask again for a secret that is already set.
34
+
35
+ A token is typed into a masked prompt and goes straight to GitHub; it is
36
+ never printed or written to a file.
37
+
38
+ ## Setting it up by hand
39
+
40
+ For anyone who cannot run `init`, or who wants to see what it does. Do
41
+ [the basics](#the-basics), then only the parts you want, in the order they
42
+ appear.
43
+
44
+ ### Choose what you want
45
+
46
+ The basics are all the [quick start](../quick-start.md) needs. Everything
47
+ else is optional, and each part stands alone.
48
+
49
+ | Part | What you get | What it takes |
50
+ | --------------------------------------------------------------------------- | ------------------------------------------------------------------------------- | ------------------------------------------------------------------ |
51
+ | [The basics](#the-basics) | Refining and building tickets in a Claude Code session on your machine | A settings file and one command |
52
+ | [The automated review](#the-automated-review) | Claude reads every pull request once it is ready, comments, and gives a verdict | The Claude GitHub App, a workflow file, and your Claude token |
53
+ | [A board](#a-board) | A GitHub Project showing each ticket's state, its session, and its cost | A Project, one setting, and a GitHub token |
54
+ | [Builds in the cloud](#builds-in-the-cloud) | A ticket builds in GitHub Actions, with no session open on your machine | Your Claude token and a GitHub token |
55
+ | [Pull requests that merge themselves](#pull-requests-that-merge-themselves) | A pull request that touches only files you listed merges once its checks pass | A list of files, one repository setting, and a second GitHub token |
56
+ | [Signed commits from cloud builds](#signed-commits-from-cloud-builds) | A build's commits show as "Verified" | A signing key |
57
+
58
+ Every part's secrets are gathered in [Secrets](#secrets), so you can make
59
+ them all at once.
60
+
61
+ ### The basics
62
+
63
+ If you followed the quick start, this is done.
64
+
65
+ 1. Write `.claude/factory.yaml`, with your repository's owner and name:
66
+
67
+ ```yaml
68
+ version: 1
69
+ repository: your-name/your-repo
70
+ ```
71
+
72
+ 2. Write the factory's files:
73
+
74
+ ```bash
75
+ factory sync
76
+ ```
77
+
78
+ It writes the skills, agents, and rules Claude Code loads, under
79
+ `.claude/`; adds hook entries to `.claude/settings.json`; adds one line
80
+ to `CLAUDE.md`; and writes the workflows under `.github/workflows/`.
81
+ [What lives where](reference.md) names each.
82
+
83
+ 3. Say in your `CLAUDE.md` how to check a change, such as the commands for
84
+ your tests and linter. A build runs them.
85
+ 4. Optionally, list commands to run before every commit a session makes:
86
+
87
+ ```yaml
88
+ before-commit:
89
+ - npm run lint
90
+ ```
91
+
92
+ 5. Check, commit, and merge:
93
+
94
+ ```bash
95
+ factory sync --check
96
+ factory config check
97
+ git switch -c set-up-factory && git add -A
98
+ git commit -m "Set up the software factory"
99
+ git push -u origin set-up-factory
100
+ gh pr create --fill
101
+ ```
102
+
103
+ Merge the pull request on GitHub, then `git switch main && git pull`,
104
+ and start a new Claude Code session.
105
+
106
+ **It worked when** typing `/factory` in the new session offers
107
+ `/factory-refine` and `/factory-build`.
108
+
109
+ Every part below is turned on the same way: add its settings to
110
+ `.claude/factory.yaml`, run `factory sync`, do the steps
111
+ the part lists, and merge what `sync` wrote.
112
+
113
+ ### The automated review
114
+
115
+ Claude reads every pull request once it is marked ready, comments on what
116
+ it finds, and posts a verdict. The session that built the pull request
117
+ answers each comment, fixing it or rejecting it with evidence.
118
+
119
+ It is on while `.claude/factory.yaml` has
120
+ [`ci-review`](../configuration.md#ci-review), which `init` writes when you
121
+ choose it. Three files have similar names, and `sync` writes all three:
122
+
123
+ | File | What it is |
124
+ | ---------------------------------------------- | ---------------------------------------------------------- |
125
+ | `.github/workflows/factory-claude-review.yml` | The workflow that runs the review |
126
+ | `.github/factory-review.md` | The review's instructions |
127
+ | `.github/workflows/factory-review-verdict.yml` | Turns each review's summary into a "Review verdict" status |
128
+
129
+ 1. **Install the Claude GitHub App** on the repository, from
130
+ <https://github.com/apps/claude>. The review posts its comments through
131
+ it. Or run `/install-github-app` in Claude Code, which installs the app
132
+ and also stores the Claude token for you.
133
+ 2. **Store your Claude token** as `CLAUDE_CODE_OAUTH_TOKEN`
134
+ ([Secrets](#secrets)), unless step 1 did.
135
+ 3. **Write `ci-review` in `.claude/factory.yaml`,** with the commands the
136
+ reviewer may run to confirm a finding, such as your tests, and run
137
+ `factory sync`. The workflow installs your project with
138
+ `npm ci`, and chooses the model from `FACTORY_BUILD_MODEL`
139
+ ([Variables](reference.md#workflows)) when it is set.
140
+ 4. **Optionally, write `.github/review-notes.md`:** what a reviewer must
141
+ know about your project that your `CLAUDE.md` does not say. The
142
+ reviewer reads it when it exists.
143
+ 5. **To make the verdict count,** add "Review verdict" to the required
144
+ status checks of your default branch: Settings, then Rules or Branches.
145
+ Until you do, it is information only.
146
+
147
+ ### A board
148
+
149
+ A GitHub Project that shows each ticket's state as a column, which session
150
+ has it, and what it has cost. [Workflow](../workflow.md#the-board) says
151
+ what each column means.
152
+
153
+ 1. **Create a Project** under the account or the organization that owns the
154
+ repository: its Projects tab, "New project", Board layout. Link it to
155
+ the repository from the Project's menu, so it shows on the repository's
156
+ Projects tab. Its number is the last part of its address.
157
+ 2. **Give it the factory's columns:** Backlog, In refinement, Ready, In
158
+ progress, In review, and Done, in its Status field. A new Project starts
159
+ with Todo, In Progress, and Done. To keep columns of your own, map them
160
+ under [`tickets.columns`](../configuration.md#ticketscolumns) instead.
161
+ 3. **Give it the three fields the sync writes:** Session, a Text field;
162
+ Runs in, a single select with the options Local and Actions; and Cost, a
163
+ Number. A field the sync does not find, it skips.
164
+ 4. **Point the settings at it:**
165
+
166
+ ```yaml
167
+ tickets:
168
+ board: 7
169
+ ```
170
+
171
+ Then `factory board check` shows how it reads your
172
+ columns.
173
+
174
+ 5. **Store a GitHub token** as `FACTORY_BOARD_TOKEN` ([Secrets](#secrets)).
175
+ 6. **Run `factory sync`.** It writes the board-sync
176
+ workflow, the only thing that writes to the board. It never creates,
177
+ renames, or removes a column or field.
178
+
179
+ ### Builds in the cloud
180
+
181
+ `factory build 12` builds ticket 12 in GitHub Actions and
182
+ prints the run's link, with no session open on your machine.
183
+
184
+ `sync` already wrote the workflows these use, and each does nothing until
185
+ it has work and its secrets:
186
+
187
+ | Workflow | Runs a Claude Code session that |
188
+ | ----------------------- | ------------------------------------------------------------------------------------ |
189
+ | `factory-build.yml` | builds a ticket |
190
+ | `factory-review.yml` | answers a review you submit on a pull request |
191
+ | `factory-conflicts.yml` | resolves a conflict between a pull request and your main branch |
192
+ | `factory-deps.yml` | moves Dependabot's pull requests along, written once `.github/dependabot.yml` exists |
193
+
194
+ 1. **Store your Claude token** as `CLAUDE_CODE_OAUTH_TOKEN`.
195
+ 2. **Store a GitHub token that can push**, as `FACTORY_BUILD_TOKEN`. With
196
+ a board, `FACTORY_BOARD_TOKEN` stands in for it when it has the
197
+ `workflow` scope, so one token does both ([Secrets](#secrets)).
198
+
199
+ A build may run for 230 minutes, which
200
+ [`session-minutes`](../configuration.md#session-minutes) changes; GitHub
201
+ stops any job at six hours.
202
+
203
+ #### Starting builds from the board
204
+
205
+ To have a ticket build when you move its card to Ready, set
206
+ `builds.trigger: own-server` and run the poller, a small program that
207
+ watches the board and starts each build. [Builds in the cloud](../builds.md)
208
+ explains how to host it and what it costs.
209
+
210
+ ### Pull requests that merge themselves
211
+
212
+ A pull request that touches only files you listed as safe merges once
213
+ every check passes. Everything else still waits for you. Turn this on
214
+ last: it is only as safe as your tests and the review. Start with a short
215
+ list, such as documentation.
216
+
217
+ 1. **List the files** under `auto-merge.allow`, with exceptions under
218
+ `deny`. [Configuration](../configuration.md#auto-merge) explains the
219
+ rules. `sync` then writes the merge-policy workflow, which labels each
220
+ pull request `merge: automatic` or `merge: manual` and says why.
221
+ 2. **Allow auto-merge** on the repository: Settings, General, "Allow
222
+ auto-merge".
223
+ 3. **Store a GitHub token** as `FACTORY_AUTOMERGE_TOKEN` ([Secrets](#secrets)).
224
+
225
+ ### Signed commits from cloud builds
226
+
227
+ Without a key, a build's commits are unsigned.
228
+
229
+ 1. Make a key for this and nothing else, with no passphrase:
230
+
231
+ ```bash
232
+ ssh-keygen -t ed25519 -N "" -C "factory builds" -f factory-signing-key
233
+ ```
234
+
235
+ 2. Add `factory-signing-key.pub` to the GitHub account whose token the
236
+ builds use: Settings, "SSH and GPG keys", "New SSH key", key type
237
+ "Signing Key".
238
+ 3. Store the private half, then delete both files:
239
+
240
+ ```bash
241
+ gh secret set FACTORY_SIGNING_KEY < factory-signing-key
242
+ rm factory-signing-key factory-signing-key.pub
243
+ ```
244
+
245
+ Anything that can run a workflow in the repository can read the key, as
246
+ it can the build token. Removing the public key from the account ends its
247
+ use.
248
+
249
+ ### Secrets
250
+
251
+ Everything here is stored on the repository with `gh secret set NAME`,
252
+ which asks for the value. Nothing the factory runs on your machine needs
253
+ one; each is for something that runs in GitHub Actions.
254
+
255
+ | Secret | Needed for | Make it |
256
+ | ------------------------- | -------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
257
+ | `CLAUDE_CODE_OAUTH_TOKEN` | The automated review, and builds in the cloud | `claude setup-token`, on your machine. It bills your Claude subscription |
258
+ | `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` |
259
+ | `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` |
260
+ | `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` |
261
+ | `FACTORY_SIGNING_KEY` | Signed commits from cloud builds | [The steps above](#signed-commits-from-cloud-builds) |
262
+
263
+ Each token link opens GitHub's page with the scopes checked; choose an
264
+ expiry date and generate it. The account that makes a token is the one
265
+ its work is done as, and must be able to write the repository, and the
266
+ Project for the board token.
267
+
268
+ **One GitHub token is enough for everything.** Make one classic token with
269
+ `repo` and `workflow`, and `project` when you have a board, and store it
270
+ under each name your parts read; `init` does the same. Any workflow a pull
271
+ request from the repository adds can read every secret, so separate tokens
272
+ protect little.
273
+
274
+ Builds and auto-merge also take a fine-grained token instead: read and
275
+ write access to Contents, Pull requests, Issues, and Workflows for builds,
276
+ and to Contents and Pull requests for auto-merge. The board token must be
277
+ classic.
278
+
279
+ To set the ones you need in one go, paste each value when asked:
280
+
281
+ ```bash
282
+ claude setup-token
283
+ gh secret set CLAUDE_CODE_OAUTH_TOKEN
284
+ gh secret set FACTORY_BOARD_TOKEN
285
+ gh secret set FACTORY_AUTOMERGE_TOKEN
286
+ ```
287
+
288
+ Paste the same GitHub token for both of the last two.
289
+
290
+ Two optional settings:
291
+
292
+ - **Paying by the token instead of a subscription:** store an API key from
293
+ the [Claude Console](https://platform.claude.com) as `ANTHROPIC_API_KEY`.
294
+ A workflow uses it when `CLAUDE_CODE_OAUTH_TOKEN` is not set.
295
+ - **The model a cloud session uses:** `gh variable set FACTORY_BUILD_MODEL`.
296
+ This is a variable, not a secret.
297
+
298
+ Everything the factory owns starts with `FACTORY_`. The other two keep the
299
+ names Claude's GitHub Action gives them, since your other workflows may
300
+ use them too.
301
+
302
+ ### Checking it
303
+
304
+ ```bash
305
+ factory doctor
306
+ ```
307
+
308
+ It checks the settings, that the factory's files match them, the installed
309
+ version, who the GitHub CLI is signed in as, that each secret your parts
310
+ read is set, and the board's columns. GitHub never lets a secret be read
311
+ back, so a secret is checked only for being set: a wrong one shows when
312
+ the first run that needs it fails, naming it.