@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.
Files changed (80) 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 +28 -1
  7. package/dist/code-host/github-setup.mjs +1 -1
  8. package/dist/commands.d.mts +16 -0
  9. package/dist/commands.mjs +129 -0
  10. package/dist/config.d.mts +61 -13
  11. package/dist/config.mjs +271 -69
  12. package/dist/deps.d.mts +7 -4
  13. package/dist/deps.mjs +20 -9
  14. package/dist/doctor.d.mts +3 -2
  15. package/dist/doctor.mjs +19 -4
  16. package/dist/explain.d.mts +4 -2
  17. package/dist/explain.mjs +70 -23
  18. package/dist/guard-commit.d.mts +7 -2
  19. package/dist/guard-commit.mjs +58 -21
  20. package/dist/init.d.mts +4 -2
  21. package/dist/init.mjs +18 -8
  22. package/dist/lib/default-branch.d.mts +35 -0
  23. package/dist/lib/default-branch.mjs +117 -0
  24. package/dist/lib/refined-check.d.mts +7 -0
  25. package/dist/lib/refined-check.mjs +76 -0
  26. package/dist/lib/work-status.d.mts +2 -2
  27. package/dist/lib/work-status.mjs +4 -4
  28. package/dist/parts.d.mts +1 -1
  29. package/dist/parts.mjs +2 -2
  30. package/dist/patch-coverage.d.mts +13 -0
  31. package/dist/patch-coverage.mjs +73 -0
  32. package/dist/pr-watch.d.mts +3 -2
  33. package/dist/pr-watch.mjs +22 -5
  34. package/dist/pr.mjs +34 -2
  35. package/dist/review-cost.mjs +1 -1
  36. package/dist/review-tools.mjs +3 -3
  37. package/dist/session-start.d.mts +23 -13
  38. package/dist/session-start.mjs +56 -44
  39. package/dist/site/servers.d.mts +6 -2
  40. package/dist/site/servers.mjs +14 -9
  41. package/dist/site.mjs +2 -2
  42. package/dist/sync.d.mts +8 -2
  43. package/dist/sync.mjs +41 -7
  44. package/dist/ticket.mjs +19 -1
  45. package/docs/builds.md +8 -8
  46. package/docs/cli.md +82 -45
  47. package/docs/configuration.md +838 -565
  48. package/docs/design.md +17 -4
  49. package/docs/developing.md +44 -8
  50. package/docs/existing-repo.md +9 -7
  51. package/docs/github/by-hand.md +27 -14
  52. package/docs/github/reference.md +21 -16
  53. package/docs/github/setup.md +14 -11
  54. package/docs/glossary.md +14 -5
  55. package/docs/limitations.md +27 -2
  56. package/docs/plugins.md +307 -52
  57. package/docs/quick-start.md +37 -9
  58. package/docs/removing.md +2 -2
  59. package/docs/skills.md +103 -54
  60. package/docs/updating.md +149 -3
  61. package/docs/workflow.md +13 -10
  62. package/package.json +1 -1
  63. package/review.md +20 -11
  64. package/rules.md +23 -19
  65. package/settings.schema.json +292 -72
  66. package/skills/factory-address-review/SKILL.md +50 -30
  67. package/skills/factory-build/SKILL.md +76 -23
  68. package/skills/factory-deps/SKILL.md +46 -21
  69. package/skills/factory-design/SKILL.md +18 -9
  70. package/skills/factory-diagnose/SKILL.md +22 -20
  71. package/skills/factory-mutate/SKILL.md +38 -24
  72. package/skills/factory-refine/SKILL.md +55 -31
  73. package/skills/factory-resolve-conflicts/SKILL.md +76 -34
  74. package/skills/factory-trace/SKILL.md +3 -2
  75. package/workflows/factory-build.yml +1 -1
  76. package/workflows/factory-claude-review.yml +1 -1
  77. package/workflows/factory-conflicts.yml +8 -8
  78. package/workflows/factory-deps.yml +1 -1
  79. package/workflows/factory-review.yml +1 -1
  80. 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 [plugin](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 pull request 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
@@ -44,7 +44,7 @@ marked working below exist only in these docs.
44
44
  | The follow-ups ticket as one checklist | Working |
45
45
  | The `factory` tool, `sync`, and the package folder | Working |
46
46
  | A global `factory` command that runs each repository's own copy | Working |
47
- | The automated review as one of the factory's workflows, and [`ci-review`](configuration.md#ci-review) | Working |
47
+ | The automated review as one of the factory's workflows, and [`pr-review`](configuration.md#pr-review) | Working |
48
48
  | Nothing in the package names the repository it was drawn out of, checked in the folder and the packed tarball | Working |
49
49
  | The `factory-` names and the `FACTORY_` secrets | Working |
50
50
  | Ticket commands that go through one interface | Working |
@@ -61,13 +61,18 @@ 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 plugins 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 |
69
74
  | Each tool's setup, checks, and removal declared by the tool | Working |
70
- | Sharing plug-ins between repositories | Not planned |
75
+ | Sharing plugins between repositories | Not planned |
71
76
 
72
77
  When a part is built, its pull request updates this table, and corrects any
73
78
  page the build had to differ from. [The CLI](cli.md) marks each command
@@ -88,7 +93,7 @@ built or planned.
88
93
  skills/factory-*/SKILL.md the skills
89
94
  agents/factory-*.md the built-in reviewers
90
95
  rules.md the process rules
91
- review.md the CI reviewer's instructions
96
+ review.md the pull request reviewer's instructions
92
97
  workflows/factory-*.yml the workflows copied into .github/workflows/
93
98
  poller.Dockerfile the poller's image
94
99
  docs/ these pages
@@ -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 plugin role** goes in `ROLES` and `ROLE_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,7 +485,7 @@ 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
488
+ - **The factory's own words:** ticket, follow-up, the six states, the seven
458
489
  roles. 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
@@ -487,3 +518,8 @@ this repository's own reviewer, reads a changed page as that person.
487
518
  what each line is for.
488
519
  - **A step ends with how the reader knows it worked.**
489
520
  - **Each fact has one home.** Every other page links to it.
521
+ - **Write it as you would say it to a new teammate.** Whole sentences, a
522
+ person doing each thing, and an example where the rule is abstract. A
523
+ word the factory gives its own meaning, such as "the sync" or "a
524
+ session", is explained or linked where the page first uses it. A table
525
+ cell reads as part of a sentence, and no column repeats another.
@@ -36,15 +36,16 @@ 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
45
46
  the repository, needs none of this.
46
47
 
47
- [Configuration](configuration.md#a-repository-that-is-not-javascript) has a
48
+ [Configuration](configuration.md#a-project-that-isnt-javascript) has a
48
49
  complete settings file for a PHP library.
49
50
 
50
51
  ## You already have a board
@@ -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`.
@@ -85,7 +98,7 @@ it finds, and posts a verdict. The session that built the pull request
85
98
  answers each comment, fixing it or rejecting it with evidence.
86
99
 
87
100
  It is on while `.claude/factory.yaml` has
88
- [`ci-review`](../configuration.md#ci-review). Three files have similar
101
+ [`pr-review`](../configuration.md#pr-review). Three files have similar
89
102
  names, and `sync` writes all three:
90
103
 
91
104
  | File | What it is |
@@ -100,22 +113,22 @@ names, and `sync` writes all three:
100
113
  and also stores the Claude token for you.
101
114
  2. **Store your Claude token** as `CLAUDE_CODE_OAUTH_TOKEN`
102
115
  ([Secrets](#secrets)), unless step 1 did.
103
- 3. **Write `ci-review` in `.claude/factory.yaml`,** and run
116
+ 3. **Write `pr-review` in `.claude/factory.yaml`,** and run
104
117
  `factory sync`, which writes the three files above:
105
118
 
106
119
  ```yaml
107
- ci-review:
120
+ pr-review:
108
121
  commands:
109
122
  - npm test
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
 
117
130
  ```yaml
118
- ci-review:
131
+ pr-review:
119
132
  ```
120
133
 
121
134
  The workflow installs your project with `npm ci`, and chooses the
@@ -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 |
@@ -82,7 +82,7 @@ anything to do, and stops there when there is not.
82
82
  | `factory-board-sync.yml` | Ticket and pull request events, and nightly | Sets the board's columns and fields from the tickets' marker comments. Written once [`tickets.board`](../configuration.md#tickets) is set |
83
83
  | `factory-merge-policy.yml` | Every pull request | Labels it `merge: automatic` or `merge: manual`, and turns auto-merge on for the first. Written once `auto-merge.allow` is set |
84
84
  | `factory-review-verdict.yml` | Each automated review | Posts the "Review verdict" status from the review's summary |
85
- | `factory-claude-review.yml` | Every pull request once it is marked ready, and each push after | Runs the automated review. Written once [`ci-review`](../configuration.md#ci-review) is set |
85
+ | `factory-claude-review.yml` | Every pull request once it is marked ready, and each push after | Runs the automated review. Written once [`pr-review`](../configuration.md#pr-review) is set |
86
86
  | `factory-poller.yml` | Every `builds.poll-minutes` minutes, or by hand | Runs one pass of the poller, starting a build for each Ready ticket. Written once `builds.trigger` is `github-action` |
87
87
 
88
88
  **Starting a build by hand.** The Actions tab, "Factory build", "Run
@@ -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
@@ -209,7 +209,7 @@ a session picked the factory up.
209
209
  `.claude/skills/factory-*/` and its agents to
210
210
  `.claude/agents/factory-*.md`. Your own skills go in
211
211
  `.claude/skills/NAME/SKILL.md` and your own agents in
212
- `.claude/agents/NAME.md`, as for any Claude Code project. A plug-in names
212
+ `.claude/agents/NAME.md`, as for any Claude Code project. A plugin names
213
213
  one under [`plugins`](../configuration.md#plugins) in
214
214
  `.claude/factory.yaml`, with `skill:` for a folder in `.claude/skills/`
215
215
  and `agent:` for a file in `.claude/agents/`. An agent's description is
@@ -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,35 +69,38 @@ 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
 
81
82
  Each is a few lines in `.claude/factory.yaml`, merged like any change.
82
83
 
83
84
  - **Let the review run your tests.** `init` writes
84
- [`ci-review`](../configuration.md#ci-review) with no commands, so the
85
+ [`pr-review`](../configuration.md#pr-review) with no commands, so the
85
86
  reviewer reads the pull request and runs nothing of yours. To let it
86
87
  confirm a finding by running something, list each command:
87
88
 
88
89
  ```yaml
89
- ci-review:
90
+ pr-review:
90
91
  commands:
91
92
  - npm test
92
93
  - npx tsc --noEmit
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
@@ -79,8 +84,7 @@ recording what happened. The board is worked out from these.
79
84
  **OpenSpec.** A tool that keeps a written description of what a project
80
85
  does, in the repository. Optional.
81
86
 
82
- **Plug-in.** One of your own skills or agents that the factory calls at a
83
- set moment.
87
+ **Plugin.** One of your own skills or agents, given a role in the work.
84
88
 
85
89
  **Poller.** A small program that watches your board and starts a cloud
86
90
  build for each ticket moved to Ready, on a server you host or on a
@@ -92,6 +96,11 @@ decisions with you along the way.
92
96
  **Review verdict.** A status on a pull request that says whether the
93
97
  automated review of the newest commit found it ready.
94
98
 
99
+ **Role.** A job in the work that a plugin of yours can take on, such as
100
+ `reviewer`, an agent that reads a finished change, or `refiner`, a skill
101
+ that refines a ticket in place of the factory's own. There are seven.
102
+ [Plugins](plugins.md#the-roles) lists them.
103
+
95
104
  **Session.** One conversation with the coding agent in your repository, on
96
105
  your machine or in the cloud.
97
106
 
@@ -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 [plugin](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.**