@davidbyoung/software-factory 0.1.2 → 0.1.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (83) hide show
  1. package/README.md +8 -9
  2. package/dist/agent/claude-code.d.mts +3 -0
  3. package/dist/agent/claude-code.mjs +89 -0
  4. package/dist/agent/index.d.mts +2 -0
  5. package/dist/agent/index.mjs +5 -0
  6. package/dist/board.mjs +1 -1
  7. package/dist/cli.mjs +17 -2
  8. package/dist/code-host/github-setup.d.mts +5 -0
  9. package/dist/code-host/github-setup.mjs +133 -0
  10. package/dist/code-host/github.mjs +4 -0
  11. package/dist/code-host/index.d.mts +1 -1
  12. package/dist/code-host/index.mjs +2 -1
  13. package/dist/code-host/types.d.mts +2 -0
  14. package/dist/config.d.mts +26 -7
  15. package/dist/config.mjs +79 -26
  16. package/dist/doctor.d.mts +6 -14
  17. package/dist/doctor.mjs +52 -64
  18. package/dist/explain.d.mts +2 -0
  19. package/dist/explain.mjs +127 -0
  20. package/dist/init.d.mts +8 -12
  21. package/dist/init.mjs +179 -131
  22. package/dist/lib/has-command.d.mts +5 -0
  23. package/dist/lib/has-command.mjs +8 -0
  24. package/dist/lib/listed.d.mts +2 -0
  25. package/dist/lib/listed.mjs +4 -0
  26. package/dist/lib/work-status.d.mts +12 -2
  27. package/dist/lib/work-status.mjs +14 -3
  28. package/dist/parts.d.mts +18 -15
  29. package/dist/parts.mjs +15 -43
  30. package/dist/poller.d.mts +20 -3
  31. package/dist/poller.mjs +62 -15
  32. package/dist/remove.d.mts +11 -0
  33. package/dist/remove.mjs +156 -0
  34. package/dist/runner/github-actions.d.mts +1 -1
  35. package/dist/runner/github-actions.mjs +12 -0
  36. package/dist/runner/index.d.mts +1 -1
  37. package/dist/runner/index.mjs +2 -1
  38. package/dist/runner/setup.d.mts +2 -0
  39. package/dist/runner/setup.mjs +22 -0
  40. package/dist/runner/types.d.mts +3 -0
  41. package/dist/runner/types.mjs +0 -2
  42. package/dist/setup.d.mts +98 -0
  43. package/dist/setup.mjs +3 -0
  44. package/dist/status.d.mts +4 -4
  45. package/dist/status.mjs +8 -7
  46. package/dist/sync.d.mts +18 -0
  47. package/dist/sync.mjs +137 -7
  48. package/dist/tickets/github-setup.d.mts +2 -0
  49. package/dist/tickets/github-setup.mjs +50 -0
  50. package/dist/tickets/github.mjs +0 -2
  51. package/dist/tickets/index.mjs +2 -1
  52. package/dist/tickets/transport.mjs +1 -3
  53. package/dist/tickets/types.mjs +0 -2
  54. package/dist/tool-names.d.mts +11 -0
  55. package/dist/tool-names.mjs +20 -0
  56. package/dist/tools.d.mts +56 -0
  57. package/dist/tools.mjs +76 -0
  58. package/docs/builds.md +103 -51
  59. package/docs/cli.md +42 -42
  60. package/docs/configuration.md +34 -32
  61. package/docs/design.md +1 -1
  62. package/docs/developing.md +143 -68
  63. package/docs/existing-repo.md +20 -9
  64. package/docs/github/by-hand.md +321 -0
  65. package/docs/github/reference.md +65 -61
  66. package/docs/github/setup.md +83 -267
  67. package/docs/glossary.md +5 -4
  68. package/docs/limitations.md +12 -10
  69. package/docs/plugins.md +9 -14
  70. package/docs/quick-start.md +62 -105
  71. package/docs/removing.md +36 -16
  72. package/docs/skills.md +47 -37
  73. package/docs/updating.md +2 -6
  74. package/docs/workflow.md +13 -12
  75. package/package.json +1 -1
  76. package/poller.Dockerfile +10 -18
  77. package/rules.md +14 -12
  78. package/settings.schema.json +24 -0
  79. package/skills/factory-build/SKILL.md +1 -1
  80. package/skills/factory-trace/SKILL.md +79 -0
  81. package/workflows/factory-build.yml +5 -4
  82. package/workflows/factory-deps-auto-merge.yml +3 -2
  83. package/workflows/factory-poller.yml +46 -0
@@ -1,33 +1,25 @@
1
1
  # Quick start
2
2
 
3
- From nothing to a pull request built from one of your tickets. You run a
4
- few commands, write one ticket, and answer a question or two; your coding
5
- agent does the rest. This page needs no board, no secrets, and nothing to
6
- host.
3
+ For someone with a repository and a coding agent who has never used the
4
+ factory. At the end you have a pull request built from one of your
5
+ tickets. You run a few commands, write one ticket, and answer a question
6
+ or two. It needs no board, no secrets, and nothing to host.
7
7
 
8
- A word you do not know is in the [glossary](glossary.md). A step marked
9
- _[Planned](developing.md#what-is-built)_ is not built yet, and says what to
10
- do until then.
8
+ A word you do not know is in the [glossary](glossary.md).
11
9
 
12
10
  ## You need
13
11
 
14
12
  - A repository on a supported code host, cloned on your machine, with the
15
13
  code host's command-line tool signed in.
16
14
  - A supported coding agent, signed in.
17
- - Node 22.18 or later. Check with `node --version`.
15
+ - Node 22.18 or later.
18
16
 
19
- Which tools are supported, and how to check each is ready, is in
20
- [What you need](github/setup.md#what-you-need) on the GitHub page.
21
-
22
- Your repository does not have to be JavaScript. If it is not, read
23
- [this section](existing-repo.md#a-repository-that-is-not-javascript)
24
- first: installing adds a small `package.json`.
17
+ [What you need](github/setup.md#what-you-need) names the supported tools
18
+ and how to check each. A repository with no `package.json` works too:
19
+ [read this first](existing-repo.md#a-repository-that-is-not-javascript).
25
20
 
26
21
  ## 1. Install
27
22
 
28
- _[Planned](developing.md#what-is-built)._ Until the package is published,
29
- it cannot be installed outside the repository it is developed in.
30
-
31
23
  Once on your machine, so you can type `factory`:
32
24
 
33
25
  ```bash
@@ -41,8 +33,7 @@ npm install --save-dev @davidbyoung/software-factory
41
33
  ```
42
34
 
43
35
  **It worked when** `factory`, run in your repository, prints the list of
44
- its commands. It exits non-zero, since no command was given; that is
45
- expected.
36
+ its commands.
46
37
 
47
38
  ## 2. Set it up
48
39
 
@@ -50,50 +41,23 @@ expected.
50
41
  factory init
51
42
  ```
52
43
 
53
- It says what it found, asks which optional parts you want, and shows
54
- everything it will do before it does any of it. For this first ticket,
55
- uncheck every part: the basics need none.
56
-
57
- Told to go ahead, it writes your settings file, `.claude/factory.yaml`,
58
- and the instructions your coding agent follows when it works a ticket. It
59
- adds hooks: small checks your agent runs on its own, such as refusing a
60
- commit on your main branch. It adds one line to your agent's instructions
61
- file, such as `CLAUDE.md`, and the hooks to your agent's settings,
62
- creating either file if you have none. It changes nothing else of yours,
63
- and commits nothing. [What it changes](removing.md) lists every item and
64
- how to undo it.
65
-
66
- **It worked when** the checks it prints last all show ✓. Run them again at
67
- any time with `factory doctor`.
68
-
69
- **To do it by hand instead,** write the shortest settings file, with your
70
- repository's owner and name, then write the factory's files:
71
-
72
- ```yaml
73
- version: 1
74
- repository: your-name/your-repo
75
- ```
76
-
77
- ```bash
78
- factory sync
79
- ```
44
+ It shows what it found and asks which optional parts you want. For this
45
+ first ticket, uncheck every part. It then lists everything it will do, and
46
+ once you tell it to go ahead, writes your settings file,
47
+ `.claude/factory.yaml`, and the instructions and checks your coding agent
48
+ follows. It commits nothing. [What it changes](removing.md) lists every
49
+ file.
80
50
 
81
51
  A build checks its change with the commands your agent's instructions
82
- file names, such as your tests and your linter, so say there how to check
83
- a change. Without any, it checks with the tests it wrote.
52
+ file, such as `CLAUDE.md`, names. If it names none, add your test and lint
53
+ commands there now.
84
54
 
85
- To have a command run before every commit a session makes, such as your
86
- linter, list it under `before-commit` in the settings file:
87
-
88
- ```yaml
89
- before-commit:
90
- - npm run lint
91
- ```
55
+ **It worked when** the checks `init` prints last all show ✓, or `-` for a
56
+ part you left off. `factory doctor` runs them again at any time.
92
57
 
93
58
  ## 3. Merge the setup
94
59
 
95
- Commit what `sync` wrote on a branch, push it, then open a pull request for
96
- it on your code host, as for any change, and merge it:
60
+ Commit what `init` wrote on a branch and push it:
97
61
 
98
62
  ```bash
99
63
  git switch -c set-up-factory
@@ -102,24 +66,25 @@ git commit -m "Set up the software factory"
102
66
  git push -u origin set-up-factory
103
67
  ```
104
68
 
105
- Then bring your main branch up to date:
69
+ Open a pull request for the branch on your code host and merge it, as for
70
+ any change. Then bring your main branch up to date:
106
71
 
107
72
  ```bash
108
73
  git switch main
109
74
  git pull
110
75
  ```
111
76
 
112
- Your coding agent loads the factory from the files in your repository, so
113
- start a new session after this step.
77
+ Start a new session of your coding agent, which loads the factory from the
78
+ files now in your repository.
114
79
 
115
80
  **It worked when** the new session, asked which skills it has, lists
116
- `factory-refine` and `factory-build`. A skill is a set of instructions for
117
- one kind of job, such as refining a ticket.
81
+ `factory-refine` and `factory-build`.
118
82
 
119
83
  ## 4. Open a ticket
120
84
 
121
- A ticket in your ticket system. Say three things: what you want, why, and
122
- how you will know it is done. A few sentences is enough.
85
+ Open a ticket in your ticket system: on GitHub, an issue in your
86
+ repository. Say three things: what you want, why, and how you will know it
87
+ is done. A few sentences is enough.
123
88
 
124
89
  ```text
125
90
  Title: Show the opening hours in the footer
@@ -128,17 +93,17 @@ The hours are only on the contact page, and people ask for them.
128
93
  Done when: every page's footer shows the same hours the contact page does.
129
94
  ```
130
95
 
131
- Note its number. This page uses 12.
96
+ **It worked when** the ticket has a number. This page uses 12.
132
97
 
133
98
  ## 5. Refine it
134
99
 
135
- In a session of your coding agent, in your repository, say:
100
+ In the session, say:
136
101
 
137
102
  ```text
138
103
  refine ticket 12
139
104
  ```
140
105
 
141
- The session reads the ticket and the code it touches. Then it asks you the
106
+ The session reads the ticket and the code it touches, then asks you the
142
107
  decisions that are yours, each as a choice with its recommendation first:
143
108
 
144
109
  ```text
@@ -148,8 +113,7 @@ Where should the hours come from?
148
113
  ```
149
114
 
150
115
  **It worked when** the ticket ends with acceptance criteria, a checklist
151
- that says exactly what "done" means, and the session says it is ready to
152
- build.
116
+ of exactly what "done" means, and the session says it is ready to build.
153
117
 
154
118
  ## 6. Build it
155
119
 
@@ -159,22 +123,14 @@ In the same session, or a new one:
159
123
  build ticket 12
160
124
  ```
161
125
 
162
- Telling a session to build a ticket is how you approve it.
163
-
164
- You can watch it work. The session:
165
-
166
- 1. comments on the ticket that it has claimed it, so no other session
167
- builds the same one;
168
- 2. makes a branch;
169
- 3. writes a test, then the change;
170
- 4. checks each commit with your `before-commit` commands, if you set any;
171
- 5. opens a pull request that closes the ticket, as a draft, which tells
172
- people and the automated review it is not finished;
173
- 6. marks it ready for review once your CI passes on it, or after two
174
- minutes when no CI runs on it, and answers any review it gets.
126
+ Telling a session to build a ticket is how you approve it. The session
127
+ makes a branch, writes a test and then the change, and opens a pull
128
+ request that closes the ticket. Expect minutes, not seconds.
129
+ [Workflow](workflow.md#from-a-ticket-to-a-merge) has each step.
175
130
 
176
131
  **It worked when** its last message names the pull request, says what it
177
- built, and says how it checked it. Expect minutes, not seconds.
132
+ built, and says how it checked it. This page uses 15 for the pull
133
+ request's number.
178
134
 
179
135
  ## 7. Read it and merge
180
136
 
@@ -189,34 +145,35 @@ answer your comments:
189
145
  address the review on pull request 15
190
146
  ```
191
147
 
148
+ **It worked when** the pull request is merged and ticket 12 is closed.
192
149
  That is the whole loop: **ticket, refine, build, read, merge.**
193
150
 
194
151
  ## If something goes wrong
195
152
 
196
- | What happened | What to do |
197
- | ------------------------------------------------ | ------------------------------------------------------------------------------------------- |
198
- | A `before-commit` command fails during the build | Nothing. The session sees the output, fixes the cause, and tries again |
199
- | The session stops and says it needs you | It says why, in the session and on the ticket. Answer, then ask it to build ticket 12 again |
200
- | The session was closed or crashed partway | Ask a new session to build ticket 12. It picks up the branch it made |
201
- | You want to change what was decided | Ask a session to refine ticket 12 again, or edit the ticket |
202
- | CI fails on the pull request | Ask a session to address the review on pull request 15. It reads the failure and fixes it |
203
- | The session does not know the factory's skills | The setup is not merged, or the session started before it was. See step 3 |
204
- | Anything else | Run `factory doctor`. It says what is wrong, and what to do about it |
153
+ | What happened | What to do |
154
+ | ---------------------------------------------- | ------------------------------------------------------------------------------------------- |
155
+ | A test or a check fails during the build | Nothing. The session sees the output, fixes the cause, and tries again |
156
+ | The session stops and says it needs you | It says why, in the session and on the ticket. Answer, then ask it to build ticket 12 again |
157
+ | The session was closed or crashed partway | Ask a new session to build ticket 12. It picks up the branch it made |
158
+ | You want to change what was decided | Ask a session to refine ticket 12 again, or edit the ticket |
159
+ | CI fails on the pull request | Ask a session to address the review on pull request 15. It reads the failure and fixes it |
160
+ | The session does not know the factory's skills | The setup is not merged, or the session started before it was. See step 3 |
161
+ | Anything else | Run `factory doctor`. It says what is wrong, and what to do about it |
205
162
 
206
163
  ## What to add next
207
164
 
208
- Everything above runs on your machine while you watch. Each part below is
165
+ Everything above runs on your machine while you watch. Each of these is
209
166
  optional, stands alone, and can come later.
210
167
 
211
- | Add | So that | It asks of you |
212
- | ----------------------------------- | -------------------------------------------------------------------- | --------------------------------------------- |
213
- | An automated review | Every pull request is read by your coding agent before you read it | Your agent's token, stored on the code host |
214
- | A board | You see every ticket's state, which session has it, and what it cost | A board, and a token that can write to it |
215
- | Builds in the cloud | A ticket builds with no session open on your machine | Your agent's token, and a token that can push |
216
- | Builds that start from the board | Moving a ticket to Ready builds it | A small program, the poller, that you host |
217
- | Pull requests that merge themselves | Changes to files you list as safe do not wait for you | The list of files, and a token that can merge |
218
- | Your own reviewers | A change to your content or your design is read by an expert agent | A few lines of settings |
219
-
220
- Run `factory init` again and turn on the parts you want;
221
- it sets up each one, tokens included. [Setting up on GitHub](github/setup.md)
222
- has the same steps by hand, on one page.
168
+ - **An automated review, a board, builds in the cloud, builds that start
169
+ from the board, and pull requests that merge themselves.** Run
170
+ `factory init` again and check the parts you want. It asks for a token
171
+ or two and sets everything else up.
172
+ [Setting up on GitHub](github/setup.md#run-factory-init) says what each
173
+ part gives you and what it asks.
174
+ - **A command before every commit a session makes,** such as your linter:
175
+ two lines under [`before-commit`](configuration.md#before-commit).
176
+ - **Your own reviewers,** so a change to your content or your design is
177
+ read by an expert agent: a few lines under
178
+ [`plugins`](configuration.md#plugins), which [Plug-ins](plugins.md)
179
+ walks through.
package/docs/removing.md CHANGED
@@ -12,8 +12,8 @@ hook, label, and setting.
12
12
  lock file beside it; its own skills, agents, rules, and CI workflows, all
13
13
  named `factory-...`; one line in your agent's instructions file that
14
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.
15
+ every session. If you had no `package.json`, you made a small one to install the factory
16
+ with.
17
17
  - **On your code host:** the secrets you create for the parts you turn on;
18
18
  the labels and statuses that say who merges a pull request and whether
19
19
  the automated review found it ready; comments on the tickets it works;
@@ -22,22 +22,19 @@ hook, label, and setting.
22
22
  Cost, which `factory init` adds when the board lacks
23
23
  them, and the board's own Status, which the sync sets. `init` adds any of
24
24
  the six columns the board lacked.
25
- - **Outside both,** only if builds start from your board: the poller,
26
- wherever you host it.
25
+ - **Outside both,** only if you host the poller: the poller, wherever you
26
+ host it. `factory remove` names it in what is left by hand.
27
27
 
28
28
  ## What it never touches
29
29
 
30
30
  Your code, your tickets, and your pull requests. Your own skills, agents,
31
31
  plug-ins, and CI workflows, which the factory never writes to.
32
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.
33
+ One file belongs to you, and removing the factory leaves it: the review
34
+ notes you write for the automated review. The review's workflow is the
35
+ factory's: every sync rewrites it, and removing the factory deletes it.
36
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.
37
+ ## Removing it
41
38
 
42
39
  ```bash
43
40
  factory remove
@@ -47,10 +44,32 @@ factory remove
47
44
  npm uninstall @davidbyoung/software-factory
48
45
  ```
49
46
 
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.
47
+ If you installed the `factory` command on your machine and no longer want
48
+ it anywhere:
49
+
50
+ ```bash
51
+ npm uninstall -g @davidbyoung/software-factory
52
+ ```
53
+
54
+ The first command shows every file it will delete or change and asks
55
+ before changing anything. It then deletes the factory's files, takes its
56
+ hooks and its import line out of the files it shares with your coding
57
+ agent, and prints what is left outside the repository for you to remove by
58
+ hand: secrets, the rule that requires the review's verdict, labels, and the
59
+ board's fields. Each tool you use adds its own lines to that list. It
60
+ commits nothing. Review the changes, commit them on a branch, and merge.
61
+
62
+ If your settings file is gone or cannot be read, it says so, removes what
63
+ it finds, and names what the tools it ships with leave behind.
64
+
65
+ It leaves `package.json`, `package-lock.json`, `node_modules/` in your
66
+ `.gitignore`, and the setting that turns off your agent's lines naming
67
+ itself in commits and pull requests. The second command takes the
68
+ factory's entry out of `package.json`; delete the rest if nothing else
69
+ uses them, as [the reference](github/reference.md#what-setup-adds) says
70
+ for each. If you delete `package.json` and remove the `.gitignore` line,
71
+ delete the `node_modules/` folder too, and any file setup made that is now
72
+ empty, such as `.gitignore` or `.claude/settings.json`.
54
73
 
55
74
  ## Before you remove it
56
75
 
@@ -73,4 +92,5 @@ Each optional part can be turned off by itself. Remove its key from
73
92
  factory sync
74
93
  ```
75
94
 
76
- That deletes the CI workflows the part used. Delete its secret afterward.
95
+ That deletes the CI workflows only that part uses. Delete its secret
96
+ afterward.
package/docs/skills.md CHANGED
@@ -16,33 +16,33 @@ The factory's core is what its own steps call, and every repository gets
16
16
  it. Everything else is written only when a setting or a file turns it on,
17
17
  and `factory sync` removes it again when that is undone.
18
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 |
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`](configuration.md#site) in your settings |
30
+ | `factory-ui-reviewer` | With `site` in your settings |
31
+ | `factory-deps` | With a `.github/dependabot.yml` file |
32
32
 
33
33
  ## At a glance
34
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 |
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` | Traces a change to the rules through every kind of change |
46
46
 
47
47
  ## `factory-refine`
48
48
 
@@ -57,7 +57,7 @@ acceptance criteria cannot be built; `factory-build` sends it here.
57
57
  **What it reads.** The ticket and its comments, the open tickets that touch
58
58
  the same code, the code itself, your project's instructions for the agent
59
59
  (`CLAUDE.md` files, on Claude Code), and the existing
60
- spec when `specs` is on.
60
+ spec when [`specs`](configuration.md#specs) is on.
61
61
 
62
62
  **What it writes.**
63
63
 
@@ -120,8 +120,9 @@ and says why. The ticket stays in "building", waiting on you.
120
120
  on. Add the label that overrides a review's verdict. Guess at a decision
121
121
  the ticket left open. Reopen a decision the ticket settled.
122
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.
123
+ **Defaults you can change.**
124
+ [`rules.small-change-lines`](configuration.md#rules), default 30: a change
125
+ under it takes the lighter path [Workflow](workflow.md) describes.
125
126
 
126
127
  ## `factory-address-review`
127
128
 
@@ -148,7 +149,7 @@ something to do, and starts no session when there is not.
148
149
  **What it writes.** Commits on the branch, a reply on each thread, and one
149
150
  report.
150
151
 
151
- **When it stops.** After two rounds (`rules.review-rounds`, _[Planned](developing.md#what-is-built)_), whatever
152
+ **When it stops.** After two rounds (`rules.review-rounds`), whatever
152
153
  is still in dispute goes to you instead of through another round.
153
154
 
154
155
  **What it never does.** Resolve a thread it neither fixed nor disproved.
@@ -214,11 +215,12 @@ does not get it at all.
214
215
  or one made by editing a running page instead of building it. Leave a
215
216
  scratch worktree behind.
216
217
 
217
- ## `factory-trace` _[Planned](developing.md#what-is-built)_
218
+ ## `factory-trace`
218
219
 
219
220
  **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
221
+ every other kind. Before a change to the rules, a skill, an agent, or a
222
+ workflow that alters what triggers a step, who runs, or when is marked
223
+ ready, this has a fresh agent trace each kind of change your
222
224
  repository gets through the rules as they would stand, and report any kind
223
225
  that got heavier, lighter, or ambiguous, and any two rules that now
224
226
  disagree.
@@ -226,6 +228,13 @@ disagree.
226
228
  **What it reads.** `.claude/change-types.md`, your list of the kinds of
227
229
  change your repository gets, each with a real example.
228
230
 
231
+ **What it writes.** The fresh agent's report: on the pull request when the
232
+ branch has one, and otherwise in the session.
233
+
234
+ **When it stops.** Before starting an agent, when `.claude/change-types.md`
235
+ is missing. The pull request stays a draft, and a comment on it shows the
236
+ file's shape for you to write.
237
+
229
238
  ## `factory-resolve-conflicts`
230
239
 
231
240
  **What it does.** Merges your main branch into a pull request that conflicts
@@ -252,12 +261,13 @@ Read-only.
252
261
  ### `factory-ui-reviewer`
253
262
 
254
263
  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.
264
+ `factory site compare`, reads the before and after pictures of the pages
265
+ that changed, drives the states the change is about, and judges them
266
+ against built-in rules, your `design-guide` when you wrote one, and what
267
+ your `checks` printed. It is listed under
268
+ [`plugins`](configuration.md#plugins) like a reviewer of your own, with
269
+ the `files` that should trigger it, and is written only to a repository
270
+ with `site` in its settings. Read-only, and slow.
261
271
 
262
272
  ### `factory-test-reviewer`
263
273
 
package/docs/updating.md CHANGED
@@ -1,8 +1,4 @@
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.
1
+ # Updating
6
2
 
7
3
  **When a new version is released, a pull request appears in your
8
4
  repository. You read it and merge it.** That is all you have to do.
@@ -17,7 +13,7 @@ repository. You read it and merge it.** That is all you have to do.
17
13
  runs `factory sync` on its branch and adds what it wrote as a second
18
14
  commit. Until it has, CI's `factory sync --check` fails.
19
15
  3. You read it and merge it. It never merges itself, whatever your
20
- `auto-merge` settings allow.
16
+ [`auto-merge`](configuration.md#auto-merge) settings allow.
21
17
  4. Everyone working on the repository, you included, pulls and runs
22
18
  `npm ci`, as after any dependency change.
23
19
 
package/docs/workflow.md CHANGED
@@ -102,18 +102,19 @@ That is why a ticket's history survives even if the board is rebuilt.
102
102
  When building one ticket first would break another, or mean redoing work,
103
103
  the second is recorded as blocked by the first, using the ticket system's
104
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.
105
+ starts at the poller's first pass after the blocker closes if the ticket is in Ready.
106
106
 
107
107
  Two tickets touching the same file is not a blocker. That is a merge
108
108
  conflict, and the session that owns the pull request resolves it.
109
109
 
110
110
  ## Sizing the work to the change
111
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.
112
+ A change under about 30 lines outside tests (30 by default,
113
+ [`rules.small-change-lines`](configuration.md#rules)), adding no new
114
+ component and no new state, is **small**. It skips the heavier steps: no
115
+ separate spec, no readiness read, and one test that reproduces the defect
116
+ or checks the change. The first message of the work says which path it is
117
+ taking, so you can overrule it before it starts.
117
118
 
118
119
  The number is `rules.small-change-lines` in your
119
120
  [settings](configuration.md), _[Planned](developing.md#what-is-built)_; until it is built, it is 30.
@@ -185,11 +186,11 @@ verdict.
185
186
 
186
187
  ## A change your users will see
187
188
 
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.
189
+ With [`specs: openspec`](configuration.md#specs), a change that adds or
190
+ alters behavior someone can see, and is not small, carries the `spec`
191
+ label. Its ticket holds a "Spec" section of plain "When this, then that"
192
+ lines. The build turns those lines into an OpenSpec change, builds to
193
+ them, and folds them into `openspec/specs/` in the same pull request, so
194
+ that folder always describes what the project does now.
194
195
 
195
196
  With `specs: none`, the ticket's acceptance criteria are the whole spec.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@davidbyoung/software-factory",
3
- "version": "0.1.2",
3
+ "version": "0.1.3",
4
4
  "description": "Refines, builds, and reviews tickets with Claude Code sessions, from a board to a merged pull request.",
5
5
  "license": "MIT",
6
6
  "repository": {
package/poller.Dockerfile CHANGED
@@ -1,21 +1,13 @@
1
- # The poller's image. It copies only the poller and the modules it imports:
2
- # the shared work-status rules, the GitHub ticket adapter with its `fetch`
3
- # transport, GitHub as the code host, and GitHub Actions as the runner, each
4
- # with the interface it fills. No npm install and no build, so
5
- # the repository's build variables are not needed here, and the `factory`
6
- # launcher is not used. A test fails when the poller imports a file not
7
- # copied below.
1
+ # The poller's image: one published version of the factory, installed from
2
+ # npm, and nothing else. The release workflow builds it with VERSION set to
3
+ # the version it has just published, and pushes it to GitHub's container
4
+ # registry. It runs outside any checkout, so the `factory` launcher runs
5
+ # the installed copy itself.
8
6
  FROM node:22-slim
7
+ ARG VERSION
8
+ LABEL org.opencontainers.image.source="https://github.com/davidbyoung/software-factory"
9
9
  WORKDIR /app
10
- COPY src/poller.mts src/poller.mts
11
- COPY src/lib/work-status.mts src/lib/work-status.mts
12
- COPY src/lib/gh.mts src/lib/gh.mts
13
- COPY src/tickets/types.mts src/tickets/types.mts
14
- COPY src/tickets/transport.mts src/tickets/transport.mts
15
- COPY src/tickets/github.mts src/tickets/github.mts
16
- COPY src/code-host/types.mts src/code-host/types.mts
17
- COPY src/code-host/github.mts src/code-host/github.mts
18
- COPY src/runner/types.mts src/runner/types.mts
19
- COPY src/runner/github-actions.mts src/runner/github-actions.mts
10
+ RUN npm install --omit=dev --no-audit --no-fund --no-save \
11
+ "@davidbyoung/software-factory@${VERSION}"
20
12
  USER node
21
- CMD ["node", "src/poller.mts"]
13
+ CMD ["node", "node_modules/@davidbyoung/software-factory/bin/factory.js", "poller"]