@davidbyoung/software-factory 0.1.3 → 0.1.4
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 +29 -2
- package/dist/commands.d.mts +16 -0
- package/dist/commands.mjs +129 -0
- package/dist/config.d.mts +61 -13
- package/dist/config.mjs +267 -65
- 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 +66 -19
- 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 +15 -5
- 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/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/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 +40 -6
- package/dist/ticket.mjs +19 -1
- package/docs/builds.md +8 -8
- package/docs/cli.md +82 -45
- package/docs/configuration.md +455 -139
- package/docs/design.md +17 -4
- package/docs/developing.md +37 -6
- package/docs/existing-repo.md +8 -6
- package/docs/github/by-hand.md +23 -10
- package/docs/github/reference.md +19 -14
- package/docs/github/setup.md +12 -9
- package/docs/glossary.md +13 -3
- package/docs/limitations.md +27 -2
- package/docs/plugins.md +302 -48
- package/docs/quick-start.md +36 -8
- package/docs/removing.md +1 -1
- package/docs/skills.md +101 -52
- package/docs/updating.md +148 -3
- package/docs/workflow.md +13 -10
- package/package.json +1 -1
- package/review.md +20 -11
- package/rules.md +22 -18
- package/settings.schema.json +289 -69
- package/skills/factory-address-review/SKILL.md +50 -30
- package/skills/factory-build/SKILL.md +75 -22
- package/skills/factory-deps/SKILL.md +46 -21
- package/skills/factory-design/SKILL.md +17 -8
- 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-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/design.md
CHANGED
|
@@ -68,10 +68,23 @@ differently from one day to the next.
|
|
|
68
68
|
|
|
69
69
|
## The order of the workflow is fixed
|
|
70
70
|
|
|
71
|
-
You can turn parts off
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
|
|
71
|
+
You can turn parts off in [the settings](configuration.md), such as
|
|
72
|
+
written specs or the automated review, and a [plug-in](plugins.md) of yours can take a
|
|
73
|
+
step over: how a ticket is refined, how a ticket with one of your labels
|
|
74
|
+
is built, how a test is proved able to fail, which agents read the tests
|
|
75
|
+
and the change, and how a generated file is rebuilt after a conflict. You
|
|
76
|
+
cannot reorder the six states, add one, or leave one out.
|
|
77
|
+
|
|
78
|
+
A step can be replaced because what it hands to the next one can be
|
|
79
|
+
written down, and the part a build depends on is checked by a script: a
|
|
80
|
+
refined ticket is refused until its body has the sections a build reads,
|
|
81
|
+
whichever skill refined it. So whatever does a step, the next step reads
|
|
82
|
+
the same thing.
|
|
83
|
+
|
|
84
|
+
The order is another matter. Mapping names is cheap to support, which is
|
|
85
|
+
why a board's columns can be yours. Every extra shape of workflow is one
|
|
86
|
+
more path each skill has to handle correctly, and a skill is instructions,
|
|
87
|
+
which cannot be unit tested.
|
|
75
88
|
|
|
76
89
|
## Small problems go on one checklist
|
|
77
90
|
|
package/docs/developing.md
CHANGED
|
@@ -13,7 +13,7 @@ it shares with that repository: each repository's sync reads only its own
|
|
|
13
13
|
cards.
|
|
14
14
|
|
|
15
15
|
**It uses the factory on itself.** `.claude/factory.yaml` here sets the
|
|
16
|
-
board, OpenSpec, and the CI review, and `node bin/factory.js sync` copies
|
|
16
|
+
board, OpenSpec, the gate, and the CI review, and `node bin/factory.js sync` copies
|
|
17
17
|
this repository's own skills, agents, rules, and workflows into `.claude/`
|
|
18
18
|
and `.github/`, with hooks that run `bin/factory.js` at the root. So a
|
|
19
19
|
change to a skill shows in the same pull request twice: the source, and
|
|
@@ -61,8 +61,13 @@ marked working below exist only in these docs.
|
|
|
61
61
|
| `factory remove` | Working |
|
|
62
62
|
| Starting builds from a scheduled workflow, `factory poller --once`, and a poller built from an installed package | Working |
|
|
63
63
|
| [`rules`](configuration.md#rules) in the settings, `factory config explain`, and the `factory-trace` skill | Working |
|
|
64
|
+
| Settings version 2: commands, a spec check, and plug-ins grouped by phase | Working |
|
|
65
|
+
| `factory gate`, `test-one`, `end-to-end`, and `specs check`, which run the settings' commands | Working |
|
|
66
|
+
| The default branch read from Git and the code host, never assumed, and `factory default-branch` | Working |
|
|
67
|
+
| A refiner, a prover, test reviewers, and conflict resolvers of your own, and `factory-e2e-reviewer` | Working |
|
|
68
|
+
| `factory ticket refined` refusing a ticket a build could not read | Working |
|
|
69
|
+
| No skill, agent, rule, or review instruction names a stack, checked by a test | Working |
|
|
64
70
|
| `approvers` in the settings | Planned, [#14](https://github.com/davidbyoung/software-factory/issues/14) |
|
|
65
|
-
| `factory migrate` | Not planned. The first release that changes the settings' shape adds it |
|
|
66
71
|
| Another ticket system, such as Jira | Not planned. The design leaves room |
|
|
67
72
|
| A ticket system or code host named by a package, for an adapter you write yourself | Not planned. The design leaves room |
|
|
68
73
|
| Another code host or runner | Not planned. The design leaves room |
|
|
@@ -99,8 +104,23 @@ It is laid out as a Claude Code plugin even though it is not delivered as
|
|
|
99
104
|
one. That costs nothing, and it keeps the plugin's own tooling usable on the
|
|
100
105
|
folder. The settings are validated in code, and `settings.schema.json` is the
|
|
101
106
|
editor's copy of their keys. A new key goes in `SETTINGS_KEYS` in
|
|
102
|
-
`src/config.mts`, in the schema,
|
|
103
|
-
fails when the first two differ.
|
|
107
|
+
`src/config.mts`, in the schema, in `src/explain.mts`, which prints it, and
|
|
108
|
+
in `docs/configuration.md`, and a test fails when the first two differ.
|
|
109
|
+
|
|
110
|
+
- **A command a session runs** goes under
|
|
111
|
+
[`commands`](configuration.md#commands), with a `factory`
|
|
112
|
+
command in `src/commands.mts` that runs it, so a skill names the
|
|
113
|
+
`factory` command and never the repository's own.
|
|
114
|
+
- **A plug-in slot** goes in `SLOTS` and `SLOT_SHAPE` in `src/config.mts`,
|
|
115
|
+
which say its phase, whether it takes a skill or an agent, one or a
|
|
116
|
+
list, and `files` or `labels`. Its keys in `SETTINGS_KEYS` follow from
|
|
117
|
+
that table. `docs/plugins.md` gains its table of what it is handed and
|
|
118
|
+
what it returns.
|
|
119
|
+
- **A key that is renamed or moved** raises the settings' `version`.
|
|
120
|
+
There is no command that converts a file: the older version is refused
|
|
121
|
+
with a line that names a section of `docs/updating.md`, as version 1 is
|
|
122
|
+
with "Moving to settings version 2", and that section shows each key
|
|
123
|
+
before and after.
|
|
104
124
|
|
|
105
125
|
## Running from source
|
|
106
126
|
|
|
@@ -164,6 +184,17 @@ A factory file must name nothing that belongs to the host repository: not
|
|
|
164
184
|
its paths, its commands, its subject, or its own skills. A test fails when
|
|
165
185
|
one does. That is what keeps the folder movable.
|
|
166
186
|
|
|
187
|
+
Nor does a skill, an agent, the rules, or the review's instructions name
|
|
188
|
+
one stack: a test runner, a framework, a package manager's commands, or a
|
|
189
|
+
branch called `main`. A skill runs `factory gate`, `factory test-one`,
|
|
190
|
+
`factory end-to-end`, and `factory specs check`, which run the repository's
|
|
191
|
+
own commands from its settings, and writes the default branch as the name
|
|
192
|
+
`factory default-branch` prints. `tests/boundary.test.ts` lists the words
|
|
193
|
+
it fails on. The three files written only for a website or an end-to-end
|
|
194
|
+
suite, `factory-ui-reviewer`, `factory-e2e-reviewer`, and `factory-design`,
|
|
195
|
+
may name a browser tool, and `factory-deps` npm's own files and commands,
|
|
196
|
+
since the factory's update is an npm package's.
|
|
197
|
+
|
|
167
198
|
## Adding a ticket system
|
|
168
199
|
|
|
169
200
|
Only GitHub is built. The factory is built so that a second system is an
|
|
@@ -454,8 +485,8 @@ drawn out of.
|
|
|
454
485
|
## Writing for the factory
|
|
455
486
|
|
|
456
487
|
- **American English, with the Oxford comma.**
|
|
457
|
-
- **The factory's own words:** ticket, follow-up, the six states, the
|
|
458
|
-
|
|
488
|
+
- **The factory's own words:** ticket, follow-up, the six states, the seven
|
|
489
|
+
slots. Not issue, card, or sweep.
|
|
459
490
|
- **A key name must make sense unexplained.** Each reference settings file
|
|
460
491
|
is read cold by a fresh agent that is told only what the factory is. A key
|
|
461
492
|
it explains wrongly, or cannot tell from another, is renamed or given a
|
package/docs/existing-repo.md
CHANGED
|
@@ -36,9 +36,10 @@ project is written in. In a PHP, Python, or Go repository that means:
|
|
|
36
36
|
- **Your own CI does not change.** The factory's cloud jobs install Node
|
|
37
37
|
for themselves. If you turn on the automated review, how it installs your
|
|
38
38
|
project, such as `composer install`, is yours to edit.
|
|
39
|
-
- **Your commands stay yours.**
|
|
40
|
-
[`
|
|
41
|
-
|
|
39
|
+
- **Your commands stay yours.** The gate a build runs, and everything
|
|
40
|
+
else under [`commands`](configuration.md#commands) in the settings, is
|
|
41
|
+
whatever your project runs: `composer test`, `make check`,
|
|
42
|
+
`go vet ./...`.
|
|
42
43
|
|
|
43
44
|
The factory's hooks run its own tool, so they need nothing beyond Node.
|
|
44
45
|
Someone who only writes code by hand, and never runs an agent session in
|
|
@@ -139,9 +140,10 @@ and how to undo each. The short version:
|
|
|
139
140
|
- Files it owns, all named `factory-...`, and its rules.
|
|
140
141
|
- One line in your agent's instructions file, and a few hooks in your
|
|
141
142
|
agent's settings.
|
|
142
|
-
- Hooks that stop a session committing on your
|
|
143
|
-
pushing, and that run your
|
|
144
|
-
|
|
143
|
+
- Hooks that stop a session committing on your default branch or force
|
|
144
|
+
pushing, and that run your
|
|
145
|
+
[`commands.before-commit`](configuration.md#commandsbefore-commit)
|
|
146
|
+
commands. They apply to agent sessions, not to your own terminal.
|
|
145
147
|
- Its CI workflows: one that checks the factory's files are in step, the
|
|
146
148
|
ones that run a session in the cloud, and one more for each optional part
|
|
147
149
|
you turn on. With a Dependabot configuration, two more complete
|
package/docs/github/by-hand.md
CHANGED
|
@@ -32,7 +32,7 @@ If you followed the quick start, this is done.
|
|
|
32
32
|
1. Write `.claude/factory.yaml`, with your repository's owner and name:
|
|
33
33
|
|
|
34
34
|
```yaml
|
|
35
|
-
version:
|
|
35
|
+
version: 2
|
|
36
36
|
repository: your-name/your-repo
|
|
37
37
|
```
|
|
38
38
|
|
|
@@ -47,14 +47,26 @@ If you followed the quick start, this is done.
|
|
|
47
47
|
to `CLAUDE.md`; and writes the workflows under `.github/workflows/`.
|
|
48
48
|
[What lives where](reference.md) names each.
|
|
49
49
|
|
|
50
|
-
3.
|
|
51
|
-
|
|
50
|
+
3. List the commands that check a change, such as your tests and linter,
|
|
51
|
+
under [`commands.gate`](../configuration.md#commandsgate). A build runs
|
|
52
|
+
them, and cannot finish without them:
|
|
53
|
+
|
|
54
|
+
```yaml
|
|
55
|
+
commands:
|
|
56
|
+
gate:
|
|
57
|
+
- npm test
|
|
58
|
+
- npm run lint
|
|
59
|
+
```
|
|
60
|
+
|
|
52
61
|
4. Optionally, list commands to run before every commit a session makes,
|
|
53
|
-
under
|
|
62
|
+
under
|
|
63
|
+
[`commands.before-commit`](../configuration.md#commandsbefore-commit),
|
|
64
|
+
in the same block:
|
|
54
65
|
|
|
55
66
|
```yaml
|
|
56
|
-
|
|
57
|
-
-
|
|
67
|
+
commands:
|
|
68
|
+
before-commit:
|
|
69
|
+
- npm run lint
|
|
58
70
|
```
|
|
59
71
|
|
|
60
72
|
5. Check, commit, and merge:
|
|
@@ -68,8 +80,9 @@ If you followed the quick start, this is done.
|
|
|
68
80
|
gh pr create --fill
|
|
69
81
|
```
|
|
70
82
|
|
|
71
|
-
Merge the pull request on GitHub, then
|
|
72
|
-
and start a new Claude
|
|
83
|
+
Merge the pull request on GitHub, then switch to your default branch
|
|
84
|
+
and pull, such as `git switch main && git pull`, and start a new Claude
|
|
85
|
+
Code session.
|
|
73
86
|
|
|
74
87
|
**It worked when** typing `/factory` in the new session offers
|
|
75
88
|
`/factory-refine` and `/factory-build`.
|
|
@@ -110,7 +123,7 @@ names, and `sync` writes all three:
|
|
|
110
123
|
- npx tsc --noEmit
|
|
111
124
|
```
|
|
112
125
|
|
|
113
|
-
Each
|
|
126
|
+
Each command under it is one the reviewer may run to confirm a finding,
|
|
114
127
|
such as your tests. To let it run nothing of yours, write the key
|
|
115
128
|
alone, and it reads the pull request and comments:
|
|
116
129
|
|
|
@@ -177,7 +190,7 @@ it has work and its secrets:
|
|
|
177
190
|
| ----------------------- | ------------------------------------------------------------------------------------ |
|
|
178
191
|
| `factory-build.yml` | builds a ticket |
|
|
179
192
|
| `factory-review.yml` | answers a review you submit on a pull request |
|
|
180
|
-
| `factory-conflicts.yml` | resolves a conflict between a pull request and your
|
|
193
|
+
| `factory-conflicts.yml` | resolves a conflict between a pull request and your default branch |
|
|
181
194
|
| `factory-deps.yml` | moves Dependabot's pull requests along, written once `.github/dependabot.yml` exists |
|
|
182
195
|
|
|
183
196
|
1. **Store your Claude token** as `CLAUDE_CODE_OAUTH_TOKEN`.
|
package/docs/github/reference.md
CHANGED
|
@@ -73,7 +73,7 @@ anything to do, and stops there when there is not.
|
|
|
73
73
|
|
|
74
74
|
| Workflow | Starts on | What it does |
|
|
75
75
|
| ----------------------------- | --------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
76
|
-
| `factory-check.yml` | Every pull request
|
|
76
|
+
| `factory-check.yml` | Every pull request, and a push to the default branch | Fails when the factory's files differ from what your settings and version would write |
|
|
77
77
|
| `factory-build.yml` | The poller, `factory build N`, or by hand | Runs a session that builds the ticket |
|
|
78
78
|
| `factory-review.yml` | A review you submit on a pull request | Runs a session that answers it, when `factory pr review-pending N REVIEW` exits 0 |
|
|
79
79
|
| `factory-conflicts.yml` | A push to the default branch, nightly at 09:00 UTC, or by hand | Runs the conflict sweep, when `factory pr conflicts` exits 0 |
|
|
@@ -163,13 +163,13 @@ number, the last part of its address, is `tickets.board` in your settings.
|
|
|
163
163
|
`sync` adds five hooks to `.claude/settings.json`. They run inside Claude
|
|
164
164
|
Code sessions in this repository, not in your own terminal.
|
|
165
165
|
|
|
166
|
-
| Hook | What it does
|
|
167
|
-
| --------------------------------------------------------- |
|
|
168
|
-
| Before a shell command | Blocks a commit on your
|
|
169
|
-
| Before posting ticket text | Refuses text with a bare `<tag>`, which GitHub would silently drop
|
|
170
|
-
| When a reviewer starts or stops | Records the run on the ticket, so its cost is counted
|
|
171
|
-
| Before an unattended build writes a file under `.claude/` | Approves the write, when the run is one the factory started and the file is not `.claude/settings.json` or `.claude/settings.local.json`
|
|
172
|
-
| When a session starts | Shows unfinished branches and where each ticket stands
|
|
166
|
+
| Hook | What it does |
|
|
167
|
+
| --------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
168
|
+
| Before a shell command | Blocks a commit on your default branch, a push to it, and a force push. Runs your [`commands.before-commit`](../configuration.md#commandsbefore-commit) commands before a commit |
|
|
169
|
+
| Before posting ticket text | Refuses text with a bare `<tag>`, which GitHub would silently drop |
|
|
170
|
+
| When a reviewer starts or stops | Records the run on the ticket, so its cost is counted |
|
|
171
|
+
| Before an unattended build writes a file under `.claude/` | Approves the write, when the run is one the factory started and the file is not `.claude/settings.json` or `.claude/settings.local.json` |
|
|
172
|
+
| When a session starts | Shows unfinished branches and where each ticket stands |
|
|
173
173
|
|
|
174
174
|
Claude Code protects `.claude/`, and an unattended run denies a write
|
|
175
175
|
there that nothing approves. The fourth hook approves, only in a run the
|
|
@@ -223,9 +223,11 @@ still laid out as a valid Claude Code plugin, so loading the skills from
|
|
|
223
223
|
it instead of copying them stays possible.
|
|
224
224
|
|
|
225
225
|
**Your project's instructions** are its `CLAUDE.md` files: the one at the
|
|
226
|
-
root, and any beside the code they govern. The skills read
|
|
227
|
-
|
|
228
|
-
|
|
226
|
+
root, and any beside the code they govern. The skills read the rules for
|
|
227
|
+
each area from them. How to check a change is not there: it is
|
|
228
|
+
[`commands.gate`](../configuration.md#commandsgate) in your settings.
|
|
229
|
+
`sync` adds one line to the root `CLAUDE.md`, which loads the factory's
|
|
230
|
+
rules.
|
|
229
231
|
|
|
230
232
|
## Dependency bots
|
|
231
233
|
|
|
@@ -270,9 +272,12 @@ factory.
|
|
|
270
272
|
- GitHub switches off scheduled workflows in a public repository with no
|
|
271
273
|
activity for 60 days.
|
|
272
274
|
- GitHub limits how many jobs an account runs at the same time.
|
|
273
|
-
- **A
|
|
274
|
-
|
|
275
|
-
|
|
275
|
+
- **A workflow's trigger cannot ask for the default branch's name,** so
|
|
276
|
+
`factory sync` writes the name into the push triggers of
|
|
277
|
+
`factory-check.yml` and `factory-conflicts.yml`. After you rename the
|
|
278
|
+
default branch, `factory sync --check` fails until you run
|
|
279
|
+
`factory sync` again, and until then the conflict sweep runs nightly and
|
|
280
|
+
by hand, not on a push.
|
|
276
281
|
- **Every review event costs a minute of Actions,** including the
|
|
277
282
|
factory's own replies, which start runs that find nothing to do.
|
|
278
283
|
- **A token from a GitHub App is not supported** for a build. The run asks
|
package/docs/github/setup.md
CHANGED
|
@@ -69,12 +69,13 @@ you left off.
|
|
|
69
69
|
|
|
70
70
|
`init` ends with this list, under "Left to do":
|
|
71
71
|
|
|
72
|
-
| If you chose | Do this
|
|
73
|
-
| -------------------------------------------- |
|
|
74
|
-
| Anything
|
|
75
|
-
|
|
|
76
|
-
|
|
|
77
|
-
|
|
|
72
|
+
| If you chose | Do this |
|
|
73
|
+
| -------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
|
|
74
|
+
| Anything, while your settings name no gate | Add the commands that check a change, such as your tests and linter, under [`commands.gate`](../configuration.md#commandsgate). A build cannot finish without them |
|
|
75
|
+
| Anything | Commit what it wrote on a branch, open a pull request, and merge it, as in [step 3 of the quick start](../quick-start.md#3-merge-the-setup) |
|
|
76
|
+
| The automated review | Install the Claude GitHub App on the repository, from <https://github.com/apps/claude>. The review posts its comments through it |
|
|
77
|
+
| Builds from the board, on a server you host | Run the poller's image with the four values `init` prints. [Hosting the poller](../builds.md#hosting-the-poller-own-server) has the steps |
|
|
78
|
+
| Signed commits, and it could not add the key | Add the public key it prints to the GitHub account that made the access token you pasted: Settings, "SSH and GPG keys", "New SSH key", key type "Signing Key" |
|
|
78
79
|
|
|
79
80
|
## Optional: tune it
|
|
80
81
|
|
|
@@ -93,11 +94,13 @@ Each is a few lines in `.claude/factory.yaml`, merged like any change.
|
|
|
93
94
|
```
|
|
94
95
|
|
|
95
96
|
- **Run a command before every commit a session makes,** such as your
|
|
96
|
-
linter, under
|
|
97
|
+
linter, under
|
|
98
|
+
[`commands.before-commit`](../configuration.md#commandsbefore-commit):
|
|
97
99
|
|
|
98
100
|
```yaml
|
|
99
|
-
|
|
100
|
-
-
|
|
101
|
+
commands:
|
|
102
|
+
before-commit:
|
|
103
|
+
- npm run lint
|
|
101
104
|
```
|
|
102
105
|
|
|
103
106
|
- **Tell the reviewer what your `CLAUDE.md` does not say** about your
|
package/docs/glossary.md
CHANGED
|
@@ -30,7 +30,7 @@ follows the factory's skills, and writes the change. Today: Claude Code.
|
|
|
30
30
|
written so each item can be checked. Refining a ticket produces it.
|
|
31
31
|
|
|
32
32
|
**Agent (reviewer).** A separate reviewer that a session launches to read
|
|
33
|
-
something and report back. It changes nothing. The factory brings
|
|
33
|
+
something and report back. It changes nothing. The factory brings four,
|
|
34
34
|
and you can add your own.
|
|
35
35
|
|
|
36
36
|
**Approver.** A person whose comments a session treats as instructions,
|
|
@@ -57,6 +57,10 @@ your board.
|
|
|
57
57
|
written into your repository by `factory sync`. You do not
|
|
58
58
|
edit them.
|
|
59
59
|
|
|
60
|
+
**Default branch.** The branch your pull requests merge into, often
|
|
61
|
+
called `main`. The factory reads its name from your checkout or your code
|
|
62
|
+
host, and assumes none.
|
|
63
|
+
|
|
60
64
|
**Dependency bot.** A tool that opens pull requests when a dependency has
|
|
61
65
|
a new version.
|
|
62
66
|
|
|
@@ -64,8 +68,9 @@ a new version.
|
|
|
64
68
|
small problems sessions noticed while doing other work.
|
|
65
69
|
|
|
66
70
|
**Gate.** The commands that must pass before a session calls a task done,
|
|
67
|
-
such as your tests and linter. Yours,
|
|
68
|
-
|
|
71
|
+
such as your tests and linter. Yours, listed under
|
|
72
|
+
[`commands.gate`](configuration.md#commandsgate) in your settings and run
|
|
73
|
+
by `factory gate`. A build cannot finish without one.
|
|
69
74
|
|
|
70
75
|
**Hook.** A command the coding agent runs at a set moment in a session,
|
|
71
76
|
such as before a shell command. The factory uses hooks to block risky
|
|
@@ -99,6 +104,11 @@ your machine or in the cloud.
|
|
|
99
104
|
for the factory's own. You call one by asking a session in plain words,
|
|
100
105
|
such as "refine ticket 12".
|
|
101
106
|
|
|
107
|
+
**Slot.** One of the seven moments where the factory calls a plug-in, such
|
|
108
|
+
as `reviewer`, for an agent that reads a finished change, or `refiner`,
|
|
109
|
+
for a skill that refines a ticket in place of the factory's own.
|
|
110
|
+
[Plug-ins](plugins.md#the-slots) lists them.
|
|
111
|
+
|
|
102
112
|
**Spec.** A written statement of what a change must do. For most tickets
|
|
103
113
|
that is the acceptance criteria. With OpenSpec turned on, a change your
|
|
104
114
|
users will see also gets its behavior recorded in the repository.
|
package/docs/limitations.md
CHANGED
|
@@ -30,8 +30,28 @@ as a code host's billing or what its workflows can see, are in
|
|
|
30
30
|
- **It is written for one approver.** `approvers` lets a team list several
|
|
31
31
|
people (_[Planned](developing.md#what-is-built)_), but review by teams, required reviewers per folder, and monorepos
|
|
32
32
|
with several owners are not designed.
|
|
33
|
-
- **The order of the workflow is fixed.**
|
|
34
|
-
|
|
33
|
+
- **The order of the workflow is fixed.** A [plug-in](plugins.md) of
|
|
34
|
+
yours can replace how a ticket is refined, how a ticket with one of your
|
|
35
|
+
labels is built, how a test is proved able to fail, which agents review
|
|
36
|
+
the tests, and how a generated file is rebuilt after a conflict, and you
|
|
37
|
+
can add reviewers and turn written specs off. The six states and their
|
|
38
|
+
order still cannot change: you cannot add a state, leave one out, or
|
|
39
|
+
reorder them ([why](design.md#the-order-of-the-workflow-is-fixed)).
|
|
40
|
+
- **A build needs a gate you wrote.** With nothing under
|
|
41
|
+
[`commands.gate`](configuration.md#commandsgate), `factory gate` fails
|
|
42
|
+
and a build stops there. The factory cannot guess how your repository is
|
|
43
|
+
checked.
|
|
44
|
+
- **A renamed default branch is read under its old name** until
|
|
45
|
+
`git remote set-head origin --auto` runs in the checkout, which keeps
|
|
46
|
+
the name in `origin/HEAD`. The factory reads the name there before it
|
|
47
|
+
asks the code host, so a stale one gives a stale answer: the commit hook
|
|
48
|
+
then guards the old branch and not the new one. After the rename, run
|
|
49
|
+
that command in each checkout, then `factory sync`, which writes the
|
|
50
|
+
name into two workflows.
|
|
51
|
+
- **One lock file is rebuilt for you after a conflict,** the one
|
|
52
|
+
[`commands.relock`](configuration.md#commandsrelock) rebuilds, npm's by
|
|
53
|
+
default. A second, such as another package manager's beside the
|
|
54
|
+
factory's own, needs a [resolver](plugins.md#resolver) of yours.
|
|
35
55
|
- **On a board with no refining column, a ticket cannot be sent back to the
|
|
36
56
|
backlog by moving its card.** The card already shows in the backlog column
|
|
37
57
|
while a ticket is being refined, so the move says nothing.
|
|
@@ -78,6 +98,11 @@ as a code host's billing or what its workflows can see, are in
|
|
|
78
98
|
merge policy. They could match differently. The switch compares the old and new
|
|
79
99
|
decision on recent pull requests.
|
|
80
100
|
- **A scheduled job as the poller,** including what it costs.
|
|
101
|
+
- **A default branch not called `main`.** The name is read, never assumed,
|
|
102
|
+
and the tests run with a branch called `develop`, but no repository with
|
|
103
|
+
one has run the factory.
|
|
104
|
+
- **A refiner, a prover, or a resolver of your own.** The settings accept
|
|
105
|
+
each and the skills call them, but no repository has run one.
|
|
81
106
|
- **Windows.** The tool and its hooks need only Node, but nothing here has
|
|
82
107
|
been run on Windows.
|
|
83
108
|
- **Adding the factory's columns to a board you already have.**
|