@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/design.md CHANGED
@@ -101,6 +101,16 @@ name ever had to mean different states for different kinds of ticket,
101
101
  an optional `columns-by-type` setting would hold only those exceptions,
102
102
  and every settings file written before it would read the same.
103
103
 
104
+ Refinement writes each factory field into a ticket field of yours, or
105
+ into the description, by the ticket field's name, with no setting for
106
+ each kind of ticket. A ticket whose kind can't hold the ticket field
107
+ keeps that factory field in its description.
108
+ [_Planned_](developing.md#what-is-built): on Jira, where a kind of
109
+ ticket can leave a field out, a factory field could name a list of
110
+ ticket fields, `spec: [Acceptance criteria, AC]`, and go in the first
111
+ the ticket can hold, as a state does with columns. A `fields-by-type`
112
+ setting would hold only the exceptions, if one were ever needed.
113
+
104
114
  ## Small problems go on one checklist
105
115
 
106
116
  A session that notices a small problem adds a line to one follow-ups
@@ -54,6 +54,7 @@ marked working below exist only in these docs.
54
54
  | `factory board --dry-run` | Working |
55
55
  | Your own column names on a board | Working |
56
56
  | `init` suggesting a board's columns through the coding agent | Working |
57
+ | Refinement's factory fields in your ticket fields, suggested by `init` | Working |
57
58
  | A UI reviewer for any website | Working |
58
59
  | Built-in measurements for any website | Working |
59
60
  | A design skill for any website | Working |
@@ -249,18 +250,25 @@ whole or not at all, and `factory ticket supports GROUP` prints `yes` or
249
250
  `no`. A skill asks before it relies on one; a command that needs a group
250
251
  its adapter lacks exits non-zero, names the group, and posts nothing.
251
252
 
252
- | Group | In `Tickets` | Operations |
253
- | --------------- | -------------- | ------------------------------------------------------------------------------------------------------------------------------- |
254
- | `board` | `board` | Read every card and the board's fields; list a board's columns, in the board's order; add a ticket to the board; set its fields |
255
- | `blockers` | `blockers` | List what a ticket waits on; record that it waits on another; remove that |
256
- | `label-history` | `labelHistory` | Whether a label was ever removed from a ticket, which is how the factory knows the owner took `spec` off |
257
- | `attachments` | `attachments` | Comment with images attached, or write a body with them |
253
+ | Group | In `Tickets` | Operations |
254
+ | --------------- | -------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
255
+ | `board` | `board` | Read every card and the board's fields; list a board's columns, in the board's order; add a ticket to the board; set its fields |
256
+ | `blockers` | `blockers` | List what a ticket waits on; record that it waits on another; remove that |
257
+ | `label-history` | `labelHistory` | Whether a label was ever removed from a ticket, which is how the factory knows the owner took `spec` off |
258
+ | `attachments` | `attachments` | Comment with images attached, or write a body with them |
259
+ | `fields` | `fields` | List the ticket fields that hold text, with their descriptions; say whether a ticket can hold one, and how much; read a ticket's field values; set or clear them |
258
260
 
259
261
  The GitHub adapter has every group, except that `attachments` needs the
260
262
  GitHub CLI, so an adapter built without it has none. With
261
263
  no board, state lives in the ticket's comments. With no blockers, the build
262
264
  order is prose in the ticket and nothing enforces it.
263
265
 
266
+ The GitHub adapter's `fields` are issue fields, which it reads and
267
+ writes with the `repo` scope. With no fields group, every factory field
268
+ of a refined ticket stays in its description. `factory ticket view` and
269
+ `edit` join and split a ticket's document above the interface, so no
270
+ skill or agent knows whether a ticket has fields.
271
+
264
272
  **The transport is a parameter.** The GitHub adapter, `src/code-host/`, and
265
273
  `src/runner/` take one function for a REST call, one for a GraphQL query,
266
274
  and one for an answer in plain text, such as a job's log
@@ -400,7 +408,7 @@ when the two differ. Every member of a setup is optional.
400
408
 
401
409
  | Member | What it gives | Used by |
402
410
  | ------------- | --------------------------------------------------------------------------------------------------------------------------------------- | -------- |
403
- | `found` | Its row under "Found", when it says more than the tool's name, such as that a command is not installed | `init` |
411
+ | `found` | Its row under "Found", when it says more than the tool's name, such as where it was found | `init` |
404
412
  | `steps` | A value to write under the tool's block of the settings, or a secret: which parts read it, how to get it, and how to check a pasted one | `init` |
405
413
  | `checks` | Its own lines in `doctor`: that it is reachable, signed in, or configured, each failure with its fix in the tool's words | `doctor` |
406
414
  | `leftovers` | What removing the factory leaves outside the repository, such as its secrets | `remove` |
@@ -425,9 +433,12 @@ A coding agent also answers one question for `init`: given a prompt and
425
433
  the shape of the answer as a JSON schema, it runs once, with no tools and
426
434
  none of the repository's settings or hooks, and returns the answer or
427
435
  the reason it has none. Claude Code runs `claude -p` on its smallest
428
- model, from an empty folder. The prompt, the checks on the answer, and
429
- what `init` prints live in `src/columns-suggest.mts`, which names no
430
- agent and no ticket system, so a second agent adds only its `answer`.
436
+ model, from an empty folder. The prompts, the checks on the answers, and
437
+ what `init` prints live in `src/columns-suggest.mts` and
438
+ `src/ticket-fields.mts`, which name no agent and no ticket system, so a
439
+ second agent adds only its `answer`. `factory init` stops before its
440
+ first question when the coding agent's command isn't installed, by the
441
+ agent's `installed` method.
431
442
 
432
443
  The tests show a tool that the factory does not ship going through all
433
444
  three commands: `tests/fake-tools.ts` has a ticket system with a site
@@ -436,14 +447,14 @@ one file.
436
447
 
437
448
  ## Checking a change
438
449
 
439
- | Check | What it proves |
440
- | ---------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
441
- | The tool's unit tests | Each command does what it says. A new test is seen failing before it is trusted |
442
- | `factory sync --check` | The copies match the source |
443
- | Pack and install | CI packs the folder, installs it into an empty scratch repository, and runs `sync`, `config check`, and one read-only command there. It works outside its host |
444
- | `factory-trace` | A change to a rule did not make some kind of change heavier, lighter, or ambiguous |
445
- | Fork safety | No workflow it runs or ships could run a fork's code with a secret or write access (`tests/fork-safety.test.ts`). This repository is public |
446
- | One throwaway ticket | After each stage, one small ticket goes through refine, build, and review for real. Nothing else tests the prose |
450
+ | Check | What it proves |
451
+ | ---------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
452
+ | The tool's unit tests | Each command does what it says, with coverage at or above the floors in `vitest.config.ts`. A new test is seen failing before it is trusted |
453
+ | `factory sync --check` | The copies match the source |
454
+ | Pack and install | CI packs the folder, installs it into an empty scratch repository, and runs `sync`, `config check`, and one read-only command there. It works outside its host |
455
+ | `factory-trace` | A change to a rule did not make some kind of change heavier, lighter, or ambiguous |
456
+ | Fork safety | No `pull_request_target` or `workflow_run` job it runs or ships checks out a pull request's code, which would run a fork's code with secrets (`tests/fork-safety.test.ts`) |
457
+ | One throwaway ticket | After each stage, one small ticket goes through refine, build, and review for real. Nothing else tests the prose |
447
458
 
448
459
  The skills are instructions, and instructions cannot be unit tested. The
449
460
  last row is the only real proof that a change to one still works.
@@ -539,3 +550,23 @@ this repository's own reviewer, reads a changed page as that person.
539
550
  "Without one", and reads on its own: not a pronoun or a clipped phrase,
540
551
  such as "It" or "Left out", that makes sense only once a cell is read
541
552
  into it.
553
+
554
+ ### A command's output
555
+
556
+ A person reads it in a terminal, often while doing something else.
557
+
558
+ - **Precise and short.** A label and a value, or a mark and a few words,
559
+ not a sentence explaining them. What a mark or a state word means is
560
+ said once, in `docs/cli.md`.
561
+ - **A block is headed by the setting it shows,** such as
562
+ [`tickets.fields`](configuration.md#ticketsfields), so the reader knows
563
+ what to edit.
564
+ - **The marks mean one thing everywhere:** ✓ works, ✗ needs fixing,
565
+ ? worth a look, - off on purpose.
566
+ - **A fault sits on the line it is about,** with the fix after it.
567
+ - **Success prints one line.** Silence reads as nothing happened.
568
+ - **A command is named as `factory X`,** as the docs write it.
569
+ - **Piped output is the same text,** without color. Lines a skill reads
570
+ keep their format.
571
+ - **Another tool's output passes through unchanged.** The factory adds
572
+ its own line after it, never rewrites it.
@@ -51,16 +51,34 @@ complete settings file for a PHP library.
51
51
  ## You already have a board
52
52
 
53
53
  A ticket is always in one of six [states](workflow.md#the-six-states),
54
- and the factory shows each state as a column of your board. Its own names
55
- for them are Backlog, In refinement, Ready, In progress, In review, and
56
- Done, and the settings call the states `backlog`, `refining`, `ready`,
57
- `building`, `review`, and `done`, in that order. Capitals don't matter, so
58
- your "In Progress" is its "In progress".
54
+ and the factory shows each state as a column of your board. The settings
55
+ call the states `backlog`, `refining`, `ready`, `building`, `review`, and
56
+ `done`, in that order. `factory init` saves which of your columns shows
57
+ each in [`tickets.columns`](configuration.md#ticketscolumns), always all
58
+ six, and every factory command needs all six there.
59
59
 
60
60
  When you run `factory init`, step 2 of the
61
- [quick start](quick-start.md#2-set-it-up), it lists your boards to choose from. If the
62
- one you choose has all six columns, there is nothing to set up. If it
63
- lacks any, init asks your coding agent, Claude Code, which of your
61
+ [quick start](quick-start.md#2-set-it-up), it lists your boards to choose
62
+ from. If the one you choose already has the factory's own columns,
63
+ Backlog, In refinement, Ready, In progress, In review, and Done, init
64
+ asks nothing and saves them. Capitals don't matter, so your
65
+ "In Progress" is its "In progress":
66
+
67
+ ```text
68
+ ? Which board? Use an existing one: Shop board (#3)
69
+
70
+ Board 3 has a column for each of the factory's six states:
71
+
72
+ State Column
73
+ backlog Backlog
74
+ refining In refinement
75
+ ready Ready
76
+ building In Progress
77
+ review In review
78
+ done Done
79
+ ```
80
+
81
+ If it lacks any, init asks your coding agent, Claude Code, which of your
64
82
  columns shows each state, and shows you the answer before it changes
65
83
  anything. This is one short request with no tools, made with the sign-in
66
84
  Claude Code already has, and it sends your column names and nothing else.
@@ -74,8 +92,8 @@ Asking Claude Code which of them shows each of the factory's six states...
74
92
 
75
93
  State Column
76
94
  backlog Todo
77
- refining no column, shows in Todo
78
- ready no column: builds start only when you ask
95
+ refining none, shows in Todo
96
+ ready none
79
97
  building In Progress
80
98
  review Code review
81
99
  done Done
@@ -89,12 +107,11 @@ Asking Claude Code which of them shows each of the factory's six states...
89
107
  A state with no column shows its tickets in the column of the state
90
108
  before it, so here a ticket being refined stays in Todo. With no column
91
109
  for ready, you start each build with `/factory-build N` in a session,
92
- rather than by moving its ticket on the board. That is the factory's
93
- default, so the settings need nothing more: init offers no column for
94
- ready only when builds start when you ask.
110
+ rather than by moving its ticket on the board. So init offers no column
111
+ for ready only when [`builds.trigger`](configuration.md#builds) is
112
+ `manual`, the setting for builds that start when you ask.
95
113
 
96
- - **Yes** saves the table in your settings, `.claude/factory.yaml`, with
97
- only the states whose column isn't the factory's own name:
114
+ - **Yes** saves the table in your settings, `.claude/factory.yaml`:
98
115
 
99
116
  ```yaml
100
117
  tickets:
@@ -103,7 +120,9 @@ ready only when builds start when you ask.
103
120
  backlog: Todo
104
121
  refining: none
105
122
  ready: none
123
+ building: In Progress
106
124
  review: Code review
125
+ done: Done
107
126
  ```
108
127
 
109
128
  - **Change some** lets you pick the states to change from a list, then,
@@ -111,11 +130,11 @@ ready only when builds start when you ask.
111
130
  factory's name, which init adds to your board. Each state needs a column
112
131
  of its own: two states can't share one.
113
132
  - **No** adds each of the factory's six columns your board lacks, here
114
- Backlog, In refinement, Ready, and In review, and saves nothing. Your
115
- Todo, In Progress, Code review, and Done columns stay. In Progress and
116
- Done are used, since their names match. The factory ignores the tickets
117
- in Todo and Code review: nothing moves or builds them until you move
118
- them to one of its columns.
133
+ Backlog, In refinement, Ready, and In review, and saves the six
134
+ factory names. Your Todo, In Progress, Code review, and Done columns
135
+ stay. In Progress and Done are used, since their names match. The
136
+ factory ignores the tickets in Todo and Code review: nothing moves or
137
+ builds them until you move them to one of its columns.
119
138
 
120
139
  Init ends by running its checks. When the columns are right, you see:
121
140
 
@@ -125,20 +144,22 @@ Checks
125
144
  ```
126
145
 
127
146
  **Init stops, and changes nothing, when it can't get an answer:** when
128
- Claude Code isn't installed or isn't signed in, or when its answer can't
129
- be used, such as one column for two states. It prints why. Then do one of
130
- these, and run `factory init` again:
147
+ Claude Code isn't signed in, or when its answer can't be used, such as
148
+ one column for two states. It prints why. Then do one of these, and run
149
+ `factory init` again:
131
150
 
132
- - install Claude Code and sign in, by running `claude` once;
151
+ - sign in to Claude Code, by running `claude` once;
133
152
  - write a `columns` block like the one above in `.claude/factory.yaml`
134
- yourself, with your own columns, as
135
- [`tickets.columns`](configuration.md#ticketscolumns) describes: init
136
- then doesn't ask;
153
+ yourself, with all six states, beside your `board`, as
154
+ [`tickets.columns`](configuration.md#ticketscolumns) describes. When
155
+ `factory config check` ends with `✓ The settings are valid.`, init
156
+ won't ask;
137
157
  - add the six columns to your board yourself, so init has nothing to ask.
138
158
 
139
- Running init again is safe: it keeps what your settings already say. Once
140
- they have a `columns` block, init doesn't ask about columns again. If you
141
- change your board's columns later, edit the block, or delete it and run
159
+ Running init again is safe: it keeps what your settings already say. If
160
+ the block leaves a state out, every factory command stops and names it,
161
+ and running init asks you only for that state. If you change your
162
+ board's columns later, edit the block, or delete it and run
142
163
  `factory init` again for a new suggestion.
143
164
 
144
165
  Init suggests one column for each state. When two of your columns mean the
@@ -150,8 +171,8 @@ What else to expect on a board you already use:
150
171
  - **The factory never renames or deletes your columns,** and only adds the
151
172
  ones you agree to.
152
173
  - **It adds three fields to your board,** Session, Runs in, and Cost, and
153
- overwrites them on every sync, so don't type into them. Your own fields
154
- are never touched. [`tickets.fields`](configuration.md#ticketsfields)
174
+ overwrites them on every sync, so don't type into them. Your own board
175
+ fields are never touched. [`tickets.fields`](configuration.md#ticketsfields)
155
176
  says what each holds.
156
177
  - **Your board's own automations**, such as moving a closed ticket to
157
178
  Done, have not been tested alongside the factory. Turn them off if
@@ -159,8 +180,137 @@ What else to expect on a board you already use:
159
180
 
160
181
  To see what the factory will do with your board at any time, run
161
182
  `factory board check`. It lists each state's column, as the table above
162
- does, and ends with any problem, such as a column your settings name that
163
- the board lacks.
183
+ does, and each field the sync fills in, and marks a problem with ✗ on its
184
+ row, such as a column your settings name that the board lacks.
185
+
186
+ ## Your tickets already have fields
187
+
188
+ If your tickets have text fields of their own, such as an "Acceptance
189
+ criteria" field your team fills in by hand, the factory can write what
190
+ it settles when it refines a ticket into those fields instead of the
191
+ ticket's description. At the end, refining a ticket fills in your
192
+ fields, and the description holds your text and whatever has no field.
193
+ If your tickets have no such field, skip this section: nothing changes.
194
+
195
+ [Refining a ticket](skills.md#factory-refine), with `/factory-refine N`,
196
+ writes four parts after your own text, each under its own heading. These
197
+ are the factory's fields for a refined ticket:
198
+
199
+ | Factory field | What it holds |
200
+ | ------------------- | ---------------------------------------------------------- |
201
+ | Decisions | The questions refinement settled, and what was chosen |
202
+ | Spec | What a change your users will notice must do, line by line |
203
+ | Acceptance criteria | What must be true for any other ticket to be done |
204
+ | For the builder | How to build it, as a design and a list of tasks |
205
+
206
+ A ticket has a Spec or Acceptance criteria, never both: refinement writes
207
+ a Spec when the change is one
208
+ [your users will notice](workflow.md#a-change-your-users-will-see), and
209
+ Acceptance criteria otherwise.
210
+
211
+ This page calls a field of yours that is set on the ticket itself a
212
+ ticket field. On GitHub, a ticket field is an
213
+ [issue field](https://docs.github.com/en/issues/tracking-your-work-with-issues/using-issues/managing-issue-fields-in-your-organization),
214
+ shown beside the issue, which you create in your account's or
215
+ organization's settings, under Issue fields. A field you add to your
216
+ board, which shows as a column of the board's table, can't hold a
217
+ factory field: GitHub limits it to 1,024 characters, and a Spec is often
218
+ several thousand. Create the issue field before you run init, since init
219
+ offers only ticket fields that exist.
220
+
221
+ When you run `factory init`, step 2 of the
222
+ [quick start](quick-start.md#2-set-it-up), it finds your text ticket
223
+ fields and asks your coding agent, Claude Code, which of them should hold
224
+ each factory field. If you already ran init, run it again after creating
225
+ the field: it keeps what your settings say and asks only about ticket
226
+ fields. As for your board's columns, this is one short request with no
227
+ tools, and it sends your ticket fields' names and descriptions and
228
+ nothing else. Init shows you the answer before it writes anything. On a
229
+ repository whose tickets have the text fields Acceptance criteria,
230
+ Design notes, and Customer, init shows:
231
+
232
+ ```text
233
+ acme/shop's tickets have the text fields Acceptance criteria, Design notes, and Customer.
234
+ Asking Claude Code which of them should hold each of the factory's fields...
235
+
236
+ Factory field Ticket field
237
+ Decisions the description
238
+ Spec Acceptance criteria
239
+ Acceptance criteria Acceptance criteria
240
+ For the builder Design notes
241
+
242
+ Your own text stays in the description.
243
+ GitHub Issues shows a field's text as typed, without Markdown formatting.
244
+
245
+ ? Use these ticket fields? (Use arrow keys)
246
+ ❯ Yes
247
+ Change some
248
+ No: keep everything in the description
249
+ ```
250
+
251
+ A factory field goes in the description unless a ticket field clearly
252
+ fits it, so here Decisions stays there, and nothing goes in Customer.
253
+ Spec and Acceptance criteria share a ticket field here, since a ticket
254
+ has only one of them.
255
+
256
+ - **Yes** saves the table in your settings, `.claude/factory.yaml`, one
257
+ line for each factory field, with `none` for one that stays in the
258
+ description:
259
+
260
+ ```yaml
261
+ tickets:
262
+ fields:
263
+ decisions: none
264
+ spec: Acceptance criteria
265
+ acceptance-criteria: Acceptance criteria
266
+ for-the-builder: Design notes
267
+ ```
268
+
269
+ - **Change some** lets you pick the factory fields to change from a list,
270
+ then, for each, pick one of your ticket fields or the description.
271
+ - **No** saves all four as `none`, so everything stays in the
272
+ description, as it would with no ticket fields.
273
+
274
+ When your tickets have no text field, init doesn't ask, writes nothing
275
+ about them, and prints no check for them.
276
+
277
+ **It worked when** the checks init prints last include:
278
+
279
+ ```text
280
+ Checks
281
+ ✓ acme/shop's tickets have every field the settings name
282
+ ```
283
+
284
+ Then refine a ticket and open it on GitHub. Here, its Spec or
285
+ Acceptance criteria shows in the Acceptance criteria field beside the
286
+ issue, and its design and tasks in Design notes. GitHub shows a field's
287
+ text as typed, so a list reads as written, with its numbers and dashes,
288
+ and a table shows its `|` marks. You and your coding agent see no other
289
+ difference: the agent still reads the whole ticket, fields included.
290
+
291
+ **Init stops, and changes nothing, when it can't use the answer,** such
292
+ as when Claude Code isn't signed in, or names a ticket field your tickets
293
+ don't have. It prints why. Then do one of these, and run `factory init`
294
+ again:
295
+
296
+ - if it says Claude Code isn't signed in, sign in by running `claude`
297
+ once;
298
+ - otherwise, write the four lines above yourself, as
299
+ [`tickets.fields`](configuration.md#ticketsfields) describes: init
300
+ then doesn't ask.
301
+
302
+ **Running init again** keeps what the four lines say, and doesn't ask
303
+ again. To be asked again, for example after creating another ticket
304
+ field, delete the four lines and run `factory init`.
305
+
306
+ **If you change a line later,** a ticket refined before keeps its
307
+ factory fields where they were written, and a ticket field it no longer
308
+ uses keeps its text until you clear it. For a ticket not yet built, run
309
+ `/factory-refine N` again: it rewrites the four parts where the settings
310
+ now say, and leaves your own text as it is.
311
+
312
+ A heading of your own, such as one your own refiner writes, can go in a
313
+ ticket field too: see [`tickets.fields`](configuration.md#ticketsfields).
164
314
 
165
315
  ## You already have agent instructions, settings, or CI workflows
166
316
 
@@ -34,6 +34,9 @@ If you followed the quick start, this is done.
34
34
  ```yaml
35
35
  version: 2
36
36
  repository: your-name/your-repo
37
+ code-host:
38
+ type: github
39
+ branch-name: "{ticket}"
37
40
  ```
38
41
 
39
42
  2. Write the factory's files:
@@ -163,11 +166,20 @@ what each column means.
163
166
  Runs in, a single select with the options Local and Actions; and Cost, a
164
167
  Number. A field the sync does not find, it skips.
165
168
  4. **Point the settings at it,** with the Project's number under
166
- [`tickets`](../configuration.md#tickets):
169
+ [`tickets`](../configuration.md#tickets), and which column shows each
170
+ state under [`tickets.columns`](../configuration.md#ticketscolumns),
171
+ here the columns step 2 added:
167
172
 
168
173
  ```yaml
169
174
  tickets:
170
175
  board: 7
176
+ columns:
177
+ backlog: Backlog
178
+ refining: In refinement
179
+ ready: Ready
180
+ building: In progress
181
+ review: In review
182
+ done: Done
171
183
  ```
172
184
 
173
185
  Then `factory board check` shows how it reads your
@@ -15,6 +15,11 @@ it leaves for you to do.
15
15
  | Claude Code, signed in | `claude --version` | [Install it](https://claude.com/claude-code), run `claude`, and sign in |
16
16
  | Node 22.18 or later | `node --version` | [nodejs.org](https://nodejs.org) |
17
17
 
18
+ `factory init` stops before its first question when Claude Code isn't
19
+ installed, and changes nothing. It needs Claude Code to set up the
20
+ coding agent's token, and to suggest your board's columns and your
21
+ tickets' fields.
22
+
18
23
  ## Run `factory init`
19
24
 
20
25
  In your repository, with the package
@@ -24,8 +29,15 @@ In your repository, with the package
24
29
  factory init
25
30
  ```
26
31
 
27
- It shows what it found, then asks which parts you want. Each is optional
28
- and stands alone:
32
+ It shows what it found, then asks what to name the branch a session
33
+ pushes when it builds a ticket, offering `{ticket}`, the ticket's
34
+ number, so ticket 12 is built on a branch named `12`. Press Enter to
35
+ keep it, or type your team's pattern, such as `feature/{user}/{ticket}`,
36
+ where `{user}` is your GitHub account;
37
+ [`code-host`](../configuration.md#code-host) lists what a pattern can
38
+ hold. When a [preset](../presets.md) you follow already sets it, init
39
+ doesn't ask. Then it asks which parts you want. Each is optional and
40
+ stands alone:
29
41
 
30
42
  | Part | What you get |
31
43
  | ----------------------------------------------- | ------------------------------------------------------------------------------ |
package/docs/presets.md CHANGED
@@ -18,9 +18,11 @@ It has two readers:
18
18
  Without a preset, every repository's
19
19
  [`.claude/factory.yaml`](configuration.md) repeats the same lines, such as
20
20
  the board's number in [`tickets.board`](configuration.md#tickets), the
21
- size limit in [`rules.small-change-lines`](configuration.md#rules), and
22
- the same [reviewer plugins](plugins.md#reviewer), your own agents that
23
- read every change. Changing one of them means a pull request in every
21
+ size limit in [`rules.small-change-lines`](configuration.md#rules), the
22
+ way your team names branches in
23
+ [`code-host.branch-name`](configuration.md#code-host), and the same
24
+ [reviewer plugins](plugins.md#reviewer), your own agents that read every
25
+ change. Changing one of them means a pull request in every
24
26
  repository, and nothing shows which ones have fallen behind.
25
27
 
26
28
  With a preset, a repository names it under
@@ -298,6 +300,16 @@ maintains the preset.
298
300
  tickets:
299
301
  type: github
300
302
  board: 7
303
+ columns:
304
+ backlog: Backlog
305
+ refining: In refinement
306
+ ready: Ready
307
+ building: In progress
308
+ review: In review
309
+ done: Done
310
+ code-host:
311
+ type: github
312
+ branch-name: "feature/{user}/{ticket}"
301
313
  rules:
302
314
  small-change-lines: 40
303
315
  plugins:
@@ -12,7 +12,7 @@ A word you do not know is in the [glossary](glossary.md).
12
12
 
13
13
  - A repository on a supported code host, cloned on your machine, with the
14
14
  code host's command-line tool signed in.
15
- - A supported coding agent, signed in.
15
+ - A supported coding agent, signed in. `factory init` stops without one.
16
16
  - Node 22.18 or later.
17
17
 
18
18
  [What you need](github/setup.md#what-you-need) names the supported tools
@@ -77,8 +77,8 @@ A repository with no tests yet lists the checks it does have, such as a
77
77
  formatter or a compile, and adds its tests to the gate when there are
78
78
  some.
79
79
 
80
- **It worked when** `factory gate` runs each command and ends without a
81
- line that starts `gate failed on`.
80
+ **It worked when** `factory gate` runs each command and ends with
81
+ `✓ Every gate command passed.`
82
82
 
83
83
  ## 3. Merge the setup
84
84
 
package/docs/skills.md CHANGED
@@ -79,7 +79,9 @@ spec when [`specs`](configuration.md#specs) is on.
79
79
  **What it writes.**
80
80
 
81
81
  - The ticket's body: your text first, untouched, then Decisions and
82
- Acceptance criteria, or a Spec when the change is visible and not small.
82
+ Acceptance criteria, or a Spec when the change is visible and not
83
+ small. Each of these goes in a ticket field of yours instead, when
84
+ [`tickets.fields`](configuration.md#ticketsfields) names one.
83
85
  - Marker comments that move the ticket to "refining" and show it waiting on
84
86
  you.
85
87
  - A blocked-by relationship for each ticket that must be built first.