@davidbyoung/software-factory 0.1.8 → 0.1.10

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 (69) hide show
  1. package/README.md +2 -0
  2. package/dist/agent/claude-code.mjs +15 -21
  3. package/dist/board.d.mts +20 -3
  4. package/dist/board.mjs +124 -38
  5. package/dist/cli.mjs +84 -9
  6. package/dist/code-host/github-setup.mjs +2 -2
  7. package/dist/code-host/github.d.mts +1 -1
  8. package/dist/code-host/github.mjs +29 -2
  9. package/dist/code-host/types.d.mts +16 -1
  10. package/dist/code-host/types.mjs +8 -0
  11. package/dist/columns-suggest.d.mts +25 -6
  12. package/dist/columns-suggest.mjs +119 -29
  13. package/dist/commands.d.mts +5 -2
  14. package/dist/commands.mjs +37 -12
  15. package/dist/config.d.mts +25 -3
  16. package/dist/config.mjs +159 -33
  17. package/dist/doctor.d.mts +6 -1
  18. package/dist/doctor.mjs +78 -18
  19. package/dist/explain.d.mts +5 -0
  20. package/dist/explain.mjs +36 -1
  21. package/dist/init.d.mts +10 -0
  22. package/dist/init.mjs +133 -31
  23. package/dist/lib/color.d.mts +11 -0
  24. package/dist/lib/color.mjs +15 -0
  25. package/dist/lib/gh.d.mts +6 -0
  26. package/dist/lib/gh.mjs +11 -1
  27. package/dist/lib/listed.d.mts +3 -2
  28. package/dist/lib/listed.mjs +5 -4
  29. package/dist/poller.d.mts +1 -1
  30. package/dist/poller.mjs +9 -6
  31. package/dist/pr.mjs +9 -1
  32. package/dist/preset-commands.d.mts +2 -0
  33. package/dist/preset-commands.mjs +18 -12
  34. package/dist/preset.mjs +3 -2
  35. package/dist/setup.d.mts +3 -0
  36. package/dist/site.d.mts +3 -0
  37. package/dist/site.mjs +8 -1
  38. package/dist/status.d.mts +5 -2
  39. package/dist/status.mjs +13 -22
  40. package/dist/sync.d.mts +7 -1
  41. package/dist/sync.mjs +17 -5
  42. package/dist/ticket-fields.d.mts +84 -0
  43. package/dist/ticket-fields.mjs +374 -0
  44. package/dist/ticket.d.mts +3 -0
  45. package/dist/ticket.mjs +35 -8
  46. package/dist/tickets/github-setup.mjs +1 -1
  47. package/dist/tickets/github.mjs +69 -0
  48. package/dist/tickets/index.d.mts +8 -1
  49. package/dist/tickets/index.mjs +67 -7
  50. package/dist/tickets/types.d.mts +27 -1
  51. package/dist/tickets/types.mjs +4 -0
  52. package/dist/tools.d.mts +1 -1
  53. package/docs/builds.md +26 -13
  54. package/docs/cli.md +73 -36
  55. package/docs/configuration.md +264 -59
  56. package/docs/design.md +10 -0
  57. package/docs/developing.md +49 -18
  58. package/docs/existing-repo.md +184 -34
  59. package/docs/github/by-hand.md +13 -1
  60. package/docs/github/setup.md +14 -2
  61. package/docs/presets.md +15 -3
  62. package/docs/quick-start.md +3 -3
  63. package/docs/skills.md +3 -1
  64. package/docs/updating.md +132 -5
  65. package/docs/workflow.md +1 -1
  66. package/package.json +4 -2
  67. package/settings.schema.json +82 -20
  68. package/skills/factory-build/SKILL.md +39 -7
  69. package/skills/factory-deps/SKILL.md +6 -4
package/docs/cli.md CHANGED
@@ -11,6 +11,12 @@ keeps its own version; in a repository with none, it says how to install
11
11
  one and exits 1. `factory` with no command, or one it does not have, prints
12
12
  the list of commands it has and exits non-zero.
13
13
 
14
+ Commands you read yourself, such as `doctor`, `status`, and
15
+ `config explain`, use color when they print to a terminal: a green ✓, a
16
+ red ✗, and dim text for what needs no attention. The marks and words
17
+ are the same without it. Set `NO_COLOR` to turn color off, or
18
+ `FORCE_COLOR=1` to keep it when you pipe the output, as to `less -R`.
19
+
14
20
  > **Without the global install, type `npx --no-install factory`.** Another
15
21
  > package on npm is called `factory`. Where this one is not installed, `npx`
16
22
  > without `--no-install` offers to download and run that one instead; with
@@ -36,9 +42,37 @@ slash command, such as `/factory-refine 12`. [Skills](skills.md) lists them.
36
42
  | `factory doctor` | When something seems off. It checks the settings, files, version, secrets, board, and each tool's own setup |
37
43
 
38
44
  `init` asks its questions in the terminal, and reads each token in a
39
- masked prompt. `doctor` exits 1 when a check fails. GitHub never lets a
40
- secret be read back, so `doctor` checks only that each secret your parts
41
- read is set.
45
+ masked prompt.
46
+
47
+ `sync --check` ends with `✓ The factory's files match the settings.`,
48
+ and `config check` with `✓ The settings are valid.`, when there is
49
+ nothing to fix.
50
+
51
+ `doctor` prints its checks under headings: `Settings and files`, then
52
+ each tool's name, such as `GitHub` or `Claude Code`, then the parts you
53
+ left off. Each check starts with a mark: ✓ works, ✗ needs fixing, ?
54
+ worth a look, and - off on purpose. `doctor` exits 1 when a
55
+ check fails. GitHub never lets a secret be read back, so `doctor` checks
56
+ only that each secret your parts read is set.
57
+
58
+ `board check` prints two blocks, each headed by the setting it shows.
59
+ Under [`tickets.columns`](configuration.md#ticketscolumns) is a row for
60
+ each of a ticket's states, such as `backlog` or `review`, with the
61
+ [board](glossary.md) column it sits in. Under
62
+ [`tickets.fields`](configuration.md#ticketsfields) is a row for each
63
+ field the [board sync](glossary.md) fills in on a card. A row is a mark,
64
+ the state or the field, and what the factory makes of it, such as
65
+ `✗ review In review: no such column on the board`. When every row is
66
+ ✓ or -, the factory reads your board as your settings say. A ✗ makes the
67
+ command exit 1.
68
+
69
+ | Mark | Words after the state or field | What to do |
70
+ | ---- | ---------------------------------- | ----------------------------------------------------------------------------------------------------------- |
71
+ | ✓ | the column's name, or `synced` | Nothing |
72
+ | - | `none, shows in Backlog`, or `off` | Nothing: the settings set it to `none`, so the ticket shows in the column named, or the field is left empty |
73
+ | ? | `skipped: no such field` | Add the field to the board, or set it to `none` under `tickets.fields`, if you want it gone from this list |
74
+ | ? | `no state: left alone` | Name the column under `tickets.columns` if the factory should move cards there; otherwise nothing |
75
+ | ✗ | `no such column on the board` | Add the column to the board, or change its name under `tickets.columns` to one the board has |
42
76
 
43
77
  ## Every day
44
78
 
@@ -103,32 +137,33 @@ prints what the ticket system returned as one JSON value. `edit`,
103
137
  `comment`, and `open` refuse a body with a bare tag-like `<word>` the
104
138
  ticket system would swallow, name it, and post nothing.
105
139
 
106
- | Command | What it does |
107
- | ---------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------- |
108
- | `factory ticket view N` | Prints ticket N: its title, state, labels, body, and comments with their IDs and authors |
109
- | `factory ticket view N --field NAME` | Prints one of `title`, `state`, `labels` (one per line), or `body`, and nothing else |
110
- | `factory ticket list` | Lists the open tickets: number, title, and labels, separated by tabs |
111
- | `factory ticket list --label LABEL` | Only those with the label. `--title "TITLE"` keeps those whose title is exactly that |
112
- | `factory ticket edit N [--title TITLE] [--body-file FILE]` | Replaces N's title, its body, or both. `--attach FILE` adds an image to a body |
113
- | `factory ticket comment N --body-file FILE` | Comments on N and prints the comment's ID. `--attach FILE` adds an image |
114
- | `factory ticket open --title TITLE --body-file FILE` | Opens a ticket and prints its number. `--label LABEL` adds a label |
115
- | `factory ticket label N --add LABEL` | Adds a label to N. `--remove LABEL` takes one off |
116
- | `factory ticket label N --was-removed LABEL` | Prints `yes` if the label was ever removed from N, otherwise `no` |
117
- | `factory ticket link N` | Prints the text that makes a merged pull request close N, such as "Closes #12" |
118
- | `factory ticket blockers N` | One line per ticket N waits on: its number and whether it is open |
119
- | `factory ticket block N --by M` | Records that N waits on M |
120
- | `factory ticket unblock N --by M` | Removes that record |
121
- | `factory ticket supports GROUP` | Prints `yes` or `no` for `board`, `blockers`, `label-history`, or `attachments` |
122
- | `factory ticket claim N` | Claims ticket N for this session. Prints `claimed`, `held by`, or `blocked by` |
123
- | `factory ticket still-live N` | Says whether this session still holds N |
124
- | `factory ticket stop N "reason"` | Releases N and says why |
125
- | `factory ticket end N` | A run's last step: releases this session's claim if no open pull request links N. Prints `released`, `kept`, or `not live` |
126
- | `factory ticket refining N` | Marks N as being refined |
127
- | `factory ticket waiting N` | Marks N as waiting on your reply to a round of questions |
128
- | `factory ticket refined N` | Marks N as refined, unless its body lacks what a build reads. `--check` makes that check alone and posts nothing |
129
- | `factory ticket ready N` | Moves N to Ready. Only when you ask a session to |
130
- | `factory ticket cost N` | Notes what this session spent on N since it started |
131
- | `factory follow-up FILE "what is wrong"` | Adds a line about that file to the follow-ups ticket, opening the ticket if none is open |
140
+ | Command | What it does |
141
+ | ---------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
142
+ | `factory ticket view N` | Prints ticket N: its title, state, labels, body, and comments with their IDs and authors |
143
+ | `factory ticket view N --field NAME` | Prints one of `title`, `state`, `labels` (one per line), or `body`, and nothing else |
144
+ | `factory ticket list` | Lists the open tickets: number, title, and labels, separated by tabs |
145
+ | `factory ticket list --label LABEL` | Only those with the label. `--title "TITLE"` keeps those whose title is exactly that |
146
+ | `factory ticket edit N [--title TITLE] [--body-file FILE]` | Replaces N's title, its body, or both. `--attach FILE` adds an image to a body |
147
+ | `factory ticket comment N --body-file FILE` | Comments on N and prints the comment's ID. `--attach FILE` adds an image |
148
+ | `factory ticket open --title TITLE --body-file FILE` | Opens a ticket and prints its number. `--label LABEL` adds a label |
149
+ | `factory ticket label N --add LABEL` | Adds a label to N. `--remove LABEL` takes one off |
150
+ | `factory ticket label N --was-removed LABEL` | Prints `yes` if the label was ever removed from N, otherwise `no` |
151
+ | `factory ticket link N` | Prints the text that makes a merged pull request close N, such as "Closes #12" |
152
+ | `factory ticket branch N` | Prints the branch a build of N pushes, from [`code-host.branch-name`](configuration.md#code-host), such as `12` or `feature/octocat/12`. Exits 1 when N does not exist, or the pattern has `{user}` and `gh` is not signed in |
153
+ | `factory ticket blockers N` | One line per ticket N waits on: its number and whether it is open |
154
+ | `factory ticket block N --by M` | Records that N waits on M |
155
+ | `factory ticket unblock N --by M` | Removes that record |
156
+ | `factory ticket supports GROUP` | Prints `yes` or `no` for `board`, `blockers`, `label-history`, or `attachments` |
157
+ | `factory ticket claim N` | Claims ticket N for this session. Prints `claimed`, `held by`, or `blocked by` |
158
+ | `factory ticket still-live N` | Says whether this session still holds N |
159
+ | `factory ticket stop N "reason"` | Releases N and says why |
160
+ | `factory ticket end N` | A run's last step: releases this session's claim if no open pull request links N. Prints `released`, `kept`, or `not live` |
161
+ | `factory ticket refining N` | Marks N as being refined |
162
+ | `factory ticket waiting N` | Marks N as waiting on your reply to a round of questions |
163
+ | `factory ticket refined N` | Marks N as refined, unless its body lacks what a build reads. `--check` makes that check alone and posts nothing |
164
+ | `factory ticket ready N` | Moves N to Ready. Only when you ask a session to |
165
+ | `factory ticket cost N` | Notes what this session spent on N since it started |
166
+ | `factory follow-up FILE "what is wrong"` | Adds a line about that file to the follow-ups ticket, opening the ticket if none is open |
132
167
 
133
168
  `factory ticket refined N` posts nothing and exits 1 when N's body lacks a
134
169
  section a build reads, printing one line for each, such as
@@ -148,6 +183,7 @@ ticket system.
148
183
  | `factory pr reply N COMMENT --body-file FILE` | Replies on a thread |
149
184
  | `factory pr resolve N COMMENT` | Resolves a thread |
150
185
  | `factory pr closes N` | The tickets N closes |
186
+ | `factory pr for-branch BRANCH` | The newest pull request from BRANCH, open or not: `#N open`, `#N merged`, or `#N closed`, or `none` when there has been none |
151
187
  | `factory pr wait-checks N` | Waits for every CI run on the pushed commit. Prints `success`, `failure:` with the failed checks, or `no checks` |
152
188
  | `factory pr ready N` | Marks a draft ready for review. When `commit.gpgsign` is `true`, refuses while the code host shows a commit as not verified |
153
189
  | `factory pr comments N` | N's conversation comments: ID, author, time, and first line. `--author LOGIN`, `--contains TEXT`, and `--json`, which prints each comment's `id`, `user.login`, `body`, and `created_at` |
@@ -183,13 +219,14 @@ runner or a linter: each runs what your settings list under
183
219
  [`specs`](configuration.md#specs), with bash, from the repository's root.
184
220
  You can run them too.
185
221
 
186
- | Command | What it does |
187
- | ------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
188
- | `factory gate` | Runs each [`commands.gate`](configuration.md#commandsgate) command in order, printing `$` and the command before each. Stops at the first that fails, with `gate failed on:` and the command. Exits 0 when every command passes, and 1 at the first that fails or when no gate is set |
189
- | `factory test-one FILE [NAME]` | Runs [`commands.test-one`](configuration.md#commandstest-one), one test file alone or the one test NAME in it, and exits with its status |
190
- | `factory end-to-end FILE [--times K]` | Runs [`commands.end-to-end`](configuration.md#commandsend-to-end), one end-to-end spec alone, and exits with its status. With `--times K`, K times in a row, stopping at the first run that fails |
191
- | `factory specs check` | Runs [`specs.check`](configuration.md#specscheck), the check of your written specs, and exits with its status. Prints `specs are off` when `specs` is `none` |
192
- | `factory default-branch` | Prints the name of your repository's default branch, which nothing in the factory assumes is `main` |
222
+ | Command | What it does |
223
+ | ------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
224
+ | `factory gate` | Runs each [`commands.gate`](configuration.md#commandsgate) command in order, printing `$` and the command before each. Stops at the first that fails, with `✗ The gate failed on:` and the command. Ends with `✓ Every gate command passed.` and exits 0 when every command passes, and exits 1 at the first that fails or when no gate is set |
225
+ | `factory test-one FILE [NAME]` | Runs [`commands.test-one`](configuration.md#commandstest-one), one test file alone or the one test NAME in it, and exits with its status |
226
+ | `factory end-to-end FILE [--times K]` | Runs [`commands.end-to-end`](configuration.md#commandsend-to-end), one end-to-end spec alone, and exits with its status. With `--times K`, K times in a row, stopping at the first run that fails. Ends with `✓ The test passed.` or `✗ The test failed.` |
227
+ | `factory specs check` | Runs [`specs.check`](configuration.md#specscheck), the check of your written specs, and exits with its status, ending with `✓ The specs check passed.` or `✗ The specs check failed.`. Prints `specs are off` when `specs` is `none` |
228
+ | `factory specs change-name N` | Prints the name of the OpenSpec change a build of N writes, always `issue-N` whatever [`code-host.branch-name`](configuration.md#code-host) says. Exits 1 with `specs are off: there is no spec change to name` when [`specs`](configuration.md#specs) is `none` |
229
+ | `factory default-branch` | Prints the name of your repository's default branch, which nothing in the factory assumes is `main` |
193
230
 
194
231
  `factory default-branch` asks, in turn, the event of the workflow run it
195
232
  is in, `origin/HEAD` in your checkout, and the code host, whose answer it
@@ -34,9 +34,10 @@ The [glossary](glossary.md) has the rest.
34
34
 
35
35
  ## How the file works
36
36
 
37
- - **Two settings are required, and a third before any build.** Every
38
- file has [`version`](#version) and [`repository`](#repository), and a
39
- session can't build a ticket until you set
37
+ - **Three settings are required, and a fourth before any build.** Every
38
+ file has [`version`](#version), [`repository`](#repository), and
39
+ [`code-host.branch-name`](#code-host), which `factory init` writes for
40
+ you, and a session can't build a ticket until you set
40
41
  [`commands.gate`](#commandsgate). Every other setting has a default, and
41
42
  you write it only when you want something else.
42
43
  - **It holds only what a script needs.** Anything that needs judgment,
@@ -85,6 +86,9 @@ The [glossary](glossary.md) has the rest.
85
86
  ```yaml
86
87
  version: 2
87
88
  repository: your-name/your-repo
89
+ code-host:
90
+ type: github
91
+ branch-name: "{ticket}"
88
92
  ```
89
93
 
90
94
  With only this, the factory refines a ticket when you run `/factory-refine N` in a session,
@@ -115,8 +119,8 @@ factory config check
115
119
  factory sync
116
120
  ```
117
121
 
118
- `factory config check` prints nothing when the file is valid, and names
119
- the setting when it is not. `factory sync` then rewrites the lock and the
122
+ `factory config check` prints `✓ The settings are valid.` when the file
123
+ is valid, and names the setting when it is not. `factory sync` then rewrites the lock and the
120
124
  copied files that depend on what you changed, and lists each file it
121
125
  wrote. Every change needs it, one under `plugins` included, as
122
126
  [How the file works](#how-the-file-works) says.
@@ -177,6 +181,13 @@ Where your tickets live, and which board shows them.
177
181
  tickets:
178
182
  type: github
179
183
  board: 1
184
+ columns:
185
+ backlog: Backlog
186
+ refining: In refinement
187
+ ready: Ready
188
+ building: In progress
189
+ review: In review
190
+ done: Done
180
191
  ```
181
192
 
182
193
  - **`type`** is the ticket system. Only `github` is built, and it is the
@@ -184,6 +195,8 @@ tickets:
184
195
  - **`board`** is your GitHub Project's number: the last part of its
185
196
  address, such as `1` in `github.com/users/your-name/projects/1`. The
186
197
  default, `none`, means no board.
198
+ - **`columns`** says which of the board's columns shows each state, and a
199
+ board needs it: see [`tickets.columns`](#ticketscolumns).
187
200
 
188
201
  Without a board, `factory status` still shows every ticket's state, which
189
202
  the factory keeps in comments on the ticket. Builds then start only when
@@ -199,12 +212,14 @@ with it.
199
212
  #### `tickets.columns`
200
213
 
201
214
  The board has one column for each of the six
202
- [states](workflow.md#the-six-states) a ticket goes through. If your
203
- board's columns have the factory's names, write nothing here. If they have
204
- other names, or your board has fewer columns, say which column shows each
205
- state. `factory init` suggests this block when you choose a board without the
206
- factory's columns: see
215
+ [states](workflow.md#the-six-states) a ticket goes through. This block
216
+ says which of your board's columns shows each state, and it names all
217
+ six. `factory init` writes it for you, from the board you choose: see
207
218
  [You already have a board](existing-repo.md#you-already-have-a-board).
219
+ There is no default: your board's column names may not be the
220
+ factory's, and a guess would put tickets in the wrong column without
221
+ telling you.
222
+
208
223
  A new GitHub Project starts with only Todo, In Progress, and Done,
209
224
  so its settings would be:
210
225
 
@@ -213,120 +228,277 @@ tickets:
213
228
  board: 7
214
229
  columns:
215
230
  backlog: Todo
216
- building: In Progress
217
- done: Done
218
231
  refining: none
219
232
  ready: none
233
+ building: In Progress
220
234
  review: none
235
+ done: Done
221
236
  builds:
222
237
  trigger: manual
223
238
  ```
224
239
 
225
- The factory's own names, used for any state you leave out, are:
240
+ When init creates your board, or adds columns to one, it gives them the
241
+ factory's own names:
226
242
 
227
- | State | Column the factory looks for |
228
- | ---------- | ---------------------------- |
229
- | `backlog` | Backlog |
230
- | `refining` | In refinement |
231
- | `ready` | Ready |
232
- | `building` | In progress |
233
- | `review` | In review |
234
- | `done` | Done |
243
+ | Key | Name of the column init creates |
244
+ | ---------- | ------------------------------- |
245
+ | `backlog` | Backlog |
246
+ | `refining` | In refinement |
247
+ | `ready` | Ready |
248
+ | `building` | In progress |
249
+ | `review` | In review |
250
+ | `done` | Done |
235
251
 
236
252
  - **Capitals don't matter,** so "In progress" finds your "In Progress".
237
253
  - **`none` means your board has no column for that state.** A ticket in
238
254
  that state stays in the column of the state before it. With
239
255
  `review: none`, a ticket whose pull request is in review stays in In
240
- progress. Every state can be `none` except `backlog`.
256
+ Progress. Every state can be `none` except `backlog`.
241
257
  - **A state can take a list of columns,** when more than one of yours
242
- means it. `factory init` suggests one column for each state, so you
243
- write a list yourself. A ticket in any of the columns is in that
244
- state. When the factory moves a ticket into the state, it uses the
245
- first, and a ticket already in any of them stays where it is:
258
+ means it. Init never writes a list, so add one to the block yourself.
259
+ A ticket in any of the columns is in that state. When the factory
260
+ moves a ticket into the state, it uses the first, and a ticket already
261
+ in any of them stays where it is:
246
262
 
247
263
  ```yaml
248
264
  tickets:
249
265
  board: 7
250
266
  columns:
251
267
  backlog: Todo
268
+ refining: none
269
+ ready: none
270
+ building: In Progress
252
271
  # When a pull request opens, its ticket moves to Code review.
253
272
  # One you moved to QA stays there.
254
273
  review: [Code review, QA]
274
+ done: Done
255
275
  ```
256
276
 
257
277
  `ready` takes one column, since only a ticket you approved goes there.
258
278
 
259
- - **A ticket never falls back into Ready,** since only a ticket you
260
- approved goes there, so the fallback skips it. With `building: none`
261
- alone, a ticket being built has no column of its own, the state before
262
- building is ready, and Ready is skipped, so it shows in In refinement.
279
+ - **A ticket never stays in the ready column unless you approved it.**
280
+ With `building: none`, a ticket being built would stay in ready's
281
+ column, so it stays in refining's column instead. On a board with the
282
+ factory's columns and `building: none`, it shows in In refinement.
263
283
  - **With `ready: none`, nothing on the board approves a build,** so you
264
284
  need `builds.trigger: manual`, and you start each build by asking a
265
285
  session.
266
286
  - **A ticket in a column no state uses is left alone.** The board sync
267
287
  doesn't move it or fill in its fields, and nothing builds it.
268
- - **If you host your own poller** and rename the Ready column, the poller
269
- needs the new name too: see `FACTORY_READY_COLUMN` in
288
+ - **If you host your own poller,** it needs `FACTORY_READY_COLUMN` set
289
+ to the column `ready` names: see
270
290
  [Builds](builds.md#what-it-reads-from-its-environment).
271
291
 
272
292
  `factory config check` stops, naming the key, when `columns` has:
273
293
 
294
+ - no `board` beside it, or a `board` with no `columns`;
295
+ - a state left out, naming each one;
274
296
  - a state it doesn't know;
275
297
  - `backlog: none`;
276
298
  - one column for two states;
277
299
  - an empty list, or a list for `ready`;
278
- - no `board` beside it;
279
300
  - `ready: none` while [`builds.trigger`](#builds) isn't `manual`,
280
301
  since then a build starts only from the ready column.
281
302
 
282
- It doesn't read your board: `factory board check` does.
303
+ Such as:
283
304
 
284
- #### `tickets.fields`
305
+ ```text
306
+ .claude/factory.yaml: tickets.columns: building and done have no column: give each a column, a list of columns, or none, or run factory init to choose them
307
+ ```
285
308
 
286
- Besides moving a ticket between columns, the board sync fills in three
287
- fields so you can see at a glance what is happening to it:
309
+ `factory config check` doesn't read your board. `factory board check`
310
+ does, and says which of the columns you named the board lacks.
288
311
 
289
- - **Session:** which session is working on the ticket, or "Waiting on
290
- you".
291
- - **Runs in:** whether that session is on someone's machine or in the
292
- cloud.
293
- - **Cost:** roughly what refining and building the ticket has cost so far.
312
+ #### `tickets.fields`
294
313
 
295
- `factory init` adds these three fields to your board, so most repositories
296
- write nothing here. Write this block only when your board already has a
297
- field you want used instead, or to stop the board sync filling one in:
314
+ The factory fills in fields of its own in two places: on your board,
315
+ to show what is happening to a ticket, and on the ticket itself, to hold
316
+ the result of refining it. This block maps each of these factory fields
317
+ to the field of yours that holds it: a board field, or a ticket field
318
+ set on the ticket itself. `factory init` sets up both the board fields
319
+ and the ticket fields, so most repositories write nothing here by
320
+ hand.
298
321
 
299
322
  ```yaml
300
323
  tickets:
301
324
  board: 7
302
325
  fields:
326
+ # Factory fields on the board
303
327
  session: Agent # fill in your existing "Agent" field instead
304
328
  cost: none # never fill in a cost
329
+ # Factory fields on the ticket
330
+ decisions: none
331
+ spec: Acceptance criteria
332
+ acceptance-criteria: Acceptance criteria
333
+ for-the-builder: Design notes
305
334
  ```
306
335
 
307
- - **A field you name must exist,** holding the right kind of value: text
308
- for Session, a single select with the options Local and Actions for Runs
309
- in, and a number for Cost. If it doesn't, the board sync stops and says
310
- which field is wrong.
311
- - **When you name nothing,** the board sync looks for fields called
312
- Session, Runs in, and Cost, fills in those it finds, and skips the rest
313
- with a note.
336
+ **On the board,** besides moving a ticket between columns, the
337
+ [board sync](workflow.md#the-board) fills in three factory fields so you
338
+ can see at a glance what is happening to a ticket:
339
+
340
+ - **`session`:** which session is working on the ticket, or "Waiting on
341
+ you".
342
+ - **`runs-in`:** whether that session is on someone's machine or in the
343
+ cloud.
344
+ - **`cost`:** roughly what refining and building the ticket has cost so
345
+ far.
346
+
347
+ `factory init` adds board fields called Session, Runs in, and Cost. Name
348
+ a board field here only when your board already has one you want used
349
+ instead, or write `none` to stop the board sync filling one in.
350
+
351
+ - **These three need [`board`](#tickets).**
352
+ - **A board field you name must exist,** holding the right kind of
353
+ value: text for `session`, a single select with the options Local and
354
+ Actions for `runs-in`, and a number for `cost`. If it doesn't, the
355
+ board sync stops and says which field is wrong.
356
+ - **When you name nothing,** the board sync looks for board fields
357
+ called Session, Runs in, and Cost, fills in those it finds, and skips
358
+ the rest with a note.
314
359
  - **It never overwrites a field of yours.** If your board has a field
315
- called Cost that holds text, the board sync stops rather than write over
316
- it, and asks you to name another field or write `cost: none`.
360
+ called Cost that holds text, the board sync stops rather than write
361
+ over it, and asks you to name another field or write `cost: none`.
317
362
  - **The column itself is the board's own Status field,** which has to be
318
363
  a single select with an option for each column in
319
364
  [`tickets.columns`](#ticketscolumns).
320
365
 
366
+ **On the ticket,** refining a ticket writes four factory fields into its
367
+ description, each under its own heading. Each can go instead in a ticket
368
+ field that holds text, which on GitHub is an issue field: see
369
+ [Your tickets already have fields](existing-repo.md#your-tickets-already-have-fields),
370
+ which also says why a board field can't hold one.
371
+
372
+ | Key | What the factory field holds |
373
+ | --------------------- | ---------------------------------------------------------------------- |
374
+ | `decisions` | Decisions: the questions refinement settled, and what was chosen |
375
+ | `spec` | Spec: what a change your users will notice must do, line by line |
376
+ | `acceptance-criteria` | Acceptance criteria: what must be true for any other ticket to be done |
377
+ | `for-the-builder` | For the builder: how to build it, as a design and a list of tasks |
378
+
379
+ `factory init` asks your coding agent to suggest the ticket fields, and
380
+ you confirm them.
381
+
382
+ - **`none` keeps the factory field in the description,** and so does
383
+ leaving its key out. Unlike the board's three, a factory field never
384
+ goes in a ticket field just because the names match.
385
+ - **A ticket field is named as GitHub shows it,** capitals included.
386
+ - **These keys don't need a board,** since the ticket field belongs to
387
+ the ticket.
388
+ - **The ticket field must exist and hold text.** One that doesn't, such
389
+ as a single select, fails the checks [`factory doctor`](cli.md#setting-up)
390
+ and init print, and refining a ticket stops, naming it, and writes
391
+ nothing.
392
+ - **Two factory fields can't name the same ticket field,** except `spec`
393
+ and `acceptance-criteria`, since a ticket has only one of them.
394
+ `factory config check` stops on any other pair.
395
+ - **A heading of your own,** such as one
396
+ [a refiner of your own](plugins.md#refiner) writes, can go in a ticket
397
+ field too: write it in lowercase, with hyphens for spaces, so
398
+ `## Proposed docs` is `proposed-docs`.
399
+ - **Changing a line** affects tickets refined afterwards. A ticket
400
+ refined before keeps its factory fields where they were written.
401
+
321
402
  ### `code-host`
322
403
 
323
- Where your repository and its pull requests live. Only `github` is built,
324
- and it is the default, so most files leave this out.
404
+ Where your repository and its pull requests live, and what every
405
+ [build](#words-this-page-uses) names the branch it pushes, in a session
406
+ on your machine and in the cloud alike.
325
407
 
326
408
  ```yaml
327
- code-host: github
409
+ code-host:
410
+ type: github
411
+ branch-name: "feature/{user}/{ticket}"
412
+ ```
413
+
414
+ - **`type`** is the code host. GitHub is the only one so far, and it is
415
+ the default.
416
+ - **`branch-name`** is the pattern for the branch's name. It has no
417
+ default: [`factory init`](github/setup.md) asks for it and offers
418
+ `{ticket}`, so ticket 12 is built on a branch named `12`. A
419
+ [preset](#presets) can set it for every repository that follows it.
420
+
421
+ Without `branch-name`, `factory config check` stops:
422
+
423
+ ```text
424
+ .claude/factory.yaml: code-host.branch-name: is required. Run factory init to set it, or add it, such as branch-name: "{ticket}"
425
+ ```
426
+
427
+ A pattern uses these placeholders. It must have `{ticket}`; `{user}` is
428
+ for a convention that names who did the work, and a pattern can leave
429
+ it out:
430
+
431
+ | Placeholder | What it becomes | For ticket 12 |
432
+ | ----------- | ------------------------------------ | ------------- |
433
+ | `{ticket}` | The ticket's number, without `#` | `12` |
434
+ | `{user}` | The GitHub account the build runs as | `octocat` |
435
+
436
+ In a session, `{user}` is the account the GitHub CLI, `gh`, is signed in
437
+ as, exactly as GitHub spells it, so the same ticket built by two people
438
+ gets two branches. In GitHub Actions, it is the owner of
439
+ the [token the build runs with](github/reference.md#workflows), not
440
+ whoever approved the ticket, so with a shared bot account every branch
441
+ built in Actions carries the bot's name.
442
+
443
+ Keep the quotes, as in the examples. YAML reads an unquoted
444
+ `branch-name: {ticket}` as a map rather than as text, and
445
+ `factory config check` stops and says to quote it.
446
+
447
+ `{ticket}` gives each ticket its own branch, and the same branch every
448
+ time. So a ticket built a second time, such as the
449
+ [follow-ups ticket](workflow.md#follow-ups), a reopened ticket, or one whose first
450
+ build stopped, finds its earlier branch still on GitHub, unless GitHub
451
+ deleted it when its pull request merged. What the build does depends on
452
+ that branch's newest pull request:
453
+
454
+ - **Merged, with nothing pushed to the branch since:** the build deletes
455
+ the old branch and starts fresh, since its work is already merged.
456
+ - **Open:** the build stops before it starts and names the pull request.
457
+ Work that one instead, with `/factory-address-review N` for pull
458
+ request N.
459
+ - **Anything else:** closed without merging, no pull request at all, or
460
+ merged with commits pushed since. The build stops before it starts, so
461
+ no work is lost:
462
+
463
+ ```text
464
+ Branch 12 is already on origin, with work no pull request merged. Open a pull request from it to keep that work, or delete it with: git push origin --delete 12
465
+ ```
466
+
467
+ A build that stopped partway pushes its branch so its work is kept. To
468
+ keep it, open a pull request from the branch on GitHub. Otherwise
469
+ delete the branch, and build the ticket again with `/factory-build 12`.
470
+
471
+ Once you change the pattern, run `factory config check`, then
472
+ `factory sync` (every setting needs it, as
473
+ [How the file works](#how-the-file-works) says), then see what the
474
+ pattern gives one ticket:
475
+
476
+ ```console
477
+ $ factory config check
478
+ ✓ The settings are valid.
479
+ $ factory ticket branch 12
480
+ feature/octocat/12
328
481
  ```
329
482
 
483
+ `factory config check` stops on a placeholder it doesn't know, a pattern
484
+ without `{ticket}`, and a pattern git can't use as a branch name. Git
485
+ refuses a name that:
486
+
487
+ - has a space, a control character, `..`, `//`, or `@{`
488
+ - has any of `~`, `^`, `:`, `?`, `*`, `[`, or `\`
489
+ - starts with `-` or `/`, or ends with `/`, `.`, or `.lock`
490
+ - has a part between slashes that starts with `.` or ends with `.lock`
491
+
492
+ Anything else is fine, `#` and `_` included. The check names the first
493
+ fault it finds:
494
+
495
+ ```text
496
+ .claude/factory.yaml: code-host.branch-name: feature//{ticket} can't be a git branch name: it has //
497
+ ```
498
+
499
+ Commit `.claude/factory.yaml` and `.claude/factory.lock`. The next build
500
+ uses the new pattern; branches already pushed keep their names.
501
+
330
502
  ### `builds`
331
503
 
332
504
  What starts a build when you approve a ticket, and where the build runs.
@@ -558,8 +730,8 @@ There is no default. Without a gate, `factory gate` fails with
558
730
  `commands.gate is not set`, and a build stops there, because an empty gate
559
731
  would pass every change. `factory init` lists it under "Left to do".
560
732
 
561
- When a command fails, `factory gate` prints `gate failed on:` and the
562
- command, and runs none after it. The session fixes the cause and runs the
733
+ When a command fails, `factory gate` prints `✗ The gate failed on:` and
734
+ the command, and runs none after it. The session fixes the cause and runs the
563
735
  gate again.
564
736
 
565
737
  **Check your gate yourself** before a session relies on it: run
@@ -1048,6 +1220,17 @@ repository: harbor-goods/storefront
1048
1220
 
1049
1221
  tickets:
1050
1222
  board: 1
1223
+ columns:
1224
+ backlog: Backlog
1225
+ refining: In refinement
1226
+ ready: Ready
1227
+ building: In progress
1228
+ review: In review
1229
+ done: Done
1230
+
1231
+ code-host:
1232
+ type: github
1233
+ branch-name: "{ticket}"
1051
1234
 
1052
1235
  builds:
1053
1236
  trigger: own-server
@@ -1117,6 +1300,17 @@ repository: riverbend-studio/site
1117
1300
 
1118
1301
  tickets:
1119
1302
  board: 4
1303
+ columns:
1304
+ backlog: Backlog
1305
+ refining: In refinement
1306
+ ready: Ready
1307
+ building: In progress
1308
+ review: In review
1309
+ done: Done
1310
+
1311
+ code-host:
1312
+ type: github
1313
+ branch-name: "{ticket}"
1120
1314
 
1121
1315
  commands:
1122
1316
  before-commit:
@@ -1140,6 +1334,17 @@ repository: northwind-php/ledger
1140
1334
 
1141
1335
  tickets:
1142
1336
  board: 2
1337
+ columns:
1338
+ backlog: Backlog
1339
+ refining: In refinement
1340
+ ready: Ready
1341
+ building: In progress
1342
+ review: In review
1343
+ done: Done
1344
+
1345
+ code-host:
1346
+ type: github
1347
+ branch-name: "{ticket}"
1143
1348
 
1144
1349
  commands:
1145
1350
  build-setup: