@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.
Files changed (43) hide show
  1. package/README.md +9 -8
  2. package/dist/cli.mjs +12 -0
  3. package/dist/config.d.mts +57 -3
  4. package/dist/config.mjs +268 -18
  5. package/dist/deps.d.mts +6 -4
  6. package/dist/deps.mjs +29 -7
  7. package/dist/doctor.d.mts +3 -0
  8. package/dist/doctor.mjs +7 -4
  9. package/dist/explain.d.mts +12 -1
  10. package/dist/explain.mjs +47 -32
  11. package/dist/init.mjs +6 -4
  12. package/dist/lib/default-branch.d.mts +1 -1
  13. package/dist/lib/default-branch.mjs +2 -2
  14. package/dist/preset-commands.d.mts +65 -0
  15. package/dist/preset-commands.mjs +1148 -0
  16. package/dist/preset.d.mts +169 -0
  17. package/dist/preset.mjs +550 -0
  18. package/dist/remove.mjs +34 -1
  19. package/dist/session-start.d.mts +3 -0
  20. package/dist/session-start.mjs +12 -1
  21. package/dist/sync.d.mts +42 -7
  22. package/dist/sync.mjs +165 -31
  23. package/docs/builds.md +12 -11
  24. package/docs/cli.md +21 -2
  25. package/docs/configuration.md +65 -13
  26. package/docs/developing.md +9 -2
  27. package/docs/github/by-hand.md +5 -5
  28. package/docs/github/reference.md +2 -17
  29. package/docs/github/setup.md +1 -1
  30. package/docs/glossary.md +12 -2
  31. package/docs/limitations.md +3 -0
  32. package/docs/plugins.md +16 -5
  33. package/docs/presets.md +410 -0
  34. package/docs/quick-start.md +20 -17
  35. package/docs/skills.md +21 -16
  36. package/docs/updating.md +14 -7
  37. package/docs/workflow.md +12 -13
  38. package/package.json +1 -1
  39. package/settings.schema.json +52 -3
  40. package/skills/factory-deps/SKILL.md +23 -12
  41. package/skills/factory-design/SKILL.md +1 -1
  42. package/skills/factory-resolve-conflicts/SKILL.md +6 -0
  43. 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 asking a session in plain words, such as "refine ticket
9
- 12". Your coding agent may also have a shorter way to call one by name; on
10
- Claude Code it is a slash command, as
11
- [the reference](github/reference.md#skills-in-claude-code) shows.
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
- | Ask a session | Skill | It does |
48
- | ---------------------------------- | --------------------------- | ------------------------------------------------------------------------ |
49
- | "refine ticket 12" | `factory-refine` | Turns a ticket into a spec a builder can start from |
50
- | "build ticket 12" | `factory-build` | Builds a ticket to a reviewed pull request |
51
- | "address the review on 280" | `factory-address-review` | Works a pull request's review until it can merge |
52
- | "resolve the conflicts on 280" | `factory-resolve-conflicts` | Merges your default branch into a pull request and settles the conflicts |
53
- | "diagnose this failing test" | `factory-diagnose` | Finds a bug's cause before any code changes |
54
- | "mutate this test" | `factory-mutate` | Proves a test can fail |
55
- | "fix the dependency pull requests" | `factory-deps` | Moves dependency pull requests toward merged |
56
- | "mock up a new about page" | `factory-design` | Designs a visible change to a website, with mockups |
57
- | "trace this rule change" | `factory-trace` | Traces a change to the rules through every kind of 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. Telling a session "build ticket 12" is approval. So is moving the ticket
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 | What happened | What to do |
228
- | --------------------------------------------------------------------------- | --------------------------------------------------------------------- | -------------------------------------------------------------------------- |
229
- | 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 |
230
- | `factory doctor` says your installed version is older than the repository's | You pulled an update and have not installed it | Run `npm ci` |
231
- | 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) |
232
- | 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 |
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 | Tell a session to build it, or move its card to Ready |
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 telling a
33
- session to build the ticket, or by running
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 | It means |
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 ask to refine it |
56
- | refining → ready | **You**, by moving the card, or by telling a session to build it |
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
- | The session noticed | It becomes |
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
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@davidbyoung/software-factory",
3
- "version": "0.1.5",
3
+ "version": "0.1.6",
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": {
@@ -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", "labels"]
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", "files"]
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", "files"]
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, and this skill
12
- never turns it on or merges anything: the owner reads a major's migration,
13
- and every update of the factory, before it lands.
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, as
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` gets steps 2 and
137
- 3, and the files the new version writes. After `npm ci` on its branch:
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, or any other `factory` command, fails on the settings after
144
- the update, the release changed the settings' shape, as version 2 does.
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 with the
154
- files the sync changed and the release notes' steps to do by hand, first.
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 `.claude/factory.yaml` has a `site` block:
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 cat-file -e "$BASE:.claude/factory.yaml" 2>/dev/null; then
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"