@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/README.md +1 -1
- package/dist/cli.mjs +1 -1
- package/dist/code-host/github-setup.mjs +1 -1
- package/dist/config.d.mts +17 -17
- package/dist/config.mjs +59 -59
- package/dist/explain.d.mts +1 -1
- package/dist/explain.mjs +11 -11
- package/dist/init.mjs +3 -3
- 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/review-cost.mjs +1 -1
- package/dist/review-tools.mjs +3 -3
- package/dist/sync.mjs +1 -1
- package/docs/cli.md +6 -6
- package/docs/configuration.md +672 -715
- package/docs/design.md +1 -1
- package/docs/developing.md +12 -7
- package/docs/existing-repo.md +1 -1
- package/docs/github/by-hand.md +4 -4
- package/docs/github/reference.md +2 -2
- package/docs/github/setup.md +2 -2
- package/docs/glossary.md +6 -7
- package/docs/limitations.md +1 -1
- package/docs/plugins.md +22 -21
- package/docs/quick-start.md +1 -1
- package/docs/removing.md +1 -1
- package/docs/skills.md +7 -7
- package/docs/updating.md +8 -7
- package/docs/workflow.md +1 -1
- package/package.json +1 -1
- package/rules.md +1 -1
- package/settings.schema.json +8 -8
- package/skills/factory-build/SKILL.md +1 -1
- package/skills/factory-design/SKILL.md +1 -1
- package/skills/factory-refine/SKILL.md +2 -2
- package/workflows/factory-claude-review.yml +1 -1
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
|
|
@@ -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.
|
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
|
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
|
|
@@ -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
|
|
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
|
package/docs/github/setup.md
CHANGED
|
@@ -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
|
@@ -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
|
-
**
|
|
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.
|
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
|
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
|
+
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
|
|
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 | 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
|
|
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
|
|
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,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
|
|
392
|
-
`files` or `labels` where the
|
|
393
|
-
4. Run `factory config check`. It fails, naming the
|
|
394
|
-
missing, or 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.
|
|
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
|
|
406
|
+
**It worked when** your plugin is in that list, in its role.
|
|
406
407
|
|
|
407
|
-
No sync is needed.
|
|
408
|
+
No sync is needed. Plugins are read from your settings each time.
|
|
408
409
|
|
|
409
|
-
## What is not a
|
|
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
|
|
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
|
|
package/docs/quick-start.md
CHANGED
|
@@ -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 [
|
|
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
|
-
|
|
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
|
-
[
|
|
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`
|
|
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`
|
|
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`
|
|
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`
|
|
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`
|
|
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`
|
|
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
|
|
100
|
-
| A
|
|
101
|
-
| A
|
|
102
|
-
| A
|
|
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
|
|
199
|
-
reviewers, and conflict resolvers ([
|
|
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 [
|
|
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
|
-
[
|
|
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
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
|
|
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
|
|
package/settings.schema.json
CHANGED
|
@@ -60,8 +60,8 @@
|
|
|
60
60
|
"auto-merge": {
|
|
61
61
|
"$ref": "#/definitions/auto-merge"
|
|
62
62
|
},
|
|
63
|
-
"
|
|
64
|
-
"$ref": "#/definitions/
|
|
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
|
|
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": "
|
|
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": "
|
|
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": "
|
|
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": "
|
|
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
|
-
"
|
|
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
|
|
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`
|
|
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
|
|
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
|
|
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
|
-
# `
|
|
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
|