@davidbyoung/software-factory 0.1.9 → 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/dist/board.mjs +1 -3
- package/dist/cli.mjs +9 -0
- 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 -5
- package/dist/columns-suggest.mjs +117 -21
- package/dist/commands.d.mts +3 -2
- package/dist/commands.mjs +16 -2
- package/dist/config.d.mts +16 -3
- package/dist/config.mjs +102 -22
- package/dist/doctor.mjs +1 -2
- package/dist/explain.mjs +7 -1
- package/dist/init.d.mts +8 -0
- package/dist/init.mjs +83 -22
- 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/ticket.d.mts +3 -0
- package/dist/ticket.mjs +27 -1
- package/docs/builds.md +26 -13
- package/docs/cli.md +30 -27
- package/docs/configuration.md +187 -35
- package/docs/existing-repo.md +47 -26
- package/docs/github/by-hand.md +13 -1
- package/docs/github/setup.md +9 -2
- package/docs/presets.md +15 -3
- package/docs/updating.md +129 -2
- package/docs/workflow.md +1 -1
- package/package.json +1 -1
- package/settings.schema.json +14 -9
- package/skills/factory-build/SKILL.md +39 -7
- package/skills/factory-deps/SKILL.md +6 -4
package/docs/existing-repo.md
CHANGED
|
@@ -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.
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
|
|
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
|
|
62
|
-
one you choose has
|
|
63
|
-
|
|
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
|
|
78
|
-
ready
|
|
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.
|
|
93
|
-
|
|
94
|
-
|
|
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
|
|
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
|
|
115
|
-
Todo, In Progress, Code review, and Done columns
|
|
116
|
-
Done are used, since their names match. The
|
|
117
|
-
in Todo and Code review: nothing moves or
|
|
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
|
|
135
|
-
[`tickets.columns`](configuration.md#ticketscolumns) describes
|
|
136
|
-
|
|
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.
|
|
140
|
-
|
|
141
|
-
|
|
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
|
package/docs/github/by-hand.md
CHANGED
|
@@ -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
|
package/docs/github/setup.md
CHANGED
|
@@ -29,8 +29,15 @@ In your repository, with the package
|
|
|
29
29
|
factory init
|
|
30
30
|
```
|
|
31
31
|
|
|
32
|
-
It shows what it found, then asks
|
|
33
|
-
|
|
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:
|
|
34
41
|
|
|
35
42
|
| Part | What you get |
|
|
36
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),
|
|
22
|
-
|
|
23
|
-
|
|
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:
|
package/docs/updating.md
CHANGED
|
@@ -3,8 +3,12 @@
|
|
|
3
3
|
**When a new version is released, a pull request appears in your
|
|
4
4
|
repository. You read it and merge it.** That is all you have to do.
|
|
5
5
|
|
|
6
|
-
|
|
7
|
-
settings file: [Moving to settings version
|
|
6
|
+
Three releases ask more of you, because they need lines in your
|
|
7
|
+
settings file that it doesn't have: [Moving to settings version
|
|
8
|
+
2](#moving-to-settings-version-2) and [Naming build
|
|
9
|
+
branches](#naming-build-branches), for every repository, and [Naming
|
|
10
|
+
every column](#naming-every-column), for a repository whose settings
|
|
11
|
+
have a [`tickets.board`](configuration.md#tickets).
|
|
8
12
|
|
|
9
13
|
## What happens
|
|
10
14
|
|
|
@@ -149,6 +153,10 @@ After:
|
|
|
149
153
|
version: 2
|
|
150
154
|
repository: your-name/your-repo
|
|
151
155
|
|
|
156
|
+
code-host:
|
|
157
|
+
type: github
|
|
158
|
+
branch-name: "{ticket}"
|
|
159
|
+
|
|
152
160
|
specs: openspec
|
|
153
161
|
|
|
154
162
|
commands:
|
|
@@ -207,6 +215,123 @@ needed, and the rest are worth a look while the file is open.
|
|
|
207
215
|
branch is not `main` needs no setting: `factory sync` writes the
|
|
208
216
|
branch's name where the workflows need it.
|
|
209
217
|
|
|
218
|
+
## Naming every column
|
|
219
|
+
|
|
220
|
+
From this release, a repository with a board names a column for all six
|
|
221
|
+
states in [`tickets.columns`](configuration.md#ticketscolumns). Before
|
|
222
|
+
it, a state you left out used the factory's own column name, so a
|
|
223
|
+
repository set up earlier has no `columns` block, or one with only the
|
|
224
|
+
states whose column has another name. A repository with no
|
|
225
|
+
`tickets.board` needs nothing.
|
|
226
|
+
|
|
227
|
+
Until the block names all six, every command that reads the settings
|
|
228
|
+
stops with one of these, the second naming the states you left out:
|
|
229
|
+
|
|
230
|
+
```text
|
|
231
|
+
.claude/factory.yaml: tickets.columns: is required with tickets.board: run factory init to choose which of board 3's columns shows each state
|
|
232
|
+
.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
|
|
233
|
+
```
|
|
234
|
+
|
|
235
|
+
So on the factory's update pull request, `factory-deps`, which opens
|
|
236
|
+
and finishes it ([What happens](#what-happens)), cannot run
|
|
237
|
+
`factory sync`. It stops and opens an issue in your repository quoting
|
|
238
|
+
the line. Check out the pull request's branch, and from your
|
|
239
|
+
repository's root run:
|
|
240
|
+
|
|
241
|
+
```bash
|
|
242
|
+
gh pr checkout 123 # the update pull request's number
|
|
243
|
+
factory init
|
|
244
|
+
```
|
|
245
|
+
|
|
246
|
+
Init keeps everything your settings already say and adds only the
|
|
247
|
+
missing states. It shows the whole block it saves, the states you had
|
|
248
|
+
and the ones it added. A state whose column of the factory's name is on
|
|
249
|
+
your board, which is the column the factory was reading for it, is added
|
|
250
|
+
with no question:
|
|
251
|
+
|
|
252
|
+
```text
|
|
253
|
+
Your settings give no column to building or done.
|
|
254
|
+
Board 3 has a column of the factory's name for each:
|
|
255
|
+
|
|
256
|
+
State Column
|
|
257
|
+
backlog Todo
|
|
258
|
+
refining none, shows in Todo
|
|
259
|
+
ready none
|
|
260
|
+
building In Progress
|
|
261
|
+
review Code review
|
|
262
|
+
done Done
|
|
263
|
+
```
|
|
264
|
+
|
|
265
|
+
For a state whose column your board doesn't have, init asks which column
|
|
266
|
+
shows it, offering your columns, no column, or a new column with the
|
|
267
|
+
factory's name. When it needs Claude Code to suggest columns, it asks
|
|
268
|
+
as [You already have a board](existing-repo.md#you-already-have-a-board)
|
|
269
|
+
shows.
|
|
270
|
+
|
|
271
|
+
You can add the lines by hand instead. For each state your block leaves
|
|
272
|
+
out, the factory used the name in the table in
|
|
273
|
+
[`tickets.columns`](configuration.md#ticketscolumns), so write that name
|
|
274
|
+
to keep things as they were. If your board has no column of that name,
|
|
275
|
+
write one of your columns, or `none`.
|
|
276
|
+
|
|
277
|
+
Then run `factory sync`, which rewrites the factory's files for the new
|
|
278
|
+
version, commit what changed, `.claude/factory.yaml` included, and push.
|
|
279
|
+
The pull request's checks run again, and you close the issue
|
|
280
|
+
`factory-deps` opened.
|
|
281
|
+
|
|
282
|
+
**It worked when** `factory config check` prints
|
|
283
|
+
`✓ The settings are valid.`, and `factory sync --check` passes.
|
|
284
|
+
|
|
285
|
+
## Naming build branches
|
|
286
|
+
|
|
287
|
+
From this release, every repository says how a build names its branch,
|
|
288
|
+
in [`code-host.branch-name`](configuration.md#code-host). Before it, a
|
|
289
|
+
build named its branch `issue-` with the ticket's number and a few words
|
|
290
|
+
of its title, such as `issue-47-terminal-color`, and no setting said so.
|
|
291
|
+
So a repository set up earlier has no `branch-name`, or writes
|
|
292
|
+
`code-host: github` on one line, and every command that reads the
|
|
293
|
+
settings stops with `code-host.branch-name: is required`.
|
|
294
|
+
|
|
295
|
+
There is no pattern that keeps the old names, since they held words a
|
|
296
|
+
session chose. The pattern you choose names new builds only: branches
|
|
297
|
+
already pushed keep their names, and their pull requests carry on as
|
|
298
|
+
before.
|
|
299
|
+
|
|
300
|
+
So on the factory's update pull request, `factory-deps` cannot run
|
|
301
|
+
`factory sync`. It stops and opens an issue in your repository quoting
|
|
302
|
+
the line. Check out the pull request's branch, and from your
|
|
303
|
+
repository's root run:
|
|
304
|
+
|
|
305
|
+
```bash
|
|
306
|
+
gh pr checkout 123 # the update pull request's number
|
|
307
|
+
factory init
|
|
308
|
+
```
|
|
309
|
+
|
|
310
|
+
Init keeps everything your settings already say, so it asks again only
|
|
311
|
+
what they lack: how a build names its branch, offering `{ticket}`. Press
|
|
312
|
+
Enter to keep it, or type your team's pattern, such as
|
|
313
|
+
`feature/{user}/{ticket}`; [`code-host`](configuration.md#code-host)
|
|
314
|
+
lists what a pattern can hold. If the update also needs [Naming every
|
|
315
|
+
column](#naming-every-column), the same run fills in both. When a
|
|
316
|
+
[preset](presets.md) you follow sets the pattern, init asks nothing.
|
|
317
|
+
|
|
318
|
+
You can add the lines by hand instead:
|
|
319
|
+
|
|
320
|
+
```yaml
|
|
321
|
+
code-host:
|
|
322
|
+
type: github
|
|
323
|
+
branch-name: "{ticket}"
|
|
324
|
+
```
|
|
325
|
+
|
|
326
|
+
Keep the quotes: without them, YAML reads `{ticket}` as a map rather
|
|
327
|
+
than as text. Then run `factory sync`, commit what changed,
|
|
328
|
+
`.claude/factory.yaml` included, and push. The pull request's checks run
|
|
329
|
+
again, and you close the issue `factory-deps` opened.
|
|
330
|
+
|
|
331
|
+
**It worked when** `factory config check` prints
|
|
332
|
+
`✓ The settings are valid.`, and `factory ticket branch 12` prints the
|
|
333
|
+
branch a build of ticket 12 would push.
|
|
334
|
+
|
|
210
335
|
## The commands
|
|
211
336
|
|
|
212
337
|
| Command | When |
|
|
@@ -234,6 +359,8 @@ not match `package-lock.json`.
|
|
|
234
359
|
| CI fails with "of the factory's files don't match the settings" | A factory file was edited by hand, or settings changed without a sync | Run `factory sync` and commit the result |
|
|
235
360
|
| `factory doctor` says your installed version is older than the repository's | You pulled an update and have not installed it | Run `npm ci` |
|
|
236
361
|
| A command stops with `version: must be 2` | The update changed the shape of the settings file | [Move the file](#moving-to-settings-version-2) |
|
|
362
|
+
| A command stops with `tickets.columns: is required` or `have no column` | The update needs a column named for every state | [Name every column](#naming-every-column) |
|
|
363
|
+
| A command stops with `code-host.branch-name: is required` | The update needs the pattern a build names its branch by | [Name build branches](#naming-build-branches) |
|
|
237
364
|
| A command stops with `.claude/factory.lock is from an earlier version of the factory` | The update's sync has not run on this checkout | Run `factory sync` and commit the result |
|
|
238
365
|
| A command stops with `.claude/factory.yaml changed since the last sync` | The settings changed without a sync | Run `factory sync` and commit the result |
|
|
239
366
|
| The update pull request conflicts with your default branch | Something else changed the same file | `factory-deps` resolves it on its next run, or close it and update by hand |
|
package/docs/workflow.md
CHANGED
|
@@ -25,7 +25,7 @@ A ticket is always in one of six states. They are fixed: you cannot add one
|
|
|
25
25
|
or reorder them. Your board shows them as columns, and which column shows
|
|
26
26
|
which state is your repository's choice
|
|
27
27
|
([`tickets.columns`](configuration.md#ticketscolumns)). The table gives the
|
|
28
|
-
|
|
28
|
+
names `factory init` gives the columns it adds.
|
|
29
29
|
|
|
30
30
|
A state with no column of its own shows in the column of the nearest earlier
|
|
31
31
|
state that has one, and a ticket is shown in the `ready` column only when it
|
package/package.json
CHANGED
package/settings.schema.json
CHANGED
|
@@ -36,7 +36,7 @@
|
|
|
36
36
|
]
|
|
37
37
|
},
|
|
38
38
|
"code-host": {
|
|
39
|
-
"description": "Where pull requests are.",
|
|
39
|
+
"description": "Where pull requests are, and what a build names its branch.",
|
|
40
40
|
"anyOf": [
|
|
41
41
|
{
|
|
42
42
|
"$ref": "#/definitions/code-host/properties/type"
|
|
@@ -114,7 +114,7 @@
|
|
|
114
114
|
},
|
|
115
115
|
"tickets.columns": {
|
|
116
116
|
"type": "object",
|
|
117
|
-
"description": "Which of your board's columns shows each state. Needs a board.",
|
|
117
|
+
"description": "Which of your board's columns shows each state. Needs a board. With a board, all six states are required, here or from a preset.",
|
|
118
118
|
"additionalProperties": false,
|
|
119
119
|
"properties": {
|
|
120
120
|
"backlog": {
|
|
@@ -132,7 +132,7 @@
|
|
|
132
132
|
}
|
|
133
133
|
}
|
|
134
134
|
],
|
|
135
|
-
"description": "The board's column for the backlog state, or a list of its columns.
|
|
135
|
+
"description": "The board's column for the backlog state, or a list of its columns."
|
|
136
136
|
},
|
|
137
137
|
"refining": {
|
|
138
138
|
"oneOf": [
|
|
@@ -149,12 +149,12 @@
|
|
|
149
149
|
}
|
|
150
150
|
}
|
|
151
151
|
],
|
|
152
|
-
"description": "The board's column for the refining state, or a list of its columns.
|
|
152
|
+
"description": "The board's column for the refining state, or a list of its columns. May be none."
|
|
153
153
|
},
|
|
154
154
|
"ready": {
|
|
155
155
|
"type": "string",
|
|
156
156
|
"minLength": 1,
|
|
157
|
-
"description": "The board's column for the ready state.
|
|
157
|
+
"description": "The board's column for the ready state. May be none."
|
|
158
158
|
},
|
|
159
159
|
"building": {
|
|
160
160
|
"oneOf": [
|
|
@@ -171,7 +171,7 @@
|
|
|
171
171
|
}
|
|
172
172
|
}
|
|
173
173
|
],
|
|
174
|
-
"description": "The board's column for the building state, or a list of its columns.
|
|
174
|
+
"description": "The board's column for the building state, or a list of its columns. May be none."
|
|
175
175
|
},
|
|
176
176
|
"review": {
|
|
177
177
|
"oneOf": [
|
|
@@ -188,7 +188,7 @@
|
|
|
188
188
|
}
|
|
189
189
|
}
|
|
190
190
|
],
|
|
191
|
-
"description": "The board's column for the review state, or a list of its columns.
|
|
191
|
+
"description": "The board's column for the review state, or a list of its columns. May be none."
|
|
192
192
|
},
|
|
193
193
|
"done": {
|
|
194
194
|
"oneOf": [
|
|
@@ -205,7 +205,7 @@
|
|
|
205
205
|
}
|
|
206
206
|
}
|
|
207
207
|
],
|
|
208
|
-
"description": "The board's column for the done state, or a list of its columns.
|
|
208
|
+
"description": "The board's column for the done state, or a list of its columns. May be none."
|
|
209
209
|
}
|
|
210
210
|
}
|
|
211
211
|
},
|
|
@@ -260,12 +260,17 @@
|
|
|
260
260
|
},
|
|
261
261
|
"code-host": {
|
|
262
262
|
"type": "object",
|
|
263
|
-
"description": "Where pull requests are.",
|
|
263
|
+
"description": "Where pull requests are, and what a build names its branch. branch-name is required, here or from a preset.",
|
|
264
264
|
"additionalProperties": false,
|
|
265
265
|
"properties": {
|
|
266
266
|
"type": {
|
|
267
267
|
"enum": ["github"],
|
|
268
268
|
"description": "The code host. Default: github."
|
|
269
|
+
},
|
|
270
|
+
"branch-name": {
|
|
271
|
+
"type": "string",
|
|
272
|
+
"minLength": 1,
|
|
273
|
+
"description": "The pattern a build names its branch by: {ticket}, the ticket's number, which it must have, and {user}, the code host account the build runs as. Quote it, as \"{ticket}\" or \"feature/{user}/{ticket}\". No default: factory init asks for it."
|
|
269
274
|
}
|
|
270
275
|
}
|
|
271
276
|
},
|
|
@@ -225,11 +225,40 @@ uncommitted changes onto the new branch, where the issue's commit would sweep
|
|
|
225
225
|
them into its PR, and refuses outright when a changed file differs between
|
|
226
226
|
the branches.
|
|
227
227
|
|
|
228
|
-
Then
|
|
228
|
+
Then name the branch, as `code-host.branch-name` in the settings says,
|
|
229
|
+
and look for it on `origin`:
|
|
229
230
|
|
|
230
231
|
```bash
|
|
231
232
|
git fetch origin
|
|
232
|
-
|
|
233
|
+
npx --no-install factory ticket branch N # prints BRANCH
|
|
234
|
+
git ls-remote --exit-code origin refs/heads/BRANCH
|
|
235
|
+
```
|
|
236
|
+
|
|
237
|
+
Give `ls-remote` the full ref: `--heads origin 12` also matches
|
|
238
|
+
`feature/someone/12`. Exit 2 means `origin` has no such branch: go on.
|
|
239
|
+
Exit 0 means an earlier build's branch is there, and its newest pull
|
|
240
|
+
request decides, from `npx --no-install factory pr for-branch BRANCH`:
|
|
241
|
+
|
|
242
|
+
- **`#M merged`,** and the commit `ls-remote` printed is
|
|
243
|
+
`npx --no-install factory pr view M --field head`: its work is on the
|
|
244
|
+
default branch. Delete it with `git push origin --delete BRANCH`, say
|
|
245
|
+
`Branch BRANCH's pull request #M merged; replacing it.`, and go on.
|
|
246
|
+
- **`#M open`:** stop ("The claim") with
|
|
247
|
+
`Branch BRANCH is already on origin, with open pull request #M. Work it with /factory-address-review M`.
|
|
248
|
+
- **Anything else,** or commits pushed after the merge: stop with
|
|
249
|
+
`Branch BRANCH 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 BRANCH`.
|
|
250
|
+
A build that lost its claim pushed its branch to keep its work, and
|
|
251
|
+
this is how the owner keeps it.
|
|
252
|
+
|
|
253
|
+
No build carries on from an unmerged branch. A local branch of the same
|
|
254
|
+
name stops the build the same way, naming `git branch -D BRANCH` for the
|
|
255
|
+
owner to run once they have looked at its commits, unless its last
|
|
256
|
+
commit is the merged pull request's head: then switch away from it if
|
|
257
|
+
it is checked out, with `git switch --detach origin/DEFAULT`, and
|
|
258
|
+
delete it with the remote one. Then, from the latest default branch:
|
|
259
|
+
|
|
260
|
+
```bash
|
|
261
|
+
git switch -c BRANCH origin/DEFAULT
|
|
233
262
|
```
|
|
234
263
|
|
|
235
264
|
If the branch you left has commits not on `origin/DEFAULT`, name it in the
|
|
@@ -242,12 +271,15 @@ commit. Nothing in it is new; the thinking was done at refinement.
|
|
|
242
271
|
|
|
243
272
|
```bash
|
|
244
273
|
export DO_NOT_TRACK=1
|
|
245
|
-
npx --no-install
|
|
246
|
-
npx --no-install openspec
|
|
274
|
+
npx --no-install factory specs change-name N # prints NAME
|
|
275
|
+
npx --no-install openspec new change NAME
|
|
276
|
+
npx --no-install openspec status --change NAME
|
|
247
277
|
```
|
|
248
278
|
|
|
249
|
-
|
|
250
|
-
|
|
279
|
+
Read NAME once, here, and use it through step 4's archive, whatever
|
|
280
|
+
the branch is called. For each artifact `status` lists, run
|
|
281
|
+
`npx --no-install openspec instructions <artifact> --change NAME` and
|
|
282
|
+
fill it from the issue. An issue without
|
|
251
283
|
the `spec` label fills `proposal.md` and the spec delta only; OpenSpec
|
|
252
284
|
validates and archives a change without `design.md` or `tasks.md`.
|
|
253
285
|
|
|
@@ -336,7 +368,7 @@ Then fold the change into the specs, as the last commit before the pull
|
|
|
336
368
|
request:
|
|
337
369
|
|
|
338
370
|
```bash
|
|
339
|
-
DO_NOT_TRACK=1 npx --no-install openspec archive
|
|
371
|
+
DO_NOT_TRACK=1 npx --no-install openspec archive NAME --yes
|
|
340
372
|
```
|
|
341
373
|
|
|
342
374
|
Then run the spec check, `npx --no-install factory specs check`.
|
|
@@ -146,10 +146,12 @@ npx --no-install factory sync
|
|
|
146
146
|
```
|
|
147
147
|
|
|
148
148
|
When the sync itself fails on the settings after the update, the release
|
|
149
|
-
|
|
150
|
-
|
|
151
|
-
|
|
152
|
-
release
|
|
149
|
+
needs lines the settings don't have, as version 2 and naming every
|
|
150
|
+
column do.
|
|
151
|
+
Stop (step 6), and say the settings are the owner's to change, naming the
|
|
152
|
+
release's section of the factory's `docs/updating.md`, such as "Moving to
|
|
153
|
+
settings version 2" or "Naming every column". Never edit
|
|
154
|
+
`.claude/factory.yaml`.
|
|
153
155
|
When it fails on `.npmrc` instead, refusing a variable a sign-in line
|
|
154
156
|
reads, stop the same way and say the name is the owner's to change:
|
|
155
157
|
renaming it renames the secret and every developer's variable. Never edit
|