@davidbyoung/software-factory 0.1.5 → 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 +12 -0
- package/dist/config.d.mts +57 -3
- package/dist/config.mjs +268 -18
- 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 +12 -1
- package/dist/explain.mjs +47 -32
- package/dist/init.mjs +6 -4
- package/dist/lib/default-branch.d.mts +1 -1
- package/dist/lib/default-branch.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/session-start.d.mts +3 -0
- package/dist/session-start.mjs +12 -1
- package/dist/sync.d.mts +42 -7
- package/dist/sync.mjs +165 -31
- package/docs/builds.md +12 -11
- package/docs/cli.md +21 -2
- package/docs/configuration.md +65 -13
- package/docs/developing.md +9 -2
- package/docs/github/by-hand.md +5 -5
- package/docs/github/reference.md +2 -17
- package/docs/github/setup.md +1 -1
- package/docs/glossary.md +12 -2
- package/docs/limitations.md +3 -0
- package/docs/plugins.md +16 -5
- package/docs/presets.md +410 -0
- package/docs/quick-start.md +20 -17
- package/docs/skills.md +21 -16
- package/docs/updating.md +14 -7
- package/docs/workflow.md +12 -13
- package/package.json +1 -1
- package/settings.schema.json +52 -3
- package/skills/factory-deps/SKILL.md +23 -12
- package/skills/factory-design/SKILL.md +1 -1
- package/skills/factory-resolve-conflicts/SKILL.md +6 -0
- package/workflows/factory-claude-review.yml +7 -2
package/docs/skills.md
CHANGED
|
@@ -5,10 +5,12 @@ it. An agent, in this page's sense, is a separate reviewer a session
|
|
|
5
5
|
launches, which reads and reports and changes nothing. This page covers
|
|
6
6
|
every skill and agent the factory brings.
|
|
7
7
|
|
|
8
|
-
You call a skill by
|
|
9
|
-
|
|
10
|
-
Claude Code
|
|
11
|
-
|
|
8
|
+
You call a skill by typing its name as a slash command in a session, with
|
|
9
|
+
the ticket or pull request number after it: `/factory-refine 12`. Slash
|
|
10
|
+
commands are how Claude Code, the one coding agent the factory supports
|
|
11
|
+
today, calls a skill. Asking in
|
|
12
|
+
plain words, such as "refine ticket 12", usually calls the same skill, but
|
|
13
|
+
the session decides which one fits, so the command is the sure way.
|
|
12
14
|
|
|
13
15
|
## Which ones a repository gets
|
|
14
16
|
|
|
@@ -44,17 +46,20 @@ refiner, builder, prover, test reviewers, and conflict resolvers.
|
|
|
44
46
|
|
|
45
47
|
## At a glance
|
|
46
48
|
|
|
47
|
-
|
|
|
48
|
-
|
|
|
49
|
-
| "refine ticket 12" |
|
|
50
|
-
| "build ticket 12" |
|
|
51
|
-
| "address the review on 280" |
|
|
52
|
-
| "resolve the conflicts on 280" |
|
|
53
|
-
| "diagnose this failing test" |
|
|
54
|
-
| "mutate this test" |
|
|
55
|
-
| "fix the dependency pull requests" |
|
|
56
|
-
| "mock up a new about page" |
|
|
57
|
-
| "trace this rule change" |
|
|
49
|
+
| Slash command | Plain words that also work | What it does |
|
|
50
|
+
| -------------------------------- | ---------------------------------- | ------------------------------------------------------------------------ |
|
|
51
|
+
| `/factory-refine 12` | "refine ticket 12" | Turns a ticket into a spec a builder can start from |
|
|
52
|
+
| `/factory-build 12` | "build ticket 12" | Builds a ticket to a reviewed pull request |
|
|
53
|
+
| `/factory-address-review 280` | "address the review on 280" | Works a pull request's review until it can merge |
|
|
54
|
+
| `/factory-resolve-conflicts 280` | "resolve the conflicts on 280" | Merges your default branch into a pull request and settles the conflicts |
|
|
55
|
+
| `/factory-diagnose` | "diagnose this failing test" | Finds a bug's cause before any code changes |
|
|
56
|
+
| `/factory-mutate` | "mutate this test" | Proves a test can fail |
|
|
57
|
+
| `/factory-deps` | "fix the dependency pull requests" | Moves dependency pull requests toward merged |
|
|
58
|
+
| `/factory-design` | "mock up a new about page" | Designs a visible change to a website, with mockups |
|
|
59
|
+
| `/factory-trace` | "trace this rule change" | Traces a change to the rules through every kind of change |
|
|
60
|
+
|
|
61
|
+
Typing `/factory` in a session lists them, which is also how to check that
|
|
62
|
+
a session picked the factory up.
|
|
58
63
|
|
|
59
64
|
## `factory-refine`
|
|
60
65
|
|
|
@@ -126,7 +131,7 @@ leave for the build. To add questions to this one, write them under
|
|
|
126
131
|
review with `factory-address-review`.
|
|
127
132
|
|
|
128
133
|
**When to use it.** On a ticket that has acceptance criteria and your
|
|
129
|
-
approval.
|
|
134
|
+
approval. Running `/factory-build 12` in a session is approval. So is moving the ticket
|
|
130
135
|
to Ready.
|
|
131
136
|
|
|
132
137
|
**What it reads.** The ticket, its Decisions, and your project's
|
package/docs/updating.md
CHANGED
|
@@ -23,7 +23,8 @@ settings file: [Moving to settings version 2](#moving-to-settings-version-2).
|
|
|
23
23
|
## What the pull request holds
|
|
24
24
|
|
|
25
25
|
- **The new version**, in `package.json`, the lockfile, and
|
|
26
|
-
`.claude/factory.lock`.
|
|
26
|
+
`.claude/factory.lock`. The lock also holds every setting in effect, so
|
|
27
|
+
a release that changes a default shows in its diff.
|
|
27
28
|
- **The factory's files, rewritten.** Its skills, agents, rules, and CI
|
|
28
29
|
workflows live in your repository, so the diff shows exactly which
|
|
29
30
|
instruction changed.
|
|
@@ -33,6 +34,10 @@ settings file: [Moving to settings version 2](#moving-to-settings-version-2).
|
|
|
33
34
|
An update changes the instructions your sessions follow and the code that
|
|
34
35
|
runs with your tokens. Read it as carefully as you would read code.
|
|
35
36
|
|
|
37
|
+
A new version of a [preset](presets.md) arrives the same way, with a
|
|
38
|
+
comment saying what it changes in this repository:
|
|
39
|
+
[When a preset changes](presets.md#when-a-preset-changes).
|
|
40
|
+
|
|
36
41
|
## Doing it yourself
|
|
37
42
|
|
|
38
43
|
To update now instead of waiting for Dependabot:
|
|
@@ -224,12 +229,14 @@ not match `package-lock.json`.
|
|
|
224
229
|
|
|
225
230
|
## When something goes wrong
|
|
226
231
|
|
|
227
|
-
| What you see
|
|
228
|
-
|
|
|
229
|
-
| CI fails with "the factory's files are out of sync"
|
|
230
|
-
| `factory doctor` says your installed version is older than the repository's
|
|
231
|
-
| A command stops with `version: must be 2`
|
|
232
|
-
|
|
|
232
|
+
| What you see | What happened | What to do |
|
|
233
|
+
| ------------------------------------------------------------------------------------- | --------------------------------------------------------------------- | -------------------------------------------------------------------------- |
|
|
234
|
+
| CI fails with "the factory's files are out of sync" | A factory file was edited by hand, or settings changed without a sync | Run `factory sync` and commit the result |
|
|
235
|
+
| `factory doctor` says your installed version is older than the repository's | You pulled an update and have not installed it | Run `npm ci` |
|
|
236
|
+
| A command stops with `version: must be 2` | The update changed the shape of the settings file | [Move the file](#moving-to-settings-version-2) |
|
|
237
|
+
| A command stops with `.claude/factory.lock is from an earlier version of the factory` | The update's sync has not run on this checkout | Run `factory sync` and commit the result |
|
|
238
|
+
| A command stops with `.claude/factory.yaml changed since the last sync` | The settings changed without a sync | Run `factory sync` and commit the result |
|
|
239
|
+
| The update pull request conflicts with your default branch | Something else changed the same file | `factory-deps` resolves it on its next run, or close it and update by hand |
|
|
233
240
|
|
|
234
241
|
## Never edit a factory file
|
|
235
242
|
|
package/docs/workflow.md
CHANGED
|
@@ -9,7 +9,7 @@ each step, and what the factory will not do on its own.
|
|
|
9
9
|
| ----------------- | -------------------------------------------------- | -------------------------------------------------- | ----------------------------------------------------------------------------- |
|
|
10
10
|
| Write a ticket | You | Your ticket system | A ticket saying what, why, and when it is done |
|
|
11
11
|
| Refine it | A session you start | Your machine, in your coding agent | The ticket rewritten into acceptance criteria, after you answer its decisions |
|
|
12
|
-
| Approve it | **You** | A session, or your board |
|
|
12
|
+
| Approve it | **You** | A session, or your board | Run `/factory-build N` in a session, or move its card to Ready |
|
|
13
13
|
| Build it | A session | Your machine, or the cloud when started from Ready | A tested change in a pull request that closes the ticket |
|
|
14
14
|
| Review it | The automated review, if you set it up | Your CI | Comments and a verdict on the pull request |
|
|
15
15
|
| Answer the review | The session that built it | Where it was built | Each comment fixed, or rejected with evidence |
|
|
@@ -29,11 +29,10 @@ default names.
|
|
|
29
29
|
|
|
30
30
|
A state with no column of its own shows in the column of the nearest earlier
|
|
31
31
|
state that has one, and a ticket is shown in the `ready` column only when it
|
|
32
|
-
is approved. A board without a `ready` column approves a build by
|
|
33
|
-
|
|
34
|
-
`factory build N`.
|
|
32
|
+
is approved. A board without a `ready` column approves a build by running
|
|
33
|
+
`/factory-build N` in a session, or by running `factory build N`.
|
|
35
34
|
|
|
36
|
-
| State | Board column |
|
|
35
|
+
| State | Board column | What it means |
|
|
37
36
|
| -------- | ------------- | ----------------------------------------------------------------------------- |
|
|
38
37
|
| backlog | Backlog | Nothing is happening |
|
|
39
38
|
| refining | In refinement | A session is turning it into a spec, or the spec is written and waits for you |
|
|
@@ -50,13 +49,13 @@ backlog → refining → ready → building → review → done
|
|
|
50
49
|
|
|
51
50
|
## Who moves a ticket
|
|
52
51
|
|
|
53
|
-
| Move | Who
|
|
54
|
-
| ------------------ |
|
|
55
|
-
| backlog → refining | The session you
|
|
56
|
-
| refining → ready | **You**, by moving the card, or by
|
|
57
|
-
| ready → building | The session that claims it
|
|
58
|
-
| building → review | Opening the pull request
|
|
59
|
-
| review → done | The merge, which closes the ticket
|
|
52
|
+
| Move | Who |
|
|
53
|
+
| ------------------ | -------------------------------------------------------------------------- |
|
|
54
|
+
| backlog → refining | The session you run `/factory-refine N` in |
|
|
55
|
+
| refining → ready | **You**, by moving the card, or by running `/factory-build N` in a session |
|
|
56
|
+
| ready → building | The session that claims it |
|
|
57
|
+
| building → review | Opening the pull request |
|
|
58
|
+
| review → done | The merge, which closes the ticket |
|
|
60
59
|
|
|
61
60
|
Approving a ticket is the only move a person has to make. A session moves
|
|
62
61
|
the card to Ready only when you ask it to, as your own move.
|
|
@@ -149,7 +148,7 @@ small fixes on one checklist cost you one approval and one pull request.
|
|
|
149
148
|
|
|
150
149
|
**What becomes a line, and what gets its own ticket.**
|
|
151
150
|
|
|
152
|
-
|
|
|
151
|
+
| What the session noticed | What it becomes |
|
|
153
152
|
| -------------------------------------------------------- | ----------------------------------------------------- |
|
|
154
153
|
| Something small that breaks a rule your guides state | A line |
|
|
155
154
|
| Something that needs your call before it can be fixed | A line that says "Needs a decision:" and the question |
|
package/package.json
CHANGED
package/settings.schema.json
CHANGED
|
@@ -15,6 +15,15 @@
|
|
|
15
15
|
"pattern": "^[\\w.-]+/[\\w.-]+$",
|
|
16
16
|
"description": "The repository's owner and name, as owner/name."
|
|
17
17
|
},
|
|
18
|
+
"presets": {
|
|
19
|
+
"type": "array",
|
|
20
|
+
"uniqueItems": true,
|
|
21
|
+
"items": {
|
|
22
|
+
"type": "string",
|
|
23
|
+
"minLength": 1
|
|
24
|
+
},
|
|
25
|
+
"description": "The presets this repository follows, each an npm package, or a folder of one, holding a factory-preset.yaml. Later ones win over earlier ones, and this file wins over them all."
|
|
26
|
+
},
|
|
18
27
|
"tickets": {
|
|
19
28
|
"description": "Where tickets live and how their state is shown.",
|
|
20
29
|
"anyOf": [
|
|
@@ -403,9 +412,21 @@
|
|
|
403
412
|
"minLength": 1
|
|
404
413
|
},
|
|
405
414
|
"description": "It builds a ticket carrying one of these labels."
|
|
415
|
+
},
|
|
416
|
+
"off": {
|
|
417
|
+
"const": true,
|
|
418
|
+
"description": "Leaves out the plugin of this name that a preset adds. Only this file can."
|
|
406
419
|
}
|
|
407
420
|
},
|
|
408
|
-
"required": ["skill",
|
|
421
|
+
"required": ["skill"],
|
|
422
|
+
"anyOf": [
|
|
423
|
+
{
|
|
424
|
+
"required": ["labels"]
|
|
425
|
+
},
|
|
426
|
+
{
|
|
427
|
+
"required": ["off"]
|
|
428
|
+
}
|
|
429
|
+
]
|
|
409
430
|
},
|
|
410
431
|
"plugins.build.reviewers[]": {
|
|
411
432
|
"type": "object",
|
|
@@ -425,9 +446,21 @@
|
|
|
425
446
|
"minLength": 1
|
|
426
447
|
},
|
|
427
448
|
"description": "It is considered when a change touches one of these."
|
|
449
|
+
},
|
|
450
|
+
"off": {
|
|
451
|
+
"const": true,
|
|
452
|
+
"description": "Leaves out the plugin of this name that a preset adds. Only this file can."
|
|
428
453
|
}
|
|
429
454
|
},
|
|
430
|
-
"required": ["agent",
|
|
455
|
+
"required": ["agent"],
|
|
456
|
+
"anyOf": [
|
|
457
|
+
{
|
|
458
|
+
"required": ["files"]
|
|
459
|
+
},
|
|
460
|
+
{
|
|
461
|
+
"required": ["off"]
|
|
462
|
+
}
|
|
463
|
+
]
|
|
431
464
|
},
|
|
432
465
|
"plugins.test.prover": {
|
|
433
466
|
"type": "object",
|
|
@@ -460,6 +493,10 @@
|
|
|
460
493
|
"minLength": 1
|
|
461
494
|
},
|
|
462
495
|
"description": "It is considered only when a change touches one of these. Left out, it is considered whenever a change touches tests."
|
|
496
|
+
},
|
|
497
|
+
"off": {
|
|
498
|
+
"const": true,
|
|
499
|
+
"description": "Leaves out the plugin of this name that a preset adds. Only this file can."
|
|
463
500
|
}
|
|
464
501
|
},
|
|
465
502
|
"required": ["agent"]
|
|
@@ -482,9 +519,21 @@
|
|
|
482
519
|
"minLength": 1
|
|
483
520
|
},
|
|
484
521
|
"description": "It resolves a conflict in one of these."
|
|
522
|
+
},
|
|
523
|
+
"off": {
|
|
524
|
+
"const": true,
|
|
525
|
+
"description": "Leaves out the plugin of this name that a preset adds. Only this file can."
|
|
485
526
|
}
|
|
486
527
|
},
|
|
487
|
-
"required": ["skill",
|
|
528
|
+
"required": ["skill"],
|
|
529
|
+
"anyOf": [
|
|
530
|
+
{
|
|
531
|
+
"required": ["files"]
|
|
532
|
+
},
|
|
533
|
+
{
|
|
534
|
+
"required": ["off"]
|
|
535
|
+
}
|
|
536
|
+
]
|
|
488
537
|
},
|
|
489
538
|
"auto-merge": {
|
|
490
539
|
"type": "object",
|
|
@@ -8,9 +8,10 @@ description: Move every open Dependabot pull request one step closer to merged:
|
|
|
8
8
|
A minor or patch bump already has auto-merge on, set by
|
|
9
9
|
`factory-deps-auto-merge.yml`, so it merges by itself once its checks are
|
|
10
10
|
green. The job here is to get it there. A major bump never has
|
|
11
|
-
auto-merge, and neither does a bump of the factory itself
|
|
12
|
-
never turns it on or merges anything:
|
|
13
|
-
and every update of the factory
|
|
11
|
+
auto-merge, and neither does a bump of the factory itself or of a preset
|
|
12
|
+
the settings list, and this skill never turns it on or merges anything:
|
|
13
|
+
the owner reads a major's migration, and every update of the factory or a
|
|
14
|
+
preset, before it lands.
|
|
14
15
|
|
|
15
16
|
Every command below goes through `factory deps`, `factory ticket`, or
|
|
16
17
|
`factory pr`. The default branch's name is what
|
|
@@ -70,7 +71,8 @@ take the default branch's lock file, run `commands.relock`, the command
|
|
|
70
71
|
`npx --no-install factory config get commands.relock` prints, so the bump
|
|
71
72
|
is reapplied on top of it, and commit the merge. Any other conflicted file
|
|
72
73
|
that matches the `files` of a resolver
|
|
73
|
-
(`npx --no-install factory plugins resolver`) is that resolver's,
|
|
74
|
+
(`npx --no-install factory plugins resolver`) is that resolver's, and a
|
|
75
|
+
conflict in `.claude/factory.lock` is resolved first, by `factory sync`, as
|
|
74
76
|
"Merge" in the `factory-resolve-conflicts` skill says.
|
|
75
77
|
|
|
76
78
|
Then go on: a branch with a conflict can be failing as well.
|
|
@@ -131,27 +133,36 @@ running after 20 minutes: leave the bump for the next run.
|
|
|
131
133
|
If one still fails, try once more in the same run. A second failure is the
|
|
132
134
|
end for this run: comment what was tried and leave it for the next one.
|
|
133
135
|
|
|
134
|
-
## 4. An update of the factory
|
|
136
|
+
## 4. An update of the factory or a preset
|
|
135
137
|
|
|
136
|
-
A pull request that bumps `@davidbyoung/software-factory
|
|
137
|
-
|
|
138
|
+
A pull request that bumps `@davidbyoung/software-factory`, or the package
|
|
139
|
+
of a preset `.claude/factory.lock` lists, gets steps 2 and 3, and the files
|
|
140
|
+
the new version writes. `factory deps` says `sync (step 4)` for each. Run
|
|
141
|
+
the sync right after `npm ci` on its branch, before step 3's gate: until it
|
|
142
|
+
runs, every `factory` command stops on the stale lock and names it.
|
|
138
143
|
|
|
139
144
|
```bash
|
|
140
145
|
npx --no-install factory sync
|
|
141
146
|
```
|
|
142
147
|
|
|
143
|
-
When the sync
|
|
144
|
-
|
|
148
|
+
When the sync itself fails on the settings after the update, the release
|
|
149
|
+
changed the settings' shape, as version 2 does.
|
|
145
150
|
Stop (step 6), and say the settings are the owner's to move, as "Moving to
|
|
146
151
|
settings version 2" in the factory's `docs/updating.md` says for that
|
|
147
152
|
release. Never edit `.claude/factory.yaml`.
|
|
148
153
|
|
|
149
154
|
Commit what the sync wrote as a second commit, "Sync the factory's files to
|
|
150
|
-
VERSION", and push. The push changes workflows, so it needs a token with
|
|
155
|
+
VERSION" or "Sync the settings to PACKAGE VERSION", and push. The push changes workflows, so it needs a token with
|
|
151
156
|
the `workflow` scope, such as the build token; a refused push is a stop
|
|
152
157
|
(step 6), with GitHub's error. Until then CI's `factory sync --check` fails, which is
|
|
153
|
-
the sign the commit is missing. Then comment on the pull request
|
|
154
|
-
files the sync changed and the release notes' steps to do by
|
|
158
|
+
the sign the commit is missing. Then comment on the pull request: for the
|
|
159
|
+
factory, the files the sync changed and the release notes' steps to do by
|
|
160
|
+
hand, first; for a preset, what this prints, as it stands:
|
|
161
|
+
|
|
162
|
+
```bash
|
|
163
|
+
npx --no-install factory preset changes origin/DEFAULT
|
|
164
|
+
```
|
|
165
|
+
|
|
155
166
|
Never enable auto-merge, never approve and never merge: it waits for the
|
|
156
167
|
owner, whatever its size.
|
|
157
168
|
|
|
@@ -10,7 +10,7 @@ them a recommendation, not a menu. Each round the owner has to spend
|
|
|
10
10
|
catching a defect or making a design call is a round this skill exists to
|
|
11
11
|
remove.
|
|
12
12
|
|
|
13
|
-
It works on any site whose
|
|
13
|
+
It works on any site whose settings have a `site` block:
|
|
14
14
|
`site.start` says how to build and serve it, and `factory site compare`
|
|
15
15
|
pictures it.
|
|
16
16
|
|
|
@@ -153,6 +153,12 @@ area" in `CLAUDE.md`).
|
|
|
153
153
|
line on one side and a real change on the other is not a contradiction:
|
|
154
154
|
apply both. In content, that includes sweeps such as the serial
|
|
155
155
|
comma.
|
|
156
|
+
- **`.claude/factory.lock`, first:** it is never merged by hand. Resolve
|
|
157
|
+
`.claude/factory.yaml` and `.claude/factory.choices.yaml`, take either
|
|
158
|
+
side's lock, and run `npx --no-install factory sync`, which writes it
|
|
159
|
+
from them. Do it before anything else that runs `factory`: every command
|
|
160
|
+
but the sync reads its settings from the lock, and stops while it is
|
|
161
|
+
conflicted or stale.
|
|
156
162
|
- **The lock file `commands.relock` regenerates:** resolve the manifest
|
|
157
163
|
it is generated from first, then take the default branch's copy of the
|
|
158
164
|
lock file and run `commands.relock`, the command
|
|
@@ -85,14 +85,19 @@ jobs:
|
|
|
85
85
|
done
|
|
86
86
|
|
|
87
87
|
# From the base commit too, so a change to the settings alone cannot
|
|
88
|
-
# widen the commands its own review may run.
|
|
88
|
+
# widen the commands its own review may run. Its lock holds them, from
|
|
89
|
+
# a preset as well; a lock written before presets holds no settings,
|
|
90
|
+
# and then the base commit's settings file does.
|
|
89
91
|
- name: List the tools the review may use
|
|
90
92
|
id: tools
|
|
91
93
|
env:
|
|
92
94
|
BASE: ${{ github.event.pull_request.base.sha }}
|
|
93
95
|
FACTORY_SETTINGS: ${{ runner.temp }}/factory.yaml
|
|
94
96
|
run: |
|
|
95
|
-
if git
|
|
97
|
+
if git show "$BASE:.claude/factory.lock" > "$RUNNER_TEMP/factory.lock" 2>/dev/null &&
|
|
98
|
+
grep -q '^settings:' "$RUNNER_TEMP/factory.lock"; then
|
|
99
|
+
export FACTORY_LOCK="$RUNNER_TEMP/factory.lock"
|
|
100
|
+
elif git cat-file -e "$BASE:.claude/factory.yaml" 2>/dev/null; then
|
|
96
101
|
git show "$BASE:.claude/factory.yaml" > "$FACTORY_SETTINGS"
|
|
97
102
|
else
|
|
98
103
|
cp .claude/factory.yaml "$FACTORY_SETTINGS"
|