@davidbyoung/software-factory 0.0.0-stage → 0.1.1

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 (141) hide show
  1. package/.claude-plugin/plugin.json +5 -0
  2. package/LICENSE +21 -0
  3. package/README.md +135 -2
  4. package/actions/factory-agent/action.yml +218 -0
  5. package/agents/factory-test-reviewer.md +129 -0
  6. package/agents/factory-ticket-readiness.md +107 -0
  7. package/agents/factory-ui-reviewer.md +160 -0
  8. package/bin/factory.js +45 -0
  9. package/bin/launch.js +67 -0
  10. package/dist/board.d.mts +128 -0
  11. package/dist/board.mjs +456 -0
  12. package/dist/build.d.mts +18 -0
  13. package/dist/build.mjs +60 -0
  14. package/dist/cli.d.mts +17 -0
  15. package/dist/cli.mjs +264 -0
  16. package/dist/code-host/github.d.mts +118 -0
  17. package/dist/code-host/github.mjs +419 -0
  18. package/dist/code-host/index.d.mts +9 -0
  19. package/dist/code-host/index.mjs +18 -0
  20. package/dist/code-host/types.d.mts +205 -0
  21. package/dist/code-host/types.mjs +12 -0
  22. package/dist/config.d.mts +166 -0
  23. package/dist/config.mjs +548 -0
  24. package/dist/deps.d.mts +32 -0
  25. package/dist/deps.mjs +126 -0
  26. package/dist/doctor.d.mts +34 -0
  27. package/dist/doctor.mjs +188 -0
  28. package/dist/guard-commit.d.mts +41 -0
  29. package/dist/guard-commit.mjs +209 -0
  30. package/dist/guard-permission.d.mts +15 -0
  31. package/dist/guard-permission.mjs +52 -0
  32. package/dist/guard-ticket-text.d.mts +27 -0
  33. package/dist/guard-ticket-text.mjs +288 -0
  34. package/dist/guard.d.mts +4 -0
  35. package/dist/guard.mjs +37 -0
  36. package/dist/init.d.mts +58 -0
  37. package/dist/init.mjs +556 -0
  38. package/dist/lib/clock.d.mts +14 -0
  39. package/dist/lib/clock.mjs +36 -0
  40. package/dist/lib/gh.d.mts +28 -0
  41. package/dist/lib/gh.mjs +92 -0
  42. package/dist/lib/glob.d.mts +2 -0
  43. package/dist/lib/glob.mjs +41 -0
  44. package/dist/lib/pricing.d.mts +25 -0
  45. package/dist/lib/pricing.mjs +77 -0
  46. package/dist/lib/usage.d.mts +34 -0
  47. package/dist/lib/usage.mjs +128 -0
  48. package/dist/lib/work-status.d.mts +251 -0
  49. package/dist/lib/work-status.mjs +510 -0
  50. package/dist/merge-policy.d.mts +66 -0
  51. package/dist/merge-policy.mjs +146 -0
  52. package/dist/parts.d.mts +39 -0
  53. package/dist/parts.mjs +138 -0
  54. package/dist/poller.d.mts +61 -0
  55. package/dist/poller.mjs +247 -0
  56. package/dist/pr-watch.d.mts +45 -0
  57. package/dist/pr-watch.mjs +244 -0
  58. package/dist/pr.d.mts +65 -0
  59. package/dist/pr.mjs +571 -0
  60. package/dist/review-cost.d.mts +18 -0
  61. package/dist/review-cost.mjs +95 -0
  62. package/dist/review-tools.d.mts +5 -0
  63. package/dist/review-tools.mjs +46 -0
  64. package/dist/review-verdict.d.mts +50 -0
  65. package/dist/review-verdict.mjs +171 -0
  66. package/dist/reviewers.d.mts +54 -0
  67. package/dist/reviewers.mjs +312 -0
  68. package/dist/runner/github-actions.d.mts +12 -0
  69. package/dist/runner/github-actions.mjs +97 -0
  70. package/dist/runner/index.d.mts +9 -0
  71. package/dist/runner/index.mjs +22 -0
  72. package/dist/runner/types.d.mts +60 -0
  73. package/dist/runner/types.mjs +7 -0
  74. package/dist/session-start.d.mts +20 -0
  75. package/dist/session-start.mjs +115 -0
  76. package/dist/site/capture.d.mts +44 -0
  77. package/dist/site/capture.mjs +114 -0
  78. package/dist/site/measure.d.mts +83 -0
  79. package/dist/site/measure.mjs +225 -0
  80. package/dist/site/pages.d.mts +10 -0
  81. package/dist/site/pages.mjs +71 -0
  82. package/dist/site/pixels.d.mts +47 -0
  83. package/dist/site/pixels.mjs +157 -0
  84. package/dist/site/servers.d.mts +47 -0
  85. package/dist/site/servers.mjs +141 -0
  86. package/dist/site.d.mts +60 -0
  87. package/dist/site.mjs +341 -0
  88. package/dist/status.d.mts +100 -0
  89. package/dist/status.mjs +514 -0
  90. package/dist/sync.d.mts +59 -0
  91. package/dist/sync.mjs +292 -0
  92. package/dist/ticket.d.mts +61 -0
  93. package/dist/ticket.mjs +562 -0
  94. package/dist/tickets/github.d.mts +128 -0
  95. package/dist/tickets/github.mjs +491 -0
  96. package/dist/tickets/index.d.mts +15 -0
  97. package/dist/tickets/index.mjs +27 -0
  98. package/dist/tickets/transport.d.mts +42 -0
  99. package/dist/tickets/transport.mjs +158 -0
  100. package/dist/tickets/types.d.mts +191 -0
  101. package/dist/tickets/types.mjs +76 -0
  102. package/docs/builds.md +227 -0
  103. package/docs/cli.md +221 -0
  104. package/docs/configuration.md +809 -0
  105. package/docs/design.md +106 -0
  106. package/docs/developing.md +400 -0
  107. package/docs/existing-repo.md +138 -0
  108. package/docs/github/reference.md +288 -0
  109. package/docs/github/setup.md +312 -0
  110. package/docs/glossary.md +106 -0
  111. package/docs/limitations.md +115 -0
  112. package/docs/plugins.md +192 -0
  113. package/docs/quick-start.md +222 -0
  114. package/docs/removing.md +76 -0
  115. package/docs/skills.md +270 -0
  116. package/docs/updating.md +108 -0
  117. package/docs/workflow.md +195 -0
  118. package/package.json +67 -4
  119. package/poller.Dockerfile +21 -0
  120. package/review.md +170 -0
  121. package/rules.md +313 -0
  122. package/settings.schema.json +411 -0
  123. package/skills/factory-address-review/SKILL.md +547 -0
  124. package/skills/factory-address-review/patch-coverage.py +68 -0
  125. package/skills/factory-build/SKILL.md +412 -0
  126. package/skills/factory-deps/SKILL.md +185 -0
  127. package/skills/factory-design/SKILL.md +159 -0
  128. package/skills/factory-diagnose/SKILL.md +93 -0
  129. package/skills/factory-mutate/SKILL.md +76 -0
  130. package/skills/factory-refine/SKILL.md +417 -0
  131. package/skills/factory-resolve-conflicts/SKILL.md +235 -0
  132. package/workflows/factory-board-sync.yml +91 -0
  133. package/workflows/factory-build.yml +72 -0
  134. package/workflows/factory-check.yml +37 -0
  135. package/workflows/factory-claude-review.yml +133 -0
  136. package/workflows/factory-conflicts.yml +69 -0
  137. package/workflows/factory-deps-auto-merge.yml +43 -0
  138. package/workflows/factory-deps.yml +59 -0
  139. package/workflows/factory-merge-policy.yml +121 -0
  140. package/workflows/factory-review-verdict.yml +54 -0
  141. package/workflows/factory-review.yml +75 -0
package/docs/design.md ADDED
@@ -0,0 +1,106 @@
1
+ # Why it works this way
2
+
3
+ The reasons behind the choices a user runs into. You do not need this page
4
+ to use the factory. Read it when something seems odd and you want to know
5
+ whether it is deliberate.
6
+
7
+ ## Your agent writes the code; a person approves it
8
+
9
+ A cloud build's commits name your coding agent as their author, and as
10
+ their committer the account whose token the build is given, which is the
11
+ account that signs them. The build pushes and opens its pull request as
12
+ that account too. Working alone, that is usually your own account. A team
13
+ can give it an agent account instead, one account on the code host that
14
+ every cloud build acts as, so the pull request's author is not one of the
15
+ people who must approve it. Nothing else changes between the two.
16
+
17
+ A session on your machine commits as you, since you are the one steering
18
+ it. `factory sync` turns the coding agent's attribution
19
+ lines off, unless your agent's settings already said otherwise, so a
20
+ session's commits carry your name alone.
21
+
22
+ Either way, a person is accountable for every change that merges: the one
23
+ who merges it. The factory's job is to make that person's read of a pull
24
+ request easy, and to hold anything risky for it. When builds act as your
25
+ own account, the guard against a session approving its own work is a
26
+ tripwire that catches accidents, not a wall against the account's owner.
27
+ Your read is the control.
28
+
29
+ ## Everything waits for you by default
30
+
31
+ No pull request merges itself until you list the files that may. A tool
32
+ that merges on its own has to earn that one file pattern at a time.
33
+
34
+ ## The factory's files are copied into your repository
35
+
36
+ The skills, agents, rules, and CI workflows are written into your
37
+ repository and checked for drift, which is more machinery than loading
38
+ them from the package. A cloud build starts from a fresh checkout, and what
39
+ is committed to the repository is what it reads, so the instructions a
40
+ build follows are the ones the pull request shows. The choice is not
41
+ forced: loading them from the package would also work, and would mean
42
+ one version for every repository.
43
+
44
+ It has one real benefit. Every version of the instructions your sessions
45
+ followed is in your repository's history, beside the code they built, and
46
+ an update shows you exactly which instruction changed.
47
+
48
+ The package is still laid out as a plugin for today's coding agent, so
49
+ that route stays open.
50
+
51
+ ## Skill names start with `factory-`
52
+
53
+ The prefix is part of each skill's name. It shows which skill files an
54
+ update will overwrite and which are yours, and keeps the factory's names
55
+ from colliding with your own.
56
+ [The reference](github/reference.md#skills-in-claude-code) says why the
57
+ name is not written with a colon.
58
+
59
+ ## The settings hold only what a script computes
60
+
61
+ Every key in `.claude/factory.yaml` is something the tool calculates with:
62
+ a path pattern, a command, a number. Anything that needs judgment, such as
63
+ when a reviewer applies, stays as prose in your instructions for the agent
64
+ or in the agent's own description, where a session reads it.
65
+
66
+ A setting that a session would have to interpret is a setting that behaves
67
+ differently from one day to the next.
68
+
69
+ ## The order of the workflow is fixed
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.
75
+
76
+ ## Small problems go on one checklist
77
+
78
+ A session that notices a small problem adds a line to one follow-ups
79
+ ticket instead of opening a ticket for it. Every ticket costs the same
80
+ steps whatever its size, so twenty small fixes as twenty tickets cost
81
+ twenty approvals and twenty pull requests. On one checklist they cost one
82
+ of each.
83
+
84
+ ## Three version numbers
85
+
86
+ They are separate on purpose.
87
+
88
+ | Number | Where it is | Changes when |
89
+ | ------------------- | -------------------------------------------- | ------------------------------------ |
90
+ | The factory's | `package.json` and `.claude/factory.lock` | Every release |
91
+ | The settings file's | `version:` at the top of `factory.yaml` | A key is renamed or moved |
92
+ | The markers' | In the comments the factory posts on tickets | The format of those comments changes |
93
+
94
+ - **Below `1.0.0`, a release may change anything**, and its notes say what.
95
+ `1.0.0` comes when a second repository has run on the factory for a while
96
+ and the settings have stopped moving.
97
+ - **The settings file has its own version** so that a release which does not
98
+ touch its shape never asks you to change it.
99
+ - **The markers have a version** because those comments stay in your
100
+ tickets' history for good, and an old one has to stay readable.
101
+
102
+ ## Secrets are named for what they do
103
+
104
+ Everything the factory owns starts with `FACTORY_` and says its purpose:
105
+ `FACTORY_BOARD_TOKEN`, not a name another tool might already use. You can
106
+ tell which secrets it needs and which are safe to delete.
@@ -0,0 +1,400 @@
1
+ # Developing the factory
2
+
3
+ How to work on the factory itself. For using it, start with the
4
+ [quick start](quick-start.md).
5
+
6
+ ## Where it lives
7
+
8
+ This repository holds the package, its docs, and its tests, and publishes
9
+ the package to npm as `@davidbyoung/software-factory`. It was developed
10
+ inside the private repository it was drawn out of until 0.1.0, and moved
11
+ here with a fresh history. Its tickets are kept, for now, on that
12
+ repository's board.
13
+
14
+ A change reaches a repository that uses the factory as a release: a new
15
+ version on npm, then Dependabot's pull request there, which `factory-deps`
16
+ completes with the files the version writes ([Updating](updating.md)).
17
+
18
+ ## What is built
19
+
20
+ The factory is the npm package `@davidbyoung/software-factory`. Parts not
21
+ marked working below exist only in these docs.
22
+
23
+ | Part | State |
24
+ | ------------------------------------------------------------------------------------------------------------- | ----------------------------------- |
25
+ | Refining, building, and working a pull request's review | Working |
26
+ | The board, its sync, and `status` | Working |
27
+ | Builds from the board, with a poller you host | Working |
28
+ | Builds that run in GitHub Actions, started by a command | Working |
29
+ | Starting builds from the board, and the review, conflict, and dependency runs, in GitHub Actions | Working |
30
+ | Who merges, and the review's verdict | Working |
31
+ | The labels `merge: manual` and `verdict: override` | Working |
32
+ | These docs | Working |
33
+ | `.claude/factory.yaml`, and the factory's files kept apart from the host's | Working |
34
+ | The follow-ups ticket as one checklist | Working |
35
+ | The `factory` tool, `sync`, and the package folder | Working |
36
+ | A global `factory` command that runs each repository's own copy | Working |
37
+ | The automated review as one of the factory's workflows, and `ci-review` | Working |
38
+ | Nothing in the package names the repository it was drawn out of, checked in the folder and the packed tarball | Working |
39
+ | The `factory-` names and the `FACTORY_` secrets | Working |
40
+ | Ticket commands that go through one interface | Working |
41
+ | The code host and the runner, each behind one interface | Working |
42
+ | A published package, updated through Dependabot | Planned, next |
43
+ | A second repository using it | Planned, after publishing |
44
+ | Your own column names on a board | Working |
45
+ | A UI reviewer for any website | Working |
46
+ | Built-in measurements for any website | Working |
47
+ | A design skill for any website | Working |
48
+ | `init`, which can be re-run, and `doctor` | Working |
49
+ | `remove` and `config explain` | Planned, not yet scheduled |
50
+ | `approvers` and `rules` in the settings | Planned, not yet scheduled |
51
+ | Starting builds from a scheduled workflow | Planned, not yet scheduled |
52
+ | `factory poller --once`, the scheduled workflow's one pass, and a poller built from an installed package | Planned, not yet scheduled |
53
+ | `factory migrate`, `factory board sync --dry-run`, and the `/factory-trace` skill | Planned, not yet scheduled |
54
+ | Another ticket system, such as Jira | Not planned. The design leaves room |
55
+ | Another code host or runner | Not planned. The design leaves room |
56
+ | Sharing plug-ins between repositories | Not planned |
57
+
58
+ When a part is built, its pull request updates this table, and corrects any
59
+ page the build had to differ from. [The CLI](cli.md) marks each command
60
+ built or planned.
61
+
62
+ ## The folder
63
+
64
+ ```text
65
+ ./
66
+ package.json name, version, bin, files, and its own dependencies
67
+ .claude-plugin/plugin.json so the folder is also a valid Claude Code plugin
68
+ bin/factory.js the launcher: plain JavaScript, no logic of its own
69
+ src/cli.mts reads the command and loads only that command's module
70
+ src/ one module per command, and the shared library
71
+ src/tickets/ the ticket interface, its GitHub adapter, and the transports
72
+ src/code-host/ the code host's interface and GitHub's implementation of it
73
+ src/runner/ the runner's interface and GitHub Actions' implementation of it
74
+ skills/factory-*/SKILL.md the skills
75
+ agents/factory-*.md the built-in reviewers
76
+ rules.md the process rules
77
+ review.md the CI reviewer's instructions
78
+ workflows/factory-*.yml the workflows copied into .github/workflows/
79
+ poller.Dockerfile the poller's image
80
+ docs/ these pages
81
+ tests/ the tool's tests and their fixtures
82
+ ```
83
+
84
+ It is laid out as a Claude Code plugin even though it is not delivered as
85
+ one. That costs nothing, and it keeps the plugin's own tooling usable on the
86
+ folder. The settings are validated in code, and `settings.schema.json` is the
87
+ editor's copy of their keys. A new key goes in `SETTINGS_KEYS` in
88
+ `src/config.mts`, in the schema, and in `docs/configuration.md`, and a test
89
+ fails when the first two differ.
90
+
91
+ ## Running from source
92
+
93
+ The tool is TypeScript, run directly by Node 22.18 or later with no build
94
+ step. In this repository, `npm ci` and then `node bin/factory.js`, or a
95
+ global `factory`, runs the source.
96
+
97
+ Node refuses to run TypeScript from inside `node_modules`, so an installed
98
+ package runs compiled JavaScript. `prepack` compiles `src/` to `dist/` with
99
+ `tsc`, and `src/` and `tests/` are not packed. The launcher, `bin/factory.js`,
100
+ serves both, and carries out what `chooseEntry` in `bin/launch.js` picks, in
101
+ this order:
102
+
103
+ 1. The source in the repository it was run from: the first folder at or
104
+ above the current directory that has `.git`, when it has
105
+ `packages/factory/package.json` with this package's name. So a git
106
+ worktree runs its own copy, not the one `npx` finds up the tree.
107
+ 2. The copy that repository installed, when that is not this one, so a
108
+ global install runs the repository's own version.
109
+ 3. Nothing, with a line saying how to install it, when this copy is outside
110
+ that repository and the repository has none.
111
+ 4. `src/cli.mts` beside the launcher, when it exists, and otherwise
112
+ `dist/cli.mjs`. Outside any repository, as in the poller's image, this
113
+ is always the choice.
114
+
115
+ Hooks run the launcher by its path with `node`, not through `npx`, since a
116
+ guard runs before every command a session runs: `npx` took 289 ms a call,
117
+ `node` on the launcher 56 ms.
118
+
119
+ To prove the package works outside its host, CI packs the folder, installs
120
+ the tarball into an empty repository, and runs `sync`, `sync --check`,
121
+ `config check`, and `plugins` there:
122
+
123
+ ```bash
124
+ npm run pack-check
125
+ ```
126
+
127
+ To try settings against a board without changing the repository's, point
128
+ `FACTORY_SETTINGS` at another settings file. Every command reads that file in
129
+ place of `.claude/factory.yaml`, for as long as the variable is set:
130
+
131
+ ```bash
132
+ FACTORY_SETTINGS=/tmp/try.yaml factory board check
133
+ ```
134
+
135
+ ## Changing a skill, an agent, or a rule
136
+
137
+ Edit the source here. A repository that uses the factory gets the change
138
+ in the next release, as a copy under its `.claude/` and `.github/` that
139
+ `factory sync` writes; CI there runs `factory sync --check`, which fails
140
+ when a copy differs from its source, so an edit made to a copy by mistake
141
+ cannot merge.
142
+
143
+ A skill, agent, or workflow that the factory's own steps call is its core,
144
+ and every repository gets it. Anything else is written only when a setting
145
+ or a file in the repository turns it on: add it to `NEEDS` in
146
+ `src/sync.mts`, so a repository that does not use it never carries it.
147
+
148
+ A factory file must name nothing that belongs to the host repository: not
149
+ its paths, its commands, its subject, or its own skills. A test fails when
150
+ one does. That is what keeps the folder movable.
151
+
152
+ ## Adding a ticket system
153
+
154
+ Only GitHub is built. The factory is built so that a second system is an
155
+ addition, not a rewrite. Four rules keep it that way.
156
+
157
+ **1. Nothing talks to the ticket system except through the tool.** A skill
158
+ never runs `gh issue` or calls GitHub's issues or projects API. It runs
159
+ `factory ticket view 12`, `factory ticket comment 12`, and the other
160
+ commands under [Tickets](cli.md#tickets). A test fails when a factory
161
+ skill, agent, rule, review instruction, or workflow contains a direct call.
162
+
163
+ **2. Three folders are the only code that calls GitHub.**
164
+ `src/tickets/` holds tickets and the board, `src/code-host/` pull
165
+ requests, reviews, and checks, whose conversation comments and labels
166
+ GitHub serves from its issues API, and `src/runner/` builds and their
167
+ runs. Every command reaches a ticket, a pull request, or a build through
168
+ one of them, and a test fails when a file elsewhere under `src/` calls
169
+ GitHub or holds a `github.com` address.
170
+
171
+ **3. The tool reads `tickets.type` and hands the work to that type's
172
+ adapter.** An adapter is one module in `src/tickets/` that implements the
173
+ `Tickets` type in `src/tickets/types.mts`. `github` is the only one; any
174
+ other value fails `factory config check` and every ticket command with
175
+ `tickets.type "X" is not supported. "github" is the only ticket system built.`
176
+ A type that names a package, so a team can write an adapter for a system
177
+ the factory does not ship, is planned, not built.
178
+
179
+ | Operation | In `Tickets` | What it returns or does |
180
+ | ----------------------- | ------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
181
+ | Read a ticket | `read` | Its number, title, state (`open` or `closed`), when it closed, labels, body, and comments, each with its ID, author, time, and body |
182
+ | List open tickets | `listOpen` | Number, title, and labels, for every open ticket however many there are |
183
+ | Read everything at once | `readAll` | Every open ticket and the 30 closed ones most recently updated, as `read` returns each; with the board group, each carries its card. Optional: see below |
184
+ | Write a ticket's body | `writeBody` | |
185
+ | Comment | `comment` | Returns the comment's ID. Hidden markers pass through unchanged |
186
+ | Edit a comment | `editComment` | By its ID |
187
+ | Delete a comment | `deleteComment` | By its ID |
188
+ | Not found | `NotFoundError` | Reading a ticket that does not exist, or editing or deleting a comment that is gone, throws this, so a caller can tell it from any other failure |
189
+ | Open a ticket | `open` | With a title, a body, and labels. Returns its number |
190
+ | Add or remove a label | `addLabel`, `removeLabel` | |
191
+ | Link text | `linkText` | What makes a merged pull request close the ticket, such as "Closes #12" |
192
+ | The address of a ticket | `address` | Its page, which the views link a ticket's number to |
193
+
194
+ "Read everything at once" has a default, `readAll` in
195
+ `src/tickets/types.mts`, built from `listOpen` and `read`, so a new adapter
196
+ need not write it; the default returns the open tickets, since a list of
197
+ open tickets cannot name the closed ones. The GitHub adapter overrides it
198
+ with one GraphQL query.
199
+
200
+ **4. An adapter says which optional groups it has.** Each group is there
201
+ whole or not at all, and `factory ticket supports GROUP` prints `yes` or
202
+ `no`. A skill asks before it relies on one; a command that needs a group
203
+ its adapter lacks exits non-zero, names the group, and posts nothing.
204
+
205
+ | Group | In `Tickets` | Operations |
206
+ | --------------- | -------------- | -------------------------------------------------------------------------------------------------------- |
207
+ | `board` | `board` | Read every card and the board's fields; add a ticket to the board; set its fields |
208
+ | `blockers` | `blockers` | List what a ticket waits on; record that it waits on another; remove that |
209
+ | `label-history` | `labelHistory` | Whether a label was ever removed from a ticket, which is how the factory knows the owner took `spec` off |
210
+ | `attachments` | `attachments` | Comment with images attached, or write a body with them |
211
+
212
+ The GitHub adapter has every group, except that `attachments` needs the
213
+ GitHub CLI, so an adapter built without it has none. With
214
+ no board, state lives in the ticket's comments. With no blockers, the build
215
+ order is prose in the ticket and nothing enforces it.
216
+
217
+ **The transport is a parameter.** The GitHub adapter, `src/code-host/`, and
218
+ `src/runner/` take one function for a REST call, one for a GraphQL query,
219
+ and one for an answer in plain text, such as a job's log
220
+ (`src/tickets/transport.mts`). `ghTransport` runs the GitHub CLI, for
221
+ sessions and CI. `fetchTransport` calls the API with a token, for the
222
+ poller, which runs with no `gh` and no install; `poller.Dockerfile` copies
223
+ the adapter, the transport, and what else the poller imports, and a test
224
+ fails when it misses one.
225
+
226
+ What stays above the interface: working out a ticket's state from its
227
+ marker comments, costs, and the formatting of every view, in
228
+ `src/lib/work-status.mts` and the commands. They are the factory's own
229
+ logic, the same for any system.
230
+
231
+ A second adapter exists from the start: an in-memory one,
232
+ `tests/memory-tickets.ts`, that every command's tests run against. It
233
+ keeps the interface honest, since anything the tests need has to go
234
+ through it. The GitHub adapter has its own tests against recorded
235
+ responses.
236
+
237
+ What an adapter does not cover: pull requests, reviews, and checks, which
238
+ are the code host's, and where an unattended build runs, which is the
239
+ runner's. Each has an interface of its own, described next, so a team can
240
+ keep its tickets in one system, its code on another, and run its builds on
241
+ a third.
242
+
243
+ ## Adding a code host
244
+
245
+ The code host is where pull requests are. Only GitHub is built. The
246
+ settings name it with `code-host.type`, and `src/code-host/index.mts` hands
247
+ a command the implementation of that name: one module in `src/code-host/`
248
+ that implements the `CodeHost` type in `src/code-host/types.mts`. Any other
249
+ value fails `factory config check`, and every command that reads the
250
+ settings and reaches a pull request, with
251
+ `code-host.type "X" is not supported. "github" is the only code host built.`
252
+ A type that names a package is planned, not built.
253
+
254
+ A command that a workflow also runs, such as `factory pr`, does not read
255
+ the settings there, so an unreadable settings file cannot fail the
256
+ workflow's step; it asks for the default. The poller has no settings at
257
+ all and names its implementations itself.
258
+
259
+ | Operation | In `CodeHost` | What it returns or does |
260
+ | ---------------------------------------- | --------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
261
+ | Read a pull request; list the open ones | `get`, `listOpen` | Its number, title, state, whether it is merged or a draft, body, mergeable state, author, labels, head and base (commit, branch, repository), and auto-merge |
262
+ | Open a pull request | `create` | From one branch into another, with a title and a body, as a draft or not. Returns its number, and fails in the code host's own words when the branch has nothing new or already has one open |
263
+ | Find a pull request | `forBranch`, `forCommit` | The open pull request from a branch, or none; the pull requests that hold a commit |
264
+ | What a pull request changes | `files`, `mergeBase` | Each file's path, its path before a rename, and its status; the commit two commits both descend from |
265
+ | The default branch | `defaultBranch` | |
266
+ | The checks on a commit | `checkRuns`, `statuses`, `setStatus` | Check runs and commit statuses, kept apart because `factory deps` reads check runs alone and `factory pr watch` reads both; sets a status by name. A check run carries what the check wrote about its own result, when it wrote anything |
267
+ | Conversation comments | `comments`, `commentView`, `comment`, `editComment` | Each with its ID, author, time, and body. `comment` returns the new comment's ID, and hidden markers pass through unchanged |
268
+ | Not found | `NotFoundError` | Reading a pull request or a comment that does not exist throws this, the same error the ticket interface throws |
269
+ | Add or remove a label | `addLabel`, `removeLabel` | |
270
+ | Reviews | `reviews`, `reviewCommentsOf`, `reviewComments` | Each review's ID, author, body, and time; the comments one review left on lines; every such comment on the pull request. A reply in a thread carries the comment it replies to |
271
+ | Review threads | `threads`, `openThreadCount`, `reply`, `resolve` | Each thread's first comment, file and line, comments, and whether it is resolved or outdated. `reply` and `resolve` take a comment's ID |
272
+ | Write a body; mark ready | `setBody`, `ready` | |
273
+ | Commits not shown as signed | `unverifiedCommits` | One line for each, its short ID and the reason, which `factory pr ready` prints when it refuses |
274
+ | The tickets a pull request closes | `closes` | Their numbers |
275
+ | The pull requests as the views read them | `open`, `linking` | The open ones with their closing links, open threads, and check state; and those, open or not, that link to a ticket, which the board sync reads for cost notes |
276
+ | The address of a pull request | `address` | Its page, which the views link a pull request's number to |
277
+
278
+ There are no optional groups. Every operation is one a command uses
279
+ today, so a group is carved out on the day a second code host lacks one.
280
+
281
+ **No skill, agent, or rule reaches the code host or the runner itself.**
282
+ Each runs a `factory pr` command, and a test fails when one names GitHub's
283
+ CLI, as a command or in a sentence. The review's instructions, `review.md`,
284
+ are the one exception: the review's checkout is the pull request's head, so
285
+ the factory's commands there are the code under review, and its reads go
286
+ through GitHub's CLI on purpose.
287
+
288
+ A commit's checks and statuses belong to the code host, not the runner: a
289
+ pull request shows them whatever ran them. A check run carries `checksId`,
290
+ the ID it shares with the runner's run that reported it, which is how
291
+ `factory pr wait-checks` names the checks of a run that failed.
292
+
293
+ What a command prints or hands on under GitHub's own field names keeps
294
+ those names: `factory pr comments --json` prints each comment's `id`,
295
+ `user.login`, `body`, and `created_at`, and `merge-policy` hands each of
296
+ your commands `filename`, `previous_filename`, and `status`. The command
297
+ turns the interface's answer back into those names, so they hold on any
298
+ code host. Those are all it prints: a field GitHub returns that the
299
+ interface does not carry, such as a comment's `html_url`, is not among
300
+ them.
301
+
302
+ A second implementation exists from the start, `tests/memory-code-host.ts`,
303
+ that the tests of `pr`, `deps`, `build`, and `review cost` run against.
304
+ GitHub's has its own tests against faked replies, which is where a test
305
+ of which call GitHub is sent belongs.
306
+
307
+ ## Adding a runner
308
+
309
+ The runner is where an unattended build runs. Only GitHub Actions is
310
+ built. The settings name it with `builds.runner`, and
311
+ `src/runner/index.mts` hands a command the implementation of that name:
312
+ one module in `src/runner/` that implements the `Runner` type in
313
+ `src/runner/types.mts`. Any other value fails `factory config check`, and
314
+ every command that reads the settings and reaches the runner, with
315
+ `builds.runner "X" is not supported. "github-actions" is the only runner built.`
316
+
317
+ | Operation | In `Runner` | What it returns or does |
318
+ | ------------------------------ | ------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
319
+ | Start a build of a ticket | `startBuild` | On a branch. A refused start throws the runner's own error, whose status and reason the poller's comment on the ticket carries |
320
+ | Find the run a start made | `findBuild` | The page of the ticket's build started at or after a time, or nothing while none shows: a runner may answer a start with no run |
321
+ | The page that lists builds | `buildsPage` | What `factory build` prints when the run is not found |
322
+ | The page of a run | `runPage` | From the run's ID, which a ticket's claim comment records |
323
+ | The run this session is in | `thisRun` | Its ID, its page, and who started it, read from the session's environment; nothing outside a run |
324
+ | The runs for a commit | `runs` | Each run's ID, which set of jobs it is a run of, what started it, its status and conclusion, and its `checksId` |
325
+ | The review's runs for a commit | `reviewRuns` | Their status and conclusion, newest first |
326
+ | Have the review run again | `reviewAgain` | The newest run of a commit's review, run again; false when none has run on it |
327
+ | The jobs that failed in a run | `failedJobs` | Each failed job's name and everything it printed. Which runs count is the caller's: `factory pr failed` takes those `wait-checks` waits on |
328
+
329
+ **A runner also needs its own job files, which no interface covers.** The
330
+ workflows under `workflows/`, the action they share, and their secrets
331
+ are GitHub Actions' own. `factory sync` copies them whatever
332
+ `builds.runner` says, and another runner would need its own set, written
333
+ for it.
334
+
335
+ Three things stay in GitHub Actions' words whatever the runner: the
336
+ factory's messages and comments say "GitHub Actions", the marker comments
337
+ on tickets say `actions`, and the board's "Runs in" field says "Actions".
338
+ The commands only a workflow runs (`review verdict`, `merge-policy`, and
339
+ `review cost`) read GitHub Actions' event file and its `GITHUB_*`
340
+ variables, and reach pull requests through the code host.
341
+
342
+ The in-memory runner is `tests/memory-runner.ts`, and GitHub Actions' has
343
+ its own tests against faked replies.
344
+
345
+ ## Checking a change
346
+
347
+ | Check | What it proves |
348
+ | ---------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
349
+ | The tool's unit tests | Each command does what it says. A new test is seen failing before it is trusted |
350
+ | `factory sync --check` | The copies match the source |
351
+ | 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 |
352
+ | `/factory-trace` | A change to a rule did not make some kind of change heavier, lighter, or ambiguous |
353
+ | One throwaway ticket | After each stage, one small ticket goes through refine, build, and review for real. Nothing else tests the prose |
354
+
355
+ The skills are instructions, and instructions cannot be unit tested. The
356
+ last row is the only real proof that a change to one still works.
357
+
358
+ ## Releasing
359
+
360
+ 1. Raise `version` in `package.json` in a pull request, and merge it.
361
+ 2. Tag the merge commit with the same version and push the tag:
362
+
363
+ ```bash
364
+ git tag v0.2.0 && git push origin v0.2.0
365
+ ```
366
+
367
+ 3. The release workflow checks that the tag matches `package.json`,
368
+ runs the tests and `pack-check`, and publishes the version to npm.
369
+
370
+ The first version, 0.1.0, was published by hand, since npm sets up a
371
+ trusted publisher only for a package that exists:
372
+
373
+ ```bash
374
+ npm ci
375
+ npm publish --access public
376
+ ```
377
+
378
+ Then, on npmjs.com, the package's settings name this repository's
379
+ `release.yml` as its trusted publisher, so later versions publish with no
380
+ token. Nothing published can be taken back after 72 hours, and
381
+ `pack-check` fails when a packed file names the repository the factory was
382
+ drawn out of.
383
+
384
+ ## Writing for the factory
385
+
386
+ - **American English, with the Oxford comma.**
387
+ - **The factory's own words:** ticket, follow-up, the six states, the three
388
+ roles. Not issue, card, or sweep.
389
+ - **A key name must make sense unexplained.** Each reference settings file
390
+ is read cold by a fresh agent that is told only what the factory is. A key
391
+ it explains wrongly, or cannot tell from another, is renamed or given a
392
+ better comment.
393
+ - **A setting has a default, or it has a reason not to.**
394
+ - **A page says what is built.** Anything not built carries the _Planned_
395
+ mark where it is used, linked to "What is built", and a test fails on a
396
+ planned command named without it. When a ticket builds something, its
397
+ pull request removes the mark, and corrects the page where the build had
398
+ to differ.
399
+ - **Examples carry the reason for a rule, without the host's private
400
+ history.**
@@ -0,0 +1,138 @@
1
+ # Adopting it in an existing repository
2
+
3
+ Most repositories already have a toolchain, a board, instructions for a
4
+ coding agent, or a team. This page says what the factory does in each case,
5
+ and what it leaves alone.
6
+
7
+ ## Try it without committing to it
8
+
9
+ Do the [quick start](quick-start.md) on a branch and do not merge it. Start
10
+ an agent session on that branch and refine and build one ticket. If you
11
+ decide against it, delete the branch. [Removing it](removing.md) covers the
12
+ case where you have already merged.
13
+
14
+ ## A repository that is not JavaScript
15
+
16
+ The factory's tool runs on Node and is installed with npm, whatever your
17
+ project is written in. In a PHP, Python, or Go repository that means:
18
+
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.
22
+ - **`package-lock.json` is committed.** It is what keeps everyone on the
23
+ same version of the factory.
24
+ - **`node_modules/` is ignored.** `factory init` adds it
25
+ to your `.gitignore`.
26
+ - **Everyone who works on the repository needs Node 22.18 or later**, and
27
+ runs `npm ci` once after cloning.
28
+ - **Your own CI does not change.** The factory's cloud jobs install Node
29
+ for themselves. If you turn on the automated review, how it installs your
30
+ 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 ./...`.
33
+
34
+ The factory's hooks run its own tool, so they need nothing beyond Node.
35
+ Someone who only writes code by hand, and never runs an agent session in
36
+ the repository, needs none of this.
37
+
38
+ [Configuration](configuration.md#a-repository-that-is-not-javascript) has a
39
+ complete settings file for a PHP library.
40
+
41
+ ## You already have a board
42
+
43
+ `factory init` lists your boards to choose from, and gives
44
+ the one you choose any of the factory's six columns and three fields it
45
+ lacks. A column of yours whose name matches one of the six, whatever its
46
+ case, is used as it is; your other columns stay, after the six. It says
47
+ what it added:
48
+
49
+ ```text
50
+ Added to board 3: Backlog, In refinement, Ready, In review, Session, Runs in, Cost.
51
+ ```
52
+
53
+ - **It adds; it never renames or removes.** Your "Todo" column stays, with
54
+ its cards.
55
+ - **A card in a column the factory does not know is ignored.** Nothing
56
+ moves it, and nothing builds it. In this example that is everything in
57
+ "Todo": move a card to Backlog when you want the factory to track it,
58
+ or move them all once and retire the column.
59
+ - **The factory's fields are overwritten on every sync.** Do not type into
60
+ 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
64
+ mapping for a board with Todo, In Progress, and Done. To see what the
65
+ factory will do with your board, run:
66
+
67
+ ```bash
68
+ factory board check
69
+ ```
70
+
71
+ - **Your board's own automations**, such as moving a closed ticket to
72
+ Done, have not been tested alongside the factory. Turn them off if cards
73
+ jump unexpectedly.
74
+
75
+ A board owned by an organization is read the same way as a person's, but
76
+ has not yet been run against a real one. A repository an organization owns
77
+ has one more gap: only the owner's comments count as answers, and the
78
+ owner is read from the repository's name, which there is the
79
+ organization's.
80
+
81
+ ## You already have agent instructions, settings, or CI workflows
82
+
83
+ - **Your agent's instructions file:** one line is added at the end,
84
+ importing the factory's rules. Nothing else in it changes. Your own rules
85
+ win where the two disagree.
86
+ - **Your agent's settings:** a few hooks are added, and the agent's
87
+ attribution lines are turned off, so a session's commits and pull
88
+ requests carry no line naming an AI: they are yours. A cloud build's
89
+ commits name the agent as their author instead
90
+ ([Builds in the cloud](builds.md)). If your settings already
91
+ say how to attribute, that stays. Your existing hooks, permissions, and
92
+ settings stay as they are.
93
+ - **Your skills and agents:** untouched. Everything the factory adds is
94
+ named `factory-...`, so nothing collides.
95
+ - **Your CI workflows:** untouched. The factory's are named `factory-...`.
96
+ - **`factory init` lists every file** it would write or
97
+ change before it writes, and changes nothing if you say no.
98
+
99
+ On GitHub with Claude Code, [the reference](github/reference.md#what-setup-adds)
100
+ names each file.
101
+
102
+ ## A team
103
+
104
+ - **A person's own session acts as that person.** A commit made by a
105
+ teammate's session goes out under that teammate's account. A cloud build
106
+ acts as the one account that owns its token: yours, or an account you
107
+ create for the team's builds
108
+ ([Builds in the cloud](github/setup.md#builds-in-the-cloud)).
109
+ - **Say who approves.** By default only the repository's owner can approve
110
+ a ticket for building or give a session instructions in a comment. List
111
+ the others under [`approvers`](configuration.md#approvers), _[Planned](developing.md#what-is-built)_.
112
+ - **One version for everyone.** The version is pinned in
113
+ `package-lock.json`. After an update merges, each person pulls and runs
114
+ `npm ci`. `factory doctor` says so when the installed
115
+ version and the repository's disagree.
116
+ - **One session per ticket.** A session claims a ticket before it starts,
117
+ and a second one is told who holds it.
118
+ - **One person merges updates.** An update changes the instructions
119
+ everyone's sessions follow, so it always waits for a person.
120
+ [Updating](updating.md) describes it.
121
+ - **Check your coding agent's plan** covers the way your team would use
122
+ this, including builds that run without anyone watching.
123
+
124
+ ## What it does to your repository, in short
125
+
126
+ [What it changes](removing.md) says what kinds of things the factory adds,
127
+ and how to undo each. The short version:
128
+
129
+ - Files it owns, all named `factory-...`, and its rules.
130
+ - One line in your agent's instructions file, and a few hooks in your
131
+ 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.
135
+ - Its CI workflows: one that checks the factory's files are in step, the
136
+ 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)_.
138
+ - Comments on tickets it works, and one "Follow-ups" ticket.