@davidbyoung/software-factory 0.1.1 → 0.1.3

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 (83) hide show
  1. package/README.md +8 -9
  2. package/dist/agent/claude-code.d.mts +3 -0
  3. package/dist/agent/claude-code.mjs +89 -0
  4. package/dist/agent/index.d.mts +2 -0
  5. package/dist/agent/index.mjs +5 -0
  6. package/dist/board.mjs +1 -1
  7. package/dist/cli.mjs +17 -2
  8. package/dist/code-host/github-setup.d.mts +5 -0
  9. package/dist/code-host/github-setup.mjs +133 -0
  10. package/dist/code-host/github.mjs +4 -0
  11. package/dist/code-host/index.d.mts +1 -1
  12. package/dist/code-host/index.mjs +2 -1
  13. package/dist/code-host/types.d.mts +2 -0
  14. package/dist/config.d.mts +26 -7
  15. package/dist/config.mjs +79 -26
  16. package/dist/doctor.d.mts +6 -14
  17. package/dist/doctor.mjs +52 -64
  18. package/dist/explain.d.mts +2 -0
  19. package/dist/explain.mjs +127 -0
  20. package/dist/init.d.mts +8 -12
  21. package/dist/init.mjs +179 -131
  22. package/dist/lib/has-command.d.mts +5 -0
  23. package/dist/lib/has-command.mjs +8 -0
  24. package/dist/lib/listed.d.mts +2 -0
  25. package/dist/lib/listed.mjs +4 -0
  26. package/dist/lib/work-status.d.mts +12 -2
  27. package/dist/lib/work-status.mjs +14 -3
  28. package/dist/parts.d.mts +18 -15
  29. package/dist/parts.mjs +15 -43
  30. package/dist/poller.d.mts +20 -3
  31. package/dist/poller.mjs +62 -15
  32. package/dist/remove.d.mts +11 -0
  33. package/dist/remove.mjs +156 -0
  34. package/dist/runner/github-actions.d.mts +1 -1
  35. package/dist/runner/github-actions.mjs +12 -0
  36. package/dist/runner/index.d.mts +1 -1
  37. package/dist/runner/index.mjs +2 -1
  38. package/dist/runner/setup.d.mts +2 -0
  39. package/dist/runner/setup.mjs +22 -0
  40. package/dist/runner/types.d.mts +3 -0
  41. package/dist/runner/types.mjs +0 -2
  42. package/dist/setup.d.mts +98 -0
  43. package/dist/setup.mjs +3 -0
  44. package/dist/status.d.mts +4 -4
  45. package/dist/status.mjs +8 -7
  46. package/dist/sync.d.mts +22 -3
  47. package/dist/sync.mjs +144 -11
  48. package/dist/tickets/github-setup.d.mts +2 -0
  49. package/dist/tickets/github-setup.mjs +50 -0
  50. package/dist/tickets/github.mjs +0 -2
  51. package/dist/tickets/index.mjs +2 -1
  52. package/dist/tickets/transport.mjs +1 -3
  53. package/dist/tickets/types.mjs +0 -2
  54. package/dist/tool-names.d.mts +11 -0
  55. package/dist/tool-names.mjs +20 -0
  56. package/dist/tools.d.mts +56 -0
  57. package/dist/tools.mjs +76 -0
  58. package/docs/builds.md +103 -51
  59. package/docs/cli.md +42 -42
  60. package/docs/configuration.md +38 -32
  61. package/docs/design.md +1 -1
  62. package/docs/developing.md +156 -67
  63. package/docs/existing-repo.md +20 -9
  64. package/docs/github/by-hand.md +321 -0
  65. package/docs/github/reference.md +65 -61
  66. package/docs/github/setup.md +83 -267
  67. package/docs/glossary.md +5 -4
  68. package/docs/limitations.md +12 -10
  69. package/docs/plugins.md +12 -17
  70. package/docs/quick-start.md +62 -105
  71. package/docs/removing.md +36 -16
  72. package/docs/skills.md +47 -37
  73. package/docs/updating.md +2 -6
  74. package/docs/workflow.md +13 -12
  75. package/package.json +5 -3
  76. package/poller.Dockerfile +10 -18
  77. package/rules.md +14 -12
  78. package/settings.schema.json +24 -0
  79. package/skills/factory-build/SKILL.md +1 -1
  80. package/skills/factory-trace/SKILL.md +79 -0
  81. package/workflows/factory-build.yml +5 -4
  82. package/workflows/factory-deps-auto-merge.yml +3 -2
  83. package/workflows/factory-poller.yml +46 -0
@@ -1,9 +1,10 @@
1
1
  # Setting up on GitHub, with Claude Code
2
2
 
3
- Every step to set the factory up with GitHub as the code host, GitHub
3
+ For someone setting the factory up with GitHub as the code host, GitHub
4
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.
5
+ builds in the cloud, and Claude Code as the coding agent. One command sets
6
+ up the parts you choose. This page says what it asks you, and the little
7
+ it leaves for you to do.
7
8
 
8
9
  ## What you need
9
10
 
@@ -14,299 +15,114 @@ all of it; the rest of the page is the same setup by hand.
14
15
  | Claude Code, signed in | `claude --version` | [Install it](https://claude.com/claude-code), run `claude`, and sign in |
15
16
  | Node 22.18 or later | `node --version` | [nodejs.org](https://nodejs.org) |
16
17
 
17
- ## Setting it up with one command
18
+ ## Run `factory init`
18
19
 
19
- In your repository, with the package installed:
20
+ In your repository, with the package
21
+ [installed](../quick-start.md#1-install):
20
22
 
21
23
  ```bash
22
24
  factory init
23
25
  ```
24
26
 
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.
27
+ It shows what it found, then asks which parts you want. Each is optional
28
+ and stands alone:
31
29
 
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.
30
+ | Part | What you get |
31
+ | ----------------------------------------------- | ------------------------------------------------------------------------------ |
32
+ | An automated review of every pull request | Claude reads each pull request once it is ready, comments, and gives a verdict |
33
+ | A board | A GitHub Project showing each ticket's state, its session, and its cost |
34
+ | Builds in the cloud | A ticket builds in GitHub Actions, with no session open on your machine |
35
+ | Builds that start when you move a card to Ready | Moving a ticket's card to Ready on the board builds it |
36
+ | Pull requests that merge themselves | A pull request that touches only files you listed merges once its checks pass |
37
+ | Signed commits from cloud builds | A build's commits show as "Verified" |
118
38
 
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:
39
+ On a first run the first three start checked. With none checked, you get
40
+ the basics: refining and building tickets in a Claude Code session on your
41
+ machine, which is all the [quick start](../quick-start.md) needs.
122
42
 
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 |
43
+ It then asks only what your parts need:
128
44
 
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.
45
+ | It asks | For | What you do |
46
+ | ------------------------------------- | --------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------- |
47
+ | Which board | A board | Choose a new one, made with the factory's columns, or a Project you already have |
48
+ | Which files may merge without you | Pull requests that merge themselves | Type their patterns, such as `docs/**`. Start with a short list |
49
+ | Where the poller runs | Builds that start from the board | Choose a schedule on GitHub Actions or a server you host. [Builds in the cloud](../builds.md) compares them |
50
+ | The token `claude setup-token` prints | The review, and builds in the cloud | It runs the command for you. Follow what it says, then paste the token it prints |
51
+ | A GitHub access token | A board, builds in the cloud, and pull requests that merge themselves | It opens GitHub's page with the right scopes checked. Choose an expiry, generate the token, and paste it |
146
52
 
147
- ### A board
53
+ A token is typed into a masked prompt and goes straight to your
54
+ repository's secrets on GitHub. It is never printed or written to a file.
55
+ Leave a prompt empty to skip it, and run `init` again when you have the
56
+ token.
148
57
 
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.
58
+ Before it changes anything, it lists everything it will do and asks "Go
59
+ ahead?". Then it does the rest itself: it writes the settings and the
60
+ factory's files, gives the board its columns and fields, stores each
61
+ secret, makes the signing key, allows auto-merge on the repository, and
62
+ requires the review's verdict before a merge to your default branch. It
63
+ commits nothing. [What it changes](../removing.md) lists every file.
152
64
 
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:**
65
+ **It worked when** the checks it prints last all show ✓, or `-` for a part
66
+ you left off.
165
67
 
166
- ```yaml
167
- tickets:
168
- board: 7
169
- ```
68
+ ## What is left for you
170
69
 
171
- Then `factory board check` shows how it reads your
172
- columns.
70
+ `init` ends with this list, under "Left to do":
173
71
 
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.
72
+ | If you chose | Do this |
73
+ | -------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
74
+ | Anything | Commit what it wrote on a branch, open a pull request, and merge it, as in [step 3 of the quick start](../quick-start.md#3-merge-the-setup) |
75
+ | The automated review | Install the Claude GitHub App on the repository, from <https://github.com/apps/claude>. The review posts its comments through it |
76
+ | Builds from the board, on a server you host | Run the poller's image with the four values `init` prints. [Hosting the poller](../builds.md#hosting-the-poller-own-server) has the steps |
77
+ | Signed commits, and it could not add the key | Add the public key it prints to the GitHub account that made the access token you pasted: Settings, "SSH and GPG keys", "New SSH key", key type "Signing Key" |
178
78
 
179
- ### Builds in the cloud
79
+ ## Optional: tune it
180
80
 
181
- `factory build 12` builds ticket 12 in GitHub Actions and
182
- prints the run's link, with no session open on your machine.
81
+ Each is a few lines in `.claude/factory.yaml`, merged like any change.
183
82
 
184
- `sync` already wrote the workflows these use, and each does nothing until
185
- it has work and its secrets:
83
+ - **Let the review run your tests.** `init` writes
84
+ [`ci-review`](../configuration.md#ci-review) with no commands, so the
85
+ reviewer reads the pull request and runs nothing of yours. To let it
86
+ confirm a finding by running something, list each command:
186
87
 
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 |
88
+ ```yaml
89
+ ci-review:
90
+ commands:
91
+ - npm test
92
+ - npx tsc --noEmit
93
+ ```
193
94
 
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)).
95
+ - **Run a command before every commit a session makes,** such as your
96
+ linter, under [`before-commit`](../configuration.md#before-commit):
198
97
 
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.
98
+ ```yaml
99
+ before-commit:
100
+ - npm run lint
101
+ ```
202
102
 
203
- #### Starting builds from the board
103
+ - **Tell the reviewer what your `CLAUDE.md` does not say** about your
104
+ project, in a file you write, `.github/review-notes.md`. The reviewer
105
+ reads it when it exists.
204
106
 
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.
107
+ [Configuration](../configuration.md) has every setting.
209
108
 
210
- ### Pull requests that merge themselves
109
+ ## Changing it later
211
110
 
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:
111
+ Run `factory init` again to turn a part on or off. It starts from what you
112
+ have, and does not ask again for a secret that is already set.
280
113
 
281
114
  ```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
115
+ factory doctor
286
116
  ```
287
117
 
288
- Paste the same GitHub token for both of the last two.
289
-
290
- Two optional settings:
118
+ runs the checks again at any time: the settings, the factory's files, the
119
+ installed version, who the GitHub CLI is signed in as, that each secret
120
+ your parts read is set, and the board's columns. GitHub never lets a
121
+ secret be read back, so a wrong one shows when the first run that needs it
122
+ fails, naming it.
291
123
 
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
- ```
124
+ ## Doing it by hand
307
125
 
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.
126
+ [Setting up on GitHub by hand](by-hand.md) has every step `init` takes,
127
+ and every secret with the scopes it needs, for anyone who cannot run
128
+ `init` or wants to see what it does.
package/docs/glossary.md CHANGED
@@ -9,17 +9,17 @@ is today.
9
9
 
10
10
  **Code host.** Where your repository lives, with its pull requests, their
11
11
  reviews, the checks on each commit, and the secrets your CI reads. Today:
12
- GitHub. `code-host.type` names it.
12
+ GitHub. [`code-host.type`](configuration.md#code-host) names it.
13
13
 
14
14
  **Ticket system.** Where your tickets live. Today: GitHub Issues.
15
- `tickets.type` names it.
15
+ [`tickets.type`](configuration.md#tickets) names it.
16
16
 
17
17
  **Board.** A view of every ticket's state, one column per state, which the
18
18
  factory keeps up to date. Optional. Today: a GitHub Project.
19
19
 
20
20
  **Cloud runner.** Where work runs with no one at a keyboard: cloud builds,
21
21
  the automated review, the board sync, and the factory's other CI jobs.
22
- Today: GitHub Actions. `builds.runner` names it.
22
+ Today: GitHub Actions. [`builds.runner`](configuration.md#builds) names it.
23
23
 
24
24
  **Coding agent.** The AI tool that runs sessions: it reads your code,
25
25
  follows the factory's skills, and writes the change. Today: Claude Code.
@@ -83,7 +83,8 @@ does, in the repository. Optional.
83
83
  set moment.
84
84
 
85
85
  **Poller.** A small program that watches your board and starts a cloud
86
- build for each ticket moved to Ready.
86
+ build for each ticket moved to Ready, on a server you host or on a
87
+ schedule in the cloud.
87
88
 
88
89
  **Refine.** To turn a ticket into acceptance criteria, settling the
89
90
  decisions with you along the way.
@@ -11,10 +11,15 @@ as a code host's billing or what its workflows can see, are in
11
11
 
12
12
  - **One tool of each kind.** The factory reaches the code host, the ticket
13
13
  system, the board, and the cloud runner each through one interface, and
14
- the settings name which one you use (`code-host.type`, `tickets.type`,
15
- and `builds.runner`). Each has one implementation today, GitHub's, and no
16
- other is planned. The skills are written for one coding agent, Claude
17
- Code. [The glossary](glossary.md) says which tool each word means today.
14
+ the settings name which one you use
15
+ ([`code-host.type`](configuration.md#code-host),
16
+ [`tickets.type`](configuration.md#tickets), and
17
+ [`builds.runner`](configuration.md#builds)). Each has one implementation
18
+ today, GitHub's, and no other is planned. A ticket system or code host
19
+ named by a package, for an adapter you write yourself, is not planned
20
+ either; the design leaves room. The skills are written for one coding
21
+ agent, Claude Code. [The glossary](glossary.md) says which tool each
22
+ word means today.
18
23
  - **It needs Node and a `package.json`,** even in a repository written in
19
24
  another language.
20
25
  - **A build never changes the coding agent's settings files,** which hold
@@ -50,8 +55,8 @@ as a code host's billing or what its workflows can see, are in
50
55
  package.
51
56
  - **Nothing retries on its own.** A build that stops waits for you.
52
57
  - **A cloud build's commits are unsigned unless you give it a signing
53
- key.** [Signed commits from cloud builds](github/setup.md#signed-commits-from-cloud-builds)
54
- says how.
58
+ key.** `factory init` makes one when you choose that part
59
+ ([Setting up on GitHub](github/setup.md#run-factory-init)).
55
60
  - **A cloud build cannot be steered.** You can read its log as it runs, and
56
61
  cancel it, but not answer it: where it would ask, it stops and reports.
57
62
  - **Nothing watches a pull request after its cloud build ends.** Your own
@@ -68,8 +73,7 @@ as a code host's billing or what its workflows can see, are in
68
73
  person's, but the factory has only run against a person's.
69
74
  - **Your board's own automations,** such as moving a closed ticket to Done.
70
75
  They may fight the board sync.
71
- - **Installing an unpublished or private package** in CI and from a
72
- dependency bot.
76
+ - **A factory update reaching a repository through its dependency bot.**
73
77
  - **Glob patterns standing in for today's regular expressions** in the
74
78
  merge policy. They could match differently. The switch compares the old and new
75
79
  decision on recent pull requests.
@@ -107,8 +111,6 @@ as a code host's billing or what its workflows can see, are in
107
111
  one account's login.
108
112
  - **An update delivers instructions that run with your tokens.** Read update
109
113
  pull requests as carefully as code.
110
- - **The poller keeps its hourly cap in memory.** A restart forgets how many
111
- builds it started in the last hour.
112
114
  - **It sits on tools that change.** Several parts work around how today's
113
115
  coding agent and code host behave.
114
116
  - **Publishing cannot be undone.** A public release needs a history and
package/docs/plugins.md CHANGED
@@ -32,7 +32,7 @@ three. A repository can have several plug-ins in one role, or none.
32
32
 
33
33
  Reads a finished change and reports problems.
34
34
 
35
- | | |
35
+ | Step | What happens |
36
36
  | ------------------- | -------------------------------------------------------------------------------------------- |
37
37
  | **Called** | By `factory-build`, after the change is built and before the pull request opens |
38
38
  | **Considered when** | The change touches a file matching one of its `files` patterns |
@@ -48,11 +48,12 @@ of your components, copy that has to follow a style guide.
48
48
 
49
49
  Makes pictures to choose from when a decision changes how something looks.
50
50
 
51
- A repository with `site` in its settings has one already: the factory's
52
- own `factory-design` skill, which `factory sync` writes, is its `mockups`
53
- plug-in unless you list one of your own with this role.
51
+ A repository with [`site`](configuration.md#site) in its settings has one
52
+ already: the factory's own `factory-design` skill, which `factory sync`
53
+ writes, is its `mockups` plug-in unless you list one of your own with this
54
+ role.
54
55
 
55
- | | |
56
+ | Step | What happens |
56
57
  | --------------- | ----------------------------------------------------------------------------------- |
57
58
  | **Called** | By `factory-refine`, when one of the decisions it would bring you is about the look |
58
59
  | **Handed** | The ticket and the decision |
@@ -64,7 +65,7 @@ plug-in unless you list one of your own with this role.
64
65
 
65
66
  Builds a kind of ticket the general build would do badly.
66
67
 
67
- | | |
68
+ | Step | What happens |
68
69
  | ------------- | -------------------------------------------------------------------------- |
69
70
  | **Called** | By `factory-build`, in place of its own build step |
70
71
  | **Used when** | The ticket carries one of its `labels` |
@@ -150,7 +151,8 @@ instructions for the agent and in the agent itself. The factory holds none of th
150
151
 
151
152
  1. Write the skill or agent, and try it by hand until it does its job.
152
153
  2. Give it a description that states when it applies.
153
- 3. Add it under `plugins` with its `role`, and `files` or `labels`.
154
+ 3. Add it under [`plugins`](configuration.md#plugins) with its `role`, and
155
+ `files` or `labels`.
154
156
  4. Run `factory config check`. It fails if the file is missing or the
155
157
  role is not one of the three.
156
158
  5. Run `factory plugins` to see the list the factory will use.
@@ -164,9 +166,9 @@ No sync is needed. Plug-ins are read from your settings each time.
164
166
  ordinary skill.
165
167
  - **A skill another of your skills calls.** A reviewer that only your own
166
168
  `builder` launches is that builder's business.
167
- - **A rule.** "Migrations always wait for me" is `auto-merge`. "Every
168
- migration needs a rollback" is a sentence in your project's instructions
169
- for the agent.
169
+ - **A rule.** "Migrations always wait for me" is
170
+ [`auto-merge`](configuration.md#auto-merge). "Every migration needs a
171
+ rollback" is a sentence in your project's instructions for the agent.
170
172
 
171
173
  ## The UI reviewer
172
174
 
@@ -183,10 +185,3 @@ plugins:
183
185
  ```
184
186
 
185
187
  It needs the `site` settings, which say how to start the website.
186
-
187
- ## Sharing plug-ins between repositories
188
-
189
- Not planned. A plug-in lives in the repository that uses it. A way to
190
- package a set of them, such as a design skill and a visual reviewer for
191
- any website, and install it in several repositories is designed for but
192
- not scheduled.