@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.
- package/README.md +2 -0
- package/dist/agent/claude-code.mjs +15 -21
- package/dist/board.d.mts +20 -3
- package/dist/board.mjs +124 -38
- package/dist/cli.mjs +84 -9
- package/dist/code-host/github-setup.mjs +2 -2
- package/dist/code-host/github.d.mts +1 -1
- package/dist/code-host/github.mjs +29 -2
- package/dist/code-host/types.d.mts +16 -1
- package/dist/code-host/types.mjs +8 -0
- package/dist/columns-suggest.d.mts +25 -6
- package/dist/columns-suggest.mjs +119 -29
- package/dist/commands.d.mts +5 -2
- package/dist/commands.mjs +37 -12
- package/dist/config.d.mts +25 -3
- package/dist/config.mjs +159 -33
- package/dist/doctor.d.mts +6 -1
- package/dist/doctor.mjs +78 -18
- package/dist/explain.d.mts +5 -0
- package/dist/explain.mjs +36 -1
- package/dist/init.d.mts +10 -0
- package/dist/init.mjs +133 -31
- package/dist/lib/color.d.mts +11 -0
- package/dist/lib/color.mjs +15 -0
- package/dist/lib/gh.d.mts +6 -0
- package/dist/lib/gh.mjs +11 -1
- package/dist/lib/listed.d.mts +3 -2
- package/dist/lib/listed.mjs +5 -4
- package/dist/poller.d.mts +1 -1
- package/dist/poller.mjs +9 -6
- package/dist/pr.mjs +9 -1
- package/dist/preset-commands.d.mts +2 -0
- package/dist/preset-commands.mjs +18 -12
- package/dist/preset.mjs +3 -2
- package/dist/setup.d.mts +3 -0
- package/dist/site.d.mts +3 -0
- package/dist/site.mjs +8 -1
- package/dist/status.d.mts +5 -2
- package/dist/status.mjs +13 -22
- package/dist/sync.d.mts +7 -1
- package/dist/sync.mjs +17 -5
- package/dist/ticket-fields.d.mts +84 -0
- package/dist/ticket-fields.mjs +374 -0
- package/dist/ticket.d.mts +3 -0
- package/dist/ticket.mjs +35 -8
- package/dist/tickets/github-setup.mjs +1 -1
- package/dist/tickets/github.mjs +69 -0
- package/dist/tickets/index.d.mts +8 -1
- package/dist/tickets/index.mjs +67 -7
- package/dist/tickets/types.d.mts +27 -1
- package/dist/tickets/types.mjs +4 -0
- package/dist/tools.d.mts +1 -1
- package/docs/builds.md +26 -13
- package/docs/cli.md +73 -36
- package/docs/configuration.md +264 -59
- package/docs/design.md +10 -0
- package/docs/developing.md +49 -18
- package/docs/existing-repo.md +184 -34
- package/docs/github/by-hand.md +13 -1
- package/docs/github/setup.md +14 -2
- package/docs/presets.md +15 -3
- package/docs/quick-start.md +3 -3
- package/docs/skills.md +3 -1
- package/docs/updating.md +132 -5
- package/docs/workflow.md +1 -1
- package/package.json +4 -2
- package/settings.schema.json +82 -20
- package/skills/factory-build/SKILL.md +39 -7
- 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.
|
|
40
|
-
|
|
41
|
-
|
|
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
|
|
119
|
-
| `factory ticket
|
|
120
|
-
| `factory ticket
|
|
121
|
-
| `factory ticket
|
|
122
|
-
| `factory ticket
|
|
123
|
-
| `factory ticket
|
|
124
|
-
| `factory ticket
|
|
125
|
-
| `factory ticket
|
|
126
|
-
| `factory ticket
|
|
127
|
-
| `factory ticket
|
|
128
|
-
| `factory ticket
|
|
129
|
-
| `factory ticket
|
|
130
|
-
| `factory ticket
|
|
131
|
-
| `factory
|
|
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
|
|
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
|
|
192
|
-
| `factory
|
|
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
|
package/docs/configuration.md
CHANGED
|
@@ -34,9 +34,10 @@ The [glossary](glossary.md) has the rest.
|
|
|
34
34
|
|
|
35
35
|
## How the file works
|
|
36
36
|
|
|
37
|
-
- **
|
|
38
|
-
file has [`version`](#version)
|
|
39
|
-
|
|
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
|
|
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.
|
|
203
|
-
board's columns
|
|
204
|
-
|
|
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
|
-
|
|
240
|
+
When init creates your board, or adds columns to one, it gives them the
|
|
241
|
+
factory's own names:
|
|
226
242
|
|
|
227
|
-
|
|
|
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
|
-
|
|
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.
|
|
243
|
-
|
|
244
|
-
|
|
245
|
-
|
|
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
|
|
260
|
-
|
|
261
|
-
|
|
262
|
-
|
|
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
|
|
269
|
-
|
|
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
|
-
|
|
303
|
+
Such as:
|
|
283
304
|
|
|
284
|
-
|
|
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
|
-
|
|
287
|
-
|
|
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
|
-
|
|
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
|
-
|
|
296
|
-
|
|
297
|
-
|
|
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
|
-
|
|
308
|
-
|
|
309
|
-
|
|
310
|
-
|
|
311
|
-
-
|
|
312
|
-
|
|
313
|
-
|
|
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
|
|
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
|
|
324
|
-
|
|
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:
|
|
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
|
|
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:
|