@davidbyoung/software-factory 0.1.8 → 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.
Files changed (51) hide show
  1. package/README.md +2 -0
  2. package/dist/agent/claude-code.mjs +15 -21
  3. package/dist/board.d.mts +20 -3
  4. package/dist/board.mjs +126 -38
  5. package/dist/cli.mjs +75 -9
  6. package/dist/code-host/github-setup.mjs +2 -2
  7. package/dist/columns-suggest.d.mts +0 -1
  8. package/dist/columns-suggest.mjs +2 -8
  9. package/dist/commands.d.mts +2 -0
  10. package/dist/commands.mjs +22 -11
  11. package/dist/config.d.mts +9 -0
  12. package/dist/config.mjs +57 -11
  13. package/dist/doctor.d.mts +6 -1
  14. package/dist/doctor.mjs +79 -18
  15. package/dist/explain.d.mts +5 -0
  16. package/dist/explain.mjs +29 -0
  17. package/dist/init.d.mts +2 -0
  18. package/dist/init.mjs +50 -9
  19. package/dist/lib/color.d.mts +11 -0
  20. package/dist/lib/color.mjs +15 -0
  21. package/dist/preset-commands.d.mts +2 -0
  22. package/dist/preset-commands.mjs +18 -12
  23. package/dist/preset.mjs +3 -2
  24. package/dist/setup.d.mts +3 -0
  25. package/dist/site.d.mts +3 -0
  26. package/dist/site.mjs +8 -1
  27. package/dist/status.d.mts +5 -2
  28. package/dist/status.mjs +13 -22
  29. package/dist/sync.d.mts +7 -1
  30. package/dist/sync.mjs +17 -5
  31. package/dist/ticket-fields.d.mts +84 -0
  32. package/dist/ticket-fields.mjs +374 -0
  33. package/dist/ticket.mjs +8 -7
  34. package/dist/tickets/github-setup.mjs +1 -1
  35. package/dist/tickets/github.mjs +69 -0
  36. package/dist/tickets/index.d.mts +8 -1
  37. package/dist/tickets/index.mjs +67 -7
  38. package/dist/tickets/types.d.mts +27 -1
  39. package/dist/tickets/types.mjs +4 -0
  40. package/dist/tools.d.mts +1 -1
  41. package/docs/cli.md +44 -10
  42. package/docs/configuration.md +78 -25
  43. package/docs/design.md +10 -0
  44. package/docs/developing.md +49 -18
  45. package/docs/existing-repo.md +137 -8
  46. package/docs/github/setup.md +5 -0
  47. package/docs/quick-start.md +3 -3
  48. package/docs/skills.md +3 -1
  49. package/docs/updating.md +3 -3
  50. package/package.json +4 -2
  51. package/settings.schema.json +68 -11
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" | "auto-merge" | "from-board" | "signing">;
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. `doctor` exits 1 when a check fails. GitHub never lets a
40
- secret be read back, so `doctor` checks only that each secret your parts
41
- read is set.
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 `gate failed on:` and the command. Exits 0 when every command passes, and 1 at the first that fails or when no gate is set |
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. Prints `specs are off` when `specs` is `none` |
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
@@ -115,8 +115,8 @@ factory config check
115
115
  factory sync
116
116
  ```
117
117
 
118
- `factory config check` prints nothing when the file is valid, and names
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
- Besides moving a ticket between columns, the board sync fills in three
287
- fields so you can see at a glance what is happening to it:
288
-
289
- - **Session:** which session is working on the ticket, or "Waiting on
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.
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
- - **A field you name must exist,** holding the right kind of value: text
308
- for Session, a single select with the options Local and Actions for Runs
309
- in, and a number for Cost. If it doesn't, the board sync stops and says
310
- which field is wrong.
311
- - **When you name nothing,** the board sync looks for fields called
312
- Session, Runs in, and Cost, fills in those it finds, and skips the rest
313
- with a note.
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 over
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 `gate failed on:` and the
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
@@ -54,6 +54,7 @@ marked working below exist only in these docs.
54
54
  | `factory board --dry-run` | Working |
55
55
  | Your own column names on a board | Working |
56
56
  | `init` suggesting a board's columns through the coding agent | Working |
57
+ | Refinement's factory fields in your ticket fields, suggested by `init` | Working |
57
58
  | A UI reviewer for any website | Working |
58
59
  | Built-in measurements for any website | Working |
59
60
  | A design skill for any website | Working |
@@ -249,18 +250,25 @@ whole or not at all, and `factory ticket supports GROUP` prints `yes` or
249
250
  `no`. A skill asks before it relies on one; a command that needs a group
250
251
  its adapter lacks exits non-zero, names the group, and posts nothing.
251
252
 
252
- | Group | In `Tickets` | Operations |
253
- | --------------- | -------------- | ------------------------------------------------------------------------------------------------------------------------------- |
254
- | `board` | `board` | Read every card and the board's fields; list a board's columns, in the board's order; add a ticket to the board; set its fields |
255
- | `blockers` | `blockers` | List what a ticket waits on; record that it waits on another; remove that |
256
- | `label-history` | `labelHistory` | Whether a label was ever removed from a ticket, which is how the factory knows the owner took `spec` off |
257
- | `attachments` | `attachments` | Comment with images attached, or write a body with them |
253
+ | Group | In `Tickets` | Operations |
254
+ | --------------- | -------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
255
+ | `board` | `board` | Read every card and the board's fields; list a board's columns, in the board's order; add a ticket to the board; set its fields |
256
+ | `blockers` | `blockers` | List what a ticket waits on; record that it waits on another; remove that |
257
+ | `label-history` | `labelHistory` | Whether a label was ever removed from a ticket, which is how the factory knows the owner took `spec` off |
258
+ | `attachments` | `attachments` | Comment with images attached, or write a body with them |
259
+ | `fields` | `fields` | List the ticket fields that hold text, with their descriptions; say whether a ticket can hold one, and how much; read a ticket's field values; set or clear them |
258
260
 
259
261
  The GitHub adapter has every group, except that `attachments` needs the
260
262
  GitHub CLI, so an adapter built without it has none. With
261
263
  no board, state lives in the ticket's comments. With no blockers, the build
262
264
  order is prose in the ticket and nothing enforces it.
263
265
 
266
+ The GitHub adapter's `fields` are issue fields, which it reads and
267
+ writes with the `repo` scope. With no fields group, every factory field
268
+ of a refined ticket stays in its description. `factory ticket view` and
269
+ `edit` join and split a ticket's document above the interface, so no
270
+ skill or agent knows whether a ticket has fields.
271
+
264
272
  **The transport is a parameter.** The GitHub adapter, `src/code-host/`, and
265
273
  `src/runner/` take one function for a REST call, one for a GraphQL query,
266
274
  and one for an answer in plain text, such as a job's log
@@ -400,7 +408,7 @@ when the two differ. Every member of a setup is optional.
400
408
 
401
409
  | Member | What it gives | Used by |
402
410
  | ------------- | --------------------------------------------------------------------------------------------------------------------------------------- | -------- |
403
- | `found` | Its row under "Found", when it says more than the tool's name, such as that a command is not installed | `init` |
411
+ | `found` | Its row under "Found", when it says more than the tool's name, such as where it was found | `init` |
404
412
  | `steps` | A value to write under the tool's block of the settings, or a secret: which parts read it, how to get it, and how to check a pasted one | `init` |
405
413
  | `checks` | Its own lines in `doctor`: that it is reachable, signed in, or configured, each failure with its fix in the tool's words | `doctor` |
406
414
  | `leftovers` | What removing the factory leaves outside the repository, such as its secrets | `remove` |
@@ -425,9 +433,12 @@ A coding agent also answers one question for `init`: given a prompt and
425
433
  the shape of the answer as a JSON schema, it runs once, with no tools and
426
434
  none of the repository's settings or hooks, and returns the answer or
427
435
  the reason it has none. Claude Code runs `claude -p` on its smallest
428
- model, from an empty folder. The prompt, the checks on the answer, and
429
- what `init` prints live in `src/columns-suggest.mts`, which names no
430
- agent and no ticket system, so a second agent adds only its `answer`.
436
+ model, from an empty folder. The prompts, the checks on the answers, and
437
+ what `init` prints live in `src/columns-suggest.mts` and
438
+ `src/ticket-fields.mts`, which name no agent and no ticket system, so a
439
+ second agent adds only its `answer`. `factory init` stops before its
440
+ first question when the coding agent's command isn't installed, by the
441
+ agent's `installed` method.
431
442
 
432
443
  The tests show a tool that the factory does not ship going through all
433
444
  three commands: `tests/fake-tools.ts` has a ticket system with a site
@@ -436,14 +447,14 @@ one file.
436
447
 
437
448
  ## Checking a change
438
449
 
439
- | Check | What it proves |
440
- | ---------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
441
- | The tool's unit tests | Each command does what it says. A new test is seen failing before it is trusted |
442
- | `factory sync --check` | The copies match the source |
443
- | Pack and install | CI packs the folder, installs it into an empty scratch repository, and runs `sync`, `config check`, and one read-only command there. It works outside its host |
444
- | `factory-trace` | A change to a rule did not make some kind of change heavier, lighter, or ambiguous |
445
- | Fork safety | No workflow it runs or ships could run a fork's code with a secret or write access (`tests/fork-safety.test.ts`). This repository is public |
446
- | One throwaway ticket | After each stage, one small ticket goes through refine, build, and review for real. Nothing else tests the prose |
450
+ | Check | What it proves |
451
+ | ---------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
452
+ | The tool's unit tests | Each command does what it says, with coverage at or above the floors in `vitest.config.ts`. A new test is seen failing before it is trusted |
453
+ | `factory sync --check` | The copies match the source |
454
+ | Pack and install | CI packs the folder, installs it into an empty scratch repository, and runs `sync`, `config check`, and one read-only command there. It works outside its host |
455
+ | `factory-trace` | A change to a rule did not make some kind of change heavier, lighter, or ambiguous |
456
+ | Fork safety | No `pull_request_target` or `workflow_run` job it runs or ships checks out a pull request's code, which would run a fork's code with secrets (`tests/fork-safety.test.ts`) |
457
+ | One throwaway ticket | After each stage, one small ticket goes through refine, build, and review for real. Nothing else tests the prose |
447
458
 
448
459
  The skills are instructions, and instructions cannot be unit tested. The
449
460
  last row is the only real proof that a change to one still works.
@@ -539,3 +550,23 @@ this repository's own reviewer, reads a changed page as that person.
539
550
  "Without one", and reads on its own: not a pronoun or a clipped phrase,
540
551
  such as "It" or "Left out", that makes sense only once a cell is read
541
552
  into it.
553
+
554
+ ### A command's output
555
+
556
+ A person reads it in a terminal, often while doing something else.
557
+
558
+ - **Precise and short.** A label and a value, or a mark and a few words,
559
+ not a sentence explaining them. What a mark or a state word means is
560
+ said once, in `docs/cli.md`.
561
+ - **A block is headed by the setting it shows,** such as
562
+ [`tickets.fields`](configuration.md#ticketsfields), so the reader knows
563
+ what to edit.
564
+ - **The marks mean one thing everywhere:** ✓ works, ✗ needs fixing,
565
+ ? worth a look, - off on purpose.
566
+ - **A fault sits on the line it is about,** with the fix after it.
567
+ - **Success prints one line.** Silence reads as nothing happened.
568
+ - **A command is named as `factory X`,** as the docs write it.
569
+ - **Piped output is the same text,** without color. Lines a skill reads
570
+ keep their format.
571
+ - **Another tool's output passes through unchanged.** The factory adds
572
+ its own line after it, never rewrites it.
@@ -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 installed or isn't signed in, or when its answer can't
129
- be used, such as one column for two states. It prints why. Then do one of
130
- these, and run `factory init` again:
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
- - install Claude Code and sign in, by running `claude` once;
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 fields
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 ends with any problem, such as a column your settings name that
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
 
@@ -15,6 +15,11 @@ it leaves for you to do.
15
15
  | Claude Code, signed in | `claude --version` | [Install it](https://claude.com/claude-code), run `claude`, and sign in |
16
16
  | Node 22.18 or later | `node --version` | [nodejs.org](https://nodejs.org) |
17
17
 
18
+ `factory init` stops before its first question when Claude Code isn't
19
+ installed, and changes nothing. It needs Claude Code to set up the
20
+ coding agent's token, and to suggest your board's columns and your
21
+ tickets' fields.
22
+
18
23
  ## Run `factory init`
19
24
 
20
25
  In your repository, with the package
@@ -12,7 +12,7 @@ A word you do not know is in the [glossary](glossary.md).
12
12
 
13
13
  - A repository on a supported code host, cloned on your machine, with the
14
14
  code host's command-line tool signed in.
15
- - A supported coding agent, signed in.
15
+ - A supported coding agent, signed in. `factory init` stops without one.
16
16
  - Node 22.18 or later.
17
17
 
18
18
  [What you need](github/setup.md#what-you-need) names the supported tools
@@ -77,8 +77,8 @@ A repository with no tests yet lists the checks it does have, such as a
77
77
  formatter or a compile, and adds its tests to the gate when there are
78
78
  some.
79
79
 
80
- **It worked when** `factory gate` runs each command and ends without a
81
- line that starts `gate failed on`.
80
+ **It worked when** `factory gate` runs each command and ends with
81
+ `✓ Every gate command passed.`
82
82
 
83
83
  ## 3. Merge the setup
84
84
 
package/docs/skills.md CHANGED
@@ -79,7 +79,9 @@ spec when [`specs`](configuration.md#specs) is on.
79
79
  **What it writes.**
80
80
 
81
81
  - The ticket's body: your text first, untouched, then Decisions and
82
- Acceptance criteria, or a Spec when the change is visible and not small.
82
+ Acceptance criteria, or a Spec when the change is visible and not
83
+ small. Each of these goes in a ticket field of yours instead, when
84
+ [`tickets.fields`](configuration.md#ticketsfields) names one.
83
85
  - Marker comments that move the ticket to "refining" and show it waiting on
84
86
  you.
85
87
  - A blocked-by relationship for each ticket that must be built first.
package/docs/updating.md CHANGED
@@ -91,8 +91,8 @@ and its checks fail until the file is moved. On the pull request's branch:
91
91
  4. Run `factory config check`, then `factory sync`, and commit what
92
92
  changed.
93
93
 
94
- **It worked when** `factory config check` prints nothing, and
95
- `factory sync --check` passes.
94
+ **It worked when** `factory config check` prints
95
+ `✓ The settings are valid.`, and `factory sync --check` passes.
96
96
 
97
97
  ### Each key that moved or changed shape
98
98
 
@@ -231,7 +231,7 @@ not match `package-lock.json`.
231
231
 
232
232
  | What you see | What happened | What to do |
233
233
  | ------------------------------------------------------------------------------------- | --------------------------------------------------------------------- | -------------------------------------------------------------------------- |
234
- | CI fails with "the factory's files are out of sync" | A factory file was edited by hand, or settings changed without a sync | Run `factory sync` and commit the result |
234
+ | 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
235
  | `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
236
  | 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) |
237
237
  | 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 |
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@davidbyoung/software-factory",
3
- "version": "0.1.8",
3
+ "version": "0.1.9",
4
4
  "description": "Refines, builds, and reviews tickets with Claude Code sessions, from a board to a merged pull request.",
5
5
  "license": "MIT",
6
6
  "repository": {
@@ -30,10 +30,11 @@
30
30
  ],
31
31
  "scripts": {
32
32
  "test": "vitest run",
33
+ "coverage": "vitest run --coverage",
33
34
  "typecheck": "tsc --noEmit",
34
35
  "format": "prettier --write .",
35
36
  "format:check": "prettier --check .",
36
- "check": "prettier --check . && tsc --noEmit && npm run -s spec:validate && node bin/factory.js sync --check && node bin/factory.js config check && vitest run",
37
+ "check": "prettier --check . && tsc --noEmit && npm run -s spec:validate && node bin/factory.js sync --check && node bin/factory.js config check && vitest run --coverage",
37
38
  "prepack": "tsc -p tsconfig.build.json",
38
39
  "pack-check": "node tests/pack-check.mts",
39
40
  "site-check": "node --test tests/site-check.mts",
@@ -51,6 +52,7 @@
51
52
  "@types/js-yaml": "^4.0.9",
52
53
  "@types/node": "^22.18.0",
53
54
  "@types/pngjs": "^6.0.5",
55
+ "@vitest/coverage-v8": "^5.1.0",
54
56
  "ajv": "^8.20.0",
55
57
  "playwright": "^1.65.0",
56
58
  "prettier": "^3.10.0",