@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.
Files changed (72) hide show
  1. package/README.md +12 -11
  2. package/actions/factory-agent/action.yml +1 -1
  3. package/agents/factory-e2e-reviewer.md +102 -0
  4. package/agents/factory-test-reviewer.md +26 -64
  5. package/agents/factory-ticket-readiness.md +14 -6
  6. package/dist/cli.mjs +29 -2
  7. package/dist/commands.d.mts +16 -0
  8. package/dist/commands.mjs +129 -0
  9. package/dist/config.d.mts +61 -13
  10. package/dist/config.mjs +267 -65
  11. package/dist/deps.d.mts +7 -4
  12. package/dist/deps.mjs +20 -9
  13. package/dist/doctor.d.mts +3 -2
  14. package/dist/doctor.mjs +19 -4
  15. package/dist/explain.d.mts +4 -2
  16. package/dist/explain.mjs +66 -19
  17. package/dist/guard-commit.d.mts +7 -2
  18. package/dist/guard-commit.mjs +58 -21
  19. package/dist/init.d.mts +4 -2
  20. package/dist/init.mjs +15 -5
  21. package/dist/lib/default-branch.d.mts +35 -0
  22. package/dist/lib/default-branch.mjs +117 -0
  23. package/dist/lib/refined-check.d.mts +7 -0
  24. package/dist/lib/refined-check.mjs +76 -0
  25. package/dist/patch-coverage.d.mts +13 -0
  26. package/dist/patch-coverage.mjs +73 -0
  27. package/dist/pr-watch.d.mts +3 -2
  28. package/dist/pr-watch.mjs +22 -5
  29. package/dist/pr.mjs +34 -2
  30. package/dist/session-start.d.mts +23 -13
  31. package/dist/session-start.mjs +56 -44
  32. package/dist/site/servers.d.mts +6 -2
  33. package/dist/site/servers.mjs +14 -9
  34. package/dist/site.mjs +2 -2
  35. package/dist/sync.d.mts +8 -2
  36. package/dist/sync.mjs +40 -6
  37. package/dist/ticket.mjs +19 -1
  38. package/docs/builds.md +8 -8
  39. package/docs/cli.md +82 -45
  40. package/docs/configuration.md +455 -139
  41. package/docs/design.md +17 -4
  42. package/docs/developing.md +37 -6
  43. package/docs/existing-repo.md +8 -6
  44. package/docs/github/by-hand.md +23 -10
  45. package/docs/github/reference.md +19 -14
  46. package/docs/github/setup.md +12 -9
  47. package/docs/glossary.md +13 -3
  48. package/docs/limitations.md +27 -2
  49. package/docs/plugins.md +302 -48
  50. package/docs/quick-start.md +36 -8
  51. package/docs/removing.md +1 -1
  52. package/docs/skills.md +101 -52
  53. package/docs/updating.md +148 -3
  54. package/docs/workflow.md +13 -10
  55. package/package.json +1 -1
  56. package/review.md +20 -11
  57. package/rules.md +22 -18
  58. package/settings.schema.json +289 -69
  59. package/skills/factory-address-review/SKILL.md +50 -30
  60. package/skills/factory-build/SKILL.md +75 -22
  61. package/skills/factory-deps/SKILL.md +46 -21
  62. package/skills/factory-design/SKILL.md +17 -8
  63. package/skills/factory-diagnose/SKILL.md +22 -20
  64. package/skills/factory-mutate/SKILL.md +38 -24
  65. package/skills/factory-refine/SKILL.md +55 -31
  66. package/skills/factory-resolve-conflicts/SKILL.md +76 -34
  67. package/skills/factory-trace/SKILL.md +3 -2
  68. package/workflows/factory-build.yml +1 -1
  69. package/workflows/factory-conflicts.yml +8 -8
  70. package/workflows/factory-deps.yml +1 -1
  71. package/workflows/factory-review.yml +1 -1
  72. 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 and add reviewers. You cannot reorder the states or
72
- add one. Mapping names is cheap to support. Every extra shape of workflow
73
- is one more path each skill has to handle correctly, and a skill is
74
- instructions, which cannot be unit tested.
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
 
@@ -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, and in `docs/configuration.md`, and a test
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 three
458
- roles. Not issue, card, or sweep.
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
@@ -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
- [`before-commit`](configuration.md#before-commit) in the settings takes
41
- any command: `composer lint`, `make check`, `go vet ./...`.
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 main branch or force
143
- pushing, and that run your `before-commit` commands. They apply to agent
144
- sessions, not to your own terminal.
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
@@ -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: 1
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. Say in your `CLAUDE.md` how to check a change, such as the commands for
51
- your tests and linter. A build runs them.
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 [`before-commit`](../configuration.md#before-commit):
62
+ under
63
+ [`commands.before-commit`](../configuration.md#commandsbefore-commit),
64
+ in the same block:
54
65
 
55
66
  ```yaml
56
- before-commit:
57
- - npm run lint
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 `git switch main && git pull`,
72
- and start a new Claude Code session.
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 of `commands` is one the reviewer may run to confirm a finding,
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 main branch |
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`.
@@ -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 | Fails when the factory's files differ from what your settings and version would write |
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 main branch, a push to it, and a force push. Runs your [`before-commit`](../configuration.md#before-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 |
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 how to check a
227
- change, and the rules for each area, from them. `sync` adds one line to
228
- the root `CLAUDE.md`, which loads the factory's rules.
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 default branch not named `main` or `master` gets no conflict sweep
274
- on a push.** A copied workflow cannot ask for the default branch's name.
275
- It gets the nightly sweep, and can start one by hand.
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
@@ -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 | 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) |
75
- | The automated review | Install the Claude GitHub App on the repository, from <https://github.com/apps/claude>. The review posts its comments through it |
76
- | 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 |
77
- | 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" |
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 [`before-commit`](../configuration.md#before-commit):
97
+ linter, under
98
+ [`commands.before-commit`](../configuration.md#commandsbefore-commit):
97
99
 
98
100
  ```yaml
99
- before-commit:
100
- - npm run lint
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 three,
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, named in your instructions for the
68
- agent; without any, a session checks with the tests it wrote.
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.
@@ -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.** You can turn written specs off and
34
- add reviewers. You cannot add a state or reorder them.
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.**