@davidbyoung/software-factory 0.1.4 → 0.1.5

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/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
@@ -518,3 +518,8 @@ this repository's own reviewer, reads a changed page as that person.
518
518
  what each line is for.
519
519
  - **A step ends with how the reader knows it worked.**
520
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.
@@ -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
@@ -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
@@ -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
@@ -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
@@ -84,8 +84,7 @@ recording what happened. The board is worked out from these.
84
84
  **OpenSpec.** A tool that keeps a written description of what a project
85
85
  does, in the repository. Optional.
86
86
 
87
- **Plug-in.** One of your own skills or agents that the factory calls at a
88
- set moment.
87
+ **Plugin.** One of your own skills or agents, given a role in the work.
89
88
 
90
89
  **Poller.** A small program that watches your board and starts a cloud
91
90
  build for each ticket moved to Ready, on a server you host or on a
@@ -97,6 +96,11 @@ decisions with you along the way.
97
96
  **Review verdict.** A status on a pull request that says whether the
98
97
  automated review of the newest commit found it ready.
99
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
+
100
104
  **Session.** One conversation with the coding agent in your repository, on
101
105
  your machine or in the cloud.
102
106
 
@@ -104,11 +108,6 @@ your machine or in the cloud.
104
108
  for the factory's own. You call one by asking a session in plain words,
105
109
  such as "refine ticket 12".
106
110
 
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
-
112
111
  **Spec.** A written statement of what a change must do. For most tickets
113
112
  that is the acceptance criteria. With OpenSpec turned on, a change your
114
113
  users will see also gets its behavior recorded in the repository.
@@ -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
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
+ each belongs to. Every role is optional, and leaving one out never turns a
37
38
  step off: the last column says what does the work then.
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 | It | Left out |
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
 
@@ -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,10 +389,10 @@ 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.
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.
395
396
  5. Run `factory plugins` to see the list the factory will use, the
396
397
  built-in ones included:
397
398
 
@@ -402,11 +403,11 @@ instructions for the agent and in the agent itself. The factory holds none of th
402
403
  agent factory-test-reviewer test-reviewer
403
404
  ```
404
405
 
405
- **It worked when** your plug-in is in that list, in its slot.
406
+ **It worked when** your plugin is in that list, in its role.
406
407
 
407
- No sync is needed. Plug-ins are read from your settings each time.
408
+ No sync is needed. Plugins are read from your settings each time.
408
409
 
409
- ## What is not a plug-in
410
+ ## What is not a plugin
410
411
 
411
412
  - **A skill you call yourself.** If nothing in refining, building, or
412
413
  reviewing a ticket should call it, it needs no entry. It stays an
@@ -419,7 +420,7 @@ No sync is needed. Plug-ins are read from your settings each time.
419
420
  - **A question you want every refinement to ask.** That is a line under
420
421
  "Refining: this repository" in `CLAUDE.md`, as [`refiner`](#refiner)
421
422
  says.
422
- - **A step in another order.** A plug-in replaces a step where it stands.
423
+ - **A step in another order.** A plugin replaces a step where it stands.
423
424
  It cannot add a state or move one
424
425
  ([Why it works this way](design.md#the-order-of-the-workflow-is-fixed)).
425
426
 
@@ -203,5 +203,5 @@ optional, stands alone, and can come later.
203
203
  [`commands.before-commit`](configuration.md#commandsbefore-commit).
204
204
  - **Your own reviewers,** so a change to your content or your design is
205
205
  read by an expert agent: a few lines under
206
- [`plugins`](configuration.md#plugins), which [Plug-ins](plugins.md)
206
+ [`plugins`](configuration.md#plugins), which [Plugins](plugins.md)
207
207
  walks through.
package/docs/removing.md CHANGED
@@ -28,7 +28,7 @@ hook, label, and setting.
28
28
  ## What it never touches
29
29
 
30
30
  Your code, your tickets, and your pull requests. Your own skills, agents,
31
- plug-ins, and CI workflows, which the factory never writes to.
31
+ plugins, and CI workflows, which the factory never writes to.
32
32
 
33
33
  One file belongs to you, and removing the factory leaves it: the review
34
34
  notes you write for the automated review. The review's workflow is the
package/docs/skills.md CHANGED
@@ -39,7 +39,7 @@ commands such as `factory gate` and `factory test-one`
39
39
  `factory default-branch` for your default branch's name.
40
40
 
41
41
  Where a step below names a built-in skill or agent, a
42
- [plug-in](plugins.md#the-slots) of yours can stand in for it: your own
42
+ [plugin](plugins.md#the-roles) of yours can stand in for it: your own
43
43
  refiner, builder, prover, test reviewers, and conflict resolvers.
44
44
 
45
45
  ## At a glance
@@ -79,7 +79,7 @@ spec when [`specs`](configuration.md#specs) is on.
79
79
  you.
80
80
  - A blocked-by relationship for each ticket that must be built first.
81
81
  - For a decision about the look, mockups from your
82
- [`mockups` plug-in](plugins.md), if you have one.
82
+ [`mockups` plugin](plugins.md), if you have one.
83
83
 
84
84
  **How it asks.** In the session if you are there: each decision as a
85
85
  choice, the recommended answer first. Otherwise as one comment on the
@@ -96,7 +96,7 @@ ask. Then `factory ticket refined` refuses to mark the ticket refined
96
96
  while its body lacks a section a build reads.
97
97
 
98
98
  **Your own in its place.** A skill of yours can refine tickets instead, as
99
- the [`refiner` plug-in](plugins.md#refiner), which lists what it has to
99
+ the [`refiner` plugin](plugins.md#refiner), which lists what it has to
100
100
  leave for the build. To add questions to this one, write them under
101
101
  "Refining: this repository" in your `CLAUDE.md`.
102
102
 
@@ -109,14 +109,14 @@ leave for the build. To add questions to this one, write them under
109
109
  3. Builds to the acceptance criteria: the test first where there is a
110
110
  defect to reproduce or a behavior to add, then the change. A ticket
111
111
  carrying a label of one of your
112
- [`builder` plug-ins](plugins.md#builder) is built by that skill
112
+ [`builder` plugins](plugins.md#builder) is built by that skill
113
113
  instead.
114
114
  4. Proves each new test can fail, by its failing run before the change or
115
115
  with the [prover](plugins.md#prover), which is `factory-mutate` unless
116
116
  you name your own, and has the
117
117
  [test reviewers](plugins.md#test-reviewer) read the tests:
118
118
  `factory-test-reviewer`, unless your settings list others.
119
- 5. Has each [`reviewer` plug-in](plugins.md#reviewer) that applies read the
119
+ 5. Has each [`reviewer` plugin](plugins.md#reviewer) that applies read the
120
120
  change, and fixes what they find.
121
121
  6. Runs the gate with `factory gate`: the commands under
122
122
  [`commands.gate`](configuration.md#commandsgate) in your settings.
@@ -240,7 +240,7 @@ your visitors are from your project's own instructions.
240
240
  **When to use it.** When asked to redesign or restyle a page, and from
241
241
  `factory-refine` when a decision changes how something looks. A
242
242
  repository with `site` in its settings gets it as its
243
- [`mockups` plug-in](plugins.md) without listing it; one without `site`
243
+ [`mockups` plugin](plugins.md) without listing it; one without `site`
244
244
  does not get it at all.
245
245
 
246
246
  **What it never does.** Make a mockup of a change with no look to choose,
@@ -273,7 +273,7 @@ file's shape for you to write.
273
273
  conflicts with it, runs the gate, and pushes the merge. It never rebases or
274
274
  forces a push. A conflict in the lock file is settled by rebuilding it with
275
275
  [`commands.relock`](configuration.md#commandsrelock), and one in a file
276
- that a [`resolver` plug-in](plugins.md#resolver) of yours rebuilds, by
276
+ that a [`resolver` plugin](plugins.md#resolver) of yours rebuilds, by
277
277
  that skill. When the two sides of a conflict contradict each other, it
278
278
  pushes nothing, comments why, and opens a ticket, because which side wins
279
279
  is your decision.
package/docs/updating.md CHANGED
@@ -96,10 +96,11 @@ and its checks fail until the file is moved. On the pull request's branch:
96
96
  | `version: 1` | `version: 2` |
97
97
  | `before-commit`, at the top of the file | [`commands.before-commit`](configuration.md#commandsbefore-commit) |
98
98
  | `build-setup`, at the top of the file | [`commands.build-setup`](configuration.md#commandsbuild-setup) |
99
- | [`plugins`](configuration.md#plugins), one list, each item with a `role` | `plugins`, grouped by phase, each plug-in in a slot, with no `role` |
100
- | A plug-in with `role: mockups` | The one block [`plugins.refine.mockups`](configuration.md#pluginsrefine) |
101
- | A plug-in with `role: builder` | An item of the list [`plugins.build.builders`](configuration.md#pluginsbuild) |
102
- | A plug-in with `role: reviewer` | An item of the list `plugins.build.reviewers` |
99
+ | [`plugins`](configuration.md#plugins), one list, each item with a `role` | `plugins`, grouped by phase, each plugin listed under its role's key instead of a `role` field |
100
+ | A plugin with `role: mockups` | The one block [`plugins.refine.mockups`](configuration.md#pluginsrefine) |
101
+ | A plugin with `role: builder` | An item of the list [`plugins.build.builders`](configuration.md#pluginsbuild) |
102
+ | A plugin with `role: reviewer` | An item of the list `plugins.build.reviewers` |
103
+ | `ci-review` | [`pr-review`](configuration.md#pr-review), the same block under a new name |
103
104
  | [`specs`](configuration.md#specs), one word | Still one word. It is now also a block, with `type` and [`check`](configuration.md#specscheck) |
104
105
 
105
106
  Every other key keeps its name, its place, and its meaning.
@@ -195,8 +196,8 @@ needed, and the rest are worth a look while the file is open.
195
196
  - **Coverage, and the lock file:**
196
197
  [`commands.coverage`](configuration.md#commandscoverage) and
197
198
  [`commands.relock`](configuration.md#commandsrelock).
198
- - **Four more slots for plug-ins:** your own refiner, prover, test
199
- reviewers, and conflict resolvers ([Plug-ins](plugins.md#the-slots)).
199
+ - **Four more roles for plugins:** your own refiner, prover, test
200
+ reviewers, and conflict resolvers ([Plugins](plugins.md#the-roles)).
200
201
  - **The default branch is read, not assumed.** A repository whose default
201
202
  branch is not `main` needs no setting: `factory sync` writes the
202
203
  branch's name where the workflows need it.
@@ -241,7 +242,7 @@ To change what the factory does:
241
242
  - **For your repository only:** say so in your own instructions for the
242
243
  agent, which win over the factory's rules, change a number under
243
244
  [`rules`](configuration.md#rules) in your settings, or put a skill or
244
- an agent of your own in a [plug-in slot](plugins.md).
245
+ an agent of your own in a [plugin role](plugins.md).
245
246
  - **For everyone:** change it in the factory, and it reaches you as an
246
247
  update.
247
248
 
package/docs/workflow.md CHANGED
@@ -74,7 +74,7 @@ These hold in every repository. They are not settings.
74
74
  - **The order does not change.** A repository cannot add a state or reorder
75
75
  them. A team that wants a security review between building and review adds
76
76
  a [reviewer](plugins.md#reviewer), not a column. A
77
- [plug-in](plugins.md#the-slots) can take over a step, such as refining a
77
+ [plugin](plugins.md#the-roles) can take over a step, such as refining a
78
78
  ticket or proving a test, where the step stands.
79
79
  - **One session holds a ticket at a time.** The claim is a comment on the
80
80
  ticket. A second session that tries is told who holds it and stops.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@davidbyoung/software-factory",
3
- "version": "0.1.4",
3
+ "version": "0.1.5",
4
4
  "description": "Refines, builds, and reviews tickets with Claude Code sessions, from a board to a merged pull request.",
5
5
  "license": "MIT",
6
6
  "repository": {
package/rules.md CHANGED
@@ -64,7 +64,7 @@ here rather than restate it.
64
64
  - For a visible change, a UI reviewer read pointed at the states the change
65
65
  touched, not every size and scheme, and told the change is small. The UI
66
66
  reviewer is `factory-ui-reviewer` where the repository lists it, and
67
- otherwise the repository's own, among its reviewer plug-ins
67
+ otherwise the repository's own, among its reviewer plugins
68
68
  (`npx --no-install factory plugins reviewer`).
69
69
  - The gate and CI stay. The pull request says it took this path.
70
70
 
@@ -60,8 +60,8 @@
60
60
  "auto-merge": {
61
61
  "$ref": "#/definitions/auto-merge"
62
62
  },
63
- "ci-review": {
64
- "$ref": "#/definitions/ci-review"
63
+ "pr-review": {
64
+ "$ref": "#/definitions/pr-review"
65
65
  },
66
66
  "site": {
67
67
  "$ref": "#/definitions/site"
@@ -277,7 +277,7 @@
277
277
  },
278
278
  "plugins": {
279
279
  "type": "object",
280
- "description": "Your own skills and agents, grouped by the phase they work in. Every slot is optional.",
280
+ "description": "Your own skills and agents, grouped by the phase they work in. Every role is optional.",
281
281
  "additionalProperties": false,
282
282
  "properties": {
283
283
  "refine": {
@@ -296,7 +296,7 @@
296
296
  },
297
297
  "plugins.refine": {
298
298
  "type": "object",
299
- "description": "Plug-ins for refining a ticket.",
299
+ "description": "Plugins for refining a ticket.",
300
300
  "additionalProperties": false,
301
301
  "properties": {
302
302
  "refiner": {
@@ -309,7 +309,7 @@
309
309
  },
310
310
  "plugins.build": {
311
311
  "type": "object",
312
- "description": "Plug-ins for building a ticket.",
312
+ "description": "Plugins for building a ticket.",
313
313
  "additionalProperties": false,
314
314
  "properties": {
315
315
  "builders": {
@@ -330,7 +330,7 @@
330
330
  },
331
331
  "plugins.test": {
332
332
  "type": "object",
333
- "description": "Plug-ins for a change's tests.",
333
+ "description": "Plugins for a change's tests.",
334
334
  "additionalProperties": false,
335
335
  "properties": {
336
336
  "prover": {
@@ -347,7 +347,7 @@
347
347
  },
348
348
  "plugins.conflicts": {
349
349
  "type": "object",
350
- "description": "Plug-ins for a conflict with the default branch.",
350
+ "description": "Plugins for a conflict with the default branch.",
351
351
  "additionalProperties": false,
352
352
  "properties": {
353
353
  "resolvers": {
@@ -517,7 +517,7 @@
517
517
  }
518
518
  }
519
519
  },
520
- "ci-review": {
520
+ "pr-review": {
521
521
  "type": ["object", "null"],
522
522
  "additionalProperties": false,
523
523
  "description": "The automated review of every pull request: on when this is written, even with nothing under it.",
@@ -274,7 +274,7 @@ change on its own.
274
274
 
275
275
  Read the `CLAUDE.md` for the area first ("Rules by area" in `CLAUDE.md`).
276
276
 
277
- **A builder plug-in:** list them with
277
+ **A builder plugin:** list them with
278
278
  `npx --no-install factory plugins builder`, which prints each one's
279
279
  labels. When the issue carries one of a builder's labels, invoke that skill
280
280
  with the Skill tool to build it, in place of the steps below up to the
@@ -1,6 +1,6 @@
1
1
  ---
2
2
  name: factory-design
3
- description: Design a visible change to a website, a new page or a redesign, as the designer rather than asking the owner to be one: real-content mockups built from the site itself, pictured at its widths in light and dark, reviewed before anyone sees them, and one recommended design. Use when asked to redesign, restyle, or rethink how a page looks or what it says, when an issue asks for renderings to approve, and as the `mockups` plug-in `factory-refine` calls.
3
+ description: Design a visible change to a website, a new page or a redesign, as the designer rather than asking the owner to be one: real-content mockups built from the site itself, pictured at its widths in light and dark, reviewed before anyone sees them, and one recommended design. Use when asked to redesign, restyle, or rethink how a page looks or what it says, when an issue asks for renderings to approve, and as the `mockups` plugin `factory-refine` calls.
4
4
  ---
5
5
 
6
6
  # Designing a change
@@ -72,12 +72,12 @@ marker", it runs steps 4 and 5 only and posts none of these.
72
72
 
73
73
  ## 0. Read
74
74
 
75
- **A refiner plug-in replaces this skill.** Before anything else, run
75
+ **A refiner plugin replaces this skill.** Before anything else, run
76
76
  `npx --no-install factory plugins refiner`. When it prints a skill other
77
77
  than `factory-refine`, invoke that skill with the Skill tool, with the
78
78
  same ticket and words this one was given, and stop: the repository
79
79
  refines its own way, and what that skill must leave behind is in the
80
- factory's plug-ins guide.
80
+ factory's plugins guide.
81
81
 
82
82
  Post the `refining` marker first ("Labels and markers"), then:
83
83
 
@@ -1,7 +1,7 @@
1
1
  # The review that reads every pull request once it is marked ready, and
2
2
  # every push after that, with the instructions in .github/factory-review.md.
3
3
  # The commands it may run beyond reading and commenting are the settings'
4
- # `ci-review.commands`, read from the pull request's base commit
4
+ # `pr-review.commands`, read from the pull request's base commit
5
5
  # (`factory review tools`). Its credential is CLAUDE_CODE_OAUTH_TOKEN, or
6
6
  # ANTHROPIC_API_KEY when that is the one set, and
7
7
  # FACTORY_BUILD_MODEL, a repository variable, chooses the model as it does