@davidbyoung/software-factory 0.1.9 → 0.1.11

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 (67) hide show
  1. package/agents/factory-ticket-readiness.md +20 -15
  2. package/dist/board.d.mts +1 -1
  3. package/dist/board.mjs +4 -7
  4. package/dist/cli.mjs +23 -1
  5. package/dist/code-host/github.d.mts +1 -1
  6. package/dist/code-host/github.mjs +31 -2
  7. package/dist/code-host/types.d.mts +20 -1
  8. package/dist/code-host/types.mjs +8 -0
  9. package/dist/columns-suggest.d.mts +25 -5
  10. package/dist/columns-suggest.mjs +117 -21
  11. package/dist/commands.d.mts +8 -2
  12. package/dist/commands.mjs +92 -8
  13. package/dist/config.d.mts +19 -7
  14. package/dist/config.mjs +109 -30
  15. package/dist/doctor.mjs +1 -2
  16. package/dist/explain.mjs +7 -1
  17. package/dist/init.d.mts +19 -0
  18. package/dist/init.mjs +139 -23
  19. package/dist/lib/gh.d.mts +6 -0
  20. package/dist/lib/gh.mjs +11 -1
  21. package/dist/lib/listed.d.mts +3 -2
  22. package/dist/lib/listed.mjs +5 -4
  23. package/dist/lib/work-status.d.mts +5 -5
  24. package/dist/lib/work-status.mjs +7 -8
  25. package/dist/merge-policy.mjs +7 -3
  26. package/dist/poller.d.mts +1 -1
  27. package/dist/poller.mjs +9 -6
  28. package/dist/pr.d.mts +8 -6
  29. package/dist/pr.mjs +47 -22
  30. package/dist/review-verdict.d.mts +22 -4
  31. package/dist/review-verdict.mjs +55 -17
  32. package/dist/specs/index.d.mts +6 -0
  33. package/dist/specs/index.mjs +15 -0
  34. package/dist/specs/openspec.d.mts +2 -0
  35. package/dist/specs/openspec.mjs +78 -0
  36. package/dist/specs/types.d.mts +53 -0
  37. package/dist/specs/types.mjs +4 -0
  38. package/dist/ticket.d.mts +6 -1
  39. package/dist/ticket.mjs +62 -3
  40. package/dist/tickets/github-access.d.mts +5 -0
  41. package/dist/tickets/github-access.mjs +22 -0
  42. package/dist/tickets/github.mjs +2 -0
  43. package/dist/tickets/types.d.mts +4 -0
  44. package/dist/tool-names.d.mts +2 -0
  45. package/dist/tool-names.mjs +3 -0
  46. package/dist/tools.d.mts +2 -0
  47. package/dist/tools.mjs +3 -0
  48. package/docs/builds.md +30 -14
  49. package/docs/cli.md +48 -30
  50. package/docs/configuration.md +237 -73
  51. package/docs/developing.md +104 -59
  52. package/docs/existing-repo.md +51 -29
  53. package/docs/github/by-hand.md +13 -1
  54. package/docs/github/setup.md +26 -2
  55. package/docs/glossary.md +7 -6
  56. package/docs/limitations.md +8 -5
  57. package/docs/presets.md +15 -3
  58. package/docs/updating.md +147 -2
  59. package/docs/workflow.md +26 -9
  60. package/package.json +1 -1
  61. package/rules.md +36 -30
  62. package/settings.schema.json +14 -9
  63. package/skills/factory-address-review/SKILL.md +40 -39
  64. package/skills/factory-build/SKILL.md +77 -52
  65. package/skills/factory-deps/SKILL.md +6 -4
  66. package/skills/factory-refine/SKILL.md +30 -22
  67. package/skills/factory-resolve-conflicts/SKILL.md +8 -7
@@ -30,51 +30,51 @@ completes with the files the version writes ([Updating](updating.md)).
30
30
  The factory is the npm package `@davidbyoung/software-factory`. Parts not
31
31
  marked working below exist only in these docs.
32
32
 
33
- | Part | State |
34
- | ---------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------- |
35
- | Refining, building, and working a pull request's review | Working |
36
- | The board, its sync, and `status` | Working |
37
- | Builds from the board, with a poller you host | Working |
38
- | Builds that run in GitHub Actions, started by a command | Working |
39
- | Starting builds from the board, and the review, conflict, and dependency runs, in GitHub Actions | Working |
40
- | Who merges, and the review's verdict | Working |
41
- | The labels `merge: manual` and `verdict: override` | Working |
42
- | These docs | Working |
43
- | `.claude/factory.yaml`, and the factory's files kept apart from the host's | Working |
44
- | The follow-ups ticket as one checklist | Working |
45
- | The `factory` tool, `sync`, and the package folder | Working |
46
- | A global `factory` command that runs each repository's own copy | Working |
47
- | The automated review as one of the factory's workflows, and [`pr-review`](configuration.md#pr-review) | Working |
48
- | Nothing in the package names the repository it was drawn out of, checked in the folder and the packed tarball | Working |
49
- | The `factory-` names and the `FACTORY_` secrets | Working |
50
- | Ticket commands that go through one interface | Working |
51
- | The code host and the runner, each behind one interface | Working |
52
- | A published package | Working |
53
- | Updates through Dependabot, which `factory-deps` completes with `factory sync` | Working |
54
- | `factory board --dry-run` | Working |
55
- | Your own column names on a board | Working |
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 |
58
- | A UI reviewer for any website | Working |
59
- | Built-in measurements for any website | Working |
60
- | A design skill for any website | Working |
61
- | `init`, which can be re-run, and `doctor` | Working |
62
- | A second repository set up and removed from the quick start alone | Working |
63
- | `factory remove` | Working |
64
- | Starting builds from a scheduled workflow, `factory poller --once`, and a poller built from an installed package | Working |
65
- | [`rules`](configuration.md#rules) in the settings, `factory config explain`, and the `factory-trace` skill | Working |
66
- | Settings version 2: commands, a spec check, and plugins grouped by phase | Working |
67
- | `factory gate`, `test-one`, `end-to-end`, and `specs check`, which run the settings' commands | Working |
68
- | The default branch read from Git and the code host, never assumed, and `factory default-branch` | Working |
69
- | A refiner, a prover, test reviewers, and conflict resolvers of your own, and `factory-e2e-reviewer` | Working |
70
- | `factory ticket refined` refusing a ticket a build could not read | Working |
71
- | No skill, agent, rule, or review instruction names a stack, checked by a test | Working |
72
- | `approvers` in the settings | Planned, [#14](https://github.com/davidbyoung/software-factory/issues/14) |
73
- | Another ticket system, such as Jira | Not planned. The design leaves room |
74
- | A ticket system or code host named by a package, for an adapter you write yourself | Not planned. The design leaves room |
75
- | Another code host or runner | Not planned. The design leaves room |
76
- | Each tool's setup, checks, and removal declared by the tool | Working |
77
- | Sharing plugins between repositories | Not planned |
33
+ | Part | State |
34
+ | ---------------------------------------------------------------------------------------------------------------- | --------------------------------------------------- |
35
+ | Refining, building, and working a pull request's review | Working |
36
+ | The board, its sync, and `status` | Working |
37
+ | Builds from the board, with a poller you host | Working |
38
+ | Builds that run in GitHub Actions, started by a command | Working |
39
+ | Starting builds from the board, and the review, conflict, and dependency runs, in GitHub Actions | Working |
40
+ | Who merges, and the review's verdict | Working |
41
+ | The labels `merge: manual` and `verdict: override` | Working |
42
+ | These docs | Working |
43
+ | `.claude/factory.yaml`, and the factory's files kept apart from the host's | Working |
44
+ | The follow-ups ticket as one checklist | Working |
45
+ | The `factory` tool, `sync`, and the package folder | Working |
46
+ | A global `factory` command that runs each repository's own copy | Working |
47
+ | The automated review as one of the factory's workflows, and [`pr-review`](configuration.md#pr-review) | Working |
48
+ | Nothing in the package names the repository it was drawn out of, checked in the folder and the packed tarball | Working |
49
+ | The `factory-` names and the `FACTORY_` secrets | Working |
50
+ | Ticket commands that go through one interface | Working |
51
+ | The code host and the runner, each behind one interface | Working |
52
+ | A published package | Working |
53
+ | Updates through Dependabot, which `factory-deps` completes with `factory sync` | Working |
54
+ | `factory board --dry-run` | Working |
55
+ | Your own column names on a board | Working |
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 |
58
+ | A UI reviewer for any website | Working |
59
+ | Built-in measurements for any website | Working |
60
+ | A design skill for any website | Working |
61
+ | `init`, which can be re-run, and `doctor` | Working |
62
+ | A second repository set up and removed from the quick start alone | Working |
63
+ | `factory remove` | Working |
64
+ | Starting builds from a scheduled workflow, `factory poller --once`, and a poller built from an installed package | Working |
65
+ | [`rules`](configuration.md#rules) in the settings, `factory config explain`, and the `factory-trace` skill | Working |
66
+ | Settings version 2: commands, a spec check, and plugins grouped by phase | Working |
67
+ | `factory gate`, `test-one`, `end-to-end`, and `specs check`, which run the settings' commands | Working |
68
+ | The default branch read from Git and the code host, never assumed, and `factory default-branch` | Working |
69
+ | A refiner, a prover, test reviewers, and conflict resolvers of your own, and `factory-e2e-reviewer` | Working |
70
+ | `factory ticket refined` refusing a ticket a build could not read | Working |
71
+ | No skill, agent, rule, or review instruction names a stack, checked by a test | Working |
72
+ | Another ticket system, such as Jira | Not planned. The design leaves room |
73
+ | A ticket system or code host named by a package, for an adapter you write yourself | Not planned. The design leaves room |
74
+ | Another code host or runner | Not planned. The design leaves room |
75
+ | Another spec tool, such as Spec Kit | Not planned. An adapter under `src/specs/` adds one |
76
+ | Each tool's setup, checks, and removal declared by the tool | Working |
77
+ | Sharing plugins between repositories | Not planned |
78
78
 
79
79
  When a part is built, its pull request updates this table, and corrects any
80
80
  page the build had to differ from. [The CLI](cli.md) marks each command
@@ -224,20 +224,21 @@ the work to that type's adapter.** An adapter is one module in
224
224
  `factory config check` and every ticket command with
225
225
  `tickets.type "X" is not supported. "github" is the only ticket system built.`
226
226
 
227
- | Operation | In `Tickets` | What it returns or does |
228
- | ----------------------- | ------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
229
- | Read a ticket | `read` | Its number, title, state (`open` or `closed`), when it closed, labels, body, and comments, each with its ID, author, time, and body |
230
- | List open tickets | `listOpen` | Number, title, and labels, for every open ticket however many there are |
231
- | Read everything at once | `readAll` | Every open ticket and the 30 closed ones most recently updated, as `read` returns each; with the board group, each carries its card. Optional: see below |
232
- | Write a ticket's body | `writeBody` | |
233
- | Comment | `comment` | Returns the comment's ID. Hidden markers pass through unchanged |
234
- | Edit a comment | `editComment` | By its ID |
235
- | Delete a comment | `deleteComment` | By its ID |
236
- | Not found | `NotFoundError` | Reading a ticket that does not exist, or editing or deleting a comment that is gone, throws this, so a caller can tell it from any other failure |
237
- | Open a ticket | `open` | With a title, a body, and labels. Returns its number |
238
- | Add or remove a label | `addLabel`, `removeLabel` | |
239
- | Link text | `linkText` | What makes a merged pull request close the ticket, such as "Closes #12" |
240
- | The address of a ticket | `address` | Its page, which the views link a ticket's number to |
227
+ | Operation | In `Tickets` | What it returns or does |
228
+ | ----------------------- | ------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
229
+ | Read a ticket | `read` | Its number, title, state (`open` or `closed`), when it closed, labels, body, and comments, each with its ID, author, time, and body |
230
+ | List open tickets | `listOpen` | Number, title, and labels, for every open ticket however many there are |
231
+ | Read everything at once | `readAll` | Every open ticket and the 30 closed ones most recently updated, as `read` returns each; with the board group, each carries its card. Optional: see below |
232
+ | Write a ticket's body | `writeBody` | |
233
+ | Comment | `comment` | Returns the comment's ID. Hidden markers pass through unchanged |
234
+ | Edit a comment | `editComment` | By its ID |
235
+ | Delete a comment | `deleteComment` | By its ID |
236
+ | Not found | `NotFoundError` | Reading a ticket that does not exist, or editing or deleting a comment that is gone, throws this, so a caller can tell it from any other failure |
237
+ | Open a ticket | `open` | With a title, a body, and labels. Returns its number |
238
+ | Add or remove a label | `addLabel`, `removeLabel` | |
239
+ | Who may decide | `mayDecide` | Whether a comment's author may decide on a ticket, so `factory ticket answers` takes their comment as an answer. GitHub's asks whether they can write to the repository. Rejects when it cannot say |
240
+ | Link text | `linkText` | What makes a merged pull request close the ticket, such as "Closes #12" |
241
+ | The address of a ticket | `address` | Its page, which the views link a ticket's number to |
241
242
 
242
243
  "Read everything at once" has a default, `readAll` in
243
244
  `src/tickets/types.mts`, built from `listOpen` and `read`, so a new adapter
@@ -396,6 +397,50 @@ variables, and reach pull requests through the code host.
396
397
  The in-memory runner is `tests/memory-runner.ts`, and GitHub Actions' has
397
398
  its own tests against faked replies.
398
399
 
400
+ ## Adding a spec tool
401
+
402
+ A spec tool keeps a copy of each ticket's Spec in the repository. Only
403
+ OpenSpec is built. The settings name it with
404
+ [`specs`](configuration.md#specs), and `src/specs/index.mts` hands a
405
+ command the adapter of that name: one module in `src/specs/` that
406
+ implements the `SpecTool` type in `src/specs/types.mts`. `none` needs no
407
+ adapter. Any other value fails `factory config check` with
408
+ `specs must be one of none, openspec`, which lists a new tool once its
409
+ adapter is registered.
410
+
411
+ **Nothing runs a spec tool except its adapter.** A skill never runs
412
+ `openspec` or any other tool's command. It runs `factory specs list`,
413
+ `new N`, `check`, and `finish N` ([Your repository's
414
+ commands](cli.md#your-repositorys-commands)), which print one line and
415
+ exit 0 with no spec tool, so a skill need not ask which is set. A test
416
+ fails when a factory skill, agent, rule, review instruction, workflow,
417
+ or action runs OpenSpec itself.
418
+
419
+ | What it gives | In `SpecTool` | OpenSpec's |
420
+ | ----------------------------- | --------------------------------- | ------------------------------------------------------------------------------------------------------------ |
421
+ | Its name in init's messages | `name` | `OpenSpec` |
422
+ | Its option in init's question | `label` | `OpenSpec: each ticket holds its spec, and each build also keeps it in openspec/specs/` |
423
+ | How init installs it | `install` | `npm install --save-dev @fission-ai/openspec`, when `package.json` lists it in neither kind of dependency |
424
+ | The check by default | `defaultCheck` | `npx --no-install openspec validate --all --strict --no-interactive` |
425
+ | Its environment | `env` | `DO_NOT_TRACK=1`, so it collects no usage statistics |
426
+ | Its files that are process | `processFiles` | `openspec/config.yaml`, which the merge policy always holds for the owner, whichever tool the settings name |
427
+ | Whether it runs | `runs` | `npx --no-install openspec --version` exits 0 |
428
+ | The specs it keeps | `list` | Each folder under `openspec/specs/` with a `spec.md` |
429
+ | A ticket's spec | `folder`, `started`, `start` | A change, `openspec/changes/issue-N/`, started with `openspec new change` |
430
+ | The files to write | `files`, `then` | The proposal, the spec deltas, and, for a ticket with the `spec` label, the design and tasks; then the check |
431
+ | Folding it in | `finished`, `finish`, `foldsInto` | `openspec archive`, into `openspec/specs/`; a change already archived counts as folded |
432
+
433
+ Other tools fill these differently: one that keeps a feature's spec in a
434
+ single page marks that page `update` rather than `new`, one with no
435
+ check of its own names a skill on the "Then:" line, and one that is not
436
+ an npm package installs with its own command. `tests/memory-tools.ts`
437
+ holds such a tool, `pagesSpecTool`, and the command and init tests run
438
+ against it too, so nothing outside `src/specs/` assumes OpenSpec.
439
+
440
+ A tool's own process, such as Spec Kit's `/speckit.clarify` or EGM's
441
+ review, is not part of the adapter: a team that wants it sets it as a
442
+ [plugin](plugins.md), as the refiner or a reviewer.
443
+
399
444
  ## Setting a tool up
400
445
 
401
446
  A tool is a code host, a ticket system, a runner, or a coding agent. Each
@@ -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
 
@@ -131,14 +150,16 @@ one column for two states. It prints why. Then do one of these, and run
131
150
 
132
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
@@ -319,9 +340,10 @@ names each file.
319
340
  acts as the one account that owns its token: yours, or an account you
320
341
  create for the team's builds
321
342
  ([Secrets](github/by-hand.md#secrets)).
322
- - **Say who approves.** By default only the repository's owner can approve
323
- a ticket for building or give a session instructions in a comment. List
324
- the others under [`approvers`](configuration.md#approvers), _[Planned](developing.md#what-is-built)_.
343
+ - **Anyone who can write to the repository is obeyed.** A session takes
344
+ instructions from a review or a comment by an account with write
345
+ access, and from nobody else. There is nothing to list: give a
346
+ teammate write access, and their reviews are answered.
325
347
  - **One version for everyone.** The version is pinned in
326
348
  `package-lock.json`. After an update merges, each person pulls and runs
327
349
  `npm ci`. `factory doctor` says so when the installed
@@ -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
@@ -29,8 +29,32 @@ In your repository, with the package
29
29
  factory init
30
30
  ```
31
31
 
32
- It shows what it found, then asks which parts you want. Each is optional
33
- 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.
39
+
40
+ Next it asks which spec tool you use:
41
+
42
+ ```text
43
+ ? Which spec tool do you use?
44
+ ❯ None: each ticket holds its own spec
45
+ OpenSpec: each ticket holds its spec, and each build also keeps it in openspec/specs/
46
+ ```
47
+
48
+ Choose **None** unless you want a folder in your repository that always
49
+ describes what your project does, readable without opening a ticket:
50
+ that is what OpenSpec adds. Choose **OpenSpec** and init installs it for
51
+ you, printing `Installed @fission-ai/openspec.` once it has. Your answer is written to `.claude/factory.yaml` as
52
+ [`specs`](../configuration.md#specs).
53
+
54
+ Init skips the branch-name question when your `.claude/factory.yaml`, or
55
+ a [preset](../presets.md) you follow, sets `code-host.branch-name`, and
56
+ the spec tool question when they set `specs`. Then it asks
57
+ which parts you want. Each is optional and stands alone:
34
58
 
35
59
  | Part | What you get |
36
60
  | ----------------------------------------------- | ------------------------------------------------------------------------------ |
package/docs/glossary.md CHANGED
@@ -33,9 +33,9 @@ written so each item can be checked. Refining a ticket produces it.
33
33
  something and report back. It changes nothing. The factory brings four,
34
34
  and you can add your own.
35
35
 
36
- **Approver.** A person whose comments a session treats as instructions,
37
- and who can approve a ticket for building. By default, the repository's
38
- owner.
36
+ **Approver.** A person whose words a session treats as instructions:
37
+ anyone whose account can write to the repository. Who can approve a
38
+ ticket for building is whoever your board lets move it to Ready.
39
39
 
40
40
  **Automated review.** A review of every pull request by the coding agent,
41
41
  run in CI once the pull request is marked ready. It comments on what it
@@ -118,9 +118,10 @@ your machine or in the cloud.
118
118
  for the factory's own. You call one by typing its name as a slash command,
119
119
  such as `/factory-refine 12`.
120
120
 
121
- **Spec.** A written statement of what a change must do. For most tickets
122
- that is the acceptance criteria. With OpenSpec turned on, a change your
123
- users will see also gets its behavior recorded in the repository.
121
+ **Spec.** A written statement of what a change must do. A change your
122
+ users will see gets a Spec section of "When this, then that" lines in
123
+ its ticket; every other ticket has acceptance criteria. With OpenSpec
124
+ turned on, the Spec is also kept in the repository.
124
125
 
125
126
  **Ticket.** One item in the ticket system: a piece of work, with what,
126
127
  why, and when it is done.
@@ -27,9 +27,11 @@ as a code host's billing or what its workflows can see, are in
27
27
  there. A change to those settings is a person's to make.
28
28
  - **One ticket, one repository.** A change that spans repositories is two
29
29
  tickets.
30
- - **It is written for one approver.** `approvers` lets a team list several
31
- people (_[Planned](developing.md#what-is-built)_), but review by teams, required reviewers per folder, and monorepos
32
- with several owners are not designed.
30
+ - **Review by teams is your code host's to enforce.** A session obeys
31
+ anyone who can write to the repository. Required reviewers for a
32
+ folder, and a number of approvals before a merge, are rules you set on
33
+ the code host, and the factory's pull requests are held by them like
34
+ any other.
33
35
  - **The order of the workflow is fixed.** A [plugin](plugins.md) of
34
36
  yours can replace how a ticket is refined, how a ticket with one of your
35
37
  labels is built, how a test is proved able to fail, which agents review
@@ -127,8 +129,9 @@ as a code host's billing or what its workflows can see, are in
127
129
  - **It amplifies the checks it is given.** A repository with weak tests gets
128
130
  confident, wrong pull requests faster.
129
131
  - **Ticket text, review comments, and changelogs are read by sessions.**
130
- Only an approver's comments are treated as instructions, and that rests on
131
- one account's login.
132
+ Only an approver's words are treated as instructions, and that rests on
133
+ who your code host says can write to the repository. Give write access
134
+ as carefully as you would give a session its orders.
132
135
  - **An update delivers instructions that run with your tokens.** Read update
133
136
  pull requests as carefully as code.
134
137
  - **It sits on tools that change.** Several parts work around how today's
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: