@davidbyoung/software-factory 0.1.8 → 0.1.10
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +2 -0
- package/dist/agent/claude-code.mjs +15 -21
- package/dist/board.d.mts +20 -3
- package/dist/board.mjs +124 -38
- package/dist/cli.mjs +84 -9
- package/dist/code-host/github-setup.mjs +2 -2
- package/dist/code-host/github.d.mts +1 -1
- package/dist/code-host/github.mjs +29 -2
- package/dist/code-host/types.d.mts +16 -1
- package/dist/code-host/types.mjs +8 -0
- package/dist/columns-suggest.d.mts +25 -6
- package/dist/columns-suggest.mjs +119 -29
- package/dist/commands.d.mts +5 -2
- package/dist/commands.mjs +37 -12
- package/dist/config.d.mts +25 -3
- package/dist/config.mjs +159 -33
- package/dist/doctor.d.mts +6 -1
- package/dist/doctor.mjs +78 -18
- package/dist/explain.d.mts +5 -0
- package/dist/explain.mjs +36 -1
- package/dist/init.d.mts +10 -0
- package/dist/init.mjs +133 -31
- package/dist/lib/color.d.mts +11 -0
- package/dist/lib/color.mjs +15 -0
- package/dist/lib/gh.d.mts +6 -0
- package/dist/lib/gh.mjs +11 -1
- package/dist/lib/listed.d.mts +3 -2
- package/dist/lib/listed.mjs +5 -4
- package/dist/poller.d.mts +1 -1
- package/dist/poller.mjs +9 -6
- package/dist/pr.mjs +9 -1
- package/dist/preset-commands.d.mts +2 -0
- package/dist/preset-commands.mjs +18 -12
- package/dist/preset.mjs +3 -2
- package/dist/setup.d.mts +3 -0
- package/dist/site.d.mts +3 -0
- package/dist/site.mjs +8 -1
- package/dist/status.d.mts +5 -2
- package/dist/status.mjs +13 -22
- package/dist/sync.d.mts +7 -1
- package/dist/sync.mjs +17 -5
- package/dist/ticket-fields.d.mts +84 -0
- package/dist/ticket-fields.mjs +374 -0
- package/dist/ticket.d.mts +3 -0
- package/dist/ticket.mjs +35 -8
- package/dist/tickets/github-setup.mjs +1 -1
- package/dist/tickets/github.mjs +69 -0
- package/dist/tickets/index.d.mts +8 -1
- package/dist/tickets/index.mjs +67 -7
- package/dist/tickets/types.d.mts +27 -1
- package/dist/tickets/types.mjs +4 -0
- package/dist/tools.d.mts +1 -1
- package/docs/builds.md +26 -13
- package/docs/cli.md +73 -36
- package/docs/configuration.md +264 -59
- package/docs/design.md +10 -0
- package/docs/developing.md +49 -18
- package/docs/existing-repo.md +184 -34
- package/docs/github/by-hand.md +13 -1
- package/docs/github/setup.md +14 -2
- package/docs/presets.md +15 -3
- package/docs/quick-start.md +3 -3
- package/docs/skills.md +3 -1
- package/docs/updating.md +132 -5
- package/docs/workflow.md +1 -1
- package/package.json +4 -2
- package/settings.schema.json +82 -20
- package/skills/factory-build/SKILL.md +39 -7
- package/skills/factory-deps/SKILL.md +6 -4
package/docs/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
|
@@ -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
|
|
|
@@ -125,20 +144,22 @@ Checks
|
|
|
125
144
|
```
|
|
126
145
|
|
|
127
146
|
**Init stops, and changes nothing, when it can't get an answer:** when
|
|
128
|
-
Claude Code isn't
|
|
129
|
-
|
|
130
|
-
|
|
147
|
+
Claude Code isn't signed in, or when its answer can't be used, such as
|
|
148
|
+
one column for two states. It prints why. Then do one of these, and run
|
|
149
|
+
`factory init` again:
|
|
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
|
|
@@ -150,8 +171,8 @@ What else to expect on a board you already use:
|
|
|
150
171
|
- **The factory never renames or deletes your columns,** and only adds the
|
|
151
172
|
ones you agree to.
|
|
152
173
|
- **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)
|
|
174
|
+
overwrites them on every sync, so don't type into them. Your own board
|
|
175
|
+
fields are never touched. [`tickets.fields`](configuration.md#ticketsfields)
|
|
155
176
|
says what each holds.
|
|
156
177
|
- **Your board's own automations**, such as moving a closed ticket to
|
|
157
178
|
Done, have not been tested alongside the factory. Turn them off if
|
|
@@ -159,8 +180,137 @@ What else to expect on a board you already use:
|
|
|
159
180
|
|
|
160
181
|
To see what the factory will do with your board at any time, run
|
|
161
182
|
`factory board check`. It lists each state's column, as the table above
|
|
162
|
-
does, and
|
|
163
|
-
the board lacks.
|
|
183
|
+
does, and each field the sync fills in, and marks a problem with ✗ on its
|
|
184
|
+
row, such as a column your settings name that the board lacks.
|
|
185
|
+
|
|
186
|
+
## Your tickets already have fields
|
|
187
|
+
|
|
188
|
+
If your tickets have text fields of their own, such as an "Acceptance
|
|
189
|
+
criteria" field your team fills in by hand, the factory can write what
|
|
190
|
+
it settles when it refines a ticket into those fields instead of the
|
|
191
|
+
ticket's description. At the end, refining a ticket fills in your
|
|
192
|
+
fields, and the description holds your text and whatever has no field.
|
|
193
|
+
If your tickets have no such field, skip this section: nothing changes.
|
|
194
|
+
|
|
195
|
+
[Refining a ticket](skills.md#factory-refine), with `/factory-refine N`,
|
|
196
|
+
writes four parts after your own text, each under its own heading. These
|
|
197
|
+
are the factory's fields for a refined ticket:
|
|
198
|
+
|
|
199
|
+
| Factory field | What it holds |
|
|
200
|
+
| ------------------- | ---------------------------------------------------------- |
|
|
201
|
+
| Decisions | The questions refinement settled, and what was chosen |
|
|
202
|
+
| Spec | What a change your users will notice must do, line by line |
|
|
203
|
+
| Acceptance criteria | What must be true for any other ticket to be done |
|
|
204
|
+
| For the builder | How to build it, as a design and a list of tasks |
|
|
205
|
+
|
|
206
|
+
A ticket has a Spec or Acceptance criteria, never both: refinement writes
|
|
207
|
+
a Spec when the change is one
|
|
208
|
+
[your users will notice](workflow.md#a-change-your-users-will-see), and
|
|
209
|
+
Acceptance criteria otherwise.
|
|
210
|
+
|
|
211
|
+
This page calls a field of yours that is set on the ticket itself a
|
|
212
|
+
ticket field. On GitHub, a ticket field is an
|
|
213
|
+
[issue field](https://docs.github.com/en/issues/tracking-your-work-with-issues/using-issues/managing-issue-fields-in-your-organization),
|
|
214
|
+
shown beside the issue, which you create in your account's or
|
|
215
|
+
organization's settings, under Issue fields. A field you add to your
|
|
216
|
+
board, which shows as a column of the board's table, can't hold a
|
|
217
|
+
factory field: GitHub limits it to 1,024 characters, and a Spec is often
|
|
218
|
+
several thousand. Create the issue field before you run init, since init
|
|
219
|
+
offers only ticket fields that exist.
|
|
220
|
+
|
|
221
|
+
When you run `factory init`, step 2 of the
|
|
222
|
+
[quick start](quick-start.md#2-set-it-up), it finds your text ticket
|
|
223
|
+
fields and asks your coding agent, Claude Code, which of them should hold
|
|
224
|
+
each factory field. If you already ran init, run it again after creating
|
|
225
|
+
the field: it keeps what your settings say and asks only about ticket
|
|
226
|
+
fields. As for your board's columns, this is one short request with no
|
|
227
|
+
tools, and it sends your ticket fields' names and descriptions and
|
|
228
|
+
nothing else. Init shows you the answer before it writes anything. On a
|
|
229
|
+
repository whose tickets have the text fields Acceptance criteria,
|
|
230
|
+
Design notes, and Customer, init shows:
|
|
231
|
+
|
|
232
|
+
```text
|
|
233
|
+
acme/shop's tickets have the text fields Acceptance criteria, Design notes, and Customer.
|
|
234
|
+
Asking Claude Code which of them should hold each of the factory's fields...
|
|
235
|
+
|
|
236
|
+
Factory field Ticket field
|
|
237
|
+
Decisions the description
|
|
238
|
+
Spec Acceptance criteria
|
|
239
|
+
Acceptance criteria Acceptance criteria
|
|
240
|
+
For the builder Design notes
|
|
241
|
+
|
|
242
|
+
Your own text stays in the description.
|
|
243
|
+
GitHub Issues shows a field's text as typed, without Markdown formatting.
|
|
244
|
+
|
|
245
|
+
? Use these ticket fields? (Use arrow keys)
|
|
246
|
+
❯ Yes
|
|
247
|
+
Change some
|
|
248
|
+
No: keep everything in the description
|
|
249
|
+
```
|
|
250
|
+
|
|
251
|
+
A factory field goes in the description unless a ticket field clearly
|
|
252
|
+
fits it, so here Decisions stays there, and nothing goes in Customer.
|
|
253
|
+
Spec and Acceptance criteria share a ticket field here, since a ticket
|
|
254
|
+
has only one of them.
|
|
255
|
+
|
|
256
|
+
- **Yes** saves the table in your settings, `.claude/factory.yaml`, one
|
|
257
|
+
line for each factory field, with `none` for one that stays in the
|
|
258
|
+
description:
|
|
259
|
+
|
|
260
|
+
```yaml
|
|
261
|
+
tickets:
|
|
262
|
+
fields:
|
|
263
|
+
decisions: none
|
|
264
|
+
spec: Acceptance criteria
|
|
265
|
+
acceptance-criteria: Acceptance criteria
|
|
266
|
+
for-the-builder: Design notes
|
|
267
|
+
```
|
|
268
|
+
|
|
269
|
+
- **Change some** lets you pick the factory fields to change from a list,
|
|
270
|
+
then, for each, pick one of your ticket fields or the description.
|
|
271
|
+
- **No** saves all four as `none`, so everything stays in the
|
|
272
|
+
description, as it would with no ticket fields.
|
|
273
|
+
|
|
274
|
+
When your tickets have no text field, init doesn't ask, writes nothing
|
|
275
|
+
about them, and prints no check for them.
|
|
276
|
+
|
|
277
|
+
**It worked when** the checks init prints last include:
|
|
278
|
+
|
|
279
|
+
```text
|
|
280
|
+
Checks
|
|
281
|
+
✓ acme/shop's tickets have every field the settings name
|
|
282
|
+
```
|
|
283
|
+
|
|
284
|
+
Then refine a ticket and open it on GitHub. Here, its Spec or
|
|
285
|
+
Acceptance criteria shows in the Acceptance criteria field beside the
|
|
286
|
+
issue, and its design and tasks in Design notes. GitHub shows a field's
|
|
287
|
+
text as typed, so a list reads as written, with its numbers and dashes,
|
|
288
|
+
and a table shows its `|` marks. You and your coding agent see no other
|
|
289
|
+
difference: the agent still reads the whole ticket, fields included.
|
|
290
|
+
|
|
291
|
+
**Init stops, and changes nothing, when it can't use the answer,** such
|
|
292
|
+
as when Claude Code isn't signed in, or names a ticket field your tickets
|
|
293
|
+
don't have. It prints why. Then do one of these, and run `factory init`
|
|
294
|
+
again:
|
|
295
|
+
|
|
296
|
+
- if it says Claude Code isn't signed in, sign in by running `claude`
|
|
297
|
+
once;
|
|
298
|
+
- otherwise, write the four lines above yourself, as
|
|
299
|
+
[`tickets.fields`](configuration.md#ticketsfields) describes: init
|
|
300
|
+
then doesn't ask.
|
|
301
|
+
|
|
302
|
+
**Running init again** keeps what the four lines say, and doesn't ask
|
|
303
|
+
again. To be asked again, for example after creating another ticket
|
|
304
|
+
field, delete the four lines and run `factory init`.
|
|
305
|
+
|
|
306
|
+
**If you change a line later,** a ticket refined before keeps its
|
|
307
|
+
factory fields where they were written, and a ticket field it no longer
|
|
308
|
+
uses keeps its text until you clear it. For a ticket not yet built, run
|
|
309
|
+
`/factory-refine N` again: it rewrites the four parts where the settings
|
|
310
|
+
now say, and leaves your own text as it is.
|
|
311
|
+
|
|
312
|
+
A heading of your own, such as one your own refiner writes, can go in a
|
|
313
|
+
ticket field too: see [`tickets.fields`](configuration.md#ticketsfields).
|
|
164
314
|
|
|
165
315
|
## You already have agent instructions, settings, or CI workflows
|
|
166
316
|
|
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
|
@@ -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
|
|
@@ -24,8 +29,15 @@ In your repository, with the package
|
|
|
24
29
|
factory init
|
|
25
30
|
```
|
|
26
31
|
|
|
27
|
-
It shows what it found, then asks
|
|
28
|
-
|
|
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:
|
|
29
41
|
|
|
30
42
|
| Part | What you get |
|
|
31
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/quick-start.md
CHANGED
|
@@ -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
|
|
81
|
-
|
|
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
|
|
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.
|