@davidbyoung/software-factory 0.1.3 → 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 +12 -11
- package/actions/factory-agent/action.yml +1 -1
- package/agents/factory-e2e-reviewer.md +102 -0
- package/agents/factory-test-reviewer.md +26 -64
- package/agents/factory-ticket-readiness.md +14 -6
- package/dist/cli.mjs +28 -1
- package/dist/code-host/github-setup.mjs +1 -1
- package/dist/commands.d.mts +16 -0
- package/dist/commands.mjs +129 -0
- package/dist/config.d.mts +61 -13
- package/dist/config.mjs +271 -69
- package/dist/deps.d.mts +7 -4
- package/dist/deps.mjs +20 -9
- package/dist/doctor.d.mts +3 -2
- package/dist/doctor.mjs +19 -4
- package/dist/explain.d.mts +4 -2
- package/dist/explain.mjs +70 -23
- package/dist/guard-commit.d.mts +7 -2
- package/dist/guard-commit.mjs +58 -21
- package/dist/init.d.mts +4 -2
- package/dist/init.mjs +18 -8
- package/dist/lib/default-branch.d.mts +35 -0
- package/dist/lib/default-branch.mjs +117 -0
- package/dist/lib/refined-check.d.mts +7 -0
- package/dist/lib/refined-check.mjs +76 -0
- 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/patch-coverage.d.mts +13 -0
- package/dist/patch-coverage.mjs +73 -0
- package/dist/pr-watch.d.mts +3 -2
- package/dist/pr-watch.mjs +22 -5
- package/dist/pr.mjs +34 -2
- package/dist/review-cost.mjs +1 -1
- package/dist/review-tools.mjs +3 -3
- package/dist/session-start.d.mts +23 -13
- package/dist/session-start.mjs +56 -44
- package/dist/site/servers.d.mts +6 -2
- package/dist/site/servers.mjs +14 -9
- package/dist/site.mjs +2 -2
- package/dist/sync.d.mts +8 -2
- package/dist/sync.mjs +41 -7
- package/dist/ticket.mjs +19 -1
- package/docs/builds.md +8 -8
- package/docs/cli.md +82 -45
- package/docs/configuration.md +838 -565
- package/docs/design.md +17 -4
- package/docs/developing.md +44 -8
- package/docs/existing-repo.md +9 -7
- package/docs/github/by-hand.md +27 -14
- package/docs/github/reference.md +21 -16
- package/docs/github/setup.md +14 -11
- package/docs/glossary.md +14 -5
- package/docs/limitations.md +27 -2
- package/docs/plugins.md +307 -52
- package/docs/quick-start.md +37 -9
- package/docs/removing.md +2 -2
- package/docs/skills.md +103 -54
- package/docs/updating.md +149 -3
- package/docs/workflow.md +13 -10
- package/package.json +1 -1
- package/review.md +20 -11
- package/rules.md +23 -19
- package/settings.schema.json +292 -72
- package/skills/factory-address-review/SKILL.md +50 -30
- package/skills/factory-build/SKILL.md +76 -23
- package/skills/factory-deps/SKILL.md +46 -21
- package/skills/factory-design/SKILL.md +18 -9
- package/skills/factory-diagnose/SKILL.md +22 -20
- package/skills/factory-mutate/SKILL.md +38 -24
- package/skills/factory-refine/SKILL.md +55 -31
- package/skills/factory-resolve-conflicts/SKILL.md +76 -34
- package/skills/factory-trace/SKILL.md +3 -2
- package/workflows/factory-build.yml +1 -1
- package/workflows/factory-claude-review.yml +1 -1
- package/workflows/factory-conflicts.yml +8 -8
- package/workflows/factory-deps.yml +1 -1
- package/workflows/factory-review.yml +1 -1
- package/skills/factory-address-review/patch-coverage.py +0 -68
package/docs/configuration.md
CHANGED
|
@@ -1,95 +1,139 @@
|
|
|
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
|
-
|
|
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:
|
|
18
55
|
|
|
19
56
|
```yaml
|
|
20
57
|
specs: openspec
|
|
21
58
|
```
|
|
22
59
|
|
|
23
|
-
means the same as:
|
|
24
|
-
|
|
25
60
|
```yaml
|
|
26
61
|
specs:
|
|
27
62
|
type: openspec
|
|
28
63
|
```
|
|
29
64
|
|
|
30
|
-
- **
|
|
31
|
-
|
|
65
|
+
- **Your comments are kept.** `factory init` writes a comment above each
|
|
66
|
+
section, and updates never remove yours.
|
|
32
67
|
|
|
33
68
|
## The shortest file
|
|
34
69
|
|
|
35
70
|
```yaml
|
|
36
|
-
version:
|
|
71
|
+
version: 2
|
|
37
72
|
repository: your-name/your-repo
|
|
38
73
|
```
|
|
39
74
|
|
|
40
|
-
With this,
|
|
41
|
-
merges without you, and there is no board.
|
|
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.
|
|
42
79
|
|
|
43
80
|
## The settings most repositories change
|
|
44
81
|
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
[
|
|
52
|
-
|
|
53
|
-
-
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
|
|
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
|
|
86
|
+
[`commands.before-commit`](#commandsbefore-commit).
|
|
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
|
+
```
|
|
61
102
|
|
|
62
|
-
|
|
63
|
-
`factory sync
|
|
64
|
-
|
|
65
|
-
|
|
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.
|
|
66
108
|
|
|
67
|
-
## Every
|
|
109
|
+
## Every setting
|
|
68
110
|
|
|
69
111
|
### `version`
|
|
70
112
|
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
your file when it does.
|
|
113
|
+
Which layout of this file you are using. It is not the factory's version.
|
|
114
|
+
Write `2`.
|
|
74
115
|
|
|
75
|
-
- **Default:** none.
|
|
76
|
-
- **If wrong
|
|
77
|
-
|
|
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.
|
|
78
121
|
|
|
79
122
|
### `repository`
|
|
80
123
|
|
|
81
|
-
|
|
124
|
+
Your repository, as `owner/name`, such as `harbor-goods/storefront`.
|
|
82
125
|
|
|
83
|
-
- **Default:** none.
|
|
84
|
-
- **If wrong
|
|
85
|
-
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.
|
|
86
129
|
|
|
87
|
-
It is
|
|
88
|
-
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.
|
|
89
133
|
|
|
90
134
|
### `tickets`
|
|
91
135
|
|
|
92
|
-
Where tickets live and
|
|
136
|
+
Where your tickets live, and which board shows them.
|
|
93
137
|
|
|
94
138
|
```yaml
|
|
95
139
|
tickets:
|
|
@@ -97,346 +141,651 @@ tickets:
|
|
|
97
141
|
board: 1
|
|
98
142
|
```
|
|
99
143
|
|
|
100
|
-
|
|
101
|
-
|
|
102
|
-
|
|
103
|
-
|
|
104
|
-
|
|
105
|
-
- **With `type: github`,** the board is a GitHub Project, and its number is
|
|
106
|
-
the last part of its address.
|
|
107
|
-
- **With no board,** a ticket's state lives in its comments,
|
|
108
|
-
`factory status` still shows it, and builds start only
|
|
109
|
-
when you tell a session.
|
|
110
|
-
- **If `board` is wrong:** the board sync fails and names the board it could
|
|
111
|
-
not read.
|
|
112
|
-
- **One board can hold more than one repository's tickets.** Give each
|
|
113
|
-
repository the same `board`: each one's sync, `status`, and poller read
|
|
114
|
-
only the cards for its own issues, and GitHub's Repository field tells
|
|
115
|
-
them apart on the board.
|
|
116
|
-
|
|
117
|
-
A board shows the six states of [Workflow](workflow.md) as columns, and
|
|
118
|
-
keeps three fields the factory writes. A repository that writes nothing
|
|
119
|
-
below gets the factory's own board. `columns` and `fields` need a `board`.
|
|
120
|
-
|
|
121
|
-
#### `tickets.columns`
|
|
122
|
-
|
|
123
|
-
Which of your board's columns shows each state. Leave a key out to use the
|
|
124
|
-
factory's own name for it. `none` means your board has no column for that
|
|
125
|
-
state.
|
|
126
|
-
|
|
127
|
-
| Key | State | Default column | May be `none` |
|
|
128
|
-
| ---------- | -------- | -------------- | ------------- |
|
|
129
|
-
| `backlog` | backlog | Backlog | No |
|
|
130
|
-
| `refining` | refining | In refinement | Yes |
|
|
131
|
-
| `ready` | ready | Ready | Yes |
|
|
132
|
-
| `building` | building | In progress | Yes |
|
|
133
|
-
| `review` | review | In review | Yes |
|
|
134
|
-
| `done` | done | Done | Yes |
|
|
135
|
-
|
|
136
|
-
- **A name matches whatever its capitals and the spaces around it,** so
|
|
137
|
-
the default "In progress" finds a board's "In Progress".
|
|
138
|
-
- **A ticket shows in its state's column. When that state has none, it
|
|
139
|
-
shows in the column of the nearest earlier state that has one.** Nothing
|
|
140
|
-
but an approved ticket shows in the `ready` column, so a state with no
|
|
141
|
-
column passes over it.
|
|
142
|
-
- **A card in a column no state names is left alone.** The sync writes none
|
|
143
|
-
of its fields while it sits there, and nothing builds it.
|
|
144
|
-
- **With `ready: none`,** no column approves a build. A build starts only
|
|
145
|
-
when you tell a session to build the ticket or run
|
|
146
|
-
`factory build N`, so
|
|
147
|
-
`factory config check` requires `builds.trigger: manual`.
|
|
148
|
-
- **If a repository's `ready` column has another name,** a poller you host
|
|
149
|
-
needs it too: see `FACTORY_READY_COLUMN` in [Builds](builds.md). A
|
|
150
|
-
scheduled one reads it from here.
|
|
151
|
-
- `factory config get tickets.columns.ready` prints the
|
|
152
|
-
name in effect, or `none`.
|
|
153
|
-
|
|
154
|
-
#### `tickets.fields`
|
|
155
|
-
|
|
156
|
-
Which of your board's fields the sync writes: `session`, `runs-in`, and
|
|
157
|
-
`cost`, with the defaults Session, Runs in, and Cost. Each may be `none`.
|
|
158
|
-
The board's own status field keeps its name, Status on a GitHub Project,
|
|
159
|
-
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.
|
|
160
149
|
|
|
161
|
-
|
|
162
|
-
|
|
163
|
-
|
|
164
|
-
| name the field | lacks it, or it has the wrong type | fails, naming the field and its key |
|
|
165
|
-
| leave default | has it, with the right type | writes it |
|
|
166
|
-
| leave default | lacks it | skips it, with a note |
|
|
167
|
-
| leave default | has it, with the wrong type | fails, and says to name another field or set the key to `none` |
|
|
168
|
-
| 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.
|
|
169
153
|
|
|
170
|
-
|
|
171
|
-
|
|
172
|
-
|
|
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.
|
|
173
157
|
|
|
174
|
-
|
|
158
|
+
`factory board check` reads your board and says what the factory will do
|
|
159
|
+
with it.
|
|
175
160
|
|
|
176
|
-
|
|
177
|
-
tickets:
|
|
178
|
-
type: github
|
|
179
|
-
board: 1
|
|
180
|
-
```
|
|
161
|
+
#### `tickets.columns`
|
|
181
162
|
|
|
182
|
-
|
|
183
|
-
|
|
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:
|
|
184
169
|
|
|
185
170
|
```yaml
|
|
186
171
|
tickets:
|
|
187
|
-
type: github
|
|
188
172
|
board: 7
|
|
189
173
|
columns:
|
|
190
174
|
backlog: Todo
|
|
175
|
+
building: In Progress
|
|
176
|
+
done: Done
|
|
191
177
|
refining: none
|
|
192
178
|
ready: none
|
|
193
|
-
building: In Progress
|
|
194
179
|
review: none
|
|
195
|
-
done: Done
|
|
196
180
|
builds:
|
|
197
181
|
trigger: manual
|
|
198
182
|
```
|
|
199
183
|
|
|
200
|
-
|
|
201
|
-
|
|
202
|
-
|
|
203
|
-
|
|
204
|
-
|
|
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.
|
|
205
217
|
|
|
206
|
-
`
|
|
207
|
-
else. Only `github` is built. Any other value fails
|
|
208
|
-
`factory config check` and every ticket command with:
|
|
209
|
-
`tickets.type "X" is not supported. "github" is the only ticket system built.`
|
|
218
|
+
#### `tickets.fields`
|
|
210
219
|
|
|
211
|
-
|
|
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:
|
|
212
222
|
|
|
213
|
-
|
|
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:
|
|
214
232
|
|
|
215
233
|
```yaml
|
|
216
|
-
|
|
217
|
-
|
|
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
|
|
218
239
|
```
|
|
219
240
|
|
|
220
|
-
|
|
221
|
-
|
|
222
|
-
|
|
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`
|
|
256
|
+
|
|
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.
|
|
223
259
|
|
|
224
|
-
|
|
225
|
-
|
|
226
|
-
|
|
227
|
-
`factory config check`, and every command that reads the
|
|
228
|
-
settings and reaches a pull request, with:
|
|
229
|
-
`code-host.type "X" is not supported. "github" is the only code host built.`
|
|
260
|
+
```yaml
|
|
261
|
+
code-host: github
|
|
262
|
+
```
|
|
230
263
|
|
|
231
264
|
### `builds`
|
|
232
265
|
|
|
266
|
+
What starts a build when you approve a ticket, and where the build runs.
|
|
267
|
+
|
|
233
268
|
```yaml
|
|
234
269
|
builds:
|
|
235
270
|
trigger: own-server
|
|
236
|
-
runner: github-actions
|
|
237
271
|
```
|
|
238
272
|
|
|
239
|
-
|
|
|
240
|
-
| -------------- |
|
|
241
|
-
| `trigger` | What
|
|
242
|
-
| `runner` | Where a build in the cloud runs
|
|
243
|
-
| `poll-minutes` |
|
|
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.
|
|
244
304
|
|
|
245
|
-
|
|
246
|
-
build it starts then runs: a poller on your own server still starts its
|
|
247
|
-
builds on the cloud runner. Only `github-actions` is built. Any other value
|
|
248
|
-
fails `factory config check`, and every command that reads
|
|
249
|
-
the settings and reaches the runner, with:
|
|
250
|
-
`builds.runner "X" is not supported. "github-actions" is the only runner built.`
|
|
305
|
+
### `specs`
|
|
251
306
|
|
|
252
|
-
|
|
253
|
-
|
|
254
|
-
- **`github-action`:** a schedule on the cloud runner does the same every
|
|
255
|
-
`poll-minutes` minutes, with nothing to host. On a private repository,
|
|
256
|
-
each pass is billed as at least an Actions minute.
|
|
307
|
+
Whether a change your users will see also gets a written spec, kept beside
|
|
308
|
+
your code.
|
|
257
309
|
|
|
258
|
-
|
|
259
|
-
|
|
310
|
+
```yaml
|
|
311
|
+
specs: openspec
|
|
312
|
+
```
|
|
260
313
|
|
|
261
|
-
|
|
262
|
-
|
|
263
|
-
|
|
264
|
-
|
|
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.
|
|
265
323
|
|
|
266
|
-
|
|
324
|
+
#### `specs.check`
|
|
267
325
|
|
|
268
|
-
|
|
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.
|
|
269
329
|
|
|
270
330
|
```yaml
|
|
271
|
-
specs:
|
|
331
|
+
specs:
|
|
332
|
+
type: openspec
|
|
333
|
+
check: npx --no-install openspec validate --all --strict --no-interactive
|
|
334
|
+
```
|
|
335
|
+
|
|
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`.
|
|
343
|
+
|
|
344
|
+
### `commands`
|
|
345
|
+
|
|
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.
|
|
350
|
+
|
|
351
|
+
```yaml
|
|
352
|
+
commands:
|
|
353
|
+
build-setup:
|
|
354
|
+
- npx playwright install --with-deps chromium
|
|
355
|
+
before-commit:
|
|
356
|
+
- npm run -s format:check
|
|
357
|
+
- npx tsc --noEmit
|
|
358
|
+
gate:
|
|
359
|
+
- npm run check
|
|
360
|
+
test-one: npx vitest run $FILE -t "$NAME"
|
|
361
|
+
end-to-end: npx playwright test $FILE
|
|
362
|
+
coverage:
|
|
363
|
+
run: npm run coverage
|
|
364
|
+
report: coverage/lcov.info
|
|
365
|
+
relock: npm install
|
|
272
366
|
```
|
|
273
367
|
|
|
274
|
-
|
|
|
275
|
-
|
|
|
276
|
-
| `
|
|
277
|
-
| `
|
|
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` |
|
|
278
377
|
|
|
279
|
-
-
|
|
280
|
-
-
|
|
281
|
-
|
|
378
|
+
- **`$FILE` and `$NAME`** are set for you when a command runs one test.
|
|
379
|
+
[`commands.test-one`](#commandstest-one) says how.
|
|
380
|
+
- **Only `gate` is needed for a build.** Each of the others turns
|
|
381
|
+
something on, and its entry below says what happens without it.
|
|
382
|
+
- **A list runs in order and stops at the first command that fails.**
|
|
282
383
|
|
|
283
|
-
|
|
384
|
+
#### `commands.build-setup`
|
|
284
385
|
|
|
285
|
-
Commands run
|
|
286
|
-
|
|
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.
|
|
287
389
|
|
|
288
390
|
```yaml
|
|
289
|
-
|
|
290
|
-
-
|
|
291
|
-
|
|
292
|
-
- npm run -s lint
|
|
391
|
+
commands:
|
|
392
|
+
build-setup:
|
|
393
|
+
- npx playwright install --with-deps chromium # a browser for end-to-end tests
|
|
293
394
|
```
|
|
294
395
|
|
|
295
|
-
|
|
296
|
-
|
|
297
|
-
|
|
298
|
-
|
|
299
|
-
|
|
300
|
-
|
|
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
|
+
|
|
399
|
+
- **Default:** none.
|
|
400
|
+
- **If one fails,** the build stops before the session starts, and the
|
|
401
|
+
run's log shows that command's output.
|
|
301
402
|
|
|
302
|
-
|
|
403
|
+
#### `commands.before-commit`
|
|
303
404
|
|
|
304
|
-
|
|
305
|
-
|
|
306
|
-
with `npm ci`.
|
|
405
|
+
Quick checks that run before every commit a session makes. If one fails,
|
|
406
|
+
the commit is blocked and the session sees why.
|
|
307
407
|
|
|
308
408
|
```yaml
|
|
309
|
-
|
|
310
|
-
|
|
311
|
-
|
|
312
|
-
|
|
409
|
+
commands:
|
|
410
|
+
before-commit:
|
|
411
|
+
- npm run -s format:check
|
|
412
|
+
- npx tsc --noEmit
|
|
413
|
+
- npm run -s lint
|
|
313
414
|
```
|
|
314
415
|
|
|
315
416
|
- **Default:** none.
|
|
316
|
-
- **
|
|
317
|
-
|
|
318
|
-
- **
|
|
319
|
-
|
|
320
|
-
|
|
321
|
-
|
|
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.
|
|
421
|
+
|
|
422
|
+
#### `commands.gate`
|
|
423
|
+
|
|
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:
|
|
431
|
+
|
|
432
|
+
```yaml
|
|
433
|
+
commands:
|
|
434
|
+
gate:
|
|
435
|
+
- npm run check
|
|
436
|
+
```
|
|
437
|
+
|
|
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.
|
|
502
|
+
|
|
503
|
+
#### `commands.test-one`
|
|
504
|
+
|
|
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:
|
|
510
|
+
|
|
511
|
+
```yaml
|
|
512
|
+
commands:
|
|
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
|
|
519
|
+
```
|
|
520
|
+
|
|
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.
|
|
524
|
+
|
|
525
|
+
#### `commands.end-to-end`
|
|
526
|
+
|
|
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.
|
|
532
|
+
|
|
533
|
+
```yaml
|
|
534
|
+
commands:
|
|
535
|
+
end-to-end: npx playwright test $FILE
|
|
536
|
+
```
|
|
537
|
+
|
|
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.
|
|
543
|
+
|
|
544
|
+
#### `commands.coverage`
|
|
545
|
+
|
|
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.
|
|
549
|
+
|
|
550
|
+
```yaml
|
|
551
|
+
commands:
|
|
552
|
+
coverage:
|
|
553
|
+
run: npm run coverage
|
|
554
|
+
report: coverage/lcov.info
|
|
555
|
+
```
|
|
556
|
+
|
|
557
|
+
- **Default:** none, and a session doesn't check coverage.
|
|
558
|
+
- **Write both `run` and `report`,** or neither.
|
|
559
|
+
|
|
560
|
+
#### `commands.relock`
|
|
561
|
+
|
|
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.
|
|
565
|
+
|
|
566
|
+
```yaml
|
|
567
|
+
commands:
|
|
568
|
+
relock: composer update --lock
|
|
569
|
+
```
|
|
570
|
+
|
|
571
|
+
- **Default:** `npm install`.
|
|
572
|
+
- **Another generated file that conflicts,** such as a generated API
|
|
573
|
+
client, needs a [resolver](#pluginsconflicts).
|
|
322
574
|
|
|
323
575
|
### `session-minutes`
|
|
324
576
|
|
|
325
|
-
How long each kind of session
|
|
326
|
-
|
|
327
|
-
|
|
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.
|
|
328
580
|
|
|
329
581
|
```yaml
|
|
330
|
-
# How long each unattended session may run, in minutes.
|
|
331
582
|
session-minutes:
|
|
332
583
|
build: 300
|
|
333
584
|
```
|
|
334
585
|
|
|
335
|
-
|
|
|
336
|
-
| -------------- |
|
|
337
|
-
| `build` |
|
|
338
|
-
| `conflicts` |
|
|
339
|
-
| `review` |
|
|
340
|
-
| `dependencies` |
|
|
341
|
-
|
|
342
|
-
- **Each is a whole number above zero.**
|
|
343
|
-
|
|
344
|
-
|
|
345
|
-
|
|
346
|
-
session is stopped.
|
|
347
|
-
- **`factory sync` writes these where the cloud runner
|
|
348
|
-
reads them,** and `factory sync --check` fails until it
|
|
349
|
-
has run after a change.
|
|
350
|
-
- **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
|
|
351
597
|
[its limits](github/reference.md#limits).
|
|
352
|
-
- The cloud jobs that run no session, such as the board's sync and who
|
|
353
|
-
merges, keep fixed short limits.
|
|
354
|
-
- `factory config get session-minutes.build` prints the
|
|
355
|
-
value in effect.
|
|
356
598
|
|
|
357
599
|
### `plugins`
|
|
358
600
|
|
|
359
|
-
Your own skills and agents,
|
|
360
|
-
|
|
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`.
|
|
361
606
|
|
|
362
607
|
```yaml
|
|
363
608
|
plugins:
|
|
364
|
-
|
|
365
|
-
|
|
366
|
-
|
|
367
|
-
|
|
368
|
-
|
|
369
|
-
|
|
370
|
-
|
|
371
|
-
|
|
372
|
-
|
|
373
|
-
|
|
374
|
-
|
|
375
|
-
|
|
376
|
-
|
|
377
|
-
|
|
|
378
|
-
|
|
|
379
|
-
| `
|
|
380
|
-
| `
|
|
381
|
-
| `
|
|
382
|
-
|
|
383
|
-
|
|
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`:
|
|
384
634
|
[Skills in Claude Code](github/reference.md#skills-in-claude-code).
|
|
385
635
|
|
|
386
|
-
-
|
|
387
|
-
|
|
388
|
-
|
|
389
|
-
|
|
390
|
-
|
|
391
|
-
|
|
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:
|
|
653
|
+
|
|
654
|
+
```yaml
|
|
655
|
+
plugins:
|
|
656
|
+
refine:
|
|
657
|
+
refiner:
|
|
658
|
+
skill: acme-refine # .claude/skills/acme-refine/SKILL.md
|
|
659
|
+
mockups:
|
|
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:
|
|
676
|
+
build:
|
|
677
|
+
builders:
|
|
678
|
+
- skill: add-endpoint
|
|
679
|
+
labels:
|
|
680
|
+
- new-endpoint
|
|
681
|
+
reviewers:
|
|
682
|
+
- agent: migration-reviewer
|
|
683
|
+
files:
|
|
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:
|
|
700
|
+
test:
|
|
701
|
+
prover:
|
|
702
|
+
skill: acme-mutation
|
|
703
|
+
reviewers:
|
|
704
|
+
- agent: factory-test-reviewer
|
|
705
|
+
- agent: factory-e2e-reviewer
|
|
706
|
+
files:
|
|
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:
|
|
721
|
+
conflicts:
|
|
722
|
+
resolvers:
|
|
723
|
+
- skill: regenerate-api-client
|
|
724
|
+
files:
|
|
725
|
+
- src/generated/**
|
|
726
|
+
```
|
|
392
727
|
|
|
393
728
|
### `site`
|
|
394
729
|
|
|
395
|
-
How the factory looks at your website
|
|
396
|
-
|
|
397
|
-
|
|
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`.
|
|
737
|
+
|
|
738
|
+
Most sites need only two lines:
|
|
398
739
|
|
|
399
740
|
```yaml
|
|
400
741
|
site:
|
|
401
|
-
# A command that builds and serves the site from the repository's root,
|
|
402
|
-
# and the address it answers at. $PORT is set for you.
|
|
403
742
|
start: npm run build && npx serve out -p $PORT
|
|
404
743
|
url: http://localhost:$PORT
|
|
405
|
-
|
|
406
|
-
|
|
407
|
-
|
|
408
|
-
|
|
409
|
-
|
|
410
|
-
|
|
411
|
-
|
|
412
|
-
|
|
413
|
-
|
|
|
414
|
-
|
|
|
415
|
-
| `
|
|
416
|
-
| `
|
|
417
|
-
| `
|
|
418
|
-
| `
|
|
419
|
-
| `
|
|
420
|
-
| `
|
|
421
|
-
| `
|
|
422
|
-
|
|
423
|
-
-
|
|
424
|
-
|
|
425
|
-
|
|
426
|
-
|
|
427
|
-
|
|
428
|
-
|
|
429
|
-
|
|
430
|
-
|
|
431
|
-
|
|
432
|
-
|
|
433
|
-
|
|
434
|
-
|
|
435
|
-
|
|
744
|
+
```
|
|
745
|
+
|
|
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.
|
|
749
|
+
|
|
750
|
+
Every setting `site` takes:
|
|
751
|
+
|
|
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` |
|
|
765
|
+
|
|
766
|
+
The optional ones that take a list are written like this:
|
|
767
|
+
|
|
768
|
+
```yaml
|
|
769
|
+
site:
|
|
770
|
+
start: npm run build && npx serve out -p $PORT
|
|
771
|
+
url: http://localhost:$PORT
|
|
772
|
+
pages:
|
|
773
|
+
- /
|
|
774
|
+
- /pricing
|
|
775
|
+
hide:
|
|
776
|
+
- .chat-widget
|
|
777
|
+
checks:
|
|
778
|
+
- node scripts/check-tap-targets.mjs
|
|
779
|
+
```
|
|
780
|
+
|
|
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.
|
|
436
785
|
|
|
437
786
|
### `auto-merge`
|
|
438
787
|
|
|
439
|
-
Which pull requests may merge without you.
|
|
788
|
+
Which pull requests may merge without you reading them.
|
|
440
789
|
|
|
441
790
|
```yaml
|
|
442
791
|
auto-merge:
|
|
@@ -452,108 +801,101 @@ auto-merge:
|
|
|
452
801
|
|
|
453
802
|
A pull request merges itself only when **all** of these hold:
|
|
454
803
|
|
|
455
|
-
1. every
|
|
456
|
-
2. no
|
|
804
|
+
1. every file it changes matches a pattern under `allow`;
|
|
805
|
+
2. no file it changes matches a pattern under `deny`;
|
|
457
806
|
3. every command under `commands` exits 0;
|
|
458
|
-
4. CI passes
|
|
459
|
-
|
|
460
|
-
|
|
461
|
-
|
|
462
|
-
|
|
463
|
-
|
|
464
|
-
|
|
465
|
-
|
|
466
|
-
|
|
467
|
-
|
|
468
|
-
- **
|
|
469
|
-
|
|
470
|
-
|
|
471
|
-
|
|
472
|
-
|
|
473
|
-
|
|
474
|
-
|
|
475
|
-
|
|
476
|
-
|
|
477
|
-
|
|
478
|
-
|
|
479
|
-
|
|
480
|
-
|
|
481
|
-
|
|
482
|
-
|
|
483
|
-
|
|
484
|
-
|
|
485
|
-
|
|
486
|
-
|
|
487
|
-
|
|
488
|
-
|
|
489
|
-
|
|
490
|
-
|
|
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:
|
|
491
847
|
|
|
492
|
-
|
|
493
|
-
|
|
494
|
-
|
|
495
|
-
|
|
496
|
-
|
|
497
|
-
|
|
498
|
-
|
|
499
|
-
|
|
500
|
-
|
|
501
|
-
|
|
502
|
-
|
|
503
|
-
|
|
504
|
-
|
|
505
|
-
|
|
506
|
-
|
|
507
|
-
|
|
508
|
-
|
|
509
|
-
|
|
510
|
-
|
|
511
|
-
|
|
512
|
-
-
|
|
513
|
-
warns, since a stale pattern is how a policy rots.
|
|
514
|
-
- **If `allow` is too wide:** changes you meant to read merge unread.
|
|
515
|
-
Start with a short list and add to it.
|
|
516
|
-
- **If a `deny` pattern matches nothing inside `allow`:** it does nothing,
|
|
517
|
-
and `factory config check` says so.
|
|
518
|
-
|
|
519
|
-
### `ci-review`
|
|
520
|
-
|
|
521
|
-
The automated review of every pull request: Claude reads each one once it
|
|
522
|
-
is marked ready, comments on what it finds, and posts a verdict. It is on
|
|
523
|
-
while `ci-review` is written, even with nothing under it, and `factory
|
|
524
|
-
sync` then writes its workflow, `.github/workflows/factory-claude-review.yml`.
|
|
525
|
-
[Setting up on GitHub](github/setup.md) has what it needs on GitHub.
|
|
526
|
-
|
|
527
|
-
```yaml
|
|
528
|
-
# The automated review of every pull request, on while this is written.
|
|
529
|
-
# "commands" are what it may run to confirm a finding, beside reading the
|
|
530
|
-
# pull request and commenting on it.
|
|
531
|
-
ci-review:
|
|
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.
|
|
859
|
+
|
|
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.
|
|
866
|
+
|
|
867
|
+
```yaml
|
|
868
|
+
pr-review:
|
|
532
869
|
commands:
|
|
533
870
|
- npm test
|
|
534
871
|
- npx tsc --noEmit
|
|
535
872
|
```
|
|
536
873
|
|
|
537
|
-
- **Default:** off.
|
|
538
|
-
|
|
539
|
-
|
|
540
|
-
|
|
541
|
-
|
|
542
|
-
|
|
543
|
-
|
|
544
|
-
|
|
545
|
-
|
|
546
|
-
|
|
547
|
-
|
|
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.
|
|
548
890
|
|
|
549
891
|
### `approvers`
|
|
550
892
|
|
|
551
|
-
_[Planned](developing.md#what-is-built)_: `factory config check`
|
|
552
|
-
|
|
893
|
+
_[Planned](developing.md#what-is-built)_: `factory config check` refuses
|
|
894
|
+
this setting until it is built.
|
|
553
895
|
|
|
554
|
-
The people whose comments a session
|
|
555
|
-
of a ticket to Ready counts as
|
|
556
|
-
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.
|
|
557
899
|
|
|
558
900
|
```yaml
|
|
559
901
|
approvers:
|
|
@@ -561,20 +903,16 @@ approvers:
|
|
|
561
903
|
- a-teammate
|
|
562
904
|
```
|
|
563
905
|
|
|
564
|
-
- **Default:** the repository's owner
|
|
565
|
-
|
|
566
|
-
|
|
567
|
-
|
|
568
|
-
flags a name that is not an account with access to the repository.
|
|
569
|
-
|
|
570
|
-
A session posts through a person's account too, so it marks its own comments
|
|
571
|
-
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.
|
|
572
910
|
|
|
573
911
|
### `rules`
|
|
574
912
|
|
|
575
|
-
|
|
576
|
-
`factory sync`
|
|
577
|
-
|
|
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.
|
|
578
916
|
|
|
579
917
|
```yaml
|
|
580
918
|
rules:
|
|
@@ -582,125 +920,93 @@ rules:
|
|
|
582
920
|
review-rounds: 2
|
|
583
921
|
```
|
|
584
922
|
|
|
585
|
-
|
|
|
586
|
-
| -------------------- |
|
|
587
|
-
| `small-change-lines` |
|
|
588
|
-
| `review-rounds` |
|
|
589
|
-
|
|
590
|
-
- **If a value is not a whole number above zero:**
|
|
591
|
-
`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` |
|
|
592
927
|
|
|
593
|
-
Any rule that
|
|
594
|
-
your own instructions for the agent, such as
|
|
595
|
-
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.
|
|
596
931
|
|
|
597
932
|
## Checking the file
|
|
598
933
|
|
|
599
|
-
| Command
|
|
600
|
-
| ------------------------ |
|
|
601
|
-
| Your editor |
|
|
602
|
-
| `factory config check` |
|
|
603
|
-
| `factory config explain` | Prints
|
|
604
|
-
| `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 |
|
|
605
940
|
|
|
606
|
-
The first line
|
|
941
|
+
The first line `factory init` writes is optional. It points your editor at
|
|
942
|
+
the schema in the installed package:
|
|
607
943
|
|
|
608
944
|
```yaml
|
|
609
945
|
# $schema: ../node_modules/@davidbyoung/software-factory/settings.schema.json
|
|
610
946
|
```
|
|
611
947
|
|
|
612
|
-
|
|
613
|
-
|
|
614
|
-
|
|
615
|
-
the installed version and works offline. In a checkout with nothing installed
|
|
616
|
-
the editor finds no schema and says so.
|
|
617
|
-
|
|
618
|
-
The editor's check is a help. It accepts some files
|
|
619
|
-
`factory config check` refuses, such as a plug-in whose
|
|
620
|
-
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.
|
|
621
951
|
|
|
622
952
|
## Three complete files
|
|
623
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
|
+
|
|
624
957
|
### A web application with its own reviewers
|
|
625
958
|
|
|
626
|
-
An online store
|
|
627
|
-
|
|
628
|
-
|
|
629
|
-
|
|
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.
|
|
630
963
|
|
|
631
964
|
```yaml
|
|
632
965
|
# $schema: ../node_modules/@davidbyoung/software-factory/settings.schema.json
|
|
633
|
-
|
|
634
|
-
# docs/configuration.md in the factory's repository.
|
|
635
|
-
#
|
|
636
|
-
# Anything not listed here keeps its default: no pull request merges without
|
|
637
|
-
# you, a build starts when you tell a session to work a ticket, and only the
|
|
638
|
-
# built-in reviewers run.
|
|
639
|
-
#
|
|
640
|
-
# "version" is the shape of this file, not the factory's version.
|
|
641
|
-
version: 1
|
|
966
|
+
version: 2
|
|
642
967
|
repository: harbor-goods/storefront
|
|
643
968
|
|
|
644
|
-
# Where tickets live. "board" is the number in your GitHub Project's address.
|
|
645
969
|
tickets:
|
|
646
|
-
type: github
|
|
647
970
|
board: 1
|
|
648
971
|
|
|
649
|
-
# What starts a build once a ticket is moved to Ready on the board:
|
|
650
|
-
# own-server (a small poller you host), github-action, or manual (you tell
|
|
651
|
-
# a session to build it).
|
|
652
972
|
builds:
|
|
653
973
|
trigger: own-server
|
|
654
974
|
|
|
655
|
-
# How the written spec for a change your users will see is kept: openspec,
|
|
656
|
-
# or none.
|
|
657
975
|
specs: openspec
|
|
658
976
|
|
|
659
|
-
|
|
660
|
-
|
|
661
|
-
|
|
662
|
-
-
|
|
663
|
-
|
|
664
|
-
|
|
665
|
-
|
|
666
|
-
|
|
667
|
-
|
|
668
|
-
|
|
669
|
-
|
|
670
|
-
# mockups makes pictures to choose from when a decision changes the look
|
|
671
|
-
# builder builds a ticket that carries one of "labels" (label names),
|
|
672
|
-
# in place of the built-in build
|
|
673
|
-
# reviewer is asked to read a finished change when it touches a path
|
|
674
|
-
# matching "files", and reports problems; it edits nothing
|
|
977
|
+
commands:
|
|
978
|
+
build-setup:
|
|
979
|
+
- npx playwright install --with-deps chromium
|
|
980
|
+
before-commit:
|
|
981
|
+
- npm run -s format:check
|
|
982
|
+
- npx tsc --noEmit
|
|
983
|
+
- npm run -s lint
|
|
984
|
+
gate:
|
|
985
|
+
- npm run check
|
|
986
|
+
test-one: npx vitest run $FILE -t "$NAME"
|
|
987
|
+
|
|
675
988
|
plugins:
|
|
676
|
-
|
|
677
|
-
|
|
678
|
-
|
|
679
|
-
|
|
680
|
-
|
|
681
|
-
|
|
682
|
-
|
|
683
|
-
|
|
684
|
-
|
|
685
|
-
|
|
686
|
-
|
|
687
|
-
|
|
688
|
-
-
|
|
689
|
-
|
|
690
|
-
|
|
691
|
-
|
|
692
|
-
|
|
693
|
-
|
|
694
|
-
# How the factory looks at this website, for factory-ui-reviewer.
|
|
989
|
+
build:
|
|
990
|
+
builders:
|
|
991
|
+
- skill: add-endpoint
|
|
992
|
+
labels:
|
|
993
|
+
- new-endpoint
|
|
994
|
+
reviewers:
|
|
995
|
+
- agent: migration-reviewer
|
|
996
|
+
files:
|
|
997
|
+
- db/migrations/**
|
|
998
|
+
- agent: accessibility-reviewer
|
|
999
|
+
files:
|
|
1000
|
+
- src/components/**
|
|
1001
|
+
- agent: factory-ui-reviewer
|
|
1002
|
+
files:
|
|
1003
|
+
- src/components/**
|
|
1004
|
+
- src/styles/**
|
|
1005
|
+
|
|
695
1006
|
site:
|
|
696
1007
|
start: npm run build && npx serve out -p $PORT
|
|
697
1008
|
url: http://localhost:$PORT
|
|
698
1009
|
|
|
699
|
-
# Which pull requests may merge without you. Patterns are globs matched
|
|
700
|
-
# against paths from the repository's root, and deny wins over allow. A pull
|
|
701
|
-
# request merges itself only when every changed file matches "allow", none
|
|
702
|
-
# matches "deny", every command under "commands" (if you list any) exits 0
|
|
703
|
-
# when CI runs it, and CI passes. Anything else waits for you.
|
|
704
1010
|
auto-merge:
|
|
705
1011
|
allow:
|
|
706
1012
|
- docs/**
|
|
@@ -713,103 +1019,70 @@ auto-merge:
|
|
|
713
1019
|
- src/components/consent/**
|
|
714
1020
|
commands:
|
|
715
1021
|
- node scripts/public-api-changed.mjs
|
|
1022
|
+
|
|
1023
|
+
pr-review:
|
|
1024
|
+
commands:
|
|
1025
|
+
- npm test
|
|
716
1026
|
```
|
|
717
1027
|
|
|
718
|
-
### A
|
|
1028
|
+
### A small website
|
|
719
1029
|
|
|
720
|
-
A
|
|
721
|
-
|
|
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`.
|
|
722
1032
|
|
|
723
1033
|
```yaml
|
|
724
1034
|
# $schema: ../node_modules/@davidbyoung/software-factory/settings.schema.json
|
|
725
|
-
|
|
726
|
-
# docs/configuration.md in the factory's repository.
|
|
727
|
-
#
|
|
728
|
-
# Anything not listed here keeps its default: no pull request merges without
|
|
729
|
-
# you, a build starts when you tell a session to work a ticket, and only the
|
|
730
|
-
# built-in reviewers run.
|
|
731
|
-
#
|
|
732
|
-
# "version" is the shape of this file, not the factory's version.
|
|
733
|
-
version: 1
|
|
1035
|
+
version: 2
|
|
734
1036
|
repository: riverbend-studio/site
|
|
735
1037
|
|
|
736
|
-
# Where tickets live. "board" is the number in your GitHub Project's address.
|
|
737
1038
|
tickets:
|
|
738
1039
|
board: 4
|
|
739
1040
|
|
|
740
|
-
|
|
741
|
-
|
|
742
|
-
|
|
743
|
-
|
|
744
|
-
|
|
1041
|
+
commands:
|
|
1042
|
+
before-commit:
|
|
1043
|
+
- npm run lint
|
|
1044
|
+
gate:
|
|
1045
|
+
- npm run lint
|
|
1046
|
+
- npm run typecheck
|
|
1047
|
+
- npm test
|
|
745
1048
|
```
|
|
746
1049
|
|
|
747
|
-
|
|
748
|
-
`builds.trigger` defaults to `manual`.
|
|
749
|
-
|
|
750
|
-
### A repository that is not JavaScript
|
|
1050
|
+
### A project that isn't JavaScript
|
|
751
1051
|
|
|
752
|
-
A PHP library. Its commands are Composer's
|
|
753
|
-
|
|
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.
|
|
754
1055
|
|
|
755
1056
|
```yaml
|
|
756
1057
|
# $schema: ../node_modules/@davidbyoung/software-factory/settings.schema.json
|
|
757
|
-
|
|
758
|
-
# docs/configuration.md in the factory's repository.
|
|
759
|
-
#
|
|
760
|
-
# Anything not listed here keeps its default: no pull request merges without
|
|
761
|
-
# you, a build starts when you tell a session to work a ticket, and only the
|
|
762
|
-
# built-in reviewers run.
|
|
763
|
-
#
|
|
764
|
-
# "version" is the shape of this file, not the factory's version.
|
|
765
|
-
version: 1
|
|
1058
|
+
version: 2
|
|
766
1059
|
repository: northwind-php/ledger
|
|
767
1060
|
|
|
768
|
-
# Where tickets live. "board" is the number in your GitHub Project's address.
|
|
769
1061
|
tickets:
|
|
770
|
-
type: github
|
|
771
1062
|
board: 2
|
|
772
1063
|
|
|
773
|
-
|
|
774
|
-
|
|
775
|
-
|
|
776
|
-
-
|
|
777
|
-
|
|
778
|
-
|
|
779
|
-
|
|
780
|
-
|
|
781
|
-
|
|
782
|
-
|
|
783
|
-
|
|
784
|
-
|
|
785
|
-
# in place of the built-in build
|
|
786
|
-
# reviewer is asked to read a finished change when it touches a path
|
|
787
|
-
# matching "files", and reports problems; it edits nothing
|
|
1064
|
+
commands:
|
|
1065
|
+
build-setup:
|
|
1066
|
+
- composer install --no-interaction
|
|
1067
|
+
before-commit:
|
|
1068
|
+
- composer lint
|
|
1069
|
+
gate:
|
|
1070
|
+
- composer lint
|
|
1071
|
+
- composer analyse
|
|
1072
|
+
- composer test
|
|
1073
|
+
test-one: vendor/bin/phpunit $FILE ${NAME:+--filter "$NAME"}
|
|
1074
|
+
relock: composer update --lock
|
|
1075
|
+
|
|
788
1076
|
plugins:
|
|
789
|
-
|
|
790
|
-
|
|
791
|
-
|
|
792
|
-
|
|
793
|
-
|
|
794
|
-
|
|
795
|
-
# against paths from the repository's root, and deny wins over allow. A pull
|
|
796
|
-
# request merges itself only when every changed file matches "allow", none
|
|
797
|
-
# matches "deny", every command under "commands" (if you list any) exits 0
|
|
798
|
-
# when CI runs it, and CI passes. Anything else waits for you.
|
|
1077
|
+
build:
|
|
1078
|
+
reviewers:
|
|
1079
|
+
- agent: api-compatibility-reviewer
|
|
1080
|
+
files:
|
|
1081
|
+
- src/**
|
|
1082
|
+
|
|
799
1083
|
auto-merge:
|
|
800
1084
|
allow:
|
|
801
1085
|
- docs/**
|
|
802
1086
|
deny:
|
|
803
1087
|
- docs/security/**
|
|
804
1088
|
```
|
|
805
|
-
|
|
806
|
-
If this team moved its tickets to Jira, only the `tickets` block would
|
|
807
|
-
change. **Only GitHub is built**; the block below shows the shape the
|
|
808
|
-
design leaves room for.
|
|
809
|
-
|
|
810
|
-
```yaml
|
|
811
|
-
tickets:
|
|
812
|
-
type: jira
|
|
813
|
-
site: northwind.atlassian.net
|
|
814
|
-
project: LEDGER
|
|
815
|
-
```
|