@davidbyoung/software-factory 0.1.4 → 0.1.5
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 +1 -1
- package/dist/cli.mjs +1 -1
- package/dist/code-host/github-setup.mjs +1 -1
- package/dist/config.d.mts +17 -17
- package/dist/config.mjs +59 -59
- package/dist/explain.d.mts +1 -1
- package/dist/explain.mjs +11 -11
- package/dist/init.mjs +3 -3
- package/dist/lib/refined-check.mjs +1 -1
- package/dist/lib/work-status.d.mts +2 -2
- package/dist/lib/work-status.mjs +4 -4
- package/dist/parts.d.mts +1 -1
- package/dist/parts.mjs +2 -2
- package/dist/review-cost.mjs +1 -1
- package/dist/review-tools.mjs +3 -3
- package/dist/sync.mjs +1 -1
- package/docs/cli.md +6 -6
- package/docs/configuration.md +672 -715
- package/docs/design.md +1 -1
- package/docs/developing.md +12 -7
- package/docs/existing-repo.md +1 -1
- package/docs/github/by-hand.md +4 -4
- package/docs/github/reference.md +2 -2
- package/docs/github/setup.md +2 -2
- package/docs/glossary.md +6 -7
- package/docs/limitations.md +1 -1
- package/docs/plugins.md +22 -21
- package/docs/quick-start.md +1 -1
- package/docs/removing.md +1 -1
- package/docs/skills.md +7 -7
- package/docs/updating.md +8 -7
- package/docs/workflow.md +1 -1
- package/package.json +1 -1
- package/rules.md +1 -1
- package/settings.schema.json +8 -8
- package/skills/factory-build/SKILL.md +1 -1
- package/skills/factory-design/SKILL.md +1 -1
- package/skills/factory-refine/SKILL.md +2 -2
- package/workflows/factory-claude-review.yml +1 -1
package/docs/configuration.md
CHANGED
|
@@ -1,36 +1,69 @@
|
|
|
1
1
|
# Configuration
|
|
2
2
|
|
|
3
|
-
|
|
4
|
-
|
|
3
|
+
This page is for changing what the factory does in your repository once it
|
|
4
|
+
is set up. Everything you can change is in one file,
|
|
5
|
+
`.claude/factory.yaml`, which [`factory init`](github/setup.md) writes when
|
|
6
|
+
you set the factory up. You don't need to read this page top to bottom:
|
|
7
|
+
start with
|
|
8
|
+
[the settings most repositories change](#the-settings-most-repositories-change),
|
|
9
|
+
and look up any other setting under [Every setting](#every-setting).
|
|
10
|
+
|
|
11
|
+
## Words this page uses
|
|
12
|
+
|
|
13
|
+
- **Session:** one conversation with the coding agent, such as Claude
|
|
14
|
+
Code, working in your repository. A session on your own machine is a
|
|
15
|
+
local session. One that runs in the cloud with nobody at the keyboard is
|
|
16
|
+
an unattended session.
|
|
17
|
+
- **Build:** a session taking one approved ticket to a pull request.
|
|
18
|
+
- **The cloud runner:** where the factory's unattended work runs. Today
|
|
19
|
+
that is GitHub Actions.
|
|
20
|
+
- **The board:** a GitHub Project showing each ticket's state as a column.
|
|
21
|
+
It is optional.
|
|
22
|
+
- **The board sync:** a job on the cloud runner that moves each ticket to
|
|
23
|
+
its column on the board and fills in its fields. It is the only thing
|
|
24
|
+
that writes to the board.
|
|
25
|
+
- **`factory sync`:** a command you run. It copies the factory's skills,
|
|
26
|
+
agents, rules, and workflows into your repository, choosing which ones
|
|
27
|
+
from this file. It has nothing to do with the board sync.
|
|
28
|
+
- **Skill and agent:** a skill is a set of instructions a session follows,
|
|
29
|
+
and an agent is a separate reviewer a session launches to read something
|
|
30
|
+
and report back.
|
|
31
|
+
|
|
32
|
+
The [glossary](glossary.md) has the rest.
|
|
5
33
|
|
|
6
34
|
## How the file works
|
|
7
35
|
|
|
8
|
-
- **
|
|
9
|
-
|
|
10
|
-
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
- **
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
- **
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
|
|
36
|
+
- **Two settings are required, and a third before any build.** Every
|
|
37
|
+
file has [`version`](#version) and [`repository`](#repository), and a
|
|
38
|
+
session can't build a ticket until you set
|
|
39
|
+
[`commands.gate`](#commandsgate). Every other setting has a default, and
|
|
40
|
+
you write it only when you want something else.
|
|
41
|
+
- **It holds only what a script needs.** Anything that needs judgment,
|
|
42
|
+
such as when one of your reviewers should apply, goes in the
|
|
43
|
+
instructions your coding agent already reads, such as `CLAUDE.md`.
|
|
44
|
+
- **File patterns are globs.** `*` matches within one folder and `**`
|
|
45
|
+
matches across folders. Both match names that start with a dot. A
|
|
46
|
+
pattern with no wildcard matches that one path from the repository's
|
|
47
|
+
root.
|
|
48
|
+
- **A command is one line of shell.** Each runs with bash, from the
|
|
49
|
+
repository's root. Only the commands under [`site.checks`](#site) and
|
|
50
|
+
[`auto-merge.commands`](#auto-merge) are given anything on their
|
|
51
|
+
standard input, and their entries say what.
|
|
52
|
+
- **Some settings choose between tools, and name the tool with `type`.**
|
|
53
|
+
When `type` is the only thing in the block, you can write the tool's
|
|
54
|
+
name on the same line. These two mean the same:
|
|
20
55
|
|
|
21
56
|
```yaml
|
|
22
57
|
specs: openspec
|
|
23
58
|
```
|
|
24
59
|
|
|
25
|
-
means the same as:
|
|
26
|
-
|
|
27
60
|
```yaml
|
|
28
61
|
specs:
|
|
29
62
|
type: openspec
|
|
30
63
|
```
|
|
31
64
|
|
|
32
|
-
- **
|
|
33
|
-
|
|
65
|
+
- **Your comments are kept.** `factory init` writes a comment above each
|
|
66
|
+
section, and updates never remove yours.
|
|
34
67
|
|
|
35
68
|
## The shortest file
|
|
36
69
|
|
|
@@ -39,67 +72,68 @@ version: 2
|
|
|
39
72
|
repository: your-name/your-repo
|
|
40
73
|
```
|
|
41
74
|
|
|
42
|
-
With this,
|
|
43
|
-
without you, and there is no board.
|
|
44
|
-
|
|
75
|
+
With only this, the factory refines a ticket when you ask a session to,
|
|
76
|
+
nothing merges without you, and there is no board. Before a session can
|
|
77
|
+
build a ticket, you also need to tell it how to check a change:
|
|
78
|
+
[`commands.gate`](#commandsgate), below.
|
|
45
79
|
|
|
46
80
|
## The settings most repositories change
|
|
47
81
|
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
- **The gate,** the commands that check a change, such as your tests and
|
|
53
|
-
your linter. A build cannot finish without it. List them under
|
|
54
|
-
`commands.gate`.
|
|
55
|
-
- **The checks before every commit,** the quick ones of the gate, such as
|
|
56
|
-
your formatter. List them under
|
|
82
|
+
- **How to check a change:** your tests, linter, and type check, under
|
|
83
|
+
[`commands.gate`](#commandsgate). A build cannot finish without it.
|
|
84
|
+
- **Quick checks before every commit:** your formatter and the other
|
|
85
|
+
checks that take a few seconds, under
|
|
57
86
|
[`commands.before-commit`](#commandsbefore-commit).
|
|
58
|
-
- **A board
|
|
59
|
-
board
|
|
60
|
-
|
|
61
|
-
[
|
|
62
|
-
|
|
63
|
-
|
|
64
|
-
`
|
|
65
|
-
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
|
|
87
|
+
- **A board:** your GitHub Project's number, under
|
|
88
|
+
[`tickets.board`](#tickets).
|
|
89
|
+
- **What may merge without you:** for example your docs, under
|
|
90
|
+
[`auto-merge.allow`](#auto-merge).
|
|
91
|
+
- **Reviewers of your own:** an agent you wrote, which reads a change that
|
|
92
|
+
touches certain files, under
|
|
93
|
+
[`plugins.build.reviewers`](#pluginsbuild). [Plugins](plugins.md) has a
|
|
94
|
+
worked example.
|
|
95
|
+
|
|
96
|
+
**After you change the file,** run:
|
|
97
|
+
|
|
98
|
+
```bash
|
|
99
|
+
factory config check
|
|
100
|
+
factory sync
|
|
101
|
+
```
|
|
102
|
+
|
|
103
|
+
`factory config check` prints nothing when the file is valid, and names
|
|
104
|
+
the setting when it is not. `factory sync` then rewrites the copied files
|
|
105
|
+
that depend on what you changed, and lists each file it wrote. A change
|
|
106
|
+
under `plugins` alone needs no `factory sync`, since the factory reads
|
|
107
|
+
your plugins from this file each time.
|
|
108
|
+
|
|
109
|
+
## Every setting
|
|
75
110
|
|
|
76
111
|
### `version`
|
|
77
112
|
|
|
78
|
-
|
|
79
|
-
|
|
80
|
-
release that changes the shape says so, and
|
|
81
|
-
[Updating](updating.md#moving-to-settings-version-2) shows each key that
|
|
82
|
-
moved, before and after.
|
|
113
|
+
Which layout of this file you are using. It is not the factory's version.
|
|
114
|
+
Write `2`.
|
|
83
115
|
|
|
84
|
-
- **Default:** none.
|
|
85
|
-
- **If wrong
|
|
86
|
-
with `version: must be 2`. For a version 1 file it
|
|
87
|
-
|
|
116
|
+
- **Default:** none. `factory init` writes it.
|
|
117
|
+
- **If it is wrong,** every factory command that reads this file stops
|
|
118
|
+
with `version: must be 2`. For a version 1 file, it also says where
|
|
119
|
+
[Updating](updating.md#moving-to-settings-version-2) shows each setting
|
|
120
|
+
that moved.
|
|
88
121
|
|
|
89
122
|
### `repository`
|
|
90
123
|
|
|
91
|
-
|
|
124
|
+
Your repository, as `owner/name`, such as `harbor-goods/storefront`.
|
|
92
125
|
|
|
93
|
-
- **Default:** none.
|
|
94
|
-
- **If wrong
|
|
95
|
-
fail because it does not exist.
|
|
126
|
+
- **Default:** none. `factory init` writes it.
|
|
127
|
+
- **If it is wrong,** commands read and write another repository's
|
|
128
|
+
tickets, or fail because it does not exist.
|
|
96
129
|
|
|
97
|
-
It is
|
|
98
|
-
poller
|
|
130
|
+
It is written down rather than worked out from your checkout, because the
|
|
131
|
+
[poller](#builds), which watches your board from outside any checkout,
|
|
132
|
+
needs it too.
|
|
99
133
|
|
|
100
134
|
### `tickets`
|
|
101
135
|
|
|
102
|
-
Where tickets live and
|
|
136
|
+
Where your tickets live, and which board shows them.
|
|
103
137
|
|
|
104
138
|
```yaml
|
|
105
139
|
tickets:
|
|
@@ -107,292 +141,269 @@ tickets:
|
|
|
107
141
|
board: 1
|
|
108
142
|
```
|
|
109
143
|
|
|
110
|
-
|
|
111
|
-
|
|
112
|
-
|
|
113
|
-
|
|
114
|
-
|
|
115
|
-
- **With `type: github`,** the board is a GitHub Project, and its number is
|
|
116
|
-
the last part of its address.
|
|
117
|
-
- **With no board,** a ticket's state lives in its comments,
|
|
118
|
-
`factory status` still shows it, and builds start only
|
|
119
|
-
when you tell a session.
|
|
120
|
-
- **If `board` is wrong:** the board sync fails and names the board it could
|
|
121
|
-
not read.
|
|
122
|
-
- **One board can hold more than one repository's tickets.** Give each
|
|
123
|
-
repository the same `board`: each one's sync, `status`, and poller read
|
|
124
|
-
only the cards for its own issues, and GitHub's Repository field tells
|
|
125
|
-
them apart on the board.
|
|
126
|
-
|
|
127
|
-
A board shows the six states of [Workflow](workflow.md) as columns, and
|
|
128
|
-
keeps three fields the factory writes. A repository that writes nothing
|
|
129
|
-
below gets the factory's own board. `columns` and `fields` need a `board`.
|
|
130
|
-
|
|
131
|
-
#### `tickets.columns`
|
|
132
|
-
|
|
133
|
-
Which of your board's columns shows each state. Leave a key out to use the
|
|
134
|
-
factory's own name for it. `none` means your board has no column for that
|
|
135
|
-
state.
|
|
136
|
-
|
|
137
|
-
| Key | State | Default column | May be `none` |
|
|
138
|
-
| ---------- | -------- | -------------- | ------------- |
|
|
139
|
-
| `backlog` | backlog | Backlog | No |
|
|
140
|
-
| `refining` | refining | In refinement | Yes |
|
|
141
|
-
| `ready` | ready | Ready | Yes |
|
|
142
|
-
| `building` | building | In progress | Yes |
|
|
143
|
-
| `review` | review | In review | Yes |
|
|
144
|
-
| `done` | done | Done | Yes |
|
|
145
|
-
|
|
146
|
-
- **A name matches whatever its capitals and the spaces around it,** so
|
|
147
|
-
the default "In progress" finds a board's "In Progress".
|
|
148
|
-
- **A ticket shows in its state's column. When that state has none, it
|
|
149
|
-
shows in the column of the nearest earlier state that has one.** Nothing
|
|
150
|
-
but an approved ticket shows in the `ready` column, so a state with no
|
|
151
|
-
column passes over it.
|
|
152
|
-
- **A card in a column no state names is left alone.** The sync writes none
|
|
153
|
-
of its fields while it sits there, and nothing builds it.
|
|
154
|
-
- **With `ready: none`,** no column approves a build. A build starts only
|
|
155
|
-
when you tell a session to build the ticket or run
|
|
156
|
-
`factory build N`, so
|
|
157
|
-
`factory config check` requires `builds.trigger: manual`.
|
|
158
|
-
- **If a repository's `ready` column has another name,** a poller you host
|
|
159
|
-
needs it too: see `FACTORY_READY_COLUMN` in [Builds](builds.md). A
|
|
160
|
-
scheduled one reads it from here.
|
|
161
|
-
- `factory config get tickets.columns.ready` prints the
|
|
162
|
-
name in effect, or `none`.
|
|
163
|
-
|
|
164
|
-
#### `tickets.fields`
|
|
165
|
-
|
|
166
|
-
Which of your board's fields the sync writes: `session`, `runs-in`, and
|
|
167
|
-
`cost`, with the defaults Session, Runs in, and Cost. Each may be `none`.
|
|
168
|
-
The board's own status field keeps its name, Status on a GitHub Project,
|
|
169
|
-
and has to be a single select holding every column named above.
|
|
144
|
+
- **`type`** is the ticket system. Only `github` is built, and it is the
|
|
145
|
+
default.
|
|
146
|
+
- **`board`** is your GitHub Project's number: the last part of its
|
|
147
|
+
address, such as `1` in `github.com/users/your-name/projects/1`. The
|
|
148
|
+
default, `none`, means no board.
|
|
170
149
|
|
|
171
|
-
|
|
172
|
-
|
|
173
|
-
|
|
174
|
-
| name the field | lacks it, or it has the wrong type | fails, naming the field and its key |
|
|
175
|
-
| leave default | has it, with the right type | writes it |
|
|
176
|
-
| leave default | lacks it | skips it, with a note |
|
|
177
|
-
| leave default | has it, with the wrong type | fails, and says to name another field or set the key to `none` |
|
|
178
|
-
| say `none` | either | never writes it |
|
|
150
|
+
Without a board, `factory status` still shows every ticket's state, which
|
|
151
|
+
the factory keeps in comments on the ticket. Builds then start only when
|
|
152
|
+
you ask a session to build a ticket.
|
|
179
153
|
|
|
180
|
-
|
|
181
|
-
|
|
182
|
-
|
|
154
|
+
One board can show tickets from several repositories. Give each
|
|
155
|
+
repository the same `board`. Each repository's board sync,
|
|
156
|
+
`factory status`, and poller only touch that repository's own tickets.
|
|
183
157
|
|
|
184
|
-
|
|
158
|
+
`factory board check` reads your board and says what the factory will do
|
|
159
|
+
with it.
|
|
185
160
|
|
|
186
|
-
|
|
187
|
-
tickets:
|
|
188
|
-
type: github
|
|
189
|
-
board: 1
|
|
190
|
-
```
|
|
161
|
+
#### `tickets.columns`
|
|
191
162
|
|
|
192
|
-
|
|
193
|
-
|
|
163
|
+
The board has one column for each of the six
|
|
164
|
+
[states](workflow.md#the-six-states) a ticket goes through. If your
|
|
165
|
+
board's columns have the factory's names, write nothing here. If they have
|
|
166
|
+
other names, or your board has fewer columns, say which column shows each
|
|
167
|
+
state. A new GitHub Project starts with only Todo, In Progress, and Done,
|
|
168
|
+
so its settings would be:
|
|
194
169
|
|
|
195
170
|
```yaml
|
|
196
171
|
tickets:
|
|
197
|
-
type: github
|
|
198
172
|
board: 7
|
|
199
173
|
columns:
|
|
200
174
|
backlog: Todo
|
|
175
|
+
building: In Progress
|
|
176
|
+
done: Done
|
|
201
177
|
refining: none
|
|
202
178
|
ready: none
|
|
203
|
-
building: In Progress
|
|
204
179
|
review: none
|
|
205
|
-
done: Done
|
|
206
180
|
builds:
|
|
207
181
|
trigger: manual
|
|
208
182
|
```
|
|
209
183
|
|
|
210
|
-
|
|
211
|
-
|
|
212
|
-
|
|
213
|
-
|
|
214
|
-
|
|
184
|
+
The factory's own names, used for any state you leave out, are:
|
|
185
|
+
|
|
186
|
+
| State | Column the factory looks for |
|
|
187
|
+
| ---------- | ---------------------------- |
|
|
188
|
+
| `backlog` | Backlog |
|
|
189
|
+
| `refining` | In refinement |
|
|
190
|
+
| `ready` | Ready |
|
|
191
|
+
| `building` | In progress |
|
|
192
|
+
| `review` | In review |
|
|
193
|
+
| `done` | Done |
|
|
194
|
+
|
|
195
|
+
- **Capitals don't matter,** so "In progress" finds your "In Progress".
|
|
196
|
+
- **`none` means your board has no column for that state.** A ticket in
|
|
197
|
+
that state stays in the column of the state before it. With
|
|
198
|
+
`review: none`, a ticket whose pull request is in review stays in In
|
|
199
|
+
progress. Every state can be `none` except `backlog`.
|
|
200
|
+
- **A ticket never falls back into Ready,** since only a ticket you
|
|
201
|
+
approved goes there, so the fallback skips it. With `building: none`
|
|
202
|
+
alone, a ticket being built has no column of its own, the state before
|
|
203
|
+
building is ready, and Ready is skipped, so it shows in In refinement.
|
|
204
|
+
- **With `ready: none`, nothing on the board approves a build,** so you
|
|
205
|
+
need `builds.trigger: manual`, and you start each build by asking a
|
|
206
|
+
session.
|
|
207
|
+
- **A ticket in a column no state uses is left alone.** The board sync
|
|
208
|
+
doesn't move it or fill in its fields, and nothing builds it.
|
|
209
|
+
- **If you host your own poller** and rename the Ready column, the poller
|
|
210
|
+
needs the new name too: see `FACTORY_READY_COLUMN` in
|
|
211
|
+
[Builds](builds.md#what-it-reads-from-its-environment).
|
|
212
|
+
|
|
213
|
+
`factory config check` stops on a state it doesn't know, on
|
|
214
|
+
`backlog: none`, on two states sharing one column, on `columns` without a
|
|
215
|
+
`board`, and on `ready: none` when `builds.trigger` isn't `manual`. It
|
|
216
|
+
doesn't read your board: `factory board check` does.
|
|
215
217
|
|
|
216
|
-
`
|
|
217
|
-
else. Only `github` is built. Any other value fails
|
|
218
|
-
`factory config check` and every ticket command with:
|
|
219
|
-
`tickets.type "X" is not supported. "github" is the only ticket system built.`
|
|
218
|
+
#### `tickets.fields`
|
|
220
219
|
|
|
221
|
-
|
|
220
|
+
Besides moving a ticket between columns, the board sync fills in three
|
|
221
|
+
fields so you can see at a glance what is happening to it:
|
|
222
222
|
|
|
223
|
-
|
|
223
|
+
- **Session:** which session is working on the ticket, or "Waiting on
|
|
224
|
+
you".
|
|
225
|
+
- **Runs in:** whether that session is on someone's machine or in the
|
|
226
|
+
cloud.
|
|
227
|
+
- **Cost:** roughly what refining and building the ticket has cost so far.
|
|
228
|
+
|
|
229
|
+
`factory init` adds these three fields to your board, so most repositories
|
|
230
|
+
write nothing here. Write this block only when your board already has a
|
|
231
|
+
field you want used instead, or to stop the board sync filling one in:
|
|
224
232
|
|
|
225
233
|
```yaml
|
|
226
|
-
|
|
227
|
-
|
|
234
|
+
tickets:
|
|
235
|
+
board: 7
|
|
236
|
+
fields:
|
|
237
|
+
session: Agent # fill in your existing "Agent" field instead
|
|
238
|
+
cost: none # never fill in a cost
|
|
228
239
|
```
|
|
229
240
|
|
|
230
|
-
|
|
231
|
-
|
|
232
|
-
|
|
241
|
+
- **A field you name must exist,** holding the right kind of value: text
|
|
242
|
+
for Session, a single select with the options Local and Actions for Runs
|
|
243
|
+
in, and a number for Cost. If it doesn't, the board sync stops and says
|
|
244
|
+
which field is wrong.
|
|
245
|
+
- **When you name nothing,** the board sync looks for fields called
|
|
246
|
+
Session, Runs in, and Cost, fills in those it finds, and skips the rest
|
|
247
|
+
with a note.
|
|
248
|
+
- **It never overwrites a field of yours.** If your board has a field
|
|
249
|
+
called Cost that holds text, the board sync stops rather than write over
|
|
250
|
+
it, and asks you to name another field or write `cost: none`.
|
|
251
|
+
- **The column itself is the board's own Status field,** which has to be
|
|
252
|
+
a single select with an option for each column in
|
|
253
|
+
[`tickets.columns`](#ticketscolumns).
|
|
254
|
+
|
|
255
|
+
### `code-host`
|
|
233
256
|
|
|
234
|
-
|
|
235
|
-
|
|
236
|
-
|
|
237
|
-
|
|
238
|
-
|
|
239
|
-
|
|
257
|
+
Where your repository and its pull requests live. Only `github` is built,
|
|
258
|
+
and it is the default, so most files leave this out.
|
|
259
|
+
|
|
260
|
+
```yaml
|
|
261
|
+
code-host: github
|
|
262
|
+
```
|
|
240
263
|
|
|
241
264
|
### `builds`
|
|
242
265
|
|
|
266
|
+
What starts a build when you approve a ticket, and where the build runs.
|
|
267
|
+
|
|
243
268
|
```yaml
|
|
244
269
|
builds:
|
|
245
270
|
trigger: own-server
|
|
246
|
-
runner: github-actions
|
|
247
271
|
```
|
|
248
272
|
|
|
249
|
-
|
|
|
250
|
-
| -------------- |
|
|
251
|
-
| `trigger` | What
|
|
252
|
-
| `runner` | Where a build in the cloud runs
|
|
253
|
-
| `poll-minutes` |
|
|
254
|
-
|
|
255
|
-
|
|
256
|
-
|
|
257
|
-
|
|
258
|
-
|
|
259
|
-
|
|
260
|
-
|
|
261
|
-
|
|
262
|
-
|
|
263
|
-
- **`
|
|
264
|
-
-
|
|
265
|
-
|
|
266
|
-
|
|
267
|
-
|
|
268
|
-
|
|
269
|
-
|
|
270
|
-
|
|
271
|
-
|
|
272
|
-
|
|
273
|
-
|
|
274
|
-
|
|
273
|
+
| Setting | What it sets | Choices | Default |
|
|
274
|
+
| -------------- | ----------------------------------------------------- | --------------------------------------- | ---------------- |
|
|
275
|
+
| `trigger` | What notices you moved a ticket to Ready on the board | `manual`, `own-server`, `github-action` | `manual` |
|
|
276
|
+
| `runner` | Where a build in the cloud runs | `github-actions` | `github-actions` |
|
|
277
|
+
| `poll-minutes` | With `github-action`, how often it checks the board | 5, 10, 15, 30, or 60 | 5 |
|
|
278
|
+
|
|
279
|
+
The three triggers:
|
|
280
|
+
|
|
281
|
+
- **`manual`:** nothing watches the board. You ask a session to build a
|
|
282
|
+
ticket, such as "work ticket 12".
|
|
283
|
+
- **`own-server`:** a small program you host, the poller, checks the board
|
|
284
|
+
once a minute and starts a cloud build for each ticket in Ready.
|
|
285
|
+
[Hosting the poller](builds.md#hosting-the-poller-own-server) shows how
|
|
286
|
+
to run it.
|
|
287
|
+
- **`github-action`:** a schedule on GitHub Actions does the same every
|
|
288
|
+
`poll-minutes` minutes, with nothing for you to host. On a private
|
|
289
|
+
repository, each check is billed as at least one Actions minute.
|
|
290
|
+
`factory sync` adds its workflow.
|
|
291
|
+
|
|
292
|
+
Watch the spelling: the trigger is `github-action`, singular, and the
|
|
293
|
+
runner is `github-actions`, plural.
|
|
294
|
+
|
|
295
|
+
Whatever starts it, a cloud build runs on the cloud runner.
|
|
296
|
+
[Builds](builds.md) explains each trigger. **It worked when** a ticket you
|
|
297
|
+
move to Ready shows as In progress on the board within a few minutes. If
|
|
298
|
+
nothing is watching the board, a ticket you move to Ready just sits there, and `factory status`
|
|
299
|
+
marks it "not started": after 5 minutes with `own-server`, and after
|
|
300
|
+
`poll-minutes` plus 15 minutes with `github-action`.
|
|
301
|
+
|
|
302
|
+
`factory config check` stops on `poll-minutes` with any trigger but
|
|
303
|
+
`github-action`, and on any value but the five above.
|
|
275
304
|
|
|
276
305
|
### `specs`
|
|
277
306
|
|
|
278
|
-
|
|
279
|
-
|
|
307
|
+
Whether a change your users will see also gets a written spec, kept beside
|
|
308
|
+
your code.
|
|
280
309
|
|
|
281
310
|
```yaml
|
|
282
311
|
specs: openspec
|
|
283
312
|
```
|
|
284
313
|
|
|
285
|
-
|
|
286
|
-
|
|
287
|
-
|
|
288
|
-
|
|
289
|
-
|
|
290
|
-
-
|
|
291
|
-
|
|
292
|
-
|
|
293
|
-
|
|
294
|
-
change stops at its first spec step and says so.
|
|
295
|
-
- `factory config get specs` prints `openspec` or `none`, whichever way it
|
|
296
|
-
is written.
|
|
314
|
+
- **`none`,** the default: the ticket's acceptance criteria are the only
|
|
315
|
+
spec.
|
|
316
|
+
- **`openspec`:** a visible change that isn't
|
|
317
|
+
[small](workflow.md#sizing-the-work-to-the-change) also writes its new
|
|
318
|
+
behavior into `openspec/specs/`, using
|
|
319
|
+
[OpenSpec](https://github.com/Fission-AI/OpenSpec), so that folder
|
|
320
|
+
always describes what your project does. Install it first, with
|
|
321
|
+
`npm install -D @fission-ai/openspec`. Without it, a build stops at its
|
|
322
|
+
first spec step and says so.
|
|
297
323
|
|
|
298
324
|
#### `specs.check`
|
|
299
325
|
|
|
300
|
-
The command that
|
|
301
|
-
`factory specs check` runs it, and a build
|
|
302
|
-
spec
|
|
326
|
+
The command that checks your written specs are sound.
|
|
327
|
+
`factory specs check` runs it, and so does a build each time it writes a
|
|
328
|
+
spec.
|
|
303
329
|
|
|
304
330
|
```yaml
|
|
305
331
|
specs:
|
|
306
332
|
type: openspec
|
|
307
|
-
# The command "factory specs check" runs. This is its default.
|
|
308
333
|
check: npx --no-install openspec validate --all --strict --no-interactive
|
|
309
334
|
```
|
|
310
335
|
|
|
311
|
-
- **Default:** the command above,
|
|
312
|
-
|
|
313
|
-
|
|
314
|
-
|
|
315
|
-
|
|
316
|
-
|
|
317
|
-
`factory config check
|
|
318
|
-
- `factory config get specs.check` prints the command, or `none`.
|
|
336
|
+
- **Default:** the command above,
|
|
337
|
+
`npx --no-install openspec validate --all --strict --no-interactive`,
|
|
338
|
+
with `type: openspec`, so most repositories leave it out.
|
|
339
|
+
- **It runs with `DO_NOT_TRACK=1` set,** so OpenSpec collects no usage
|
|
340
|
+
statistics.
|
|
341
|
+
- **With `specs: none`** there is nothing to check, and writing `check`
|
|
342
|
+
fails `factory config check`.
|
|
319
343
|
|
|
320
344
|
### `commands`
|
|
321
345
|
|
|
322
|
-
The commands
|
|
323
|
-
|
|
324
|
-
linter. They run `factory gate`, `factory test-one`, and the
|
|
325
|
-
|
|
346
|
+
The commands that are your project's own: how a session checks a change,
|
|
347
|
+
runs one test, and so on. The factory's skills never name a test runner or
|
|
348
|
+
a linter. They run `factory gate`, `factory test-one`, and the like, which
|
|
349
|
+
run what you write here.
|
|
326
350
|
|
|
327
351
|
```yaml
|
|
328
|
-
# Every command a build runs, each from the repository's root.
|
|
329
352
|
commands:
|
|
330
|
-
# Before an unattended build starts work.
|
|
331
353
|
build-setup:
|
|
332
354
|
- npx playwright install --with-deps chromium
|
|
333
|
-
# Before every commit a session makes.
|
|
334
355
|
before-commit:
|
|
335
356
|
- npm run -s format:check
|
|
336
357
|
- npx tsc --noEmit
|
|
337
|
-
# Before a session reports a task done. "factory gate" runs them in order.
|
|
338
358
|
gate:
|
|
339
359
|
- npm run check
|
|
340
|
-
# One test alone. "factory test-one" sets $FILE and $NAME.
|
|
341
360
|
test-one: npx vitest run $FILE -t "$NAME"
|
|
342
|
-
# One end-to-end spec alone. "factory end-to-end" sets $FILE.
|
|
343
361
|
end-to-end: npx playwright test $FILE
|
|
344
|
-
# Coverage, and where its lcov report lands.
|
|
345
362
|
coverage:
|
|
346
363
|
run: npm run coverage
|
|
347
364
|
report: coverage/lcov.info
|
|
348
|
-
# Rebuilds the lock file after a conflict in it.
|
|
349
365
|
relock: npm install
|
|
350
366
|
```
|
|
351
367
|
|
|
352
|
-
|
|
|
353
|
-
| --------------- |
|
|
354
|
-
| `build-setup` |
|
|
355
|
-
| `before-commit` |
|
|
356
|
-
| `gate` |
|
|
357
|
-
| `test-one` |
|
|
358
|
-
| `end-to-end` |
|
|
359
|
-
| `coverage` |
|
|
360
|
-
| `relock` |
|
|
361
|
-
|
|
368
|
+
| Setting | Runs | Default |
|
|
369
|
+
| --------------- | ---------------------------------------------------------------- | -------------------------- |
|
|
370
|
+
| `build-setup` | Before a cloud build starts work | none |
|
|
371
|
+
| `before-commit` | Before every commit a session makes | none |
|
|
372
|
+
| `gate` | Before a session calls a task done | none, and a build needs it |
|
|
373
|
+
| `test-one` | When a session runs one test alone | none |
|
|
374
|
+
| `end-to-end` | When a session runs one end-to-end test file alone | none |
|
|
375
|
+
| `coverage` | When a session checks that a pull request's new lines are tested | none |
|
|
376
|
+
| `relock` | After a conflict in your lock file | `npm install` |
|
|
377
|
+
|
|
378
|
+
- **`$FILE` and `$NAME`** are set for you when a command runs one test.
|
|
379
|
+
[`commands.test-one`](#commandstest-one) says how.
|
|
362
380
|
- **Only `gate` is needed for a build.** Each of the others turns
|
|
363
|
-
something on, and its entry says what
|
|
381
|
+
something on, and its entry below says what happens without it.
|
|
364
382
|
- **A list runs in order and stops at the first command that fails.**
|
|
365
|
-
- **`factory config check` fails, naming the key,** on a list that is not a
|
|
366
|
-
list of text, on a single command that is not text or is empty, and on a
|
|
367
|
-
`coverage` block missing `run` or `report`.
|
|
368
|
-
- `factory config get commands.gate` prints one command per line, and
|
|
369
|
-
nothing for an empty list. A single command prints itself, or `none`
|
|
370
|
-
when it is not set, and so do `commands.coverage.run` and
|
|
371
|
-
`commands.coverage.report`.
|
|
372
383
|
|
|
373
384
|
#### `commands.build-setup`
|
|
374
385
|
|
|
375
|
-
Commands run
|
|
376
|
-
dependencies are already installed by then,
|
|
386
|
+
Commands that run before a cloud build starts work, to install what the
|
|
387
|
+
session will need. Your npm dependencies are already installed by then,
|
|
388
|
+
with `npm ci`, but nothing else is.
|
|
377
389
|
|
|
378
390
|
```yaml
|
|
379
391
|
commands:
|
|
380
|
-
# Commands run from the repository's root before an unattended build
|
|
381
|
-
# starts work. Your npm dependencies are already installed by then.
|
|
382
392
|
build-setup:
|
|
383
|
-
- npx playwright install --with-deps chromium
|
|
393
|
+
- npx playwright install --with-deps chromium # a browser for end-to-end tests
|
|
384
394
|
```
|
|
385
395
|
|
|
396
|
+
In a project that isn't JavaScript, install its dependencies here too,
|
|
397
|
+
such as `composer install` or `pip install -r requirements.txt`.
|
|
398
|
+
|
|
386
399
|
- **Default:** none.
|
|
387
|
-
- **
|
|
388
|
-
|
|
389
|
-
- **If one fails:** the run stops before the session starts, with that
|
|
390
|
-
command's output in its log.
|
|
400
|
+
- **If one fails,** the build stops before the session starts, and the
|
|
401
|
+
run's log shows that command's output.
|
|
391
402
|
|
|
392
403
|
#### `commands.before-commit`
|
|
393
404
|
|
|
394
|
-
|
|
395
|
-
the commit is blocked and the session
|
|
405
|
+
Quick checks that run before every commit a session makes. If one fails,
|
|
406
|
+
the commit is blocked and the session sees why.
|
|
396
407
|
|
|
397
408
|
```yaml
|
|
398
409
|
commands:
|
|
@@ -403,19 +414,20 @@ commands:
|
|
|
403
414
|
```
|
|
404
415
|
|
|
405
416
|
- **Default:** none.
|
|
406
|
-
- **Keep them
|
|
407
|
-
|
|
408
|
-
|
|
409
|
-
|
|
410
|
-
own terminal.
|
|
411
|
-
- **If one is wrong:** every commit a session makes is blocked with that
|
|
412
|
-
command's error.
|
|
417
|
+
- **Keep them to a few seconds.** They run on every commit. Your tests
|
|
418
|
+
belong in [`commands.gate`](#commandsgate), which runs once per task.
|
|
419
|
+
- **They only apply to a session's commits,** not to commits you make
|
|
420
|
+
yourself.
|
|
413
421
|
|
|
414
422
|
#### `commands.gate`
|
|
415
423
|
|
|
416
|
-
The
|
|
417
|
-
|
|
418
|
-
|
|
424
|
+
The checks a change has to pass before a session calls it done or opens a
|
|
425
|
+
pull request. Think of it as what your CI runs on a pull request, minus
|
|
426
|
+
anything too slow for a session to sit and wait for. `factory gate` runs
|
|
427
|
+
them in order and stops at the first failure, so put the fastest first.
|
|
428
|
+
|
|
429
|
+
If you already have one command that runs every check, such as
|
|
430
|
+
`npm run check` or `make check`, the gate can be just that:
|
|
419
431
|
|
|
420
432
|
```yaml
|
|
421
433
|
commands:
|
|
@@ -423,71 +435,117 @@ commands:
|
|
|
423
435
|
- npm run check
|
|
424
436
|
```
|
|
425
437
|
|
|
426
|
-
|
|
427
|
-
|
|
428
|
-
|
|
429
|
-
|
|
430
|
-
|
|
431
|
-
|
|
432
|
-
-
|
|
433
|
-
|
|
434
|
-
|
|
435
|
-
|
|
436
|
-
|
|
437
|
-
|
|
438
|
-
|
|
438
|
+
Otherwise, list each check. What that looks like in a few languages:
|
|
439
|
+
|
|
440
|
+
```yaml
|
|
441
|
+
# JavaScript or TypeScript
|
|
442
|
+
gate:
|
|
443
|
+
- npm run format:check
|
|
444
|
+
- npm run lint
|
|
445
|
+
- npx tsc --noEmit
|
|
446
|
+
- npm test
|
|
447
|
+
```
|
|
448
|
+
|
|
449
|
+
```yaml
|
|
450
|
+
# Python
|
|
451
|
+
gate:
|
|
452
|
+
- ruff format --check .
|
|
453
|
+
- ruff check .
|
|
454
|
+
- mypy src
|
|
455
|
+
- pytest -q
|
|
456
|
+
```
|
|
457
|
+
|
|
458
|
+
```yaml
|
|
459
|
+
# Go
|
|
460
|
+
gate:
|
|
461
|
+
- test -z "$(gofmt -l .)"
|
|
462
|
+
- go vet ./...
|
|
463
|
+
- go test ./...
|
|
464
|
+
```
|
|
465
|
+
|
|
466
|
+
```yaml
|
|
467
|
+
# PHP
|
|
468
|
+
gate:
|
|
469
|
+
- composer validate --strict
|
|
470
|
+
- vendor/bin/php-cs-fixer fix --dry-run --diff
|
|
471
|
+
- vendor/bin/phpstan analyse
|
|
472
|
+
- vendor/bin/phpunit
|
|
473
|
+
```
|
|
474
|
+
|
|
475
|
+
```yaml
|
|
476
|
+
# Rust
|
|
477
|
+
gate:
|
|
478
|
+
- cargo fmt --check
|
|
479
|
+
- cargo clippy -- -D warnings
|
|
480
|
+
- cargo test
|
|
481
|
+
```
|
|
482
|
+
|
|
483
|
+
Leave out:
|
|
484
|
+
|
|
485
|
+
- **Anything that changes files,** such as `prettier --write`. The gate
|
|
486
|
+
checks a change; it doesn't fix it.
|
|
487
|
+
- **A test suite that takes many minutes,** such as a full browser suite.
|
|
488
|
+
CI still runs it on the pull request.
|
|
489
|
+
- **Anything that needs production secrets, or deploys.**
|
|
490
|
+
|
|
491
|
+
There is no default. Without a gate, `factory gate` fails with
|
|
492
|
+
`commands.gate is not set`, and a build stops there, because an empty gate
|
|
493
|
+
would pass every change. `factory init` lists it under "Left to do".
|
|
494
|
+
|
|
495
|
+
When a command fails, `factory gate` prints `gate failed on:` and the
|
|
496
|
+
command, and runs none after it. The session fixes the cause and runs the
|
|
497
|
+
gate again.
|
|
498
|
+
|
|
499
|
+
**Check your gate yourself** before a session relies on it: run
|
|
500
|
+
`factory gate` on a clean checkout. It should print each command and exit 0. `factory config check` only checks that the file is valid, not that
|
|
501
|
+
your commands work.
|
|
439
502
|
|
|
440
503
|
#### `commands.test-one`
|
|
441
504
|
|
|
442
|
-
Runs one test file alone, or one test in it.
|
|
443
|
-
|
|
444
|
-
|
|
445
|
-
given,
|
|
505
|
+
Runs one test file alone, or one test in it. A session uses it to watch a
|
|
506
|
+
new test fail before the change, and to narrow down a bug.
|
|
507
|
+
`factory test-one FILE NAME` runs your command with `$FILE` and `$NAME`
|
|
508
|
+
set. When only a file is given, `$NAME` is empty, so the command should
|
|
509
|
+
run the whole file then:
|
|
446
510
|
|
|
447
511
|
```yaml
|
|
448
512
|
commands:
|
|
449
|
-
|
|
450
|
-
|
|
513
|
+
test-one: npx vitest run $FILE -t "$NAME" # an empty -t runs every test
|
|
514
|
+
```
|
|
515
|
+
|
|
516
|
+
```yaml
|
|
517
|
+
commands:
|
|
518
|
+
test-one: vendor/bin/phpunit $FILE ${NAME:+--filter "$NAME"} # --filter only with a name
|
|
451
519
|
```
|
|
452
520
|
|
|
453
|
-
- **Default:**
|
|
454
|
-
-
|
|
455
|
-
|
|
456
|
-
- **Without it,** `factory test-one` fails with
|
|
457
|
-
`commands.test-one is not set`, and a session is left to find its own
|
|
458
|
-
way to run one test.
|
|
459
|
-
- **It exits with the command's own status.**
|
|
521
|
+
- **Default:** none. `factory test-one` then fails with
|
|
522
|
+
`commands.test-one is not set`, and a session finds its own way to run
|
|
523
|
+
one test.
|
|
460
524
|
|
|
461
525
|
#### `commands.end-to-end`
|
|
462
526
|
|
|
463
|
-
Runs one end-to-end
|
|
464
|
-
`
|
|
465
|
-
|
|
466
|
-
|
|
467
|
-
|
|
527
|
+
Runs one end-to-end test file alone, with `$FILE` set.
|
|
528
|
+
`factory end-to-end FILE --times 10` runs it ten times and stops at the
|
|
529
|
+
first failure, as `failed on run 3 of 10`. A build does that with each new
|
|
530
|
+
end-to-end test, since one that fails one run in ten will fail someone's
|
|
531
|
+
pull request.
|
|
468
532
|
|
|
469
533
|
```yaml
|
|
470
534
|
commands:
|
|
471
535
|
end-to-end: npx playwright test $FILE
|
|
472
536
|
```
|
|
473
537
|
|
|
474
|
-
- **Default:**
|
|
475
|
-
|
|
476
|
-
|
|
477
|
-
|
|
478
|
-
|
|
479
|
-
2. List it under [`plugins.test.reviewers`](#pluginstest), where it
|
|
480
|
-
runs. That list is the whole list, so list `factory-test-reviewer`
|
|
481
|
-
there too: listing `factory-e2e-reviewer` alone drops it.
|
|
482
|
-
- **Without it,** `factory end-to-end` fails with
|
|
483
|
-
`commands.end-to-end is not set`.
|
|
484
|
-
- **Run `factory sync` after adding or removing it.**
|
|
538
|
+
- **Default:** none. Leave it out if you have no end-to-end tests.
|
|
539
|
+
- **Setting it makes `factory-e2e-reviewer` available,** the factory's
|
|
540
|
+
reviewer for browser tests. To use it, run `factory sync`, then list it
|
|
541
|
+
under [`plugins.test.reviewers`](#pluginstest). That list replaces the
|
|
542
|
+
default, so list `factory-test-reviewer` there too.
|
|
485
543
|
|
|
486
544
|
#### `commands.coverage`
|
|
487
545
|
|
|
488
|
-
The command that measures test coverage, and where its lcov
|
|
489
|
-
A session working a pull request's review runs
|
|
490
|
-
|
|
546
|
+
The command that measures test coverage, and where it writes its lcov
|
|
547
|
+
report. A session working on a pull request's review runs it to find new
|
|
548
|
+
lines no test covers.
|
|
491
549
|
|
|
492
550
|
```yaml
|
|
493
551
|
commands:
|
|
@@ -496,236 +554,238 @@ commands:
|
|
|
496
554
|
report: coverage/lcov.info
|
|
497
555
|
```
|
|
498
556
|
|
|
499
|
-
- **Default:**
|
|
500
|
-
- **
|
|
557
|
+
- **Default:** none, and a session doesn't check coverage.
|
|
558
|
+
- **Write both `run` and `report`,** or neither.
|
|
501
559
|
|
|
502
560
|
#### `commands.relock`
|
|
503
561
|
|
|
504
|
-
The command that rebuilds your package manager's lock file.
|
|
505
|
-
|
|
506
|
-
runs this,
|
|
507
|
-
install dependencies in a checkout it made.
|
|
562
|
+
The command that rebuilds your package manager's lock file. When the lock
|
|
563
|
+
file conflicts with the default branch, a session takes the default
|
|
564
|
+
branch's copy and runs this, instead of merging the file by hand.
|
|
508
565
|
|
|
509
566
|
```yaml
|
|
510
567
|
commands:
|
|
511
|
-
relock:
|
|
568
|
+
relock: composer update --lock
|
|
512
569
|
```
|
|
513
570
|
|
|
514
|
-
- **Default:** `npm install
|
|
515
|
-
|
|
516
|
-
|
|
517
|
-
[resolver plug-in's](#pluginsconflicts).
|
|
571
|
+
- **Default:** `npm install`.
|
|
572
|
+
- **Another generated file that conflicts,** such as a generated API
|
|
573
|
+
client, needs a [resolver](#pluginsconflicts).
|
|
518
574
|
|
|
519
575
|
### `session-minutes`
|
|
520
576
|
|
|
521
|
-
How long each kind of session
|
|
522
|
-
|
|
523
|
-
|
|
577
|
+
How long each kind of unattended session may run, in minutes, before the
|
|
578
|
+
cloud runner stops it. Raise one if your tests or your build are slow
|
|
579
|
+
enough that sessions are cut off mid-task.
|
|
524
580
|
|
|
525
581
|
```yaml
|
|
526
|
-
# How long each unattended session may run, in minutes.
|
|
527
582
|
session-minutes:
|
|
528
583
|
build: 300
|
|
529
584
|
```
|
|
530
585
|
|
|
531
|
-
|
|
|
532
|
-
| -------------- |
|
|
533
|
-
| `build` |
|
|
534
|
-
| `conflicts` |
|
|
535
|
-
| `review` |
|
|
536
|
-
| `dependencies` |
|
|
537
|
-
|
|
538
|
-
- **Each is a whole number above zero.**
|
|
539
|
-
|
|
540
|
-
|
|
541
|
-
|
|
542
|
-
session is stopped.
|
|
543
|
-
- **`factory sync` writes these where the cloud runner
|
|
544
|
-
reads them,** and `factory sync --check` fails until it
|
|
545
|
-
has run after a change.
|
|
546
|
-
- **The cloud runner may stop a job sooner.** On GitHub, see
|
|
586
|
+
| Setting | The session | Default |
|
|
587
|
+
| -------------- | --------------------------------------------------------- | ------- |
|
|
588
|
+
| `build` | Building a ticket | `230` |
|
|
589
|
+
| `conflicts` | Fixing a pull request's conflicts with the default branch | `110` |
|
|
590
|
+
| `review` | Answering your review of a pull request | `50` |
|
|
591
|
+
| `dependencies` | Working through dependency updates | `50` |
|
|
592
|
+
|
|
593
|
+
- **Each is a whole number above zero.**
|
|
594
|
+
- **Run `factory sync` after changing one,** since it writes them into the
|
|
595
|
+
workflows. `factory config check` fails until you do.
|
|
596
|
+
- **GitHub may stop a job sooner:** see
|
|
547
597
|
[its limits](github/reference.md#limits).
|
|
548
|
-
- The cloud jobs that run no session, such as the board's sync and who
|
|
549
|
-
merges, keep fixed short limits.
|
|
550
|
-
- `factory config get session-minutes.build` prints the
|
|
551
|
-
value in effect.
|
|
552
598
|
|
|
553
599
|
### `plugins`
|
|
554
600
|
|
|
555
|
-
Your own skills and agents,
|
|
556
|
-
|
|
557
|
-
|
|
558
|
-
|
|
559
|
-
|
|
560
|
-
|
|
601
|
+
Your own skills and agents, doing a job the factory would otherwise do
|
|
602
|
+
itself, or adding to it. Each job is a **role**. For example, an agent you
|
|
603
|
+
list in the `reviewers` role reads every change that touches its files,
|
|
604
|
+
alongside the factory's own reviewers. Roles are grouped by the part of
|
|
605
|
+
the work they belong to: `refine`, `build`, `test`, and `conflicts`.
|
|
606
|
+
|
|
607
|
+
```yaml
|
|
608
|
+
plugins:
|
|
609
|
+
build:
|
|
610
|
+
reviewers:
|
|
611
|
+
- agent: migration-reviewer # .claude/agents/migration-reviewer.md
|
|
612
|
+
files:
|
|
613
|
+
- db/migrations/**
|
|
614
|
+
```
|
|
615
|
+
|
|
616
|
+
Every role is optional. Leaving one out never turns a step off: the
|
|
617
|
+
factory does that step its own way. A reviewer is an agent, since it only
|
|
618
|
+
reads and reports. Every other role takes a skill, which the session
|
|
619
|
+
follows itself. [Plugins](plugins.md) says what each role is handed and
|
|
620
|
+
what it has to give back.
|
|
621
|
+
|
|
622
|
+
| Role | What you list | How many | When it is used | If you list none |
|
|
623
|
+
| --------------------- | ------------- | -------- | --------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------- |
|
|
624
|
+
| `refine.refiner` | A skill | One | Whenever a ticket is refined | `factory-refine` refines tickets |
|
|
625
|
+
| `refine.mockups` | A skill | One | Whenever a decision changes how something looks | `factory-design` draws mockups if you set [`site`](#site), and otherwise the session describes the choices in words |
|
|
626
|
+
| `build.builders` | Skills | A list | For a ticket with one of the builder's `labels`. Each builder needs at least one | The factory's own build builds every ticket |
|
|
627
|
+
| `build.reviewers` | Agents | A list | When a change touches one of the reviewer's `files`. Each reviewer needs at least one pattern | Only the factory's own reviewers read a change |
|
|
628
|
+
| `test.prover` | A skill | One | Whenever a new test needs proof that it can fail | `factory-mutate` proves each new test can fail |
|
|
629
|
+
| `test.reviewers` | Agents | A list | When a change touches tests. A reviewer given `files` reads only changes to those | `factory-test-reviewer` reads new tests |
|
|
630
|
+
| `conflicts.resolvers` | Skills | A list | When a conflict is in one of the resolver's `files`. Each resolver needs at least one pattern | The session merges conflicts by hand, and [`commands.relock`](#commandsrelock) rebuilds the lock file |
|
|
631
|
+
|
|
632
|
+
In Claude Code, a skill lives at `.claude/skills/NAME/SKILL.md` and an
|
|
633
|
+
agent at `.claude/agents/NAME.md`:
|
|
634
|
+
[Skills in Claude Code](github/reference.md#skills-in-claude-code).
|
|
635
|
+
|
|
636
|
+
- **`factory plugins`** prints every plugin the factory will use, its own
|
|
637
|
+
included, one per line: skill or agent, its name, its role, and its
|
|
638
|
+
files or labels. `factory plugins reviewer` prints one role's.
|
|
639
|
+
- **`factory config check`** stops on an agent in a role that takes a
|
|
640
|
+
skill, or the other way round; on `files` or `labels` in a role that
|
|
641
|
+
doesn't take them; on a builder with no `labels`; on a build reviewer or
|
|
642
|
+
resolver with no `files`; and on a skill or agent whose file doesn't
|
|
643
|
+
exist. It warns on a `files` pattern that matches no file.
|
|
644
|
+
|
|
645
|
+
#### `plugins.refine`
|
|
646
|
+
|
|
647
|
+
- **`refiner`:** your own skill for refining a ticket, used instead of
|
|
648
|
+
`factory-refine`.
|
|
649
|
+
- **`mockups`:** your own skill for drawing the choices when a decision
|
|
650
|
+
changes how something looks.
|
|
651
|
+
|
|
652
|
+
A role that takes one plugin is a block, not a list:
|
|
561
653
|
|
|
562
654
|
```yaml
|
|
563
|
-
# Your own skills and agents, by phase. Every slot is optional.
|
|
564
655
|
plugins:
|
|
565
656
|
refine:
|
|
566
|
-
# Replaces factory-refine. Must deliver what the build reads.
|
|
567
657
|
refiner:
|
|
568
|
-
skill: acme-refine
|
|
569
|
-
# Makes pictures when a decision changes the look. One only.
|
|
658
|
+
skill: acme-refine # .claude/skills/acme-refine/SKILL.md
|
|
570
659
|
mockups:
|
|
571
660
|
skill: design-mockups
|
|
661
|
+
```
|
|
662
|
+
|
|
663
|
+
#### `plugins.build`
|
|
664
|
+
|
|
665
|
+
- **`builders`:** your own skill for building certain tickets, used
|
|
666
|
+
instead of the factory's build for any ticket with one of its `labels`.
|
|
667
|
+
If two builders share a label, the first one listed builds the ticket.
|
|
668
|
+
- **`reviewers`:** your own agents, each asked to read a change that
|
|
669
|
+
touches a file matching its `files`. The pattern only decides who is
|
|
670
|
+
asked: the agent's own description says when it really applies. One
|
|
671
|
+
that was asked but didn't apply gets a line in the pull request saying
|
|
672
|
+
why.
|
|
673
|
+
|
|
674
|
+
```yaml
|
|
675
|
+
plugins:
|
|
572
676
|
build:
|
|
573
|
-
# Each builds a ticket that carries one of its labels.
|
|
574
677
|
builders:
|
|
575
678
|
- skill: add-endpoint
|
|
576
679
|
labels:
|
|
577
680
|
- new-endpoint
|
|
578
|
-
# Each is considered when a change touches one of its files.
|
|
579
681
|
reviewers:
|
|
580
682
|
- agent: migration-reviewer
|
|
581
683
|
files:
|
|
582
684
|
- db/migrations/**
|
|
685
|
+
```
|
|
686
|
+
|
|
687
|
+
#### `plugins.test`
|
|
688
|
+
|
|
689
|
+
- **`prover`:** your own skill for proving a new test can fail, used
|
|
690
|
+
instead of `factory-mutate`.
|
|
691
|
+
- **`reviewers`:** the agents that read new and changed tests. **This list
|
|
692
|
+
replaces the default,** so `factory-test-reviewer` runs only if you list
|
|
693
|
+
it, and `reviewers: []` means no test reviewer runs. Without `files`, a
|
|
694
|
+
reviewer reads every change to tests; with `files`, only changes to
|
|
695
|
+
matching files. `factory-e2e-reviewer` needs
|
|
696
|
+
[`commands.end-to-end`](#commandsend-to-end).
|
|
697
|
+
|
|
698
|
+
```yaml
|
|
699
|
+
plugins:
|
|
583
700
|
test:
|
|
584
|
-
# Replaces factory-mutate: proves each new test can fail.
|
|
585
701
|
prover:
|
|
586
702
|
skill: acme-mutation
|
|
587
|
-
# The whole list of test reviewers. Left out, it is factory-test-reviewer.
|
|
588
703
|
reviewers:
|
|
589
704
|
- agent: factory-test-reviewer
|
|
590
705
|
- agent: factory-e2e-reviewer
|
|
591
706
|
files:
|
|
592
707
|
- e2e/**
|
|
708
|
+
```
|
|
709
|
+
|
|
710
|
+
#### `plugins.conflicts`
|
|
711
|
+
|
|
712
|
+
- **`resolvers`:** your own skills for files that should be rebuilt rather
|
|
713
|
+
than merged by hand after a conflict, such as a generated API client.
|
|
714
|
+
Each handles the files matching its `files`. If two match one file, the
|
|
715
|
+
first one listed rebuilds it.
|
|
716
|
+
- **A new resolver is used once it has merged,** since conflicts are fixed
|
|
717
|
+
using the default branch's copy of this file, never a pull request's.
|
|
718
|
+
|
|
719
|
+
```yaml
|
|
720
|
+
plugins:
|
|
593
721
|
conflicts:
|
|
594
|
-
# Each rebuilds its files after a conflict, in place of a hand merge.
|
|
595
722
|
resolvers:
|
|
596
723
|
- skill: regenerate-api-client
|
|
597
724
|
files:
|
|
598
725
|
- src/generated/**
|
|
599
726
|
```
|
|
600
727
|
|
|
601
|
-
|
|
602
|
-
a list of them. A reviewer is an agent, since it is launched to read and
|
|
603
|
-
changes nothing. Every other slot is a skill, which the session follows.
|
|
604
|
-
|
|
605
|
-
| Slot | Takes | One or a list | `files` or `labels` | Left out |
|
|
606
|
-
| --------------------- | ------- | ------------- | ------------------- | ---------------------------------------------------------- |
|
|
607
|
-
| `refine.refiner` | A skill | One | Neither | `factory-refine` |
|
|
608
|
-
| `refine.mockups` | A skill | One | Neither | `factory-design` with [`site`](#site) set; otherwise words |
|
|
609
|
-
| `build.builders` | Skills | A list | `labels`, required | The built-in build |
|
|
610
|
-
| `build.reviewers` | Agents | A list | `files`, required | No reviewers of your own |
|
|
611
|
-
| `test.prover` | A skill | One | Neither | `factory-mutate` |
|
|
612
|
-
| `test.reviewers` | Agents | A list | `files`, optional | `factory-test-reviewer` |
|
|
613
|
-
| `conflicts.resolvers` | Skills | A list | `files`, required | A merge by hand, and [`commands.relock`](#commandsrelock) |
|
|
614
|
-
|
|
615
|
-
Where your coding agent keeps skills and agents: in Claude Code, see
|
|
616
|
-
[Skills in Claude Code](github/reference.md#skills-in-claude-code).
|
|
617
|
-
|
|
618
|
-
- **`factory plugins` prints the plug-ins the factory will use,** one to a
|
|
619
|
-
line, the built-in ones included: its kind, its name, its slot, then its
|
|
620
|
-
files or labels. `factory plugins SLOT` prints one slot's, where the
|
|
621
|
-
slot is `refiner`, `mockups`, `builder`, `reviewer`, `prover`,
|
|
622
|
-
`test-reviewer`, or `resolver`.
|
|
623
|
-
- **`factory config check` fails, naming the slot,** on a skill where the
|
|
624
|
-
slot takes an agent or an agent where it takes a skill, on `files` or
|
|
625
|
-
`labels` where the slot takes neither, on a builder with no `labels`,
|
|
626
|
-
on a build reviewer or a resolver with no `files`, and on a name whose
|
|
627
|
-
file does not exist. It warns on a `files` pattern that matches no file.
|
|
628
|
-
- **Written as a list,** the shape before settings version 2, `plugins`
|
|
629
|
-
fails with `plugins: must be grouped by phase: refine, build, test, conflicts`.
|
|
630
|
-
[Updating](updating.md#moving-to-settings-version-2) shows where each
|
|
631
|
-
plug-in goes.
|
|
632
|
-
- **`plugins: {}`, or a phase with nothing under it,** is the same as
|
|
633
|
-
leaving it out.
|
|
634
|
-
|
|
635
|
-
#### `plugins.refine`
|
|
636
|
-
|
|
637
|
-
- **`refiner`:** the skill that refines a ticket, in place of
|
|
638
|
-
`factory-refine`. One skill, with no `files` and no `labels`.
|
|
639
|
-
- **`mockups`:** the skill that makes pictures to choose from when a
|
|
640
|
-
decision changes how something looks. One skill. A repository with
|
|
641
|
-
[`site`](#site) set has the factory's own `factory-design` here without
|
|
642
|
-
writing it; any other describes the decision in words.
|
|
643
|
-
|
|
644
|
-
#### `plugins.build`
|
|
728
|
+
### `site`
|
|
645
729
|
|
|
646
|
-
|
|
647
|
-
|
|
648
|
-
|
|
649
|
-
|
|
650
|
-
|
|
651
|
-
|
|
652
|
-
|
|
653
|
-
matched but which did not apply gets one line in the pull request saying
|
|
654
|
-
why.
|
|
730
|
+
How the factory looks at your website, if your repository is one. With
|
|
731
|
+
`site` set and `factory-ui-reviewer` listed under
|
|
732
|
+
[`plugins.build.reviewers`](#pluginsbuild), every change that alters how
|
|
733
|
+
the site looks is screenshotted before and after, and the difference is
|
|
734
|
+
reviewed. The screenshots are taken with Playwright, so install it in
|
|
735
|
+
your repository first, with `npm install -D playwright`. Until you do,
|
|
736
|
+
`factory config check` fails on a file with `site`.
|
|
655
737
|
|
|
656
|
-
|
|
738
|
+
Most sites need only two lines:
|
|
657
739
|
|
|
658
|
-
|
|
659
|
-
|
|
660
|
-
|
|
661
|
-
|
|
662
|
-
|
|
663
|
-
it is the whole list:** `factory-test-reviewer` runs only when you list
|
|
664
|
-
it, and `reviewers: []` means no test reviewer runs. `files` is
|
|
665
|
-
optional: without it a reviewer reads whenever a change touches tests,
|
|
666
|
-
and with it only when the change touches a matching file. Listing
|
|
667
|
-
`factory-e2e-reviewer` needs
|
|
668
|
-
[`commands.end-to-end`](#commandsend-to-end).
|
|
740
|
+
```yaml
|
|
741
|
+
site:
|
|
742
|
+
start: npm run build && npx serve out -p $PORT
|
|
743
|
+
url: http://localhost:$PORT
|
|
744
|
+
```
|
|
669
745
|
|
|
670
|
-
|
|
746
|
+
**It worked when** `factory site compare` builds your branch and the
|
|
747
|
+
default branch, takes the screenshots, and prints where it saved them.
|
|
748
|
+
[`factory site`](cli.md#factory-site) has the details.
|
|
671
749
|
|
|
672
|
-
|
|
673
|
-
`files` after a conflict, in place of merging them by hand, such as a
|
|
674
|
-
generated API client. `files` is required. When two resolvers match one
|
|
675
|
-
file, the first listed rebuilds it. The package manager's lock file
|
|
676
|
-
needs no resolver: [`commands.relock`](#commandsrelock) rebuilds it.
|
|
677
|
-
- **The conflict sweep reads resolvers from your default branch,** never
|
|
678
|
-
from a pull request's branch, so a new resolver is used once it has
|
|
679
|
-
merged.
|
|
750
|
+
Every setting `site` takes:
|
|
680
751
|
|
|
681
|
-
|
|
752
|
+
| Setting | What it sets | Default |
|
|
753
|
+
| --------------- | ----------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------- |
|
|
754
|
+
| `start` | A command that builds and serves the site, with `$PORT` set for it. Required | none |
|
|
755
|
+
| `url` | The address `start` serves the site at. Required | none |
|
|
756
|
+
| `design-guide` | A file of your own design rules, checked on top of the factory's | none |
|
|
757
|
+
| `pages` | A list of paths to look at | The pages in `/sitemap.xml`, or else the ones the home page links to |
|
|
758
|
+
| `widths` | A list of screen widths, in pixels | `[390, 1280]` |
|
|
759
|
+
| `hide` | A list of CSS selectors hidden before each screenshot, for something that floats over the page | none |
|
|
760
|
+
| `checks` | A list of your own measuring commands, described below | none |
|
|
761
|
+
| `max-pages` | How many changed pages the reviewer reads closely | `4` |
|
|
762
|
+
| `start-minutes` | How long to wait for the site to answer after `start` runs | `5` |
|
|
763
|
+
| `accessibility` | The WCAG level changed pages are checked against: `wcag22aa`, `wcag21aa`, `wcag2aa`, or `none` | `wcag22aa` |
|
|
764
|
+
| `new-values` | Whether the review points out font sizes, colors, spacing, and corner radii that the rest of the site doesn't use | `true` |
|
|
682
765
|
|
|
683
|
-
|
|
684
|
-
one. With it, and `factory-ui-reviewer` listed under
|
|
685
|
-
`plugins.build.reviewers`, a visible change is pictured before and after,
|
|
686
|
-
and the difference is reviewed.
|
|
766
|
+
The optional ones that take a list are written like this:
|
|
687
767
|
|
|
688
768
|
```yaml
|
|
689
769
|
site:
|
|
690
|
-
# A command that builds and serves the site from the repository's root,
|
|
691
|
-
# and the address it answers at. $PORT is set for you.
|
|
692
770
|
start: npm run build && npx serve out -p $PORT
|
|
693
771
|
url: http://localhost:$PORT
|
|
694
|
-
|
|
695
|
-
|
|
772
|
+
pages:
|
|
773
|
+
- /
|
|
774
|
+
- /pricing
|
|
775
|
+
hide:
|
|
776
|
+
- .chat-widget
|
|
777
|
+
checks:
|
|
778
|
+
- node scripts/check-tap-targets.mjs
|
|
696
779
|
```
|
|
697
780
|
|
|
698
|
-
|
|
699
|
-
|
|
700
|
-
|
|
701
|
-
|
|
702
|
-
| `design-guide` | none | A file of your own design rules |
|
|
703
|
-
| `pages` | found | The paths to look at. Otherwise from `/sitemap.xml`, or the home page's links |
|
|
704
|
-
| `widths` | `[390, 1280]` | The widths, in pixels, each page is shot at |
|
|
705
|
-
| `hide` | none | CSS selectors hidden before every picture, for something that floats |
|
|
706
|
-
| `checks` | none | Your own measuring commands. Each gets one JSON object on its standard input |
|
|
707
|
-
| `max-pages` | `4` | How many changed pages the agent reads closely |
|
|
708
|
-
| `start-minutes` | `5` | How long to wait for the site to answer after `start` is run |
|
|
709
|
-
| `accessibility` | `wcag22aa` | The WCAG level axe-core measures changed pages against: `wcag22aa`, `wcag21aa`, `wcag2aa`, or `none` |
|
|
710
|
-
| `new-values` | `true` | `false` leaves out the font sizes, colors, spacing, and radii the base site does not use |
|
|
711
|
-
|
|
712
|
-
- **`factory config get site`** prints every key in this
|
|
713
|
-
order, defaults included, one `key: value` line each.
|
|
714
|
-
`factory config get site.widths` prints one key, a list one item to a line, and `none` for a key that is not
|
|
715
|
-
set; `site.pages` prints `found` when it is not set.
|
|
716
|
-
- **`factory config check`** rejects a `site` with no `start` or `url`, a
|
|
717
|
-
`design-guide` that is not a file, and `factory-ui-reviewer` listed with no
|
|
718
|
-
`site`. It also fails when the `playwright` package is not found from the
|
|
719
|
-
repository's root: `npm install -D playwright`. It looks for the package and
|
|
720
|
-
never for a browser.
|
|
721
|
-
- **A `checks` command** gets `{"before", "after", "pages", "report"}` on its
|
|
722
|
-
standard input: the two addresses, the paths that changed, and the folder of
|
|
723
|
-
pictures. Each non-empty line it prints is a finding; its exit code says
|
|
724
|
-
nothing.
|
|
781
|
+
**A command under `checks`** is given one JSON object on its standard
|
|
782
|
+
input: `before` and `after`, the two sites' addresses; `pages`, the paths
|
|
783
|
+
that changed; and `report`, the folder of screenshots. Each line it prints
|
|
784
|
+
is reported as a finding. Its exit code is ignored.
|
|
725
785
|
|
|
726
786
|
### `auto-merge`
|
|
727
787
|
|
|
728
|
-
Which pull requests may merge without you.
|
|
788
|
+
Which pull requests may merge without you reading them.
|
|
729
789
|
|
|
730
790
|
```yaml
|
|
731
791
|
auto-merge:
|
|
@@ -741,108 +801,101 @@ auto-merge:
|
|
|
741
801
|
|
|
742
802
|
A pull request merges itself only when **all** of these hold:
|
|
743
803
|
|
|
744
|
-
1. every
|
|
745
|
-
2. no
|
|
804
|
+
1. every file it changes matches a pattern under `allow`;
|
|
805
|
+
2. no file it changes matches a pattern under `deny`;
|
|
746
806
|
3. every command under `commands` exits 0;
|
|
747
|
-
4. CI passes
|
|
748
|
-
|
|
749
|
-
|
|
750
|
-
|
|
751
|
-
|
|
752
|
-
|
|
753
|
-
|
|
754
|
-
|
|
755
|
-
|
|
756
|
-
|
|
757
|
-
- **
|
|
758
|
-
|
|
759
|
-
|
|
760
|
-
|
|
761
|
-
|
|
762
|
-
|
|
763
|
-
|
|
764
|
-
|
|
765
|
-
|
|
766
|
-
|
|
767
|
-
|
|
768
|
-
|
|
769
|
-
|
|
770
|
-
|
|
771
|
-
|
|
772
|
-
|
|
773
|
-
|
|
774
|
-
|
|
775
|
-
|
|
776
|
-
|
|
777
|
-
|
|
778
|
-
|
|
779
|
-
|
|
807
|
+
4. CI passes. With [`pr-review`](#pr-review) on, that includes the
|
|
808
|
+
automated review finding it ready.
|
|
809
|
+
|
|
810
|
+
Otherwise it waits for you, and the pull request says why.
|
|
811
|
+
|
|
812
|
+
- **By default every list is empty, so nothing merges without you.**
|
|
813
|
+
- **`deny` carves exceptions out of `allow`,** and always wins.
|
|
814
|
+
- **Some files always wait for you,** whatever `allow` says: the
|
|
815
|
+
factory's own, which are everything under `.claude/` and `.github/`,
|
|
816
|
+
every `CLAUDE.md` and `AGENTS.md`, and `openspec/config.yaml`.
|
|
817
|
+
- **Start with a short `allow` list** and add to it. Too wide a list
|
|
818
|
+
merges changes you meant to read.
|
|
819
|
+
- **`factory config check` warns about a pattern that matches no file,**
|
|
820
|
+
since a stale pattern is how a policy quietly stops meaning anything.
|
|
821
|
+
|
|
822
|
+
**A command under `commands`** is your own check. It runs once for each
|
|
823
|
+
pull request, from a checkout of your default branch, never the pull
|
|
824
|
+
request's, and reads one JSON object on its standard input:
|
|
825
|
+
|
|
826
|
+
```json
|
|
827
|
+
{
|
|
828
|
+
"repository": "harbor-goods/storefront",
|
|
829
|
+
"pull": 42,
|
|
830
|
+
"base": "the commit the pull request branched from",
|
|
831
|
+
"head": "the pull request's newest commit",
|
|
832
|
+
"files": [
|
|
833
|
+
{
|
|
834
|
+
"filename": "src/a.ts",
|
|
835
|
+
"previous_filename": "src/b.ts",
|
|
836
|
+
"status": "renamed"
|
|
837
|
+
}
|
|
838
|
+
]
|
|
839
|
+
}
|
|
840
|
+
```
|
|
841
|
+
|
|
842
|
+
It exits 0 to let the pull request merge, and anything else to hold it for
|
|
843
|
+
you. Each line it prints is shown as a reason.
|
|
844
|
+
|
|
845
|
+
What a held pull request says, one line for each file or command that held
|
|
846
|
+
it:
|
|
847
|
+
|
|
848
|
+
| It says | Because |
|
|
849
|
+
| -------------------------------------- | ----------------------------------------------- |
|
|
850
|
+
| `PATH: the factory's own files` | The file is one of the factory's, listed above |
|
|
851
|
+
| `PATH: held by auto-merge.deny` | The file matches `deny` |
|
|
852
|
+
| `PATH: not in auto-merge.allow` | The file matches nothing in `allow` |
|
|
853
|
+
| What your command printed | Your command exited with something other than 0 |
|
|
854
|
+
| `held by COMMAND` | The same, and the command printed nothing |
|
|
855
|
+
| `held by COMMAND: it could not be run` | The command was not found or could not start |
|
|
856
|
+
| `no changed files` | The pull request changes nothing |
|
|
857
|
+
|
|
858
|
+
A renamed file is checked under both its old and new names.
|
|
780
859
|
|
|
781
|
-
|
|
782
|
-
|
|
783
|
-
|
|
784
|
-
|
|
785
|
-
|
|
786
|
-
|
|
787
|
-
that held it, in this order of checking:
|
|
788
|
-
|
|
789
|
-
| Reason | Why |
|
|
790
|
-
| -------------------------------------- | --------------------------------------------------- |
|
|
791
|
-
| `PATH: the factory's own files` | One of the files below, whatever `allow` says |
|
|
792
|
-
| `PATH: held by auto-merge.deny` | It matches `deny` |
|
|
793
|
-
| `PATH: not in auto-merge.allow` | It matches nothing in `allow` |
|
|
794
|
-
| What a command printed | A command exited with anything but 0 |
|
|
795
|
-
| `held by COMMAND` | A command exited with anything but 0, printing none |
|
|
796
|
-
| `held by COMMAND: it could not be run` | The command was not found or could not be started |
|
|
797
|
-
| `no changed files` | The pull request changes nothing |
|
|
798
|
-
|
|
799
|
-
A renamed file is checked under both its names.
|
|
800
|
-
|
|
801
|
-
- **If a pattern matches no file:** `factory config check`
|
|
802
|
-
warns, since a stale pattern is how a policy rots.
|
|
803
|
-
- **If `allow` is too wide:** changes you meant to read merge unread.
|
|
804
|
-
Start with a short list and add to it.
|
|
805
|
-
- **If a `deny` pattern matches nothing inside `allow`:** it does nothing,
|
|
806
|
-
and `factory config check` says so.
|
|
807
|
-
|
|
808
|
-
### `ci-review`
|
|
809
|
-
|
|
810
|
-
The automated review of every pull request: Claude reads each one once it
|
|
811
|
-
is marked ready, comments on what it finds, and posts a verdict. It is on
|
|
812
|
-
while `ci-review` is written, even with nothing under it, and `factory
|
|
813
|
-
sync` then writes its workflow, `.github/workflows/factory-claude-review.yml`.
|
|
814
|
-
[Setting up on GitHub](github/setup.md) has what it needs on GitHub.
|
|
860
|
+
### `pr-review`
|
|
861
|
+
|
|
862
|
+
An AI code review of every pull request. Once a pull request is marked
|
|
863
|
+
ready, the coding agent reads it, comments on what it finds, and posts a
|
|
864
|
+
verdict that [`auto-merge`](#auto-merge) waits for. It is separate from
|
|
865
|
+
your own CI, which keeps running your tests as before.
|
|
815
866
|
|
|
816
867
|
```yaml
|
|
817
|
-
|
|
818
|
-
# "commands" are what it may run to confirm a finding, beside reading the
|
|
819
|
-
# pull request and commenting on it.
|
|
820
|
-
ci-review:
|
|
868
|
+
pr-review:
|
|
821
869
|
commands:
|
|
822
870
|
- npm test
|
|
823
871
|
- npx tsc --noEmit
|
|
824
872
|
```
|
|
825
873
|
|
|
826
|
-
- **Default:** off.
|
|
827
|
-
|
|
828
|
-
|
|
829
|
-
|
|
830
|
-
|
|
831
|
-
|
|
832
|
-
|
|
833
|
-
|
|
834
|
-
|
|
835
|
-
|
|
836
|
-
|
|
874
|
+
- **Default:** off. Writing `pr-review` turns it on, even with nothing
|
|
875
|
+
under it (`pr-review: {}`), and `factory sync` then adds its workflow,
|
|
876
|
+
`.github/workflows/factory-claude-review.yml`.
|
|
877
|
+
[Setting up on GitHub](github/setup.md) has what it needs there.
|
|
878
|
+
- **`commands` is what the reviewer may run** to confirm something it
|
|
879
|
+
suspects, beyond reading the code and commenting. It doesn't run them on
|
|
880
|
+
every pull request. Without any, it only reads. A command can't contain
|
|
881
|
+
a comma, a parenthesis, or a quote.
|
|
882
|
+
- **Each command you list runs the pull request's own code,** in a job
|
|
883
|
+
that holds the review's token. Only list commands you'd be comfortable
|
|
884
|
+
running on any pull request.
|
|
885
|
+
- **It reads this list from the branch the pull request merges into,** so
|
|
886
|
+
a pull request can't widen what its own review may run.
|
|
887
|
+
- **To turn it off,** delete `pr-review` and run `factory sync`, which
|
|
888
|
+
removes the workflow.
|
|
889
|
+
- `factory review tools` prints everything the reviewer may use.
|
|
837
890
|
|
|
838
891
|
### `approvers`
|
|
839
892
|
|
|
840
|
-
_[Planned](developing.md#what-is-built)_: `factory config check`
|
|
841
|
-
|
|
893
|
+
_[Planned](developing.md#what-is-built)_: `factory config check` refuses
|
|
894
|
+
this setting until it is built.
|
|
842
895
|
|
|
843
|
-
The people whose comments a session
|
|
844
|
-
of a ticket to Ready counts as
|
|
845
|
-
information.
|
|
896
|
+
The people whose comments a session takes as instructions, and whose move
|
|
897
|
+
of a ticket to Ready counts as approving it. Everyone else's comments are
|
|
898
|
+
read as information.
|
|
846
899
|
|
|
847
900
|
```yaml
|
|
848
901
|
approvers:
|
|
@@ -850,20 +903,16 @@ approvers:
|
|
|
850
903
|
- a-teammate
|
|
851
904
|
```
|
|
852
905
|
|
|
853
|
-
- **Default:** the repository's owner
|
|
854
|
-
|
|
855
|
-
|
|
856
|
-
|
|
857
|
-
flags a name that is not an account with access to the repository.
|
|
858
|
-
|
|
859
|
-
A session posts through a person's account too, so it marks its own comments
|
|
860
|
-
and never takes one as an instruction.
|
|
906
|
+
- **Default:** the repository's owner, so a repository with one person
|
|
907
|
+
leaves it out.
|
|
908
|
+
- **If a name is wrong,** that person's comments are treated as
|
|
909
|
+
information, and a ticket they approve is not built.
|
|
861
910
|
|
|
862
911
|
### `rules`
|
|
863
912
|
|
|
864
|
-
|
|
865
|
-
`factory sync`
|
|
866
|
-
|
|
913
|
+
Two numbers the factory's rules use, for a repository that wants
|
|
914
|
+
different ones. Run `factory sync` after changing one, since it writes the
|
|
915
|
+
number into the rules and skills that use it.
|
|
867
916
|
|
|
868
917
|
```yaml
|
|
869
918
|
rules:
|
|
@@ -871,105 +920,71 @@ rules:
|
|
|
871
920
|
review-rounds: 2
|
|
872
921
|
```
|
|
873
922
|
|
|
874
|
-
|
|
|
875
|
-
| -------------------- |
|
|
876
|
-
| `small-change-lines` |
|
|
877
|
-
| `review-rounds` |
|
|
878
|
-
|
|
879
|
-
- **If a value is not a whole number above zero:**
|
|
880
|
-
`factory config check` fails and names the key.
|
|
923
|
+
| Setting | What it sets | Default |
|
|
924
|
+
| -------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- |
|
|
925
|
+
| `small-change-lines` | How many changed lines, outside tests, specs, and content, a change can have and still count as [small](workflow.md#sizing-the-work-to-the-change), which skips the heavier steps | `30` |
|
|
926
|
+
| `review-rounds` | How many rounds of review comments a session answers before it hands what is left to you | `2` |
|
|
881
927
|
|
|
882
|
-
Any rule that
|
|
883
|
-
your own instructions for the agent, such as
|
|
884
|
-
factory's rules.
|
|
928
|
+
Each must be a whole number above zero. Any rule that isn't a number, you
|
|
929
|
+
change by saying so in your own instructions for the coding agent, such as
|
|
930
|
+
`CLAUDE.md`, which win over the factory's rules.
|
|
885
931
|
|
|
886
932
|
## Checking the file
|
|
887
933
|
|
|
888
|
-
| Command
|
|
889
|
-
| ------------------------ |
|
|
890
|
-
| Your editor |
|
|
891
|
-
| `factory config check` |
|
|
892
|
-
| `factory config explain` | Prints
|
|
893
|
-
| `factory doctor` | Checks the file against
|
|
934
|
+
| Command or tool | What it does |
|
|
935
|
+
| ------------------------ | ---------------------------------------------------------------------------------------------------- |
|
|
936
|
+
| Your editor | Flags a misspelled setting as you type, using the schema named on the file's first line |
|
|
937
|
+
| `factory config check` | Stops on anything the factory can't use, and warns about patterns that match nothing. CI runs it |
|
|
938
|
+
| `factory config explain` | Prints the whole file as the factory reads it, with every default written out and marked `# default` |
|
|
939
|
+
| `factory doctor` | Checks the file against your real board, and that each secret the factory needs is set |
|
|
894
940
|
|
|
895
|
-
The first line
|
|
941
|
+
The first line `factory init` writes is optional. It points your editor at
|
|
942
|
+
the schema in the installed package:
|
|
896
943
|
|
|
897
944
|
```yaml
|
|
898
945
|
# $schema: ../node_modules/@davidbyoung/software-factory/settings.schema.json
|
|
899
946
|
```
|
|
900
947
|
|
|
901
|
-
|
|
902
|
-
|
|
903
|
-
|
|
904
|
-
the installed version and works offline. In a checkout with nothing installed
|
|
905
|
-
the editor finds no schema and says so.
|
|
906
|
-
|
|
907
|
-
The editor's check is a help. It accepts some files
|
|
908
|
-
`factory config check` refuses, such as a plug-in whose
|
|
909
|
-
file does not exist, and that command is the one that counts.
|
|
948
|
+
JetBrains editors and Visual Studio Code's YAML extension both read it.
|
|
949
|
+
The editor's check is only a help: it accepts some things
|
|
950
|
+
`factory config check` refuses, such as a plugin whose file doesn't exist.
|
|
910
951
|
|
|
911
952
|
## Three complete files
|
|
912
953
|
|
|
954
|
+
The skills, agents, and scripts these files name are examples. Yours would
|
|
955
|
+
have to exist in your repository for `factory config check` to pass.
|
|
956
|
+
|
|
913
957
|
### A web application with its own reviewers
|
|
914
958
|
|
|
915
|
-
An online store
|
|
916
|
-
|
|
917
|
-
|
|
918
|
-
|
|
959
|
+
An online store with a board, a skill of its own for building new API
|
|
960
|
+
endpoints, two reviewers of its own, and the factory's UI reviewer.
|
|
961
|
+
Changes to components, styles, docs, and tests merge unread, except
|
|
962
|
+
anything touching checkout or consent.
|
|
919
963
|
|
|
920
964
|
```yaml
|
|
921
965
|
# $schema: ../node_modules/@davidbyoung/software-factory/settings.schema.json
|
|
922
|
-
# Settings for the software factory. Every key is explained in
|
|
923
|
-
# docs/configuration.md in the factory's repository.
|
|
924
|
-
#
|
|
925
|
-
# Anything not listed here keeps its default: no pull request merges without
|
|
926
|
-
# you, a build starts when you tell a session to work a ticket, and only the
|
|
927
|
-
# built-in reviewers run.
|
|
928
|
-
#
|
|
929
|
-
# "version" is the shape of this file, not the factory's version.
|
|
930
966
|
version: 2
|
|
931
967
|
repository: harbor-goods/storefront
|
|
932
968
|
|
|
933
|
-
# Where tickets live. "board" is the number in your GitHub Project's address.
|
|
934
969
|
tickets:
|
|
935
|
-
type: github
|
|
936
970
|
board: 1
|
|
937
971
|
|
|
938
|
-
# What starts a build once a ticket is moved to Ready on the board:
|
|
939
|
-
# own-server (a small poller you host), github-action, or manual (you tell
|
|
940
|
-
# a session to build it).
|
|
941
972
|
builds:
|
|
942
973
|
trigger: own-server
|
|
943
974
|
|
|
944
|
-
# How the written spec for a change your users will see is kept: openspec,
|
|
945
|
-
# or none.
|
|
946
975
|
specs: openspec
|
|
947
976
|
|
|
948
|
-
# Every command a build runs, each from the repository's root.
|
|
949
977
|
commands:
|
|
950
|
-
|
|
951
|
-
|
|
978
|
+
build-setup:
|
|
979
|
+
- npx playwright install --with-deps chromium
|
|
952
980
|
before-commit:
|
|
953
981
|
- npm run -s format:check
|
|
954
982
|
- npx tsc --noEmit
|
|
955
983
|
- npm run -s lint
|
|
956
|
-
# Run before a session reports a task done, in order. A build cannot
|
|
957
|
-
# finish until they pass.
|
|
958
984
|
gate:
|
|
959
985
|
- npm run check
|
|
960
|
-
# Runs one test alone. $FILE is the test's file and $NAME the test's
|
|
961
|
-
# name, which is empty when the whole file is wanted.
|
|
962
986
|
test-one: npx vitest run $FILE -t "$NAME"
|
|
963
987
|
|
|
964
|
-
# Your own skills and agents, grouped by the phase they work in. A skill is
|
|
965
|
-
# a set of instructions a session follows; an agent is a separate reviewer a
|
|
966
|
-
# session launches. Refining, building, and reviewing tests are built in.
|
|
967
|
-
# Under "build":
|
|
968
|
-
# builders each builds a ticket that carries one of its "labels" (label
|
|
969
|
-
# names), in place of the built-in build
|
|
970
|
-
# reviewers each is asked to read a finished change when it touches a
|
|
971
|
-
# path matching its "files", and reports problems; it edits
|
|
972
|
-
# nothing
|
|
973
988
|
plugins:
|
|
974
989
|
build:
|
|
975
990
|
builders:
|
|
@@ -980,24 +995,18 @@ plugins:
|
|
|
980
995
|
- agent: migration-reviewer
|
|
981
996
|
files:
|
|
982
997
|
- db/migrations/**
|
|
983
|
-
- agent:
|
|
998
|
+
- agent: accessibility-reviewer
|
|
984
999
|
files:
|
|
985
1000
|
- src/components/**
|
|
986
|
-
|
|
987
|
-
- agent: accessibility-reviewer
|
|
1001
|
+
- agent: factory-ui-reviewer
|
|
988
1002
|
files:
|
|
989
1003
|
- src/components/**
|
|
1004
|
+
- src/styles/**
|
|
990
1005
|
|
|
991
|
-
# How the factory looks at this website, for factory-ui-reviewer.
|
|
992
1006
|
site:
|
|
993
1007
|
start: npm run build && npx serve out -p $PORT
|
|
994
1008
|
url: http://localhost:$PORT
|
|
995
1009
|
|
|
996
|
-
# Which pull requests may merge without you. Patterns are globs matched
|
|
997
|
-
# against paths from the repository's root, and deny wins over allow. A pull
|
|
998
|
-
# request merges itself only when every changed file matches "allow", none
|
|
999
|
-
# matches "deny", every command under "commands" (if you list any) exits 0
|
|
1000
|
-
# when CI runs it, and CI passes. Anything else waits for you.
|
|
1001
1010
|
auto-merge:
|
|
1002
1011
|
allow:
|
|
1003
1012
|
- docs/**
|
|
@@ -1010,96 +1019,60 @@ auto-merge:
|
|
|
1010
1019
|
- src/components/consent/**
|
|
1011
1020
|
commands:
|
|
1012
1021
|
- node scripts/public-api-changed.mjs
|
|
1022
|
+
|
|
1023
|
+
pr-review:
|
|
1024
|
+
commands:
|
|
1025
|
+
- npm test
|
|
1013
1026
|
```
|
|
1014
1027
|
|
|
1015
|
-
### A
|
|
1028
|
+
### A small website
|
|
1016
1029
|
|
|
1017
|
-
A
|
|
1018
|
-
|
|
1030
|
+
A marketing site with a board and nothing else changed. Builds start when
|
|
1031
|
+
someone asks a session, since `builds.trigger` defaults to `manual`.
|
|
1019
1032
|
|
|
1020
1033
|
```yaml
|
|
1021
1034
|
# $schema: ../node_modules/@davidbyoung/software-factory/settings.schema.json
|
|
1022
|
-
# Settings for the software factory. Every key is explained in
|
|
1023
|
-
# docs/configuration.md in the factory's repository.
|
|
1024
|
-
#
|
|
1025
|
-
# Anything not listed here keeps its default: no pull request merges without
|
|
1026
|
-
# you, a build starts when you tell a session to work a ticket, and only the
|
|
1027
|
-
# built-in reviewers run.
|
|
1028
|
-
#
|
|
1029
|
-
# "version" is the shape of this file, not the factory's version.
|
|
1030
1035
|
version: 2
|
|
1031
1036
|
repository: riverbend-studio/site
|
|
1032
1037
|
|
|
1033
|
-
# Where tickets live. "board" is the number in your GitHub Project's address.
|
|
1034
1038
|
tickets:
|
|
1035
1039
|
board: 4
|
|
1036
1040
|
|
|
1037
|
-
# Every command a build runs, each from the repository's root.
|
|
1038
1041
|
commands:
|
|
1039
|
-
# Run on the session's machine before every commit it makes. If one
|
|
1040
|
-
# fails, the commit is blocked.
|
|
1041
1042
|
before-commit:
|
|
1042
1043
|
- npm run lint
|
|
1043
|
-
- npm run typecheck
|
|
1044
|
-
# Run before a session reports a task done, in order. A build cannot
|
|
1045
|
-
# finish until they pass.
|
|
1046
1044
|
gate:
|
|
1045
|
+
- npm run lint
|
|
1046
|
+
- npm run typecheck
|
|
1047
1047
|
- npm test
|
|
1048
1048
|
```
|
|
1049
1049
|
|
|
1050
|
-
|
|
1051
|
-
`builds.trigger` defaults to `manual`.
|
|
1050
|
+
### A project that isn't JavaScript
|
|
1052
1051
|
|
|
1053
|
-
|
|
1054
|
-
|
|
1055
|
-
|
|
1056
|
-
documentation merge unread and has one reviewer of its own for its public
|
|
1057
|
-
API.
|
|
1052
|
+
A PHP library. Its commands are Composer's and PHPUnit's, and a cloud
|
|
1053
|
+
build installs its dependencies first. Docs merge unread, and one reviewer
|
|
1054
|
+
of its own reads changes to its public API.
|
|
1058
1055
|
|
|
1059
1056
|
```yaml
|
|
1060
1057
|
# $schema: ../node_modules/@davidbyoung/software-factory/settings.schema.json
|
|
1061
|
-
# Settings for the software factory. Every key is explained in
|
|
1062
|
-
# docs/configuration.md in the factory's repository.
|
|
1063
|
-
#
|
|
1064
|
-
# Anything not listed here keeps its default: no pull request merges without
|
|
1065
|
-
# you, a build starts when you tell a session to work a ticket, and only the
|
|
1066
|
-
# built-in reviewers run.
|
|
1067
|
-
#
|
|
1068
|
-
# "version" is the shape of this file, not the factory's version.
|
|
1069
1058
|
version: 2
|
|
1070
1059
|
repository: northwind-php/ledger
|
|
1071
1060
|
|
|
1072
|
-
# Where tickets live. "board" is the number in your GitHub Project's address.
|
|
1073
1061
|
tickets:
|
|
1074
|
-
type: github
|
|
1075
1062
|
board: 2
|
|
1076
1063
|
|
|
1077
|
-
# Every command a build runs, each from the repository's root.
|
|
1078
1064
|
commands:
|
|
1079
|
-
|
|
1080
|
-
|
|
1065
|
+
build-setup:
|
|
1066
|
+
- composer install --no-interaction
|
|
1081
1067
|
before-commit:
|
|
1082
1068
|
- composer lint
|
|
1083
|
-
- composer analyse
|
|
1084
|
-
# Run before a session reports a task done, in order. A build cannot
|
|
1085
|
-
# finish until they pass.
|
|
1086
1069
|
gate:
|
|
1087
1070
|
- composer lint
|
|
1088
1071
|
- composer analyse
|
|
1089
1072
|
- composer test
|
|
1090
|
-
# Runs one test alone. $FILE is the test's file and $NAME the test's
|
|
1091
|
-
# name, which is empty when the whole file is wanted.
|
|
1092
1073
|
test-one: vendor/bin/phpunit $FILE ${NAME:+--filter "$NAME"}
|
|
1074
|
+
relock: composer update --lock
|
|
1093
1075
|
|
|
1094
|
-
# Your own skills and agents, grouped by the phase they work in. A skill is
|
|
1095
|
-
# a set of instructions a session follows; an agent is a separate reviewer a
|
|
1096
|
-
# session launches. Refining, building, and reviewing tests are built in.
|
|
1097
|
-
# Under "build":
|
|
1098
|
-
# builders each builds a ticket that carries one of its "labels" (label
|
|
1099
|
-
# names), in place of the built-in build
|
|
1100
|
-
# reviewers each is asked to read a finished change when it touches a
|
|
1101
|
-
# path matching its "files", and reports problems; it edits
|
|
1102
|
-
# nothing
|
|
1103
1076
|
plugins:
|
|
1104
1077
|
build:
|
|
1105
1078
|
reviewers:
|
|
@@ -1107,25 +1080,9 @@ plugins:
|
|
|
1107
1080
|
files:
|
|
1108
1081
|
- src/**
|
|
1109
1082
|
|
|
1110
|
-
# Which pull requests may merge without you. Patterns are globs matched
|
|
1111
|
-
# against paths from the repository's root, and deny wins over allow. A pull
|
|
1112
|
-
# request merges itself only when every changed file matches "allow", none
|
|
1113
|
-
# matches "deny", every command under "commands" (if you list any) exits 0
|
|
1114
|
-
# when CI runs it, and CI passes. Anything else waits for you.
|
|
1115
1083
|
auto-merge:
|
|
1116
1084
|
allow:
|
|
1117
1085
|
- docs/**
|
|
1118
1086
|
deny:
|
|
1119
1087
|
- docs/security/**
|
|
1120
1088
|
```
|
|
1121
|
-
|
|
1122
|
-
If this team moved its tickets to Jira, only the `tickets` block would
|
|
1123
|
-
change. **Only GitHub is built**; the block below shows the shape the
|
|
1124
|
-
design leaves room for.
|
|
1125
|
-
|
|
1126
|
-
```yaml
|
|
1127
|
-
tickets:
|
|
1128
|
-
type: jira
|
|
1129
|
-
site: northwind.atlassian.net
|
|
1130
|
-
project: LEDGER
|
|
1131
|
-
```
|