@davidbyoung/software-factory 0.1.2 → 0.1.4

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 (120) hide show
  1. package/README.md +20 -20
  2. package/actions/factory-agent/action.yml +1 -1
  3. package/agents/factory-e2e-reviewer.md +102 -0
  4. package/agents/factory-test-reviewer.md +26 -64
  5. package/agents/factory-ticket-readiness.md +14 -6
  6. package/dist/agent/claude-code.d.mts +3 -0
  7. package/dist/agent/claude-code.mjs +89 -0
  8. package/dist/agent/index.d.mts +2 -0
  9. package/dist/agent/index.mjs +5 -0
  10. package/dist/board.mjs +1 -1
  11. package/dist/cli.mjs +46 -4
  12. package/dist/code-host/github-setup.d.mts +5 -0
  13. package/dist/code-host/github-setup.mjs +133 -0
  14. package/dist/code-host/github.mjs +4 -0
  15. package/dist/code-host/index.d.mts +1 -1
  16. package/dist/code-host/index.mjs +2 -1
  17. package/dist/code-host/types.d.mts +2 -0
  18. package/dist/commands.d.mts +16 -0
  19. package/dist/commands.mjs +129 -0
  20. package/dist/config.d.mts +87 -20
  21. package/dist/config.mjs +344 -89
  22. package/dist/deps.d.mts +7 -4
  23. package/dist/deps.mjs +20 -9
  24. package/dist/doctor.d.mts +9 -16
  25. package/dist/doctor.mjs +71 -68
  26. package/dist/explain.d.mts +4 -0
  27. package/dist/explain.mjs +174 -0
  28. package/dist/guard-commit.d.mts +7 -2
  29. package/dist/guard-commit.mjs +58 -21
  30. package/dist/init.d.mts +12 -14
  31. package/dist/init.mjs +194 -136
  32. package/dist/lib/default-branch.d.mts +35 -0
  33. package/dist/lib/default-branch.mjs +117 -0
  34. package/dist/lib/has-command.d.mts +5 -0
  35. package/dist/lib/has-command.mjs +8 -0
  36. package/dist/lib/listed.d.mts +2 -0
  37. package/dist/lib/listed.mjs +4 -0
  38. package/dist/lib/refined-check.d.mts +7 -0
  39. package/dist/lib/refined-check.mjs +76 -0
  40. package/dist/lib/work-status.d.mts +12 -2
  41. package/dist/lib/work-status.mjs +14 -3
  42. package/dist/parts.d.mts +18 -15
  43. package/dist/parts.mjs +15 -43
  44. package/dist/patch-coverage.d.mts +13 -0
  45. package/dist/patch-coverage.mjs +73 -0
  46. package/dist/poller.d.mts +20 -3
  47. package/dist/poller.mjs +62 -15
  48. package/dist/pr-watch.d.mts +3 -2
  49. package/dist/pr-watch.mjs +22 -5
  50. package/dist/pr.mjs +34 -2
  51. package/dist/remove.d.mts +11 -0
  52. package/dist/remove.mjs +156 -0
  53. package/dist/runner/github-actions.d.mts +1 -1
  54. package/dist/runner/github-actions.mjs +12 -0
  55. package/dist/runner/index.d.mts +1 -1
  56. package/dist/runner/index.mjs +2 -1
  57. package/dist/runner/setup.d.mts +2 -0
  58. package/dist/runner/setup.mjs +22 -0
  59. package/dist/runner/types.d.mts +3 -0
  60. package/dist/runner/types.mjs +0 -2
  61. package/dist/session-start.d.mts +23 -13
  62. package/dist/session-start.mjs +56 -44
  63. package/dist/setup.d.mts +98 -0
  64. package/dist/setup.mjs +3 -0
  65. package/dist/site/servers.d.mts +6 -2
  66. package/dist/site/servers.mjs +14 -9
  67. package/dist/site.mjs +2 -2
  68. package/dist/status.d.mts +4 -4
  69. package/dist/status.mjs +8 -7
  70. package/dist/sync.d.mts +26 -2
  71. package/dist/sync.mjs +177 -13
  72. package/dist/ticket.mjs +19 -1
  73. package/dist/tickets/github-setup.d.mts +2 -0
  74. package/dist/tickets/github-setup.mjs +50 -0
  75. package/dist/tickets/github.mjs +0 -2
  76. package/dist/tickets/index.mjs +2 -1
  77. package/dist/tickets/transport.mjs +1 -3
  78. package/dist/tickets/types.mjs +0 -2
  79. package/dist/tool-names.d.mts +11 -0
  80. package/dist/tool-names.mjs +20 -0
  81. package/dist/tools.d.mts +56 -0
  82. package/dist/tools.mjs +76 -0
  83. package/docs/builds.md +111 -59
  84. package/docs/cli.md +106 -69
  85. package/docs/configuration.md +489 -171
  86. package/docs/design.md +18 -5
  87. package/docs/developing.md +179 -73
  88. package/docs/existing-repo.md +25 -12
  89. package/docs/github/by-hand.md +334 -0
  90. package/docs/github/reference.md +76 -67
  91. package/docs/github/setup.md +105 -286
  92. package/docs/glossary.md +18 -7
  93. package/docs/limitations.md +39 -12
  94. package/docs/plugins.md +305 -56
  95. package/docs/quick-start.md +85 -100
  96. package/docs/removing.md +37 -17
  97. package/docs/skills.md +121 -62
  98. package/docs/updating.md +150 -9
  99. package/docs/workflow.md +23 -19
  100. package/package.json +1 -1
  101. package/poller.Dockerfile +10 -18
  102. package/review.md +20 -11
  103. package/rules.md +36 -30
  104. package/settings.schema.json +313 -69
  105. package/skills/factory-address-review/SKILL.md +50 -30
  106. package/skills/factory-build/SKILL.md +76 -23
  107. package/skills/factory-deps/SKILL.md +46 -21
  108. package/skills/factory-design/SKILL.md +17 -8
  109. package/skills/factory-diagnose/SKILL.md +22 -20
  110. package/skills/factory-mutate/SKILL.md +38 -24
  111. package/skills/factory-refine/SKILL.md +55 -31
  112. package/skills/factory-resolve-conflicts/SKILL.md +76 -34
  113. package/skills/factory-trace/SKILL.md +80 -0
  114. package/workflows/factory-build.yml +6 -5
  115. package/workflows/factory-conflicts.yml +8 -8
  116. package/workflows/factory-deps-auto-merge.yml +3 -2
  117. package/workflows/factory-deps.yml +1 -1
  118. package/workflows/factory-poller.yml +46 -0
  119. package/workflows/factory-review.yml +1 -1
  120. package/skills/factory-address-review/patch-coverage.py +0 -68
package/docs/design.md CHANGED
@@ -68,10 +68,23 @@ differently from one day to the next.
68
68
 
69
69
  ## The order of the workflow is fixed
70
70
 
71
- You can turn parts off and add reviewers. You cannot reorder the states or
72
- add one. Mapping names is cheap to support. Every extra shape of workflow
73
- is one more path each skill has to handle correctly, and a skill is
74
- instructions, which cannot be unit tested.
71
+ You can turn parts off in [the settings](configuration.md), such as
72
+ written specs or the automated review, and a [plug-in](plugins.md) of yours can take a
73
+ step over: how a ticket is refined, how a ticket with one of your labels
74
+ is built, how a test is proved able to fail, which agents read the tests
75
+ and the change, and how a generated file is rebuilt after a conflict. You
76
+ cannot reorder the six states, add one, or leave one out.
77
+
78
+ A step can be replaced because what it hands to the next one can be
79
+ written down, and the part a build depends on is checked by a script: a
80
+ refined ticket is refused until its body has the sections a build reads,
81
+ whichever skill refined it. So whatever does a step, the next step reads
82
+ the same thing.
83
+
84
+ The order is another matter. Mapping names is cheap to support, which is
85
+ why a board's columns can be yours. Every extra shape of workflow is one
86
+ more path each skill has to handle correctly, and a skill is instructions,
87
+ which cannot be unit tested.
75
88
 
76
89
  ## Small problems go on one checklist
77
90
 
@@ -87,7 +100,7 @@ They are separate on purpose.
87
100
 
88
101
  | Number | Where it is | Changes when |
89
102
  | ------------------- | -------------------------------------------- | ------------------------------------ |
90
- | The factory's | `package.json` and `.claude/factory.lock` | Every release |
103
+ | The factory's | The installed package and `factory.lock` | Every release |
91
104
  | The settings file's | `version:` at the top of `factory.yaml` | A key is renamed or moved |
92
105
  | The markers' | In the comments the factory posts on tickets | The format of those comments changes |
93
106
 
@@ -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, and the CI review, and `node bin/factory.js sync` copies
16
+ board, OpenSpec, the gate, and the CI 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
@@ -30,40 +30,49 @@ completes with the files the version writes ([Updating](updating.md)).
30
30
  The factory is the npm package `@davidbyoung/software-factory`. Parts not
31
31
  marked working below exist only in these docs.
32
32
 
33
- | Part | State |
34
- | ------------------------------------------------------------------------------------------------------------- | ----------------------------------- |
35
- | Refining, building, and working a pull request's review | Working |
36
- | The board, its sync, and `status` | Working |
37
- | Builds from the board, with a poller you host | Working |
38
- | Builds that run in GitHub Actions, started by a command | Working |
39
- | Starting builds from the board, and the review, conflict, and dependency runs, in GitHub Actions | Working |
40
- | Who merges, and the review's verdict | Working |
41
- | The labels `merge: manual` and `verdict: override` | Working |
42
- | These docs | Working |
43
- | `.claude/factory.yaml`, and the factory's files kept apart from the host's | Working |
44
- | The follow-ups ticket as one checklist | Working |
45
- | The `factory` tool, `sync`, and the package folder | Working |
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 `ci-review` | Working |
48
- | Nothing in the package names the repository it was drawn out of, checked in the folder and the packed tarball | Working |
49
- | The `factory-` names and the `FACTORY_` secrets | Working |
50
- | Ticket commands that go through one interface | Working |
51
- | The code host and the runner, each behind one interface | Working |
52
- | A published package, updated through Dependabot | Planned, next |
53
- | A second repository using it | Planned, after publishing |
54
- | Your own column names on a board | Working |
55
- | A UI reviewer for any website | Working |
56
- | Built-in measurements for any website | Working |
57
- | A design skill for any website | Working |
58
- | `init`, which can be re-run, and `doctor` | Working |
59
- | `remove` and `config explain` | Planned, not yet scheduled |
60
- | `approvers` and `rules` in the settings | Planned, not yet scheduled |
61
- | Starting builds from a scheduled workflow | Planned, not yet scheduled |
62
- | `factory poller --once`, the scheduled workflow's one pass, and a poller built from an installed package | Planned, not yet scheduled |
63
- | `factory migrate`, `factory board sync --dry-run`, and the `/factory-trace` skill | Planned, not yet scheduled |
64
- | Another ticket system, such as Jira | Not planned. The design leaves room |
65
- | Another code host or runner | Not planned. The design leaves room |
66
- | Sharing plug-ins between repositories | Not planned |
33
+ | Part | State |
34
+ | ---------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------- |
35
+ | Refining, building, and working a pull request's review | Working |
36
+ | The board, its sync, and `status` | Working |
37
+ | Builds from the board, with a poller you host | Working |
38
+ | Builds that run in GitHub Actions, started by a command | Working |
39
+ | Starting builds from the board, and the review, conflict, and dependency runs, in GitHub Actions | Working |
40
+ | Who merges, and the review's verdict | Working |
41
+ | The labels `merge: manual` and `verdict: override` | Working |
42
+ | These docs | Working |
43
+ | `.claude/factory.yaml`, and the factory's files kept apart from the host's | Working |
44
+ | The follow-ups ticket as one checklist | Working |
45
+ | The `factory` tool, `sync`, and the package folder | Working |
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 [`ci-review`](configuration.md#ci-review) | Working |
48
+ | Nothing in the package names the repository it was drawn out of, checked in the folder and the packed tarball | Working |
49
+ | The `factory-` names and the `FACTORY_` secrets | Working |
50
+ | Ticket commands that go through one interface | Working |
51
+ | The code host and the runner, each behind one interface | Working |
52
+ | A published package | Working |
53
+ | Updates through Dependabot, which `factory-deps` completes with `factory sync` | Working |
54
+ | `factory board --dry-run` | Working |
55
+ | Your own column names on a board | Working |
56
+ | A UI reviewer for any website | Working |
57
+ | Built-in measurements for any website | Working |
58
+ | A design skill for any website | Working |
59
+ | `init`, which can be re-run, and `doctor` | Working |
60
+ | A second repository set up and removed from the quick start alone | Working |
61
+ | `factory remove` | Working |
62
+ | Starting builds from a scheduled workflow, `factory poller --once`, and a poller built from an installed package | Working |
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 plug-ins grouped by phase | Working |
65
+ | `factory gate`, `test-one`, `end-to-end`, and `specs check`, which run the settings' commands | Working |
66
+ | The default branch read from Git and the code host, never assumed, and `factory default-branch` | Working |
67
+ | A refiner, a prover, test reviewers, and conflict resolvers of your own, and `factory-e2e-reviewer` | Working |
68
+ | `factory ticket refined` refusing a ticket a build could not read | Working |
69
+ | No skill, agent, rule, or review instruction names a stack, checked by a test | Working |
70
+ | `approvers` in the settings | Planned, [#14](https://github.com/davidbyoung/software-factory/issues/14) |
71
+ | Another ticket system, such as Jira | Not planned. The design leaves room |
72
+ | A ticket system or code host named by a package, for an adapter you write yourself | Not planned. The design leaves room |
73
+ | Another code host or runner | Not planned. The design leaves room |
74
+ | Each tool's setup, checks, and removal declared by the tool | Working |
75
+ | Sharing plug-ins between repositories | Not planned |
67
76
 
68
77
  When a part is built, its pull request updates this table, and corrects any
69
78
  page the build had to differ from. [The CLI](cli.md) marks each command
@@ -95,8 +104,23 @@ It is laid out as a Claude Code plugin even though it is not delivered as
95
104
  one. That costs nothing, and it keeps the plugin's own tooling usable on the
96
105
  folder. The settings are validated in code, and `settings.schema.json` is the
97
106
  editor's copy of their keys. A new key goes in `SETTINGS_KEYS` in
98
- `src/config.mts`, in the schema, and in `docs/configuration.md`, and a test
99
- fails when the first two differ.
107
+ `src/config.mts`, in the schema, in `src/explain.mts`, which prints it, and
108
+ in `docs/configuration.md`, and a test fails when the first two differ.
109
+
110
+ - **A command a session runs** goes under
111
+ [`commands`](configuration.md#commands), with a `factory`
112
+ command in `src/commands.mts` that runs it, so a skill names the
113
+ `factory` command and never the repository's own.
114
+ - **A plug-in slot** goes in `SLOTS` and `SLOT_SHAPE` in `src/config.mts`,
115
+ which say its phase, whether it takes a skill or an agent, one or a
116
+ list, and `files` or `labels`. Its keys in `SETTINGS_KEYS` follow from
117
+ that table. `docs/plugins.md` gains its table of what it is handed and
118
+ what it returns.
119
+ - **A key that is renamed or moved** raises the settings' `version`.
120
+ There is no command that converts a file: the older version is refused
121
+ with a line that names a section of `docs/updating.md`, as version 1 is
122
+ with "Moving to settings version 2", and that section shows each key
123
+ before and after.
100
124
 
101
125
  ## Running from source
102
126
 
@@ -127,8 +151,9 @@ guard runs before every command a session runs: `npx` took 289 ms a call,
127
151
  `node` on the launcher 56 ms.
128
152
 
129
153
  To prove the package works outside its host, CI packs the folder, installs
130
- the tarball into an empty repository, and runs `sync`, `sync --check`,
131
- `config check`, and `plugins` there:
154
+ the tarball into an empty repository, and runs `factory sync`,
155
+ `factory sync --check`, `factory config check`, and `factory plugins`
156
+ there:
132
157
 
133
158
  ```bash
134
159
  npm run pack-check
@@ -159,10 +184,22 @@ A factory file must name nothing that belongs to the host repository: not
159
184
  its paths, its commands, its subject, or its own skills. A test fails when
160
185
  one does. That is what keeps the folder movable.
161
186
 
187
+ Nor does a skill, an agent, the rules, or the review's instructions name
188
+ one stack: a test runner, a framework, a package manager's commands, or a
189
+ branch called `main`. A skill runs `factory gate`, `factory test-one`,
190
+ `factory end-to-end`, and `factory specs check`, which run the repository's
191
+ own commands from its settings, and writes the default branch as the name
192
+ `factory default-branch` prints. `tests/boundary.test.ts` lists the words
193
+ it fails on. The three files written only for a website or an end-to-end
194
+ suite, `factory-ui-reviewer`, `factory-e2e-reviewer`, and `factory-design`,
195
+ may name a browser tool, and `factory-deps` npm's own files and commands,
196
+ since the factory's update is an npm package's.
197
+
162
198
  ## Adding a ticket system
163
199
 
164
200
  Only GitHub is built. The factory is built so that a second system is an
165
- addition, not a rewrite. Four rules keep it that way.
201
+ addition, not a rewrite. Four rules keep it that way, and its setup is
202
+ [declared like any tool's](#setting-a-tool-up).
166
203
 
167
204
  **1. Nothing talks to the ticket system except through the tool.** A skill
168
205
  never runs `gh issue` or calls GitHub's issues or projects API. It runs
@@ -178,13 +215,12 @@ runs. Every command reaches a ticket, a pull request, or a build through
178
215
  one of them, and a test fails when a file elsewhere under `src/` calls
179
216
  GitHub or holds a `github.com` address.
180
217
 
181
- **3. The tool reads `tickets.type` and hands the work to that type's
182
- adapter.** An adapter is one module in `src/tickets/` that implements the
183
- `Tickets` type in `src/tickets/types.mts`. `github` is the only one; any
184
- other value fails `factory config check` and every ticket command with
218
+ **3. The tool reads [`tickets.type`](configuration.md#tickets) and hands
219
+ the work to that type's adapter.** An adapter is one module in
220
+ `src/tickets/` that implements the `Tickets` type in
221
+ `src/tickets/types.mts`. `github` is the only one; any other value fails
222
+ `factory config check` and every ticket command with
185
223
  `tickets.type "X" is not supported. "github" is the only ticket system built.`
186
- A type that names a package, so a team can write an adapter for a system
187
- the factory does not ship, is planned, not built.
188
224
 
189
225
  | Operation | In `Tickets` | What it returns or does |
190
226
  | ----------------------- | ------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
@@ -229,9 +265,8 @@ order is prose in the ticket and nothing enforces it.
229
265
  and one for an answer in plain text, such as a job's log
230
266
  (`src/tickets/transport.mts`). `ghTransport` runs the GitHub CLI, for
231
267
  sessions and CI. `fetchTransport` calls the API with a token, for the
232
- poller, which runs with no `gh` and no install; `poller.Dockerfile` copies
233
- the adapter, the transport, and what else the poller imports, and a test
234
- fails when it misses one.
268
+ poller, which runs with no `gh`: its image installs only the published
269
+ package.
235
270
 
236
271
  What stays above the interface: working out a ticket's state from its
237
272
  marker comments, costs, and the formatting of every view, in
@@ -253,18 +288,18 @@ a third.
253
288
  ## Adding a code host
254
289
 
255
290
  The code host is where pull requests are. Only GitHub is built. The
256
- settings name it with `code-host.type`, and `src/code-host/index.mts` hands
257
- a command the implementation of that name: one module in `src/code-host/`
258
- that implements the `CodeHost` type in `src/code-host/types.mts`. Any other
259
- value fails `factory config check`, and every command that reads the
260
- settings and reaches a pull request, with
291
+ settings name it with [`code-host.type`](configuration.md#code-host), and
292
+ `src/code-host/index.mts` hands a command the implementation of that name:
293
+ one module in `src/code-host/` that implements the `CodeHost` type in
294
+ `src/code-host/types.mts`. Any other value fails `factory config check`,
295
+ and every command that reads the settings and reaches a pull request, with
261
296
  `code-host.type "X" is not supported. "github" is the only code host built.`
262
- A type that names a package is planned, not built.
263
297
 
264
298
  A command that a workflow also runs, such as `factory pr`, does not read
265
299
  the settings there, so an unreadable settings file cannot fail the
266
- workflow's step; it asks for the default. The poller has no settings at
267
- all and names its implementations itself.
300
+ workflow's step; it asks for the default. The poller you host has no
301
+ settings at all and names its implementations itself; a scheduled pass
302
+ reads the settings only for its board and Ready column.
268
303
 
269
304
  | Operation | In `CodeHost` | What it returns or does |
270
305
  | ---------------------------------------- | --------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
@@ -317,7 +352,7 @@ of which call GitHub is sent belongs.
317
352
  ## Adding a runner
318
353
 
319
354
  The runner is where an unattended build runs. Only GitHub Actions is
320
- built. The settings name it with `builds.runner`, and
355
+ built. The settings name it with [`builds.runner`](configuration.md#builds), and
321
356
  `src/runner/index.mts` hands a command the implementation of that name:
322
357
  one module in `src/runner/` that implements the `Runner` type in
323
358
  `src/runner/types.mts`. Any other value fails `factory config check`, and
@@ -352,6 +387,44 @@ variables, and reach pull requests through the code host.
352
387
  The in-memory runner is `tests/memory-runner.ts`, and GitHub Actions' has
353
388
  its own tests against faked replies.
354
389
 
390
+ ## Setting a tool up
391
+
392
+ A tool is a code host, a ticket system, a runner, or a coding agent. Each
393
+ says what it needs, so `factory init` sets it up, `factory doctor` checks
394
+ it, and `factory remove` takes it out, with no edit to those commands.
395
+ `src/tools.mts` registers each one by the name a setting gives it, with
396
+ how to open it and its setup, the `ToolSetup` type in `src/setup.mts`. The
397
+ names the settings accept are in `src/tool-names.mts`, and a test fails
398
+ when the two differ. Every member of a setup is optional.
399
+
400
+ | Member | What it gives | Used by |
401
+ | ------------- | --------------------------------------------------------------------------------------------------------------------------------------- | -------- |
402
+ | `found` | Its row under "Found", when it says more than the tool's name, such as that a command is not installed | `init` |
403
+ | `steps` | A value to write under the tool's block of the settings, or a secret: which parts read it, how to get it, and how to check a pasted one | `init` |
404
+ | `checks` | Its own lines in `doctor`: that it is reachable, signed in, or configured, each failure with its fix in the tool's words | `doctor` |
405
+ | `leftovers` | What removing the factory leaves outside the repository, such as its secrets | `remove` |
406
+ | `unconfigure` | Its own files with the factory's part taken out, such as a coding agent's settings without the factory's hooks | `remove` |
407
+
408
+ **A value** is asked for once, after the parts are chosen, and written
409
+ under the tool's block: a ticket system's under `tickets`, which accepts a
410
+ key only when the ticket system in use declares it. **A secret** names the
411
+ parts that read it, or none when the tool always needs it. `init` asks for
412
+ it when one of those is not set, prints the tool's introduction, opens
413
+ its page or runs its command, reads it in a masked prompt, and stores it
414
+ through the runner under each name the tool gives. Its words are the
415
+ tool's: the prompt, the reason it refuses a value, and the line when
416
+ nothing is pasted.
417
+
418
+ With more than one tool of a kind, `init` asks which, except for the code
419
+ host, which it reads from the git remote: each code host says which
420
+ remotes are its own. The coding agent has no setting until there is a
421
+ second.
422
+
423
+ The tests show a tool that the factory does not ship going through all
424
+ three commands: `tests/fake-tools.ts` has a ticket system with a site
425
+ address and a token of its own, and a coding agent whose configuration is
426
+ one file.
427
+
355
428
  ## Checking a change
356
429
 
357
430
  | Check | What it proves |
@@ -359,7 +432,7 @@ its own tests against faked replies.
359
432
  | The tool's unit tests | Each command does what it says. A new test is seen failing before it is trusted |
360
433
  | `factory sync --check` | The copies match the source |
361
434
  | Pack and install | CI packs the folder, installs it into an empty scratch repository, and runs `sync`, `config check`, and one read-only command there. It works outside its host |
362
- | `/factory-trace` | A change to a rule did not make some kind of change heavier, lighter, or ambiguous |
435
+ | `factory-trace` | A change to a rule did not make some kind of change heavier, lighter, or ambiguous |
363
436
  | Fork safety | No workflow it runs or ships could run a fork's code with a secret or write access (`tests/fork-safety.test.ts`). This repository is public |
364
437
  | One throwaway ticket | After each stage, one small ticket goes through refine, build, and review for real. Nothing else tests the prose |
365
438
 
@@ -368,18 +441,32 @@ last row is the only real proof that a change to one still works.
368
441
 
369
442
  ## Releasing
370
443
 
371
- 1. Raise `version` in `package.json` in a pull request, run `factory sync`
372
- so `.claude/factory.lock` records it, and merge it.
373
- 2. Tag the merge commit with the same version and push the tag:
374
-
375
- ```bash
376
- git tag v0.2.0 && git push origin v0.2.0
377
- ```
378
-
379
- 3. The release workflow runs the whole CI on the tagged commit, the same
380
- jobs a pull request gets. Only once they pass does it check that the tag
381
- matches `package.json` and that `main` has the commit, then publish the
382
- version to npm.
444
+ 1. On the Actions tab, run **Release** on `main` and choose the part of
445
+ the version to raise: patch for fixes alone, minor for something new,
446
+ and major for a change that breaks a repository using the factory. From
447
+ 0.1.2, they give 0.1.3, 0.2.0, and 1.0.0.
448
+ 2. The run raises the highest `vX.Y.Z` tag by that part, and runs the
449
+ whole CI on `main`'s commit, the same jobs a pull request gets. Only
450
+ once they pass does it publish the version to npm, then the poller's
451
+ image of that version to GitHub's container registry. Last, it tags the
452
+ commit and creates a GitHub Release whose notes list the pull requests
453
+ merged since the previous version. Those notes are the changelog, and
454
+ Dependabot copies them into the update pull requests it opens, so a
455
+ pull request's title is the line a user reads. When a release needs
456
+ something done by hand in a repository that uses the factory, edit its
457
+ GitHub Release as soon as the run ends, and put the steps first.
458
+ 3. A run that stops partway has made no tag. Re-running its failed jobs,
459
+ from the run's page, finishes it on the same commit and version, and
460
+ does not publish to npm twice. A new run for a version npm already has
461
+ stops and says so.
462
+ 4. After the first release that publishes the image, pull it with no
463
+ sign-in: `docker logout ghcr.io` and
464
+ `docker pull ghcr.io/davidbyoung/software-factory-poller:VERSION`. If it
465
+ is refused, set the package to Public on its GitHub page, once.
466
+
467
+ Nothing is committed for a release. `package.json` on `main` keeps the
468
+ version `0.0.0-development`, and the run writes the real one into its own
469
+ copy before publishing, so the tags and npm hold the released versions.
383
470
 
384
471
  The first version, 0.1.0, was published by hand, since npm sets up a
385
472
  trusted publisher only for a package that exists:
@@ -398,8 +485,8 @@ drawn out of.
398
485
  ## Writing for the factory
399
486
 
400
487
  - **American English, with the Oxford comma.**
401
- - **The factory's own words:** ticket, follow-up, the six states, the three
402
- roles. Not issue, card, or sweep.
488
+ - **The factory's own words:** ticket, follow-up, the six states, the seven
489
+ slots. Not issue, card, or sweep.
403
490
  - **A key name must make sense unexplained.** Each reference settings file
404
491
  is read cold by a fresh agent that is told only what the factory is. A key
405
492
  it explains wrongly, or cannot tell from another, is renamed or given a
@@ -412,3 +499,22 @@ drawn out of.
412
499
  to differ.
413
500
  - **Examples carry the reason for a rule, without the host's private
414
501
  history.**
502
+
503
+ ### A page a reader follows
504
+
505
+ `README.md` and every page under `docs/` but this one is read by someone
506
+ who has never seen the factory and wants one thing done. `docs-reader`,
507
+ this repository's own reviewer, reads a changed page as that person.
508
+
509
+ - **A page says who it is for and what they will have at the end,** in its
510
+ first lines.
511
+ - **Lead with the command that does it.** The same steps by hand go on a
512
+ page of their own, linked once.
513
+ - **Say only what the reader must do or decide.** What a command does for
514
+ them is one sentence, and a link to the page that lists it.
515
+ - **A setting links to its entry in `docs/configuration.md` where a page
516
+ first names it.** A test fails on one that does not.
517
+ - **A setting the reader writes is shown as YAML they can paste,** with
518
+ what each line is for.
519
+ - **A step ends with how the reader knows it worked.**
520
+ - **Each fact has one home.** Every other page links to it.
@@ -17,8 +17,16 @@ The factory's tool runs on Node and is installed with npm, whatever your
17
17
  project is written in. In a PHP, Python, or Go repository that means:
18
18
 
19
19
  - **A `package.json` appears**, holding one development dependency and
20
- nothing else. `factory init` creates it if you have
21
- none, marked private so it can never be published.
20
+ nothing else. Make it yourself before installing, marked private so it
21
+ can never be published:
22
+
23
+ ```bash
24
+ echo '{ "private": true }' > package.json
25
+ ```
26
+
27
+ Without one, npm installs into the nearest folder above that has a
28
+ `package.json`, if there is one, rather than into your repository.
29
+
22
30
  - **`package-lock.json` is committed.** It is what keeps everyone on the
23
31
  same version of the factory.
24
32
  - **`node_modules/` is ignored.** `factory init` adds it
@@ -28,8 +36,10 @@ project is written in. In a PHP, Python, or Go repository that means:
28
36
  - **Your own CI does not change.** The factory's cloud jobs install Node
29
37
  for themselves. If you turn on the automated review, how it installs your
30
38
  project, such as `composer install`, is yours to edit.
31
- - **Your commands stay yours.** `before-commit` in the settings takes any
32
- command: `composer lint`, `make check`, `go vet ./...`.
39
+ - **Your commands stay yours.** The gate a build runs, and everything
40
+ else under [`commands`](configuration.md#commands) in the settings, is
41
+ whatever your project runs: `composer test`, `make check`,
42
+ `go vet ./...`.
33
43
 
34
44
  The factory's hooks run its own tool, so they need nothing beyond Node.
35
45
  Someone who only writes code by hand, and never runs an agent session in
@@ -58,9 +68,10 @@ Added to board 3: Backlog, In refinement, Ready, In review, Session, Runs in, Co
58
68
  or move them all once and retire the column.
59
69
  - **The factory's fields are overwritten on every sync.** Do not type into
60
70
  Session, Runs in, or Cost. Your own fields are never touched.
61
- - **Using your own column names** works today: `tickets.columns` in your
62
- settings says which of your columns shows each state, and `none` says your
63
- board has none. [Configuration](configuration.md#ticketscolumns) has the
71
+ - **Using your own column names** works today:
72
+ [`tickets.columns`](configuration.md#ticketscolumns) in your settings
73
+ says which of your columns shows each state, and `none` says your board
74
+ has none. [Configuration](configuration.md#ticketscolumns) has the
64
75
  mapping for a board with Todo, In Progress, and Done. To see what the
65
76
  factory will do with your board, run:
66
77
 
@@ -105,7 +116,7 @@ names each file.
105
116
  teammate's session goes out under that teammate's account. A cloud build
106
117
  acts as the one account that owns its token: yours, or an account you
107
118
  create for the team's builds
108
- ([Builds in the cloud](github/setup.md#builds-in-the-cloud)).
119
+ ([Secrets](github/by-hand.md#secrets)).
109
120
  - **Say who approves.** By default only the repository's owner can approve
110
121
  a ticket for building or give a session instructions in a comment. List
111
122
  the others under [`approvers`](configuration.md#approvers), _[Planned](developing.md#what-is-built)_.
@@ -129,10 +140,12 @@ and how to undo each. The short version:
129
140
  - Files it owns, all named `factory-...`, and its rules.
130
141
  - One line in your agent's instructions file, and a few hooks in your
131
142
  agent's settings.
132
- - Hooks that stop a session committing on your main branch or force
133
- pushing, and that run your `before-commit` commands. They apply to agent
134
- sessions, not to your own terminal.
143
+ - Hooks that stop a session committing on your default branch or force
144
+ pushing, and that run your
145
+ [`commands.before-commit`](configuration.md#commandsbefore-commit)
146
+ commands. They apply to agent sessions, not to your own terminal.
135
147
  - Its CI workflows: one that checks the factory's files are in step, the
136
148
  ones that run a session in the cloud, and one more for each optional part
137
- you turn on. One that offers you new versions is _[Planned](developing.md#what-is-built)_.
149
+ you turn on. With a Dependabot configuration, two more complete
150
+ Dependabot's pull requests, the factory's own updates among them.
138
151
  - Comments on tickets it works, and one "Follow-ups" ticket.