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