@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.
- package/README.md +9 -8
- package/dist/cli.mjs +13 -1
- package/dist/code-host/github-setup.mjs +1 -1
- package/dist/config.d.mts +74 -20
- package/dist/config.mjs +326 -76
- package/dist/deps.d.mts +6 -4
- package/dist/deps.mjs +29 -7
- package/dist/doctor.d.mts +3 -0
- package/dist/doctor.mjs +7 -4
- package/dist/explain.d.mts +13 -2
- package/dist/explain.mjs +58 -43
- package/dist/init.mjs +9 -7
- package/dist/lib/default-branch.d.mts +1 -1
- package/dist/lib/default-branch.mjs +2 -2
- package/dist/lib/refined-check.mjs +1 -1
- package/dist/lib/work-status.d.mts +2 -2
- package/dist/lib/work-status.mjs +4 -4
- package/dist/parts.d.mts +1 -1
- package/dist/parts.mjs +2 -2
- package/dist/preset-commands.d.mts +65 -0
- package/dist/preset-commands.mjs +1148 -0
- package/dist/preset.d.mts +169 -0
- package/dist/preset.mjs +550 -0
- package/dist/remove.mjs +34 -1
- package/dist/review-cost.mjs +1 -1
- package/dist/review-tools.mjs +3 -3
- package/dist/session-start.d.mts +3 -0
- package/dist/session-start.mjs +12 -1
- package/dist/sync.d.mts +42 -7
- package/dist/sync.mjs +166 -32
- package/docs/builds.md +12 -11
- package/docs/cli.md +27 -8
- package/docs/configuration.md +723 -714
- package/docs/design.md +1 -1
- package/docs/developing.md +20 -8
- package/docs/existing-repo.md +1 -1
- package/docs/github/by-hand.md +9 -9
- package/docs/github/reference.md +4 -19
- package/docs/github/setup.md +3 -3
- package/docs/glossary.md +18 -9
- package/docs/limitations.md +4 -1
- package/docs/plugins.md +36 -24
- package/docs/presets.md +410 -0
- package/docs/quick-start.md +21 -18
- package/docs/removing.md +1 -1
- package/docs/skills.md +28 -23
- package/docs/updating.md +22 -14
- package/docs/workflow.md +13 -14
- package/package.json +1 -1
- package/rules.md +1 -1
- package/settings.schema.json +60 -11
- package/skills/factory-build/SKILL.md +1 -1
- package/skills/factory-deps/SKILL.md +23 -12
- package/skills/factory-design/SKILL.md +2 -2
- package/skills/factory-refine/SKILL.md +2 -2
- package/skills/factory-resolve-conflicts/SKILL.md +6 -0
- 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 [
|
|
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
|
package/docs/developing.md
CHANGED
|
@@ -13,7 +13,7 @@ it shares with that repository: each repository's sync reads only its own
|
|
|
13
13
|
cards.
|
|
14
14
|
|
|
15
15
|
**It uses the factory on itself.** `.claude/factory.yaml` here sets the
|
|
16
|
-
board, OpenSpec, the gate, and the
|
|
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 [`
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
-
|
|
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.
|
package/docs/existing-repo.md
CHANGED
|
@@ -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-
|
|
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
|
package/docs/github/by-hand.md
CHANGED
|
@@ -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
|
-
[`
|
|
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 `
|
|
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
|
-
|
|
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
|
-
|
|
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 |
|
|
189
|
+
| Workflow | What its Claude Code session does |
|
|
190
190
|
| ----------------------- | ------------------------------------------------------------------------------------ |
|
|
191
|
-
| `factory-build.yml` |
|
|
192
|
-
| `factory-review.yml` |
|
|
193
|
-
| `factory-conflicts.yml` |
|
|
194
|
-
| `factory-deps.yml` |
|
|
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
|
package/docs/github/reference.md
CHANGED
|
@@ -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 [`
|
|
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
|
|
191
|
-
|
|
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
|
|
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
|
package/docs/github/setup.md
CHANGED
|
@@ -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
|
-
|
|
|
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
|
-
[`
|
|
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
|
-
|
|
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
|
-
**
|
|
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
|
|
105
|
-
such as
|
|
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
|
package/docs/limitations.md
CHANGED
|
@@ -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 [
|
|
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
|
-
#
|
|
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
|
|
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
|
|
32
|
+
## The roles
|
|
33
33
|
|
|
34
|
-
A
|
|
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
|
|
37
|
-
step off: the last column says what does the work
|
|
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
|
|
40
|
-
write in `.claude/factory.yaml`. The
|
|
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
|
|
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
|
-
|
|
|
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
|
|
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
|
|
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
|
|
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`
|
|
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
|
|
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
|
|
392
|
-
`files` or `labels` where the
|
|
393
|
-
4. Run `factory config check`. It fails, naming the
|
|
394
|
-
missing, or the
|
|
395
|
-
5. Run `factory
|
|
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
|
|
408
|
+
**It worked when** your plugin is in that list, in its role.
|
|
406
409
|
|
|
407
|
-
|
|
410
|
+
## Plugins from a preset
|
|
408
411
|
|
|
409
|
-
|
|
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
|
|
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
|
|