@davidbyoung/software-factory 0.1.2 → 0.1.3

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 (83) hide show
  1. package/README.md +8 -9
  2. package/dist/agent/claude-code.d.mts +3 -0
  3. package/dist/agent/claude-code.mjs +89 -0
  4. package/dist/agent/index.d.mts +2 -0
  5. package/dist/agent/index.mjs +5 -0
  6. package/dist/board.mjs +1 -1
  7. package/dist/cli.mjs +17 -2
  8. package/dist/code-host/github-setup.d.mts +5 -0
  9. package/dist/code-host/github-setup.mjs +133 -0
  10. package/dist/code-host/github.mjs +4 -0
  11. package/dist/code-host/index.d.mts +1 -1
  12. package/dist/code-host/index.mjs +2 -1
  13. package/dist/code-host/types.d.mts +2 -0
  14. package/dist/config.d.mts +26 -7
  15. package/dist/config.mjs +79 -26
  16. package/dist/doctor.d.mts +6 -14
  17. package/dist/doctor.mjs +52 -64
  18. package/dist/explain.d.mts +2 -0
  19. package/dist/explain.mjs +127 -0
  20. package/dist/init.d.mts +8 -12
  21. package/dist/init.mjs +179 -131
  22. package/dist/lib/has-command.d.mts +5 -0
  23. package/dist/lib/has-command.mjs +8 -0
  24. package/dist/lib/listed.d.mts +2 -0
  25. package/dist/lib/listed.mjs +4 -0
  26. package/dist/lib/work-status.d.mts +12 -2
  27. package/dist/lib/work-status.mjs +14 -3
  28. package/dist/parts.d.mts +18 -15
  29. package/dist/parts.mjs +15 -43
  30. package/dist/poller.d.mts +20 -3
  31. package/dist/poller.mjs +62 -15
  32. package/dist/remove.d.mts +11 -0
  33. package/dist/remove.mjs +156 -0
  34. package/dist/runner/github-actions.d.mts +1 -1
  35. package/dist/runner/github-actions.mjs +12 -0
  36. package/dist/runner/index.d.mts +1 -1
  37. package/dist/runner/index.mjs +2 -1
  38. package/dist/runner/setup.d.mts +2 -0
  39. package/dist/runner/setup.mjs +22 -0
  40. package/dist/runner/types.d.mts +3 -0
  41. package/dist/runner/types.mjs +0 -2
  42. package/dist/setup.d.mts +98 -0
  43. package/dist/setup.mjs +3 -0
  44. package/dist/status.d.mts +4 -4
  45. package/dist/status.mjs +8 -7
  46. package/dist/sync.d.mts +18 -0
  47. package/dist/sync.mjs +137 -7
  48. package/dist/tickets/github-setup.d.mts +2 -0
  49. package/dist/tickets/github-setup.mjs +50 -0
  50. package/dist/tickets/github.mjs +0 -2
  51. package/dist/tickets/index.mjs +2 -1
  52. package/dist/tickets/transport.mjs +1 -3
  53. package/dist/tickets/types.mjs +0 -2
  54. package/dist/tool-names.d.mts +11 -0
  55. package/dist/tool-names.mjs +20 -0
  56. package/dist/tools.d.mts +56 -0
  57. package/dist/tools.mjs +76 -0
  58. package/docs/builds.md +103 -51
  59. package/docs/cli.md +42 -42
  60. package/docs/configuration.md +34 -32
  61. package/docs/design.md +1 -1
  62. package/docs/developing.md +143 -68
  63. package/docs/existing-repo.md +20 -9
  64. package/docs/github/by-hand.md +321 -0
  65. package/docs/github/reference.md +65 -61
  66. package/docs/github/setup.md +83 -267
  67. package/docs/glossary.md +5 -4
  68. package/docs/limitations.md +12 -10
  69. package/docs/plugins.md +9 -14
  70. package/docs/quick-start.md +62 -105
  71. package/docs/removing.md +36 -16
  72. package/docs/skills.md +47 -37
  73. package/docs/updating.md +2 -6
  74. package/docs/workflow.md +13 -12
  75. package/package.json +1 -1
  76. package/poller.Dockerfile +10 -18
  77. package/rules.md +14 -12
  78. package/settings.schema.json +24 -0
  79. package/skills/factory-build/SKILL.md +1 -1
  80. package/skills/factory-trace/SKILL.md +79 -0
  81. package/workflows/factory-build.yml +5 -4
  82. package/workflows/factory-deps-auto-merge.yml +3 -2
  83. package/workflows/factory-poller.yml +46 -0
package/rules.md CHANGED
@@ -120,12 +120,13 @@ discovering it at push time.
120
120
  - **An issue is built in GitHub Actions by moving its card to Ready** on
121
121
  the board, the GitHub Project whose number
122
122
  `npx --no-install factory config get tickets.board` prints: the
123
- `ready-poller` worker dispatches the "Factory build" workflow within
124
- about a minute, the same run that `npx --no-install factory build N`
125
- starts by hand. A local build starts by telling a session to work the
123
+ poller dispatches the "Factory build" workflow, within about a minute
124
+ when you host it (`builds.trigger: own-server`) or at its next scheduled
125
+ pass (`github-action`), the same run that
126
+ `npx --no-install factory build N` starts by hand. A local build starts by telling a session to work the
126
127
  issue.
127
- The poller skips a card whose blocker is open and starts it within a
128
- minute of the blocker closing. A card moves only forward on its own,
128
+ The poller skips a card whose blocker is open and starts it at its first
129
+ pass after the blocker closes. A card moves only forward on its own,
129
130
  except the follow-ups issue when a pull request merged part of it,
130
131
  which goes to Backlog: a
131
132
  build that ends without a merge stays In progress, and a finished
@@ -188,7 +189,7 @@ OpenSpec collects anonymous usage statistics unless told not to. Run it with
188
189
  ## Issues that wait on another
189
190
 
190
191
  A build order stated only in prose is one nothing reads: the poller starts
191
- a build within a minute of a card moving to Ready, and it and `factory-build`
192
+ a build within minutes of a card moving to Ready, and it and `factory-build`
192
193
  stop only on a recorded relationship. So whoever opens or refines an issue records each
193
194
  blocker as a blocked-by relationship, and says why in the issue's
194
195
  body (under Decisions, for a refined issue).
@@ -284,7 +285,8 @@ The factory's skills, agents, rules, review instructions, and workflows
284
285
  under `.claude/` and `.github/` are copies, written by `factory sync` from
285
286
  the factory's package. Change the source in the package, run
286
287
  `npx --no-install factory sync`, and commit both: the gate and CI fail
287
- when a copy differs from its source.
288
+ when a copy differs from what `sync` writes from its source and the
289
+ settings.
288
290
 
289
291
  A rule written for the change in front of its author can be wrong for
290
292
  every other kind. Once, the step that adds the `spec` label kept adding
@@ -297,11 +299,11 @@ code that decides what runs and who merges (the factory's own commands,
297
299
  and the scripts "Changing the process: this
298
300
  repository" in `CLAUDE.md` names)
299
301
  that alters what triggers a step, who runs or when,
300
- gets a read from a fresh agent before its pull request is marked
301
- ready. Give it the branch and `.claude/change-types.md`. It traces each
302
- kind through the rules as they will stand, and reports a kind that got
303
- heavier, lighter, or ambiguous, and any two rules that now disagree. Fix
304
- what holds up. A change to wording alone needs no trace.
302
+ is traced with the `factory-trace` skill before its pull request is
303
+ marked ready: a fresh agent walks each kind in `.claude/change-types.md`
304
+ through the rules as they will stand, and reports a kind that got heavier,
305
+ lighter, or ambiguous, and any two rules that now disagree. Fix what holds
306
+ up. A change to wording alone needs no trace.
305
307
 
306
308
  ## Stepping back from a rabbit hole
307
309
 
@@ -85,6 +85,9 @@
85
85
  },
86
86
  "session-minutes": {
87
87
  "$ref": "#/definitions/session-minutes"
88
+ },
89
+ "rules": {
90
+ "$ref": "#/definitions/rules"
88
91
  }
89
92
  },
90
93
  "definitions": {
@@ -199,6 +202,10 @@
199
202
  "runner": {
200
203
  "enum": ["github-actions"],
201
204
  "description": "Where an unattended build runs. Default: github-actions."
205
+ },
206
+ "poll-minutes": {
207
+ "enum": [5, 10, 15, 30, 60],
208
+ "description": "How often the scheduled poller checks the board, in minutes, with builds.trigger: github-action. Default: 5."
202
209
  }
203
210
  }
204
211
  },
@@ -406,6 +413,23 @@
406
413
  "description": "Work on the dependency pull requests. Default: 50."
407
414
  }
408
415
  }
416
+ },
417
+ "rules": {
418
+ "type": "object",
419
+ "description": "Numbers the process rules use, for a repository that wants different ones.",
420
+ "additionalProperties": false,
421
+ "properties": {
422
+ "small-change-lines": {
423
+ "type": "integer",
424
+ "minimum": 1,
425
+ "description": "A change under this many lines outside tests, specs, and content, adding no component and no state, takes the lighter path. Default: 30."
426
+ },
427
+ "review-rounds": {
428
+ "type": "integer",
429
+ "minimum": 1,
430
+ "description": "Rounds a session works a review before it hands what is left to you. Default: 2."
431
+ }
432
+ }
409
433
  }
410
434
  }
411
435
  }
@@ -20,7 +20,7 @@ nonzero with the error: that is a failed read, never an empty answer.
20
20
  card stays where it is until the claim moves it.
21
21
 
22
22
  - **GitHub Actions:** the owner moves the issue's card to Ready on the
23
- board, and the `ready-poller` worker posts a start comment and dispatches
23
+ board, and the poller posts a start comment and dispatches
24
24
  "Factory build" with the issue's number; or a person runs
25
25
  `npx --no-install factory build N`, or "Run workflow" on the Actions
26
26
  tab. The two are the same run. The run's prompt says so. There is no
@@ -0,0 +1,79 @@
1
+ ---
2
+ name: factory-trace
3
+ description: Trace a change to the process through every kind of change the repository gets, with one fresh agent, and report each kind that got heavier, lighter, or ambiguous and any two rules that now disagree. Use before a pull request is marked ready when it changes the rules, a skill, an agent, or a workflow in a way that alters what triggers a step, who runs, or when, and when asked to trace a rule change. A change of wording alone needs no trace.
4
+ ---
5
+
6
+ # Tracing a change to the process
7
+
8
+ A rule written for the change in front of its author can be wrong for
9
+ every other kind. Once, the step that adds the `spec` label kept adding it
10
+ to small changes after the table that defines the label stopped. This skill
11
+ has a reader who did not write the change walk each kind of change through
12
+ the rules as the branch leaves them, before the pull request is marked
13
+ ready.
14
+
15
+ ## 1. Read the kinds of change
16
+
17
+ The kinds are in `.claude/change-types.md`, one row each with a real
18
+ example.
19
+
20
+ **When the file is missing,** start no agent. The pull request is not
21
+ marked ready untraced: leave it a draft, say on it that the trace needs
22
+ the file, and show its shape there, for the owner to write:
23
+
24
+ ```markdown
25
+ # Change types
26
+
27
+ | Kind | Example |
28
+ | -------------------------------------------------- | ---------------------------------------- |
29
+ | A small bug fix with no change to what a user sees | the guard passing an empty settings file |
30
+ | Docs only | the quick start's install line |
31
+ ```
32
+
33
+ Each kind names a change the repository really gets, and each example is
34
+ one that happened. The file lists kinds and nothing more: each kind's
35
+ path is read from the rules, so the file never restates them.
36
+
37
+ ## 2. Start one fresh agent
38
+
39
+ The branch is the current one, and its base is the default branch,
40
+ `origin/main` unless the pull request says otherwise. Start one
41
+ `general-purpose` agent, and give it only this:
42
+
43
+ > The branch BRANCH changes this repository's process: its rules, skills,
44
+ > agents, or workflows. Read what it changes with
45
+ > `git diff BASE...BRANCH`, then read the rules, skills, and agents as the
46
+ > branch leaves them, starting from `CLAUDE.md` and what it imports.
47
+ >
48
+ > For each kind of change in `.claude/change-types.md`, trace that kind's
49
+ > example through the process as it now stands, from the ticket to the
50
+ > merge: which steps it takes, which reviewers read it, and who merges it.
51
+ > Then do the same on BASE, and compare.
52
+ >
53
+ > Report one line per kind: **unchanged**, **heavier** (a step, reviewer,
54
+ > or wait it did not have), **lighter** (one it lost), or **ambiguous**
55
+ > (two readings of the rules give different paths). For every kind that is
56
+ > not unchanged, name the rule, by its file and section, that makes it so.
57
+ > Then list any two rules that now disagree, quoting both. Where the
58
+ > repository's `CLAUDE.md` asks more of this trace, do that too. Read
59
+ > only; change nothing.
60
+
61
+ Give it nothing else from this session: what the author meant is what the
62
+ trace tests.
63
+
64
+ ## 3. Report
65
+
66
+ The agent's report is the result, unedited.
67
+
68
+ **When the branch has an open pull request,** which
69
+ `npx --no-install factory pr state` names on its first line, post the
70
+ report there, so the owner reads it before merging:
71
+
72
+ ```bash
73
+ npx --no-install factory pr comment N --body-file trace.md
74
+ ```
75
+
76
+ Otherwise give it in the session.
77
+
78
+ Then fix what holds up, and say in the pull request which findings were
79
+ fixed and why any were not. A change of wording alone needs no trace.
@@ -1,6 +1,7 @@
1
- # Builds one ticket in GitHub Actions, with the factory-build skill, when a
2
- # person starts it: `npx --no-install factory build N`, or "Run workflow" on
3
- # the Actions tab with the ticket's number. Nothing else starts it.
1
+ # Builds one ticket in GitHub Actions, with the factory-build skill, when the
2
+ # poller starts it for a card moved to Ready, or a person does:
3
+ # `npx --no-install factory build N`, or "Run workflow" on the Actions tab
4
+ # with the ticket's number.
4
5
  #
5
6
  # The build acts as whoever owns its token, on GitHub and in git: the secret
6
7
  # FACTORY_BUILD_TOKEN, or FACTORY_BOARD_TOKEN when that is not set. The
@@ -52,7 +53,7 @@ jobs:
52
53
  prompt: |
53
54
  Build ticket #${{ inputs.ticket }} of this repository with the factory-build skill. You are running unattended in GitHub Actions, in a fresh checkout of the default branch with its dependencies installed and the commands under `build-setup` in `.claude/factory.yaml` already run. Nobody can answer a question here: where the skill would ask its user, stop and report instead.
54
55
 
55
- A person started this build with `factory build ${{ inputs.ticket }}` or the Actions tab's "Run workflow", which is the skill's third way to start, under "How a build starts" in `.claude/skills/factory-build/SKILL.md`: there is no start marker and no start check. This is a session nobody can wake later: once the pull request is marked ready, wait for its review with `npx --no-install factory pr state PR --wait`, where PR is its number, and work it with the factory-address-review skill. Do not start `factory pr watch`.
56
+ The poller started this build for a card moved to Ready, or a person did with `factory build ${{ inputs.ticket }}` or the Actions tab's "Run workflow": the skill's start in GitHub Actions, under "How a build starts" in `.claude/skills/factory-build/SKILL.md`, which has no start check. This is a session nobody can wake later: once the pull request is marked ready, wait for its review with `npx --no-install factory pr state PR --wait`, where PR is its number, and work it with the factory-address-review skill. Do not start `factory pr watch`.
56
57
 
57
58
  How: use the Skill tool to invoke `factory-build` with "#${{ inputs.ticket }}". If the Skill tool is unavailable, read `.claude/skills/factory-build/SKILL.md` and follow it exactly. When its claim prints `held by`, stop and post nothing. When it prints `blocked by`, stop and post the skill's report for it, since nothing else on the ticket says why this run stopped. Follow every stop the skill names. Read `CLAUDE.md`, and `AGENTS.md` where there is one, before building.
58
59
 
@@ -32,11 +32,12 @@ jobs:
32
32
  # the production smoke tests would never run on a dependency bump.
33
33
  #
34
34
  # Never a major, whose migration the owner reads first, and never the
35
- # factory itself, which changes the instructions every session follows.
35
+ # factory itself, which changes the instructions every session follows:
36
+ # its package or its poller's image, whose names both hold the match.
36
37
  - name: Enable auto-merge
37
38
  if: >-
38
39
  steps.meta.outputs.update-type != 'version-update:semver-major' &&
39
- !contains(steps.meta.outputs.dependency-names, '@davidbyoung/software-factory')
40
+ !contains(steps.meta.outputs.dependency-names, 'davidbyoung/software-factory')
40
41
  run: gh pr merge --auto --squash "$PR_URL"
41
42
  env:
42
43
  PR_URL: ${{ github.event.pull_request.html_url }}
@@ -0,0 +1,46 @@
1
+ # Starts a build for each ticket moved to Ready, for a repository with no
2
+ # server to host the poller: one pass of it on a schedule, which
3
+ # `factory sync` sets from `builds.poll-minutes`. Each build it starts is a
4
+ # run of factory-build.yml of its own, so builds still run side by side.
5
+ #
6
+ # GitHub's own token cannot reach a user's Project, so the pass reads the
7
+ # board, comments, and starts builds with FACTORY_BOARD_TOKEN, the token
8
+ # the board sync already uses. A schedule runs the default branch's copy.
9
+ name: Factory poller
10
+
11
+ on:
12
+ schedule:
13
+ - cron: "*/5 * * * *"
14
+ workflow_dispatch:
15
+
16
+ permissions:
17
+ contents: read
18
+
19
+ # A late run waits for the one before it, so two passes never read the
20
+ # same Ready card before either has posted its start comment.
21
+ concurrency:
22
+ group: factory-poller
23
+ cancel-in-progress: false
24
+
25
+ jobs:
26
+ poll:
27
+ name: Start the Ready tickets
28
+ runs-on: ubuntu-latest
29
+ timeout-minutes: 10
30
+ steps:
31
+ - name: Checkout
32
+ uses: actions/checkout@v7
33
+
34
+ - name: Set up Node
35
+ uses: actions/setup-node@v7
36
+ with:
37
+ node-version: 22
38
+ cache: npm
39
+
40
+ - name: Install dependencies
41
+ run: npm ci --ignore-scripts
42
+
43
+ - name: Start the Ready tickets
44
+ env:
45
+ FACTORY_BOARD_TOKEN: ${{ secrets.FACTORY_BOARD_TOKEN }}
46
+ run: npx --no-install factory poller --once