@davidbyoung/software-factory 0.1.7 → 0.1.9
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 +126 -38
- package/dist/cli.mjs +75 -9
- package/dist/code-host/github-setup.mjs +2 -2
- package/dist/code-host/github.mjs +4 -0
- package/dist/code-host/types.d.mts +2 -0
- package/dist/columns-suggest.d.mts +0 -1
- package/dist/columns-suggest.mjs +2 -8
- package/dist/commands.d.mts +2 -0
- package/dist/commands.mjs +22 -11
- package/dist/config.d.mts +12 -0
- package/dist/config.mjs +62 -11
- package/dist/doctor.d.mts +9 -1
- package/dist/doctor.mjs +209 -20
- package/dist/explain.d.mts +5 -0
- package/dist/explain.mjs +29 -0
- package/dist/init.d.mts +2 -0
- package/dist/init.mjs +143 -13
- package/dist/lib/color.d.mts +11 -0
- package/dist/lib/color.mjs +15 -0
- package/dist/npmrc.d.mts +29 -0
- package/dist/npmrc.mjs +98 -0
- package/dist/preset-commands.d.mts +2 -2
- package/dist/preset-commands.mjs +20 -24
- package/dist/preset.d.mts +4 -0
- package/dist/preset.mjs +13 -2
- package/dist/runner/github-actions.mjs +47 -10
- package/dist/runner/types.d.mts +13 -0
- package/dist/setup.d.mts +6 -1
- 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 +14 -1
- package/dist/sync.mjs +83 -7
- package/dist/ticket-fields.d.mts +84 -0
- package/dist/ticket-fields.mjs +374 -0
- package/dist/ticket.mjs +8 -7
- 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/cli.md +44 -10
- package/docs/configuration.md +78 -25
- package/docs/design.md +10 -0
- package/docs/developing.md +49 -18
- package/docs/existing-repo.md +137 -8
- package/docs/github/by-hand.md +4 -0
- package/docs/github/reference.md +5 -0
- package/docs/github/setup.md +146 -8
- package/docs/limitations.md +0 -3
- package/docs/presets.md +5 -9
- package/docs/quick-start.md +3 -3
- package/docs/skills.md +3 -1
- package/docs/updating.md +3 -3
- package/package.json +4 -2
- package/settings.schema.json +68 -11
- package/skills/factory-deps/SKILL.md +4 -0
package/dist/tools.d.mts
CHANGED
|
@@ -49,7 +49,7 @@ export declare function secretSteps(r: Registry, c: SetupContext): {
|
|
|
49
49
|
}[];
|
|
50
50
|
/** The same context for other parts. */
|
|
51
51
|
export declare const withParts: (c: SetupContext, parts: Iterable<Part>) => {
|
|
52
|
-
parts: Set<"board" | "review" | "cloud" | "
|
|
52
|
+
parts: Set<"board" | "review" | "cloud" | "from-board" | "auto-merge" | "signing">;
|
|
53
53
|
repository: string;
|
|
54
54
|
root: string;
|
|
55
55
|
chosen: Chosen;
|
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
|
+
can't be told from here, 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
|
|
|
@@ -183,13 +217,13 @@ runner or a linter: each runs what your settings list under
|
|
|
183
217
|
[`specs`](configuration.md#specs), with bash, from the repository's root.
|
|
184
218
|
You can run them too.
|
|
185
219
|
|
|
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 default-branch` | Prints the name of your repository's default branch, which nothing in the factory assumes is `main`
|
|
220
|
+
| Command | What it does |
|
|
221
|
+
| ------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
222
|
+
| `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 |
|
|
223
|
+
| `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 |
|
|
224
|
+
| `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.` |
|
|
225
|
+
| `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` |
|
|
226
|
+
| `factory default-branch` | Prints the name of your repository's default branch, which nothing in the factory assumes is `main` |
|
|
193
227
|
|
|
194
228
|
`factory default-branch` asks, in turn, the event of the workflow run it
|
|
195
229
|
is in, `origin/HEAD` in your checkout, and the code host, whose answer it
|
package/docs/configuration.md
CHANGED
|
@@ -115,8 +115,8 @@ factory config check
|
|
|
115
115
|
factory sync
|
|
116
116
|
```
|
|
117
117
|
|
|
118
|
-
`factory config check` prints
|
|
119
|
-
the setting when it is not. `factory sync` then rewrites the lock and the
|
|
118
|
+
`factory config check` prints `✓ The settings are valid.` when the file
|
|
119
|
+
is valid, and names the setting when it is not. `factory sync` then rewrites the lock and the
|
|
120
120
|
copied files that depend on what you changed, and lists each file it
|
|
121
121
|
wrote. Every change needs it, one under `plugins` included, as
|
|
122
122
|
[How the file works](#how-the-file-works) says.
|
|
@@ -283,41 +283,94 @@ It doesn't read your board: `factory board check` does.
|
|
|
283
283
|
|
|
284
284
|
#### `tickets.fields`
|
|
285
285
|
|
|
286
|
-
|
|
287
|
-
|
|
288
|
-
|
|
289
|
-
|
|
290
|
-
|
|
291
|
-
|
|
292
|
-
|
|
293
|
-
- **Cost:** roughly what refining and building the ticket has cost so far.
|
|
294
|
-
|
|
295
|
-
`factory init` adds these three fields to your board, so most repositories
|
|
296
|
-
write nothing here. Write this block only when your board already has a
|
|
297
|
-
field you want used instead, or to stop the board sync filling one in:
|
|
286
|
+
The factory fills in fields of its own in two places: on your board,
|
|
287
|
+
to show what is happening to a ticket, and on the ticket itself, to hold
|
|
288
|
+
the result of refining it. This block maps each of these factory fields
|
|
289
|
+
to the field of yours that holds it: a board field, or a ticket field
|
|
290
|
+
set on the ticket itself. `factory init` sets up both the board fields
|
|
291
|
+
and the ticket fields, so most repositories write nothing here by
|
|
292
|
+
hand.
|
|
298
293
|
|
|
299
294
|
```yaml
|
|
300
295
|
tickets:
|
|
301
296
|
board: 7
|
|
302
297
|
fields:
|
|
298
|
+
# Factory fields on the board
|
|
303
299
|
session: Agent # fill in your existing "Agent" field instead
|
|
304
300
|
cost: none # never fill in a cost
|
|
301
|
+
# Factory fields on the ticket
|
|
302
|
+
decisions: none
|
|
303
|
+
spec: Acceptance criteria
|
|
304
|
+
acceptance-criteria: Acceptance criteria
|
|
305
|
+
for-the-builder: Design notes
|
|
305
306
|
```
|
|
306
307
|
|
|
307
|
-
|
|
308
|
-
|
|
309
|
-
|
|
310
|
-
|
|
311
|
-
-
|
|
312
|
-
|
|
313
|
-
|
|
308
|
+
**On the board,** besides moving a ticket between columns, the
|
|
309
|
+
[board sync](workflow.md#the-board) fills in three factory fields so you
|
|
310
|
+
can see at a glance what is happening to a ticket:
|
|
311
|
+
|
|
312
|
+
- **`session`:** which session is working on the ticket, or "Waiting on
|
|
313
|
+
you".
|
|
314
|
+
- **`runs-in`:** whether that session is on someone's machine or in the
|
|
315
|
+
cloud.
|
|
316
|
+
- **`cost`:** roughly what refining and building the ticket has cost so
|
|
317
|
+
far.
|
|
318
|
+
|
|
319
|
+
`factory init` adds board fields called Session, Runs in, and Cost. Name
|
|
320
|
+
a board field here only when your board already has one you want used
|
|
321
|
+
instead, or write `none` to stop the board sync filling one in.
|
|
322
|
+
|
|
323
|
+
- **These three need [`board`](#tickets).**
|
|
324
|
+
- **A board field you name must exist,** holding the right kind of
|
|
325
|
+
value: text for `session`, a single select with the options Local and
|
|
326
|
+
Actions for `runs-in`, and a number for `cost`. If it doesn't, the
|
|
327
|
+
board sync stops and says which field is wrong.
|
|
328
|
+
- **When you name nothing,** the board sync looks for board fields
|
|
329
|
+
called Session, Runs in, and Cost, fills in those it finds, and skips
|
|
330
|
+
the rest with a note.
|
|
314
331
|
- **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`.
|
|
332
|
+
called Cost that holds text, the board sync stops rather than write
|
|
333
|
+
over it, and asks you to name another field or write `cost: none`.
|
|
317
334
|
- **The column itself is the board's own Status field,** which has to be
|
|
318
335
|
a single select with an option for each column in
|
|
319
336
|
[`tickets.columns`](#ticketscolumns).
|
|
320
337
|
|
|
338
|
+
**On the ticket,** refining a ticket writes four factory fields into its
|
|
339
|
+
description, each under its own heading. Each can go instead in a ticket
|
|
340
|
+
field that holds text, which on GitHub is an issue field: see
|
|
341
|
+
[Your tickets already have fields](existing-repo.md#your-tickets-already-have-fields),
|
|
342
|
+
which also says why a board field can't hold one.
|
|
343
|
+
|
|
344
|
+
| Key | What the factory field holds |
|
|
345
|
+
| --------------------- | ---------------------------------------------------------------------- |
|
|
346
|
+
| `decisions` | Decisions: the questions refinement settled, and what was chosen |
|
|
347
|
+
| `spec` | Spec: what a change your users will notice must do, line by line |
|
|
348
|
+
| `acceptance-criteria` | Acceptance criteria: what must be true for any other ticket to be done |
|
|
349
|
+
| `for-the-builder` | For the builder: how to build it, as a design and a list of tasks |
|
|
350
|
+
|
|
351
|
+
`factory init` asks your coding agent to suggest the ticket fields, and
|
|
352
|
+
you confirm them.
|
|
353
|
+
|
|
354
|
+
- **`none` keeps the factory field in the description,** and so does
|
|
355
|
+
leaving its key out. Unlike the board's three, a factory field never
|
|
356
|
+
goes in a ticket field just because the names match.
|
|
357
|
+
- **A ticket field is named as GitHub shows it,** capitals included.
|
|
358
|
+
- **These keys don't need a board,** since the ticket field belongs to
|
|
359
|
+
the ticket.
|
|
360
|
+
- **The ticket field must exist and hold text.** One that doesn't, such
|
|
361
|
+
as a single select, fails the checks [`factory doctor`](cli.md#setting-up)
|
|
362
|
+
and init print, and refining a ticket stops, naming it, and writes
|
|
363
|
+
nothing.
|
|
364
|
+
- **Two factory fields can't name the same ticket field,** except `spec`
|
|
365
|
+
and `acceptance-criteria`, since a ticket has only one of them.
|
|
366
|
+
`factory config check` stops on any other pair.
|
|
367
|
+
- **A heading of your own,** such as one
|
|
368
|
+
[a refiner of your own](plugins.md#refiner) writes, can go in a ticket
|
|
369
|
+
field too: write it in lowercase, with hyphens for spaces, so
|
|
370
|
+
`## Proposed docs` is `proposed-docs`.
|
|
371
|
+
- **Changing a line** affects tickets refined afterwards. A ticket
|
|
372
|
+
refined before keeps its factory fields where they were written.
|
|
373
|
+
|
|
321
374
|
### `code-host`
|
|
322
375
|
|
|
323
376
|
Where your repository and its pull requests live. Only `github` is built,
|
|
@@ -558,8 +611,8 @@ There is no default. Without a gate, `factory gate` fails with
|
|
|
558
611
|
`commands.gate is not set`, and a build stops there, because an empty gate
|
|
559
612
|
would pass every change. `factory init` lists it under "Left to do".
|
|
560
613
|
|
|
561
|
-
When a command fails, `factory gate` prints
|
|
562
|
-
command, and runs none after it. The session fixes the cause and runs the
|
|
614
|
+
When a command fails, `factory gate` prints `✗ The gate failed on:` and
|
|
615
|
+
the command, and runs none after it. The session fixes the cause and runs the
|
|
563
616
|
gate again.
|
|
564
617
|
|
|
565
618
|
**Check your gate yourself** before a session relies on it: run
|
package/docs/design.md
CHANGED
|
@@ -101,6 +101,16 @@ name ever had to mean different states for different kinds of ticket,
|
|
|
101
101
|
an optional `columns-by-type` setting would hold only those exceptions,
|
|
102
102
|
and every settings file written before it would read the same.
|
|
103
103
|
|
|
104
|
+
Refinement writes each factory field into a ticket field of yours, or
|
|
105
|
+
into the description, by the ticket field's name, with no setting for
|
|
106
|
+
each kind of ticket. A ticket whose kind can't hold the ticket field
|
|
107
|
+
keeps that factory field in its description.
|
|
108
|
+
[_Planned_](developing.md#what-is-built): on Jira, where a kind of
|
|
109
|
+
ticket can leave a field out, a factory field could name a list of
|
|
110
|
+
ticket fields, `spec: [Acceptance criteria, AC]`, and go in the first
|
|
111
|
+
the ticket can hold, as a state does with columns. A `fields-by-type`
|
|
112
|
+
setting would hold only the exceptions, if one were ever needed.
|
|
113
|
+
|
|
104
114
|
## Small problems go on one checklist
|
|
105
115
|
|
|
106
116
|
A session that notices a small problem adds a line to one follow-ups
|
package/docs/developing.md
CHANGED
|
@@ -54,6 +54,7 @@ marked working below exist only in these docs.
|
|
|
54
54
|
| `factory board --dry-run` | Working |
|
|
55
55
|
| Your own column names on a board | Working |
|
|
56
56
|
| `init` suggesting a board's columns through the coding agent | Working |
|
|
57
|
+
| Refinement's factory fields in your ticket fields, suggested by `init` | Working |
|
|
57
58
|
| A UI reviewer for any website | Working |
|
|
58
59
|
| Built-in measurements for any website | Working |
|
|
59
60
|
| A design skill for any website | Working |
|
|
@@ -249,18 +250,25 @@ whole or not at all, and `factory ticket supports GROUP` prints `yes` or
|
|
|
249
250
|
`no`. A skill asks before it relies on one; a command that needs a group
|
|
250
251
|
its adapter lacks exits non-zero, names the group, and posts nothing.
|
|
251
252
|
|
|
252
|
-
| Group | In `Tickets` | Operations
|
|
253
|
-
| --------------- | -------------- |
|
|
254
|
-
| `board` | `board` | Read every card and the board's fields; list a board's columns, in the board's order; add a ticket to the board; set its fields
|
|
255
|
-
| `blockers` | `blockers` | List what a ticket waits on; record that it waits on another; remove that
|
|
256
|
-
| `label-history` | `labelHistory` | Whether a label was ever removed from a ticket, which is how the factory knows the owner took `spec` off
|
|
257
|
-
| `attachments` | `attachments` | Comment with images attached, or write a body with them
|
|
253
|
+
| Group | In `Tickets` | Operations |
|
|
254
|
+
| --------------- | -------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
255
|
+
| `board` | `board` | Read every card and the board's fields; list a board's columns, in the board's order; add a ticket to the board; set its fields |
|
|
256
|
+
| `blockers` | `blockers` | List what a ticket waits on; record that it waits on another; remove that |
|
|
257
|
+
| `label-history` | `labelHistory` | Whether a label was ever removed from a ticket, which is how the factory knows the owner took `spec` off |
|
|
258
|
+
| `attachments` | `attachments` | Comment with images attached, or write a body with them |
|
|
259
|
+
| `fields` | `fields` | List the ticket fields that hold text, with their descriptions; say whether a ticket can hold one, and how much; read a ticket's field values; set or clear them |
|
|
258
260
|
|
|
259
261
|
The GitHub adapter has every group, except that `attachments` needs the
|
|
260
262
|
GitHub CLI, so an adapter built without it has none. With
|
|
261
263
|
no board, state lives in the ticket's comments. With no blockers, the build
|
|
262
264
|
order is prose in the ticket and nothing enforces it.
|
|
263
265
|
|
|
266
|
+
The GitHub adapter's `fields` are issue fields, which it reads and
|
|
267
|
+
writes with the `repo` scope. With no fields group, every factory field
|
|
268
|
+
of a refined ticket stays in its description. `factory ticket view` and
|
|
269
|
+
`edit` join and split a ticket's document above the interface, so no
|
|
270
|
+
skill or agent knows whether a ticket has fields.
|
|
271
|
+
|
|
264
272
|
**The transport is a parameter.** The GitHub adapter, `src/code-host/`, and
|
|
265
273
|
`src/runner/` take one function for a REST call, one for a GraphQL query,
|
|
266
274
|
and one for an answer in plain text, such as a job's log
|
|
@@ -400,7 +408,7 @@ when the two differ. Every member of a setup is optional.
|
|
|
400
408
|
|
|
401
409
|
| Member | What it gives | Used by |
|
|
402
410
|
| ------------- | --------------------------------------------------------------------------------------------------------------------------------------- | -------- |
|
|
403
|
-
| `found` | Its row under "Found", when it says more than the tool's name, such as
|
|
411
|
+
| `found` | Its row under "Found", when it says more than the tool's name, such as where it was found | `init` |
|
|
404
412
|
| `steps` | A value to write under the tool's block of the settings, or a secret: which parts read it, how to get it, and how to check a pasted one | `init` |
|
|
405
413
|
| `checks` | Its own lines in `doctor`: that it is reachable, signed in, or configured, each failure with its fix in the tool's words | `doctor` |
|
|
406
414
|
| `leftovers` | What removing the factory leaves outside the repository, such as its secrets | `remove` |
|
|
@@ -425,9 +433,12 @@ A coding agent also answers one question for `init`: given a prompt and
|
|
|
425
433
|
the shape of the answer as a JSON schema, it runs once, with no tools and
|
|
426
434
|
none of the repository's settings or hooks, and returns the answer or
|
|
427
435
|
the reason it has none. Claude Code runs `claude -p` on its smallest
|
|
428
|
-
model, from an empty folder. The
|
|
429
|
-
what `init` prints live in `src/columns-suggest.mts
|
|
430
|
-
agent and no ticket system, so a
|
|
436
|
+
model, from an empty folder. The prompts, the checks on the answers, and
|
|
437
|
+
what `init` prints live in `src/columns-suggest.mts` and
|
|
438
|
+
`src/ticket-fields.mts`, which name no agent and no ticket system, so a
|
|
439
|
+
second agent adds only its `answer`. `factory init` stops before its
|
|
440
|
+
first question when the coding agent's command isn't installed, by the
|
|
441
|
+
agent's `installed` method.
|
|
431
442
|
|
|
432
443
|
The tests show a tool that the factory does not ship going through all
|
|
433
444
|
three commands: `tests/fake-tools.ts` has a ticket system with a site
|
|
@@ -436,14 +447,14 @@ one file.
|
|
|
436
447
|
|
|
437
448
|
## Checking a change
|
|
438
449
|
|
|
439
|
-
| Check | What it proves
|
|
440
|
-
| ---------------------- |
|
|
441
|
-
| The tool's unit tests | Each command does what it says. A new test is seen failing before it is trusted
|
|
442
|
-
| `factory sync --check` | The copies match the source
|
|
443
|
-
| Pack and install | CI packs the folder, installs it into an empty scratch repository, and runs `sync`, `config check`, and one read-only command there. It works outside its host
|
|
444
|
-
| `factory-trace` | A change to a rule did not make some kind of change heavier, lighter, or ambiguous
|
|
445
|
-
| Fork safety | No
|
|
446
|
-
| One throwaway ticket | After each stage, one small ticket goes through refine, build, and review for real. Nothing else tests the prose
|
|
450
|
+
| Check | What it proves |
|
|
451
|
+
| ---------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
452
|
+
| The tool's unit tests | Each command does what it says, with coverage at or above the floors in `vitest.config.ts`. A new test is seen failing before it is trusted |
|
|
453
|
+
| `factory sync --check` | The copies match the source |
|
|
454
|
+
| Pack and install | CI packs the folder, installs it into an empty scratch repository, and runs `sync`, `config check`, and one read-only command there. It works outside its host |
|
|
455
|
+
| `factory-trace` | A change to a rule did not make some kind of change heavier, lighter, or ambiguous |
|
|
456
|
+
| Fork safety | No `pull_request_target` or `workflow_run` job it runs or ships checks out a pull request's code, which would run a fork's code with secrets (`tests/fork-safety.test.ts`) |
|
|
457
|
+
| One throwaway ticket | After each stage, one small ticket goes through refine, build, and review for real. Nothing else tests the prose |
|
|
447
458
|
|
|
448
459
|
The skills are instructions, and instructions cannot be unit tested. The
|
|
449
460
|
last row is the only real proof that a change to one still works.
|
|
@@ -539,3 +550,23 @@ this repository's own reviewer, reads a changed page as that person.
|
|
|
539
550
|
"Without one", and reads on its own: not a pronoun or a clipped phrase,
|
|
540
551
|
such as "It" or "Left out", that makes sense only once a cell is read
|
|
541
552
|
into it.
|
|
553
|
+
|
|
554
|
+
### A command's output
|
|
555
|
+
|
|
556
|
+
A person reads it in a terminal, often while doing something else.
|
|
557
|
+
|
|
558
|
+
- **Precise and short.** A label and a value, or a mark and a few words,
|
|
559
|
+
not a sentence explaining them. What a mark or a state word means is
|
|
560
|
+
said once, in `docs/cli.md`.
|
|
561
|
+
- **A block is headed by the setting it shows,** such as
|
|
562
|
+
[`tickets.fields`](configuration.md#ticketsfields), so the reader knows
|
|
563
|
+
what to edit.
|
|
564
|
+
- **The marks mean one thing everywhere:** ✓ works, ✗ needs fixing,
|
|
565
|
+
? worth a look, - off on purpose.
|
|
566
|
+
- **A fault sits on the line it is about,** with the fix after it.
|
|
567
|
+
- **Success prints one line.** Silence reads as nothing happened.
|
|
568
|
+
- **A command is named as `factory X`,** as the docs write it.
|
|
569
|
+
- **Piped output is the same text,** without color. Lines a skill reads
|
|
570
|
+
keep their format.
|
|
571
|
+
- **Another tool's output passes through unchanged.** The factory adds
|
|
572
|
+
its own line after it, never rewrites it.
|
package/docs/existing-repo.md
CHANGED
|
@@ -125,11 +125,11 @@ Checks
|
|
|
125
125
|
```
|
|
126
126
|
|
|
127
127
|
**Init stops, and changes nothing, when it can't get an answer:** when
|
|
128
|
-
Claude Code isn't
|
|
129
|
-
|
|
130
|
-
|
|
128
|
+
Claude Code isn't signed in, or when its answer can't be used, such as
|
|
129
|
+
one column for two states. It prints why. Then do one of these, and run
|
|
130
|
+
`factory init` again:
|
|
131
131
|
|
|
132
|
-
-
|
|
132
|
+
- sign in to Claude Code, by running `claude` once;
|
|
133
133
|
- write a `columns` block like the one above in `.claude/factory.yaml`
|
|
134
134
|
yourself, with your own columns, as
|
|
135
135
|
[`tickets.columns`](configuration.md#ticketscolumns) describes: init
|
|
@@ -150,8 +150,8 @@ What else to expect on a board you already use:
|
|
|
150
150
|
- **The factory never renames or deletes your columns,** and only adds the
|
|
151
151
|
ones you agree to.
|
|
152
152
|
- **It adds three fields to your board,** Session, Runs in, and Cost, and
|
|
153
|
-
overwrites them on every sync, so don't type into them. Your own
|
|
154
|
-
are never touched. [`tickets.fields`](configuration.md#ticketsfields)
|
|
153
|
+
overwrites them on every sync, so don't type into them. Your own board
|
|
154
|
+
fields are never touched. [`tickets.fields`](configuration.md#ticketsfields)
|
|
155
155
|
says what each holds.
|
|
156
156
|
- **Your board's own automations**, such as moving a closed ticket to
|
|
157
157
|
Done, have not been tested alongside the factory. Turn them off if
|
|
@@ -159,8 +159,137 @@ What else to expect on a board you already use:
|
|
|
159
159
|
|
|
160
160
|
To see what the factory will do with your board at any time, run
|
|
161
161
|
`factory board check`. It lists each state's column, as the table above
|
|
162
|
-
does, and
|
|
163
|
-
the board lacks.
|
|
162
|
+
does, and each field the sync fills in, and marks a problem with ✗ on its
|
|
163
|
+
row, such as a column your settings name that the board lacks.
|
|
164
|
+
|
|
165
|
+
## Your tickets already have fields
|
|
166
|
+
|
|
167
|
+
If your tickets have text fields of their own, such as an "Acceptance
|
|
168
|
+
criteria" field your team fills in by hand, the factory can write what
|
|
169
|
+
it settles when it refines a ticket into those fields instead of the
|
|
170
|
+
ticket's description. At the end, refining a ticket fills in your
|
|
171
|
+
fields, and the description holds your text and whatever has no field.
|
|
172
|
+
If your tickets have no such field, skip this section: nothing changes.
|
|
173
|
+
|
|
174
|
+
[Refining a ticket](skills.md#factory-refine), with `/factory-refine N`,
|
|
175
|
+
writes four parts after your own text, each under its own heading. These
|
|
176
|
+
are the factory's fields for a refined ticket:
|
|
177
|
+
|
|
178
|
+
| Factory field | What it holds |
|
|
179
|
+
| ------------------- | ---------------------------------------------------------- |
|
|
180
|
+
| Decisions | The questions refinement settled, and what was chosen |
|
|
181
|
+
| Spec | What a change your users will notice must do, line by line |
|
|
182
|
+
| Acceptance criteria | What must be true for any other ticket to be done |
|
|
183
|
+
| For the builder | How to build it, as a design and a list of tasks |
|
|
184
|
+
|
|
185
|
+
A ticket has a Spec or Acceptance criteria, never both: refinement writes
|
|
186
|
+
a Spec when the change is one
|
|
187
|
+
[your users will notice](workflow.md#a-change-your-users-will-see), and
|
|
188
|
+
Acceptance criteria otherwise.
|
|
189
|
+
|
|
190
|
+
This page calls a field of yours that is set on the ticket itself a
|
|
191
|
+
ticket field. On GitHub, a ticket field is an
|
|
192
|
+
[issue field](https://docs.github.com/en/issues/tracking-your-work-with-issues/using-issues/managing-issue-fields-in-your-organization),
|
|
193
|
+
shown beside the issue, which you create in your account's or
|
|
194
|
+
organization's settings, under Issue fields. A field you add to your
|
|
195
|
+
board, which shows as a column of the board's table, can't hold a
|
|
196
|
+
factory field: GitHub limits it to 1,024 characters, and a Spec is often
|
|
197
|
+
several thousand. Create the issue field before you run init, since init
|
|
198
|
+
offers only ticket fields that exist.
|
|
199
|
+
|
|
200
|
+
When you run `factory init`, step 2 of the
|
|
201
|
+
[quick start](quick-start.md#2-set-it-up), it finds your text ticket
|
|
202
|
+
fields and asks your coding agent, Claude Code, which of them should hold
|
|
203
|
+
each factory field. If you already ran init, run it again after creating
|
|
204
|
+
the field: it keeps what your settings say and asks only about ticket
|
|
205
|
+
fields. As for your board's columns, this is one short request with no
|
|
206
|
+
tools, and it sends your ticket fields' names and descriptions and
|
|
207
|
+
nothing else. Init shows you the answer before it writes anything. On a
|
|
208
|
+
repository whose tickets have the text fields Acceptance criteria,
|
|
209
|
+
Design notes, and Customer, init shows:
|
|
210
|
+
|
|
211
|
+
```text
|
|
212
|
+
acme/shop's tickets have the text fields Acceptance criteria, Design notes, and Customer.
|
|
213
|
+
Asking Claude Code which of them should hold each of the factory's fields...
|
|
214
|
+
|
|
215
|
+
Factory field Ticket field
|
|
216
|
+
Decisions the description
|
|
217
|
+
Spec Acceptance criteria
|
|
218
|
+
Acceptance criteria Acceptance criteria
|
|
219
|
+
For the builder Design notes
|
|
220
|
+
|
|
221
|
+
Your own text stays in the description.
|
|
222
|
+
GitHub Issues shows a field's text as typed, without Markdown formatting.
|
|
223
|
+
|
|
224
|
+
? Use these ticket fields? (Use arrow keys)
|
|
225
|
+
❯ Yes
|
|
226
|
+
Change some
|
|
227
|
+
No: keep everything in the description
|
|
228
|
+
```
|
|
229
|
+
|
|
230
|
+
A factory field goes in the description unless a ticket field clearly
|
|
231
|
+
fits it, so here Decisions stays there, and nothing goes in Customer.
|
|
232
|
+
Spec and Acceptance criteria share a ticket field here, since a ticket
|
|
233
|
+
has only one of them.
|
|
234
|
+
|
|
235
|
+
- **Yes** saves the table in your settings, `.claude/factory.yaml`, one
|
|
236
|
+
line for each factory field, with `none` for one that stays in the
|
|
237
|
+
description:
|
|
238
|
+
|
|
239
|
+
```yaml
|
|
240
|
+
tickets:
|
|
241
|
+
fields:
|
|
242
|
+
decisions: none
|
|
243
|
+
spec: Acceptance criteria
|
|
244
|
+
acceptance-criteria: Acceptance criteria
|
|
245
|
+
for-the-builder: Design notes
|
|
246
|
+
```
|
|
247
|
+
|
|
248
|
+
- **Change some** lets you pick the factory fields to change from a list,
|
|
249
|
+
then, for each, pick one of your ticket fields or the description.
|
|
250
|
+
- **No** saves all four as `none`, so everything stays in the
|
|
251
|
+
description, as it would with no ticket fields.
|
|
252
|
+
|
|
253
|
+
When your tickets have no text field, init doesn't ask, writes nothing
|
|
254
|
+
about them, and prints no check for them.
|
|
255
|
+
|
|
256
|
+
**It worked when** the checks init prints last include:
|
|
257
|
+
|
|
258
|
+
```text
|
|
259
|
+
Checks
|
|
260
|
+
✓ acme/shop's tickets have every field the settings name
|
|
261
|
+
```
|
|
262
|
+
|
|
263
|
+
Then refine a ticket and open it on GitHub. Here, its Spec or
|
|
264
|
+
Acceptance criteria shows in the Acceptance criteria field beside the
|
|
265
|
+
issue, and its design and tasks in Design notes. GitHub shows a field's
|
|
266
|
+
text as typed, so a list reads as written, with its numbers and dashes,
|
|
267
|
+
and a table shows its `|` marks. You and your coding agent see no other
|
|
268
|
+
difference: the agent still reads the whole ticket, fields included.
|
|
269
|
+
|
|
270
|
+
**Init stops, and changes nothing, when it can't use the answer,** such
|
|
271
|
+
as when Claude Code isn't signed in, or names a ticket field your tickets
|
|
272
|
+
don't have. It prints why. Then do one of these, and run `factory init`
|
|
273
|
+
again:
|
|
274
|
+
|
|
275
|
+
- if it says Claude Code isn't signed in, sign in by running `claude`
|
|
276
|
+
once;
|
|
277
|
+
- otherwise, write the four lines above yourself, as
|
|
278
|
+
[`tickets.fields`](configuration.md#ticketsfields) describes: init
|
|
279
|
+
then doesn't ask.
|
|
280
|
+
|
|
281
|
+
**Running init again** keeps what the four lines say, and doesn't ask
|
|
282
|
+
again. To be asked again, for example after creating another ticket
|
|
283
|
+
field, delete the four lines and run `factory init`.
|
|
284
|
+
|
|
285
|
+
**If you change a line later,** a ticket refined before keeps its
|
|
286
|
+
factory fields where they were written, and a ticket field it no longer
|
|
287
|
+
uses keeps its text until you clear it. For a ticket not yet built, run
|
|
288
|
+
`/factory-refine N` again: it rewrites the four parts where the settings
|
|
289
|
+
now say, and leaves your own text as it is.
|
|
290
|
+
|
|
291
|
+
A heading of your own, such as one your own refiner writes, can go in a
|
|
292
|
+
ticket field too: see [`tickets.fields`](configuration.md#ticketsfields).
|
|
164
293
|
|
|
165
294
|
## You already have agent instructions, settings, or CI workflows
|
|
166
295
|
|
package/docs/github/by-hand.md
CHANGED
|
@@ -312,6 +312,10 @@ gh secret set FACTORY_BUILD_TOKEN # builds in the cloud, with no board
|
|
|
312
312
|
gh secret set FACTORY_AUTOMERGE_TOKEN # pull requests that merge themselves
|
|
313
313
|
```
|
|
314
314
|
|
|
315
|
+
For a private npm registry, each variable your `.npmrc` reads is stored
|
|
316
|
+
twice, with `gh secret set NAME` and `gh secret set NAME --app dependabot`:
|
|
317
|
+
[Private npm packages](setup.md#private-npm-packages).
|
|
318
|
+
|
|
315
319
|
Two optional settings:
|
|
316
320
|
|
|
317
321
|
- **Paying by the token instead of a subscription:** store an API key from
|
package/docs/github/reference.md
CHANGED
|
@@ -40,6 +40,7 @@ The "Removing it" column says what `factory remove` does with each.
|
|
|
40
40
|
| ------------------------------------------------------------------------------------- | --------------------------------------------------------------- | ----------------------------------------------------------------------------------------- |
|
|
41
41
|
| Secrets and variables named `FACTORY_...` | You create them | Delete them |
|
|
42
42
|
| `CLAUDE_CODE_OAUTH_TOKEN` | You create it, for the automated review and builds in the cloud | Delete it, unless another workflow uses it |
|
|
43
|
+
| The secrets your `.npmrc` reads, such as `NPM_TOKEN`, for Actions and for Dependabot | `init`, when you paste them | Leave them if your own CI uses them; otherwise delete both copies |
|
|
43
44
|
| Labels: `merge: automatic`, `merge: manual`, `verdict: override`, `follow-up`, `spec` | First use | Delete them. Deleting a label removes it from every ticket |
|
|
44
45
|
| A CI check that the factory's files are in step | Setup | Goes with `factory-check.yml` |
|
|
45
46
|
| A "Review verdict" required check, as the ruleset "Software factory" | `init`, when the review is on; or you, in your branch rules | Delete the ruleset, under Settings, Rules, **first**, or pull requests wait on it forever |
|
|
@@ -253,6 +254,10 @@ factory.
|
|
|
253
254
|
session step's timeout.
|
|
254
255
|
- GitHub's shortest schedule is every five minutes, and scheduled runs can
|
|
255
256
|
start late.
|
|
257
|
+
- **A pull request from a fork can't install a private package.** GitHub
|
|
258
|
+
gives a fork's pull request no secrets, so the factory check fails at
|
|
259
|
+
`npm ci` on one, in a repository with
|
|
260
|
+
[private npm packages](setup.md#private-npm-packages).
|
|
256
261
|
- Public repositories are not billed for Actions minutes.
|
|
257
262
|
- GitHub switches off scheduled workflows in a public repository with no
|
|
258
263
|
activity for 60 days.
|