@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
@@ -0,0 +1,76 @@
1
+ # What it changes, and removing it
2
+
3
+ What the factory adds to your repository, your code host, and your board,
4
+ and how to undo it. Read this before you install, and again if you decide
5
+ to take it out. On GitHub with Claude Code,
6
+ [the reference](github/reference.md#what-setup-adds) names every file,
7
+ hook, label, and setting.
8
+
9
+ ## What it adds
10
+
11
+ - **In your repository:** its settings file, `.claude/factory.yaml`, and a
12
+ lock file beside it; its own skills, agents, rules, and CI workflows, all
13
+ named `factory-...`; one line in your agent's instructions file that
14
+ imports its rules; and a few hooks in your agent's settings that guard
15
+ every session. If you had no `package.json`, setup adds a small one to
16
+ install the factory with.
17
+ - **On your code host:** the secrets you create for the parts you turn on;
18
+ the labels and statuses that say who merges a pull request and whether
19
+ the automated review found it ready; comments on the tickets it works;
20
+ and one "Follow-ups" ticket.
21
+ - **On your board,** if you have one: three fields, Session, Runs in, and
22
+ Cost, which `factory init` adds when the board lacks
23
+ them, and the board's own Status, which the sync sets. `init` adds any of
24
+ the six columns the board lacked.
25
+ - **Outside both,** only if builds start from your board: the poller,
26
+ wherever you host it.
27
+
28
+ ## What it never touches
29
+
30
+ Your code, your tickets, and your pull requests. Your own skills, agents,
31
+ plug-ins, and CI workflows, which the factory never writes to.
32
+
33
+ Two files belong to you, and removing the factory leaves them: the CI
34
+ workflow that runs the automated review, which you edit to install your
35
+ project, and the review notes you write for it.
36
+
37
+ ## Removing it _[Planned](developing.md#what-is-built)_
38
+
39
+ Until `factory remove` is built, delete by hand what
40
+ [the reference](github/reference.md#what-setup-adds) lists.
41
+
42
+ ```bash
43
+ factory remove
44
+ ```
45
+
46
+ ```bash
47
+ npm uninstall @davidbyoung/software-factory
48
+ ```
49
+
50
+ The first command removes everything it added to your repository and
51
+ prints what is left for you to remove by hand: secrets, labels, and
52
+ anything outside the repository. It commits nothing. Review the changes,
53
+ commit them on a branch, and merge.
54
+
55
+ ## Before you remove it
56
+
57
+ - **If builds are running,** let them finish or stop them first. Open
58
+ tickets and pull requests stay exactly as they are.
59
+ - **If you made the review's verdict a required check** on your main
60
+ branch, remove that requirement first, or every pull request waits on it
61
+ forever.
62
+ - **Deleting a label removes it from every ticket.** Keep the labels if
63
+ you want their history.
64
+ - **The comments it posted on tickets stay.** They hold each ticket's
65
+ history.
66
+
67
+ ## Undoing one part, not all of it
68
+
69
+ Each optional part can be turned off by itself. Remove its key from
70
+ `.claude/factory.yaml`, then:
71
+
72
+ ```bash
73
+ factory sync
74
+ ```
75
+
76
+ That deletes the CI workflows the part used. Delete its secret afterward.
package/docs/skills.md ADDED
@@ -0,0 +1,270 @@
1
+ # Skills
2
+
3
+ A skill is a set of instructions an agent session follows when you ask for
4
+ it. An agent, in this page's sense, is a separate reviewer a session
5
+ launches, which reads and reports and changes nothing. This page covers
6
+ every skill and agent the factory brings.
7
+
8
+ You call a skill by asking a session in plain words, such as "refine ticket
9
+ 12". Your coding agent may also have a shorter way to call one by name; on
10
+ Claude Code it is a slash command, as
11
+ [the reference](github/reference.md#skills-in-claude-code) shows.
12
+
13
+ ## Which ones a repository gets
14
+
15
+ The factory's core is what its own steps call, and every repository gets
16
+ it. Everything else is written only when a setting or a file turns it on,
17
+ and `factory sync` removes it again when that is undone.
18
+
19
+ | Skill or agent | Written |
20
+ | --------------------------- | ------------------------------------ |
21
+ | `factory-refine` | Always |
22
+ | `factory-build` | Always |
23
+ | `factory-address-review` | Always |
24
+ | `factory-resolve-conflicts` | Always |
25
+ | `factory-diagnose` | Always |
26
+ | `factory-mutate` | Always |
27
+ | `factory-ticket-readiness` | Always |
28
+ | `factory-test-reviewer` | Always |
29
+ | `factory-design` | With `site` in your settings |
30
+ | `factory-ui-reviewer` | With `site` in your settings |
31
+ | `factory-deps` | With a `.github/dependabot.yml` file |
32
+
33
+ ## At a glance
34
+
35
+ | Ask a session | Skill | It does |
36
+ | ---------------------------------- | --------------------------- | --------------------------------------------------------------------------------------------------- |
37
+ | "refine ticket 12" | `factory-refine` | Turns a ticket into a spec a builder can start from |
38
+ | "build ticket 12" | `factory-build` | Builds a ticket to a reviewed pull request |
39
+ | "address the review on 280" | `factory-address-review` | Works a pull request's review until it can merge |
40
+ | "resolve the conflicts on 280" | `factory-resolve-conflicts` | Merges your main branch into a pull request and settles the conflicts |
41
+ | "diagnose this failing test" | `factory-diagnose` | Finds a bug's cause before any code changes |
42
+ | "mutate this test" | `factory-mutate` | Proves a test can fail |
43
+ | "fix the dependency pull requests" | `factory-deps` | Moves dependency pull requests toward merged |
44
+ | "mock up a new about page" | `factory-design` | Designs a visible change to a website, with mockups |
45
+ | "trace this rule change" | `factory-trace` | _[Planned](developing.md#what-is-built)_: Traces a change to the rules through every kind of change |
46
+
47
+ ## `factory-refine`
48
+
49
+ **What it does.** Turns a ticket into something a session can build without
50
+ asking anything. It works in two roles: a product manager, who challenges
51
+ the ask and brings you only the decisions that are yours, and a tech lead,
52
+ who settles everything the code and the rules can answer.
53
+
54
+ **When to use it.** On any ticket before it is built. A ticket with no
55
+ acceptance criteria cannot be built; `factory-build` sends it here.
56
+
57
+ **What it reads.** The ticket and its comments, the open tickets that touch
58
+ the same code, the code itself, your project's instructions for the agent
59
+ (`CLAUDE.md` files, on Claude Code), and the existing
60
+ spec when `specs` is on.
61
+
62
+ **What it writes.**
63
+
64
+ - The ticket's body: your text first, untouched, then Decisions and
65
+ Acceptance criteria, or a Spec when the change is visible and not small.
66
+ - Marker comments that move the ticket to "refining" and show it waiting on
67
+ you.
68
+ - A blocked-by relationship for each ticket that must be built first.
69
+ - For a decision about the look, mockups from your
70
+ [`mockups` plug-in](plugins.md), if you have one.
71
+
72
+ **How it asks.** In the session if you are there: each decision as a
73
+ choice, the recommended answer first. Otherwise as one comment on the
74
+ ticket, where anything you leave alone goes ahead as written.
75
+
76
+ **What it never does.** Move the ticket to Ready unasked. Edit a round of
77
+ questions once posted. Ask you something the code or the rules already
78
+ answer. Ask more than five questions: more than that means the ticket is
79
+ several tickets, and it proposes the split.
80
+
81
+ **Its check.** The built-in `factory-ticket-readiness` agent reads the
82
+ result cold, at most twice, and lists what a builder would still have to
83
+ ask.
84
+
85
+ ## `factory-build`
86
+
87
+ **What it does.** Takes an approved ticket to a reviewed pull request.
88
+
89
+ 1. Claims the ticket, so no other session builds it.
90
+ 2. Makes a branch from your main branch, named for the ticket.
91
+ 3. Builds to the acceptance criteria: the test first where there is a
92
+ defect to reproduce or a behavior to add, then the change.
93
+ 4. Proves each new test can fail, and has `factory-test-reviewer` read the
94
+ tests.
95
+ 5. Has each [`reviewer` plug-in](plugins.md) that applies read the change,
96
+ and fixes what they find.
97
+ 6. Runs the checks your project's instructions name.
98
+ 7. Opens a draft pull request that closes the ticket, saying what changed,
99
+ how it was checked, and what each reviewer found.
100
+ 8. Marks it ready once CI passes on the pushed commit, then works the
101
+ review with `factory-address-review`.
102
+
103
+ **When to use it.** On a ticket that has acceptance criteria and your
104
+ approval. Telling a session "build ticket 12" is approval. So is moving the ticket
105
+ to Ready.
106
+
107
+ **What it reads.** The ticket, its Decisions, and your project's
108
+ instructions beside the code it changes.
109
+
110
+ **What it writes.** A branch, commits, a draft pull request, a claim
111
+ comment on the ticket, a note of what the build cost, and a line on the
112
+ [follow-ups ticket](workflow.md#follow-ups) for anything small it noticed
113
+ and did not fix.
114
+
115
+ **When it stops.** On a question only you can answer, a step only you can
116
+ do, an open blocker, or a gate that will not pass. It releases the ticket
117
+ and says why. The ticket stays in "building", waiting on you.
118
+
119
+ **What it never does.** Commit on your main branch. Merge. Turn auto-merge
120
+ on. Add the label that overrides a review's verdict. Guess at a decision
121
+ the ticket left open. Reopen a decision the ticket settled.
122
+
123
+ **Defaults you can change,** _[Planned](developing.md#what-is-built)_. `rules.small-change-lines`, default 30: a
124
+ change under it takes the lighter path [Workflow](workflow.md) describes.
125
+
126
+ ## `factory-address-review`
127
+
128
+ **What it does.** Works everything standing between a pull request and its
129
+ merge: the threads from the automated review, your own comments, failed
130
+ checks, patch coverage, and a conflict with your main branch.
131
+
132
+ **When to use it.** After every push to a branch with an open pull request.
133
+ The session that built the pull request runs it without being asked.
134
+
135
+ **How it treats a finding.**
136
+
137
+ - A finding is confirmed by a repro, not by reading. It builds the smallest
138
+ input that should trigger it and runs the real code.
139
+ - It takes the finding and designs its own fix, and says in the reply when
140
+ that differs from what was suggested.
141
+ - Every thread gets a reply before it is resolved, accepted or rejected.
142
+ - A rejection cites evidence: a quoted source or a failing repro.
143
+
144
+ **Also a job in the cloud.** The job that starts when you review a pull
145
+ request runs it too, answering your review: it checks first that there is
146
+ something to do, and starts no session when there is not.
147
+
148
+ **What it writes.** Commits on the branch, a reply on each thread, and one
149
+ report.
150
+
151
+ **When it stops.** After two rounds (`rules.review-rounds`, _[Planned](developing.md#what-is-built)_), whatever
152
+ is still in dispute goes to you instead of through another round.
153
+
154
+ **What it never does.** Resolve a thread it neither fixed nor disproved.
155
+ Dismiss a failing test as flaky without reproducing it. Merge.
156
+
157
+ ## `factory-diagnose`
158
+
159
+ **What it does.** Finds the cause of a bug, a failing or flaky test, or a
160
+ slowdown, before changing any code. It starts by building one command that
161
+ fails on the exact symptom, shrinks it, ranks the possible causes, and
162
+ tests them one change at a time.
163
+
164
+ **When to use it.** When something is broken, failing, flaky, or slow, and
165
+ the cause is not already known.
166
+
167
+ **What it never does.** Change code before it can make the failure happen
168
+ on demand. Fix two things at once.
169
+
170
+ ## `factory-mutate`
171
+
172
+ **What it does.** Proves a test can fail. It breaks the code under test one
173
+ way at a time and watches the test go red, then puts the code back and
174
+ confirms the working tree is clean.
175
+
176
+ **When to use it.** For a test written after the code it tests, or one
177
+ never seen failing for the right reason. A test that passes either way
178
+ locks nothing in.
179
+
180
+ **What it never does.** Leave a mutation in place.
181
+
182
+ ## `factory-deps`
183
+
184
+ **What it does.** Moves every open dependency pull request one step closer
185
+ to merged: resolves a conflict with your main branch, fixes failing checks,
186
+ does the migration a major version asks for, and opens a ticket for
187
+ anything it cannot fix.
188
+
189
+ **When to use it.** When dependency pull requests are stuck, or from the
190
+ job in the cloud that runs it for you. It is written, with its two
191
+ workflows, only to a repository that has a `.github/dependabot.yml`. A
192
+ security update GitHub opens in a repository without that file waits for
193
+ you: nothing moves it along or lets it merge itself.
194
+
195
+ **What it never does.** Merge. Make only the changes CI caught when a
196
+ migration guide calls for more.
197
+
198
+ ## `factory-design`
199
+
200
+ **What it does.** Designs a visible change to a website as a designer
201
+ would: one recommended design in real content, built from your site and
202
+ pictured by `factory site compare` at your widths in light and dark,
203
+ reviewed by `factory-ui-reviewer` before you see it, and shown beside the
204
+ page as it is. It reads your `design-guide` when you wrote one, and who
205
+ your visitors are from your project's own instructions.
206
+
207
+ **When to use it.** When asked to redesign or restyle a page, and from
208
+ `factory-refine` when a decision changes how something looks. A
209
+ repository with `site` in its settings gets it as its
210
+ [`mockups` plug-in](plugins.md) without listing it; one without `site`
211
+ does not get it at all.
212
+
213
+ **What it never does.** Make a mockup of a change with no look to choose,
214
+ or one made by editing a running page instead of building it. Leave a
215
+ scratch worktree behind.
216
+
217
+ ## `factory-trace` _[Planned](developing.md#what-is-built)_
218
+
219
+ **What it does.** A rule written for one kind of change can be wrong for
220
+ every other kind. Before a change to the rules, a skill, or an agent is
221
+ marked ready, this has a fresh agent trace each kind of change your
222
+ repository gets through the rules as they would stand, and report any kind
223
+ that got heavier, lighter, or ambiguous, and any two rules that now
224
+ disagree.
225
+
226
+ **What it reads.** `.claude/change-types.md`, your list of the kinds of
227
+ change your repository gets, each with a real example.
228
+
229
+ ## `factory-resolve-conflicts`
230
+
231
+ **What it does.** Merges your main branch into a pull request that conflicts
232
+ with it, runs the gate, and pushes the merge. It never rebases or forces a
233
+ push. When the two sides of a conflict contradict each other, it pushes
234
+ nothing, comments why, and opens a ticket, because which side wins is your
235
+ decision.
236
+
237
+ **When to use it.** Ask it for one pull request ("resolve the conflicts on
238
+ 280"). `factory-address-review` calls it when the pull request it is
239
+ working conflicts. A job in the cloud also runs it as the conflict sweep, after each
240
+ push to your default branch and nightly, over every pull request that
241
+ conflicts. The sweep checks first that there is something to do, and starts
242
+ no session when there is not.
243
+
244
+ ## The built-in agents
245
+
246
+ ### `factory-ticket-readiness`
247
+
248
+ Reads a refined ticket cold, as the session that will build it, and lists
249
+ every question it would still have to ask. `factory-refine` runs it.
250
+ Read-only.
251
+
252
+ ### `factory-ui-reviewer`
253
+
254
+ Reads a change to how a website looks or responds. It runs
255
+ `factory site compare`, reads the before and after pictures of the pages that
256
+ changed, drives the states the change is about, and judges them against built-in
257
+ rules, your `design-guide` when you wrote one, and what your `checks` printed.
258
+ It is listed under `plugins` like a reviewer of your own, with the `files` that
259
+ should trigger it, and is written only to a repository with `site` in its
260
+ settings. Read-only, and slow.
261
+
262
+ ### `factory-test-reviewer`
263
+
264
+ Reads new or changed tests the way a test engineer reviews a pull request:
265
+ one behavior per test, each able to fail, found the way a user would find
266
+ it, with no waits on a timer. `factory-build` runs it. Read-only, and it
267
+ does not run the suite.
268
+
269
+ It takes its specifics from your project's instructions beside your tests. Without one,
270
+ it applies only those general rules.
@@ -0,0 +1,108 @@
1
+ # Updating _[Planned](developing.md#what-is-built)_
2
+
3
+ Nothing on this page works until the package is published. Until then, a
4
+ new version reaches your repository the way it was installed, and
5
+ `factory sync` applies it.
6
+
7
+ **When a new version is released, a pull request appears in your
8
+ repository. You read it and merge it.** That is all you have to do.
9
+
10
+ ## What happens
11
+
12
+ 1. Dependabot's weekly run finds the new version and opens one pull
13
+ request for it, as it does for any package. Its group for the factory
14
+ ([on GitHub](github/reference.md#dependency-bots)) keeps the pull
15
+ request to the factory alone.
16
+ 2. `factory-deps`, which already looks after Dependabot's pull requests,
17
+ runs `factory sync` on its branch and adds what it wrote as a second
18
+ commit. Until it has, CI's `factory sync --check` fails.
19
+ 3. You read it and merge it. It never merges itself, whatever your
20
+ `auto-merge` settings allow.
21
+ 4. Everyone working on the repository, you included, pulls and runs
22
+ `npm ci`, as after any dependency change.
23
+
24
+ ## What the pull request holds
25
+
26
+ - **The new version**, in `package.json`, the lockfile, and
27
+ `.claude/factory.lock`.
28
+ - **The factory's files, rewritten.** Its skills, agents, rules, and CI
29
+ workflows live in your repository, so the diff shows exactly which
30
+ instruction changed.
31
+ - **A comment from `factory-deps`** listing the files the sync changed,
32
+ and anything the release notes say to do by hand, first.
33
+
34
+ An update changes the instructions your sessions follow and the code that
35
+ runs with your tokens. Read it as carefully as you would read code.
36
+
37
+ ## Doing it yourself
38
+
39
+ To update now instead of waiting for Dependabot:
40
+
41
+ ```bash
42
+ npm install --save-dev @davidbyoung/software-factory@latest
43
+ factory sync
44
+ ```
45
+
46
+ Commit both on a branch and open a pull request. To see whether you are
47
+ behind without changing anything:
48
+
49
+ ```bash
50
+ factory doctor
51
+ ```
52
+
53
+ ## Staying on a version, or going back
54
+
55
+ - **To stay where you are,** close the update pull request. Dependabot
56
+ opens a new one for the next release.
57
+ - **To go back,** revert the update's pull request. The version and the
58
+ files go back together.
59
+
60
+ ## Without Dependabot
61
+
62
+ Update by hand as above. `factory-deps` and its workflows are written only
63
+ once `.github/dependabot.yml` exists.
64
+
65
+ ## The commands
66
+
67
+ | Command | When |
68
+ | ---------------- | ---------------------------------------------------------- |
69
+ | `factory sync` | After you edit `.claude/factory.yaml`, to apply the change |
70
+ | `factory doctor` | To see whether you are behind, or why something is off |
71
+
72
+ `factory sync` rewrites the factory's files to match your
73
+ settings and the installed version.
74
+
75
+ ## On a team
76
+
77
+ Decide who merges updates, and tell them these pull requests are theirs.
78
+ An update changes how everyone's sessions behave, so one person should
79
+ read each one. After it merges, everyone pulls and runs `npm ci`. Until
80
+ they do, `factory doctor` and the start of each session
81
+ tell them their installed version is behind the repository's; the
82
+ session's start also says so, naming `npm ci`, when `node_modules` does
83
+ not match `package-lock.json`.
84
+
85
+ ## When something goes wrong
86
+
87
+ | What you see | What happened | What to do |
88
+ | --------------------------------------------------------------------------- | --------------------------------------------------------------------- | -------------------------------------------------------------------------- |
89
+ | CI fails with "the factory's files are out of sync" | A factory file was edited by hand, or settings changed without a sync | Run `factory sync` and commit the result |
90
+ | `factory doctor` says your installed version is older than the repository's | You pulled an update and have not installed it | Run `npm ci` |
91
+ | The update pull request conflicts with your main branch | Something else changed the same file | `factory-deps` resolves it on its next run, or close it and update by hand |
92
+
93
+ ## Never edit a factory file
94
+
95
+ Every file named `factory-...`, and the factory's rules, are written by
96
+ the factory. An edit made to one would be lost on the next update, so CI
97
+ fails when one differs from what the installed version would write.
98
+
99
+ To change what the factory does:
100
+
101
+ - **For your repository only:** say so in your own instructions for the
102
+ agent, which win over the factory's rules, or, _[Planned](developing.md#what-is-built)_, change the value under
103
+ [`rules`](configuration.md#rules) in your settings.
104
+ - **For everyone:** change it in the factory, and it reaches you as an
105
+ update.
106
+
107
+ [Why it works this way](design.md) explains why the files are copied in
108
+ and what the three version numbers are.
@@ -0,0 +1,195 @@
1
+ # Workflow
2
+
3
+ How a ticket moves from an idea to a merged pull request, who moves it at
4
+ each step, and what the factory will not do on its own.
5
+
6
+ ## From a ticket to a merge
7
+
8
+ | Step | Who | Where it runs | What comes out |
9
+ | ----------------- | -------------------------------------------------- | -------------------------------------------------- | ----------------------------------------------------------------------------- |
10
+ | Write a ticket | You | Your ticket system | A ticket saying what, why, and when it is done |
11
+ | Refine it | A session you start | Your machine, in your coding agent | The ticket rewritten into acceptance criteria, after you answer its decisions |
12
+ | Approve it | **You** | A session, or your board | Tell a session to build it, or move its card to Ready |
13
+ | Build it | A session | Your machine, or the cloud when started from Ready | A tested change in a pull request that closes the ticket |
14
+ | Review it | The automated review, if you set it up | Your CI | Comments and a verdict on the pull request |
15
+ | Answer the review | The session that built it | Where it was built | Each comment fixed, or rejected with evidence |
16
+ | Merge it | **You**, or the merge policy for files you allowed | Your code host | The change on your main branch, and the ticket closed |
17
+
18
+ Everything a session does, it does as you: through your account on the
19
+ code host and your coding agent's subscription, on your machine or in the
20
+ cloud. No step needs a service of the factory's own.
21
+
22
+ ## The six states
23
+
24
+ A ticket is always in one of six states. They are fixed: you cannot add one
25
+ or reorder them. Your board shows them as columns, and which column shows
26
+ which state is your repository's choice
27
+ ([`tickets.columns`](configuration.md#ticketscolumns)). The table gives the
28
+ default names.
29
+
30
+ A state with no column of its own shows in the column of the nearest earlier
31
+ state that has one, and a ticket is shown in the `ready` column only when it
32
+ is approved. A board without a `ready` column approves a build by telling a
33
+ session to build the ticket, or by running
34
+ `factory build N`.
35
+
36
+ | State | Board column | It means |
37
+ | -------- | ------------- | ----------------------------------------------------------------------------- |
38
+ | backlog | Backlog | Nothing is happening |
39
+ | refining | In refinement | A session is turning it into a spec, or the spec is written and waits for you |
40
+ | ready | Ready | You approved it for a build from the board |
41
+ | building | In progress | A session has claimed it, or a build ended without a pull request merging |
42
+ | review | In review | A pull request that closes it is open |
43
+ | done | Done | The ticket is closed |
44
+
45
+ ```text
46
+ backlog → refining → ready → building → review → done
47
+ ↑
48
+ the one move that is yours
49
+ ```
50
+
51
+ ## Who moves a ticket
52
+
53
+ | Move | Who |
54
+ | ------------------ | ---------------------------------------------------------------- |
55
+ | backlog → refining | The session you ask to refine it |
56
+ | refining → ready | **You**, by moving the card, or by telling a session to build it |
57
+ | ready → building | The session that claims it |
58
+ | building → review | Opening the pull request |
59
+ | review → done | The merge, which closes the ticket |
60
+
61
+ Approving a ticket is the only move a person has to make. A session moves
62
+ the card to Ready only when you ask it to, as your own move.
63
+
64
+ ## What is fixed
65
+
66
+ These hold in every repository. They are not settings.
67
+
68
+ - **A ticket only moves forward on its own.** When the next step is yours,
69
+ it stays where it is and the board says "Waiting on you". Only you move a
70
+ ticket back.
71
+ - **Nothing retries by itself.** A build that stopped, failed to start, or
72
+ whose pull request you closed stays in "building", waiting on you. Moving
73
+ it to Ready again retries it.
74
+ - **The order does not change.** A repository cannot add a state or reorder
75
+ them. A team that wants a security review between building and review adds
76
+ a [reviewer](plugins.md), not a column.
77
+ - **One session holds a ticket at a time.** The claim is a comment on the
78
+ ticket. A second session that tries is told who holds it and stops.
79
+
80
+ ## The board
81
+
82
+ The factory writes four fields of the board: its Status, and three of its
83
+ own. Anything you type into the
84
+ last three is overwritten on the next sync.
85
+
86
+ | Field | Shows |
87
+ | ------- | ------------------------------------------------------------------------------------- |
88
+ | Status | The column |
89
+ | Session | Which session is on the ticket, "actions, starting", or "Waiting on you" |
90
+ | Runs in | Whether that session is on a machine or in the cloud |
91
+ | Cost | An estimate of what refining and building the ticket used, summed across its sessions |
92
+
93
+ Sessions never write the board directly. They post marker comments on the
94
+ ticket, and one job in the cloud, the board sync, reads those and sets the
95
+ fields.
96
+ That is why a ticket's history survives even if the board is rebuilt.
97
+
98
+ `factory status` prints the same picture in a terminal.
99
+
100
+ ## Tickets that wait on another
101
+
102
+ When building one ticket first would break another, or mean redoing work,
103
+ the second is recorded as blocked by the first, using the ticket system's
104
+ own relationship between tickets. A build never starts on a ticket with an open blocker, and
105
+ starts within a minute of the blocker closing if the ticket is in Ready.
106
+
107
+ Two tickets touching the same file is not a blocker. That is a merge
108
+ conflict, and the session that owns the pull request resolves it.
109
+
110
+ ## Sizing the work to the change
111
+
112
+ A change under about 30 lines outside tests, adding no new component and no
113
+ new state, is **small**. It skips the heavier steps: no separate spec, no
114
+ readiness read, and one test that reproduces the defect or checks the
115
+ change. The first message of the work says which path it is taking, so you
116
+ can overrule it before it starts.
117
+
118
+ The number is `rules.small-change-lines` in your
119
+ [settings](configuration.md), _[Planned](developing.md#what-is-built)_; until it is built, it is 30.
120
+
121
+ ## Follow-ups
122
+
123
+ A session building one ticket often notices something else: a test that
124
+ cannot fail, a stale sentence, a button under its size floor. It does not
125
+ stop to fix it, and it does not open a ticket for it. It adds a line to the
126
+ repository's **follow-ups ticket**, which is an ordinary ticket whose body
127
+ is a checklist:
128
+
129
+ ```text
130
+ Follow-ups
131
+
132
+ - [ ] src/pages/about.tsx: The heading skips from level 1 to level 3.
133
+ - [ ] scripts/release.sh: The usage text still names a flag that was removed.
134
+ - [ ] tests/search.spec.ts: This test passes even when search returns nothing.
135
+ ```
136
+
137
+ There is one per repository, it carries the `follow-up` label, and there is
138
+ nothing to configure. When you approve it, a session fixes every unchecked
139
+ line on one branch, one commit per line, in one pull request.
140
+
141
+ **Why a checklist and not a ticket each.** Every ticket costs the same
142
+ steps whatever its size: refining, your approval, a branch, a pull request,
143
+ a review, and a merge. For a one-line fix that is all overhead. Twenty
144
+ small fixes on one checklist cost you one approval and one pull request.
145
+
146
+ **What becomes a line, and what gets its own ticket.**
147
+
148
+ | The session noticed | It becomes |
149
+ | -------------------------------------------------------- | ----------------------------------------------------- |
150
+ | Something small that breaks a rule your guides state | A line |
151
+ | Something that needs your call before it can be fixed | A line that says "Needs a decision:" and the question |
152
+ | Something that would change what your users see | Its own ticket |
153
+ | Something you asked for | Its own ticket |
154
+ | Something that breaks no rule, or needs measuring to see | Nothing |
155
+
156
+ Every line names the file it is about, says what is wrong, and says which
157
+ rule it breaks, so it can be fixed as written.
158
+
159
+ ## Who merges
160
+
161
+ Every pull request gets one of two labels:
162
+
163
+ - **`merge: automatic`**: every file is allowed by your
164
+ [`auto-merge`](configuration.md#auto-merge) settings, and none of the
165
+ commands you listed there held it. It merges itself once every check
166
+ passes.
167
+ - **`merge: manual`**: anything else. It waits for a person to merge it,
168
+ and a "Who merges" status on the pull request says what held it and
169
+ why.
170
+
171
+ Two more things guard a merge:
172
+
173
+ - **"Review verdict"** is a status, which you can make required on your
174
+ main branch, that passes only when the automated
175
+ review of the newest commit said it is ready, or an approver overrode it
176
+ with the `verdict: override` label. Sessions never add that label.
177
+ - **Every review thread must be resolved.** A session answers each one,
178
+ fixed or rejected with evidence, before resolving it.
179
+
180
+ Both the labeling and the verdict run from your main branch's copy of the
181
+ rules, so a pull request cannot change how it is judged.
182
+
183
+ A session never merges, never turns auto-merge on, and never overrides a
184
+ verdict.
185
+
186
+ ## A change your users will see
187
+
188
+ With `specs: openspec`, a change that adds or alters behavior someone can
189
+ see, and is not small, carries the `spec` label. Its ticket holds a "Spec"
190
+ section of plain "When this, then that" lines. The build turns those lines
191
+ into an OpenSpec change, builds to them, and folds them into
192
+ `openspec/specs/` in the same pull request, so that folder always describes
193
+ what the project does now.
194
+
195
+ With `specs: none`, the ticket's acceptance criteria are the whole spec.