@davidbyoung/software-factory 0.1.4 → 0.1.6

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (57) hide show
  1. package/README.md +9 -8
  2. package/dist/cli.mjs +13 -1
  3. package/dist/code-host/github-setup.mjs +1 -1
  4. package/dist/config.d.mts +74 -20
  5. package/dist/config.mjs +326 -76
  6. package/dist/deps.d.mts +6 -4
  7. package/dist/deps.mjs +29 -7
  8. package/dist/doctor.d.mts +3 -0
  9. package/dist/doctor.mjs +7 -4
  10. package/dist/explain.d.mts +13 -2
  11. package/dist/explain.mjs +58 -43
  12. package/dist/init.mjs +9 -7
  13. package/dist/lib/default-branch.d.mts +1 -1
  14. package/dist/lib/default-branch.mjs +2 -2
  15. package/dist/lib/refined-check.mjs +1 -1
  16. package/dist/lib/work-status.d.mts +2 -2
  17. package/dist/lib/work-status.mjs +4 -4
  18. package/dist/parts.d.mts +1 -1
  19. package/dist/parts.mjs +2 -2
  20. package/dist/preset-commands.d.mts +65 -0
  21. package/dist/preset-commands.mjs +1148 -0
  22. package/dist/preset.d.mts +169 -0
  23. package/dist/preset.mjs +550 -0
  24. package/dist/remove.mjs +34 -1
  25. package/dist/review-cost.mjs +1 -1
  26. package/dist/review-tools.mjs +3 -3
  27. package/dist/session-start.d.mts +3 -0
  28. package/dist/session-start.mjs +12 -1
  29. package/dist/sync.d.mts +42 -7
  30. package/dist/sync.mjs +166 -32
  31. package/docs/builds.md +12 -11
  32. package/docs/cli.md +27 -8
  33. package/docs/configuration.md +723 -714
  34. package/docs/design.md +1 -1
  35. package/docs/developing.md +20 -8
  36. package/docs/existing-repo.md +1 -1
  37. package/docs/github/by-hand.md +9 -9
  38. package/docs/github/reference.md +4 -19
  39. package/docs/github/setup.md +3 -3
  40. package/docs/glossary.md +18 -9
  41. package/docs/limitations.md +4 -1
  42. package/docs/plugins.md +36 -24
  43. package/docs/presets.md +410 -0
  44. package/docs/quick-start.md +21 -18
  45. package/docs/removing.md +1 -1
  46. package/docs/skills.md +28 -23
  47. package/docs/updating.md +22 -14
  48. package/docs/workflow.md +13 -14
  49. package/package.json +1 -1
  50. package/rules.md +1 -1
  51. package/settings.schema.json +60 -11
  52. package/skills/factory-build/SKILL.md +1 -1
  53. package/skills/factory-deps/SKILL.md +23 -12
  54. package/skills/factory-design/SKILL.md +2 -2
  55. package/skills/factory-refine/SKILL.md +2 -2
  56. package/skills/factory-resolve-conflicts/SKILL.md +6 -0
  57. package/workflows/factory-claude-review.yml +8 -3
package/docs/design.md CHANGED
@@ -69,7 +69,7 @@ differently from one day to the next.
69
69
  ## The order of the workflow is fixed
70
70
 
71
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
72
+ written specs or the automated review, and a [plugin](plugins.md) of yours can take a
73
73
  step over: how a ticket is refined, how a ticket with one of your labels
74
74
  is built, how a test is proved able to fail, which agents read the tests
75
75
  and the change, and how a generated file is rebuilt after a conflict. You
@@ -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, the gate, 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,7 +61,7 @@ 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 |
64
+ | Settings version 2: commands, a spec check, and plugins grouped by phase | Working |
65
65
  | `factory gate`, `test-one`, `end-to-end`, and `specs check`, which run the settings' commands | Working |
66
66
  | The default branch read from Git and the code host, never assumed, and `factory default-branch` | Working |
67
67
  | A refiner, a prover, test reviewers, and conflict resolvers of your own, and `factory-e2e-reviewer` | Working |
@@ -72,7 +72,7 @@ marked working below exist only in these docs.
72
72
  | A ticket system or code host named by a package, for an adapter you write yourself | Not planned. The design leaves room |
73
73
  | Another code host or runner | Not planned. The design leaves room |
74
74
  | Each tool's setup, checks, and removal declared by the tool | Working |
75
- | Sharing plug-ins between repositories | Not planned |
75
+ | Sharing plugins between repositories | Not planned |
76
76
 
77
77
  When a part is built, its pull request updates this table, and corrects any
78
78
  page the build had to differ from. [The CLI](cli.md) marks each command
@@ -93,7 +93,7 @@ built or planned.
93
93
  skills/factory-*/SKILL.md the skills
94
94
  agents/factory-*.md the built-in reviewers
95
95
  rules.md the process rules
96
- review.md the CI reviewer's instructions
96
+ review.md the pull request reviewer's instructions
97
97
  workflows/factory-*.yml the workflows copied into .github/workflows/
98
98
  poller.Dockerfile the poller's image
99
99
  docs/ these pages
@@ -111,7 +111,7 @@ in `docs/configuration.md`, and a test fails when the first two differ.
111
111
  [`commands`](configuration.md#commands), with a `factory`
112
112
  command in `src/commands.mts` that runs it, so a skill names the
113
113
  `factory` command and never the repository's own.
114
- - **A plug-in slot** goes in `SLOTS` and `SLOT_SHAPE` in `src/config.mts`,
114
+ - **A plugin role** goes in `ROLES` and `ROLE_SHAPE` in `src/config.mts`,
115
115
  which say its phase, whether it takes a skill or an agent, one or a
116
116
  list, and `files` or `labels`. Its keys in `SETTINGS_KEYS` follow from
117
117
  that table. `docs/plugins.md` gains its table of what it is handed and
@@ -486,7 +486,7 @@ drawn out of.
486
486
 
487
487
  - **American English, with the Oxford comma.**
488
488
  - **The factory's own words:** ticket, follow-up, the six states, the seven
489
- slots. Not issue, card, or sweep.
489
+ roles. Not issue, card, or sweep.
490
490
  - **A key name must make sense unexplained.** Each reference settings file
491
491
  is read cold by a fresh agent that is told only what the factory is. A key
492
492
  it explains wrongly, or cannot tell from another, is renamed or given a
@@ -509,7 +509,10 @@ this repository's own reviewer, reads a changed page as that person.
509
509
  - **A page says who it is for and what they will have at the end,** in its
510
510
  first lines.
511
511
  - **Lead with the command that does it.** The same steps by hand go on a
512
- page of their own, linked once.
512
+ page of their own, linked once. A step that runs a skill shows its slash
513
+ command, such as `/factory-refine 12`, not only words to say to a
514
+ session: words leave the session to pick the skill, and leave the reader
515
+ not knowing which one ran.
513
516
  - **Say only what the reader must do or decide.** What a command does for
514
517
  them is one sentence, and a link to the page that lists it.
515
518
  - **A setting links to its entry in `docs/configuration.md` where a page
@@ -518,3 +521,12 @@ this repository's own reviewer, reads a changed page as that person.
518
521
  what each line is for.
519
522
  - **A step ends with how the reader knows it worked.**
520
523
  - **Each fact has one home.** Every other page links to it.
524
+ - **Write it as you would say it to a new teammate.** Whole sentences, a
525
+ person doing each thing, and an example where the rule is abstract. A
526
+ word the factory gives its own meaning, such as "the sync" or "a
527
+ session", is explained or linked where the page first uses it. A table
528
+ cell reads as part of a sentence, and no column repeats another. A
529
+ column header names what its cells hold, such as "What it does" or
530
+ "Without one", and reads on its own: not a pronoun or a clipped phrase,
531
+ such as "It" or "Left out", that makes sense only once a cell is read
532
+ into it.
@@ -45,7 +45,7 @@ The factory's hooks run its own tool, so they need nothing beyond Node.
45
45
  Someone who only writes code by hand, and never runs an agent session in
46
46
  the repository, needs none of this.
47
47
 
48
- [Configuration](configuration.md#a-repository-that-is-not-javascript) has a
48
+ [Configuration](configuration.md#a-project-that-isnt-javascript) has a
49
49
  complete settings file for a PHP library.
50
50
 
51
51
  ## You already have a board
@@ -98,7 +98,7 @@ it finds, and posts a verdict. The session that built the pull request
98
98
  answers each comment, fixing it or rejecting it with evidence.
99
99
 
100
100
  It is on while `.claude/factory.yaml` has
101
- [`ci-review`](../configuration.md#ci-review). Three files have similar
101
+ [`pr-review`](../configuration.md#pr-review). Three files have similar
102
102
  names, and `sync` writes all three:
103
103
 
104
104
  | File | What it is |
@@ -113,11 +113,11 @@ names, and `sync` writes all three:
113
113
  and also stores the Claude token for you.
114
114
  2. **Store your Claude token** as `CLAUDE_CODE_OAUTH_TOKEN`
115
115
  ([Secrets](#secrets)), unless step 1 did.
116
- 3. **Write `ci-review` in `.claude/factory.yaml`,** and run
116
+ 3. **Write `pr-review` in `.claude/factory.yaml`,** and run
117
117
  `factory sync`, which writes the three files above:
118
118
 
119
119
  ```yaml
120
- ci-review:
120
+ pr-review:
121
121
  commands:
122
122
  - npm test
123
123
  - npx tsc --noEmit
@@ -128,7 +128,7 @@ names, and `sync` writes all three:
128
128
  alone, and it reads the pull request and comments:
129
129
 
130
130
  ```yaml
131
- ci-review:
131
+ pr-review:
132
132
  ```
133
133
 
134
134
  The workflow installs your project with `npm ci`, and chooses the
@@ -186,12 +186,12 @@ prints the run's link, with no session open on your machine.
186
186
  `sync` already wrote the workflows these use, and each does nothing until
187
187
  it has work and its secrets:
188
188
 
189
- | Workflow | Runs a Claude Code session that |
189
+ | Workflow | What its Claude Code session does |
190
190
  | ----------------------- | ------------------------------------------------------------------------------------ |
191
- | `factory-build.yml` | builds a ticket |
192
- | `factory-review.yml` | answers a review you submit on a pull request |
193
- | `factory-conflicts.yml` | resolves a conflict between a pull request and your default branch |
194
- | `factory-deps.yml` | moves Dependabot's pull requests along, written once `.github/dependabot.yml` exists |
191
+ | `factory-build.yml` | Builds a ticket |
192
+ | `factory-review.yml` | Answers a review you submit on a pull request |
193
+ | `factory-conflicts.yml` | Resolves a conflict between a pull request and your default branch |
194
+ | `factory-deps.yml` | Moves Dependabot's pull requests along, written once `.github/dependabot.yml` exists |
195
195
 
196
196
  1. **Store your Claude token** as `CLAUDE_CODE_OAUTH_TOKEN`.
197
197
  2. **Store a GitHub token that can push**, as `FACTORY_BUILD_TOKEN`. With
@@ -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
@@ -187,29 +187,14 @@ you set yourself alone.
187
187
 
188
188
  ## Skills in Claude Code
189
189
 
190
- In Claude Code a skill is also a slash command: type `/` and its name,
191
- with the ticket or pull request number after it. Asking in plain words
192
- calls the same skill.
193
-
194
- | Type | Same as asking |
195
- | -------------------------------- | ---------------------------------- |
196
- | `/factory-refine 12` | "refine ticket 12" |
197
- | `/factory-build 12` | "build ticket 12" |
198
- | `/factory-address-review 280` | "address the review on 280" |
199
- | `/factory-resolve-conflicts 280` | "resolve the conflicts on 280" |
200
- | `/factory-diagnose` | "diagnose this failing test" |
201
- | `/factory-mutate` | "mutate this test" |
202
- | `/factory-deps` | "fix the dependency pull requests" |
203
- | `/factory-design` | "mock up a new about page" |
204
-
205
- Typing `/factory` in a session lists them, which is also how to check that
206
- a session picked the factory up.
190
+ In Claude Code each skill is a slash command, such as `/factory-refine 12`.
191
+ [Skills](../skills.md#at-a-glance) lists every one with what it does.
207
192
 
208
193
  **Where the files live.** `sync` writes the factory's skills to
209
194
  `.claude/skills/factory-*/` and its agents to
210
195
  `.claude/agents/factory-*.md`. Your own skills go in
211
196
  `.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
197
+ `.claude/agents/NAME.md`, as for any Claude Code project. A plugin names
213
198
  one under [`plugins`](../configuration.md#plugins) in
214
199
  `.claude/factory.yaml`, with `skill:` for a folder in `.claude/skills/`
215
200
  and `agent:` for a file in `.claude/agents/`. An agent's description is
@@ -42,7 +42,7 @@ machine, which is all the [quick start](../quick-start.md) needs.
42
42
 
43
43
  It then asks only what your parts need:
44
44
 
45
- | It asks | For | What you do |
45
+ | Question | Asked when you chose | What you do |
46
46
  | ------------------------------------- | --------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------- |
47
47
  | Which board | A board | Choose a new one, made with the factory's columns, or a Project you already have |
48
48
  | Which files may merge without you | Pull requests that merge themselves | Type their patterns, such as `docs/**`. Start with a short list |
@@ -82,12 +82,12 @@ you left off.
82
82
  Each is a few lines in `.claude/factory.yaml`, merged like any change.
83
83
 
84
84
  - **Let the review run your tests.** `init` writes
85
- [`ci-review`](../configuration.md#ci-review) with no commands, so the
85
+ [`pr-review`](../configuration.md#pr-review) with no commands, so the
86
86
  reviewer reads the pull request and runs nothing of yours. To let it
87
87
  confirm a finding by running something, list each command:
88
88
 
89
89
  ```yaml
90
- ci-review:
90
+ pr-review:
91
91
  commands:
92
92
  - npm test
93
93
  - npx tsc --noEmit
package/docs/glossary.md CHANGED
@@ -78,36 +78,45 @@ commits.
78
78
 
79
79
  **Local session.** A session on your own machine.
80
80
 
81
+ **Lock.** The file `.claude/factory.lock`, which `factory sync` writes:
82
+ the factory's version, the presets, every setting in effect, and the files
83
+ it copied. Every command reads its settings from it. You commit it and
84
+ never edit it.
85
+
81
86
  **Marker.** A hidden line in a comment the factory posts on a ticket,
82
87
  recording what happened. The board is worked out from these.
83
88
 
84
89
  **OpenSpec.** A tool that keeps a written description of what a project
85
90
  does, in the repository. Optional.
86
91
 
87
- **Plug-in.** One of your own skills or agents that the factory calls at a
88
- set moment.
92
+ **Plugin.** One of your own skills or agents, given a role in the work.
89
93
 
90
94
  **Poller.** A small program that watches your board and starts a cloud
91
95
  build for each ticket moved to Ready, on a server you host or on a
92
96
  schedule in the cloud.
93
97
 
98
+ **Preset.** An npm package of settings, and of any agents and skills they
99
+ name, that several repositories share. A repository lists it under
100
+ [`presets`](configuration.md#presets), and `factory sync` combines it with
101
+ the repository's own settings. [Presets](presets.md) says how.
102
+
94
103
  **Refine.** To turn a ticket into acceptance criteria, settling the
95
104
  decisions with you along the way.
96
105
 
97
106
  **Review verdict.** A status on a pull request that says whether the
98
107
  automated review of the newest commit found it ready.
99
108
 
109
+ **Role.** A job in the work that a plugin of yours can take on, such as
110
+ `reviewer`, an agent that reads a finished change, or `refiner`, a skill
111
+ that refines a ticket in place of the factory's own. There are seven.
112
+ [Plugins](plugins.md#the-roles) lists them.
113
+
100
114
  **Session.** One conversation with the coding agent in your repository, on
101
115
  your machine or in the cloud.
102
116
 
103
117
  **Skill.** A set of instructions a session follows, named `factory-...`
104
- for the factory's own. You call one by asking a session in plain words,
105
- such as "refine ticket 12".
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.
118
+ for the factory's own. You call one by typing its name as a slash command,
119
+ such as `/factory-refine 12`.
111
120
 
112
121
  **Spec.** A written statement of what a change must do. For most tickets
113
122
  that is the acceptance criteria. With OpenSpec turned on, a change your
@@ -30,7 +30,7 @@ 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.** A [plug-in](plugins.md) of
33
+ - **The order of the workflow is fixed.** A [plugin](plugins.md) of
34
34
  yours can replace how a ticket is refined, how a ticket with one of your
35
35
  labels is built, how a test is proved able to fail, which agents review
36
36
  the tests, and how a generated file is rebuilt after a conflict, and you
@@ -48,6 +48,9 @@ as a code host's billing or what its workflows can see, are in
48
48
  then guards the old branch and not the new one. After the rename, run
49
49
  that command in each checkout, then `factory sync`, which writes the
50
50
  name into two workflows.
51
+ - **A private [preset](presets.md) works on your machine, not yet in the
52
+ factory's workflows.** _[Planned](developing.md#what-is-built)_: the
53
+ workflows can't install a private package yet.
51
54
  - **One lock file is rebuilt for you after a conflict,** the one
52
55
  [`commands.relock`](configuration.md#commandsrelock) rebuilds, npm's by
53
56
  default. A second, such as another package manager's beside the
package/docs/plugins.md CHANGED
@@ -1,4 +1,4 @@
1
- # Plug-ins
1
+ # Plugins
2
2
 
3
3
  For someone who wants the factory to use a skill or an agent of their own:
4
4
  a reviewer for one part of the code, a builder for one kind of ticket, or
@@ -6,7 +6,7 @@ their own way of refining a ticket. At the end, the factory calls it at a
6
6
  set moment of every build, and `factory plugins` lists it.
7
7
 
8
8
  The factory knows how to refine, build, and review a ticket. It does not
9
- know your project. A plug-in is one of your own skills or agents that the
9
+ know your project. A plugin is one of your own skills or agents that the
10
10
  factory calls at a set moment, so what only your project knows is part of
11
11
  every build.
12
12
 
@@ -29,21 +29,22 @@ plugins:
29
29
  That is the whole of it. The factory never copies over your files, and an
30
30
  update never touches them.
31
31
 
32
- ## The slots
32
+ ## The roles
33
33
 
34
- A slot is a moment in the work where the factory hands off. There are
34
+ A role is a job in the work that your own skill or agent can take on, such
35
+ as reviewing a change or refining a ticket. There are
35
36
  seven, grouped under [`plugins`](configuration.md#plugins) by the phase
36
- each belongs to. Every slot is optional, and leaving one out never turns a
37
- step off: the last column says what does the work then.
37
+ each belongs to. Every role is optional, and leaving one out never turns a
38
+ step off: the last column says what does the work when you have none.
38
39
 
39
- A slot has two names. The settings key, in the second column, is what you
40
- write in `.claude/factory.yaml`. The slot's own name, in the first column,
40
+ A role has two names. The settings key, in the second column, is what you
41
+ write in `.claude/factory.yaml`. The role's own name, in the first column,
41
42
  is what `factory plugins` prints, and the headings below use it: `builder`
42
- is the slot you write as
43
+ is the role you write as
43
44
  [`plugins.build.builders`](configuration.md#pluginsbuild), and no key is
44
45
  called `builder`.
45
46
 
46
- | Slot | Settings key | It | Left out |
47
+ | Role | Settings key | What it does | Without one |
47
48
  | --------------- | ------------------------------------------------------------------ | ---------------------------------------------- | ----------------------------------------- |
48
49
  | `refiner` | [`plugins.refine.refiner`](configuration.md#pluginsrefine) | Refines a ticket, in place of `factory-refine` | `factory-refine` |
49
50
  | `mockups` | [`plugins.refine.mockups`](configuration.md#pluginsrefine) | Makes pictures for a decision about the look | `factory-design` on a website, else words |
@@ -58,7 +59,7 @@ whether it takes a skill or an agent, one or a list, and `files` or
58
59
  `labels`.
59
60
 
60
61
  A reviewer is an agent: a session launches it, and it reads and changes
61
- nothing. Every other slot is a skill, which the session follows itself.
62
+ nothing. Every other role is a skill, which the session follows itself.
62
63
 
63
64
  ## Refining
64
65
 
@@ -75,7 +76,7 @@ plugins:
75
76
 
76
77
  | Step | What happens |
77
78
  | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
78
- | **Called** | When you ask a session to refine a ticket: `factory-refine` hands over to it before doing anything. By `factory-build`, on a ticket that has no criteria yet, or one you approved while its questions waited |
79
+ | **Called** | When you run `/factory-refine N` in a session: `factory-refine` hands over to it before doing anything. By `factory-build`, on a ticket that has no criteria yet, or one you approved while its questions waited |
79
80
  | **Handed** | The ticket's number. From `factory-build`, for a round of questions you approved while it waited on your answers, also the words "approved while waiting: fold the owner's replies into the body, post no marker". They tell the refiner to write your replies into the ticket's body and to post no [marker](glossary.md), the hidden comment line the board reads |
80
81
  | **Returns** | A ticket a build can start from: everything in the list below |
81
82
  | **Then** | The ticket waits for your approval, and the build reads what the refiner left |
@@ -127,7 +128,7 @@ from a copy of `factory-refine` under your own name.
127
128
  **To add questions, not replace the refiner,** write them in your own
128
129
  instructions for the agent, under a heading "Refining: this repository" in
129
130
  `CLAUDE.md`. The refining session reads `CLAUDE.md`, and it wins over the
130
- factory's rules, so no plug-in is needed for that.
131
+ factory's rules, so no plugin is needed for that.
131
132
 
132
133
  ### `mockups`
133
134
 
@@ -135,7 +136,7 @@ Makes pictures to choose from when a decision changes how something looks.
135
136
 
136
137
  A repository with [`site`](configuration.md#site) in its settings has one
137
138
  already: the factory's own `factory-design` skill, which `factory sync`
138
- writes, is its `mockups` plug-in unless you name one of your own.
139
+ writes, is its `mockups` plugin unless you name one of your own.
139
140
 
140
141
  ```yaml
141
142
  plugins:
@@ -238,7 +239,7 @@ things, as a line the pull request body takes:
238
239
  that turned the test red, for a test written after the code.
239
240
 
240
241
  One proof for each test is the rule, and it stays a rule whichever prover
241
- runs: the slot cannot be set to nothing. No script checks a prover's
242
+ runs: the role cannot be set to nothing. No script checks a prover's
242
243
  report. The pull request records it, where you read it.
243
244
 
244
245
  ### `test-reviewer`
@@ -388,11 +389,13 @@ instructions for the agent and in the agent itself. The factory holds none of th
388
389
 
389
390
  1. Write the skill or agent, and try it by hand until it does its job.
390
391
  2. Give it a description that states when it applies.
391
- 3. Add it under [`plugins`](configuration.md#plugins), in its slot, with
392
- `files` or `labels` where the slot takes them.
393
- 4. Run `factory config check`. It fails, naming the slot, if the file is
394
- missing, or the slot takes a skill and you named an agent.
395
- 5. Run `factory plugins` to see the list the factory will use, the
392
+ 3. Add it under [`plugins`](configuration.md#plugins), in its role, with
393
+ `files` or `labels` where the role takes them.
394
+ 4. Run `factory config check`. It fails, naming the role, if the file is
395
+ missing, or the role takes a skill and you named an agent.
396
+ 5. Run `factory sync`. Every command reads your settings from
397
+ `.claude/factory.lock`, which the sync writes.
398
+ 6. Run `factory plugins` to see the list the factory will use, the
396
399
  built-in ones included:
397
400
 
398
401
  ```text
@@ -402,11 +405,20 @@ instructions for the agent and in the agent itself. The factory holds none of th
402
405
  agent factory-test-reviewer test-reviewer
403
406
  ```
404
407
 
405
- **It worked when** your plug-in is in that list, in its slot.
408
+ **It worked when** your plugin is in that list, in its role.
406
409
 
407
- No sync is needed. Plug-ins are read from your settings each time.
410
+ ## Plugins from a preset
408
411
 
409
- ## What is not a plug-in
412
+ A [preset](presets.md) your repository follows can add plugins too, and
413
+ ship their agents and skills, which `factory sync` copies into
414
+ `.claude/agents/` and `.claude/skills/`. They are in the list
415
+ `factory plugins` prints, beside your own. To leave one out, name it in
416
+ your own settings with `off: true`, as
417
+ [`plugins`](configuration.md#plugins) shows, then run `factory sync`.
418
+
419
+ **It worked when** `factory plugins` no longer lists it.
420
+
421
+ ## What is not a plugin
410
422
 
411
423
  - **A skill you call yourself.** If nothing in refining, building, or
412
424
  reviewing a ticket should call it, it needs no entry. It stays an
@@ -419,7 +431,7 @@ No sync is needed. Plug-ins are read from your settings each time.
419
431
  - **A question you want every refinement to ask.** That is a line under
420
432
  "Refining: this repository" in `CLAUDE.md`, as [`refiner`](#refiner)
421
433
  says.
422
- - **A step in another order.** A plug-in replaces a step where it stands.
434
+ - **A step in another order.** A plugin replaces a step where it stands.
423
435
  It cannot add a state or move one
424
436
  ([Why it works this way](design.md#the-order-of-the-workflow-is-fixed)).
425
437