@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.
- package/README.md +8 -9
- package/dist/agent/claude-code.d.mts +3 -0
- package/dist/agent/claude-code.mjs +89 -0
- package/dist/agent/index.d.mts +2 -0
- package/dist/agent/index.mjs +5 -0
- package/dist/board.mjs +1 -1
- package/dist/cli.mjs +17 -2
- package/dist/code-host/github-setup.d.mts +5 -0
- package/dist/code-host/github-setup.mjs +133 -0
- package/dist/code-host/github.mjs +4 -0
- package/dist/code-host/index.d.mts +1 -1
- package/dist/code-host/index.mjs +2 -1
- package/dist/code-host/types.d.mts +2 -0
- package/dist/config.d.mts +26 -7
- package/dist/config.mjs +79 -26
- package/dist/doctor.d.mts +6 -14
- package/dist/doctor.mjs +52 -64
- package/dist/explain.d.mts +2 -0
- package/dist/explain.mjs +127 -0
- package/dist/init.d.mts +8 -12
- package/dist/init.mjs +179 -131
- package/dist/lib/has-command.d.mts +5 -0
- package/dist/lib/has-command.mjs +8 -0
- package/dist/lib/listed.d.mts +2 -0
- package/dist/lib/listed.mjs +4 -0
- package/dist/lib/work-status.d.mts +12 -2
- package/dist/lib/work-status.mjs +14 -3
- package/dist/parts.d.mts +18 -15
- package/dist/parts.mjs +15 -43
- package/dist/poller.d.mts +20 -3
- package/dist/poller.mjs +62 -15
- package/dist/remove.d.mts +11 -0
- package/dist/remove.mjs +156 -0
- package/dist/runner/github-actions.d.mts +1 -1
- package/dist/runner/github-actions.mjs +12 -0
- package/dist/runner/index.d.mts +1 -1
- package/dist/runner/index.mjs +2 -1
- package/dist/runner/setup.d.mts +2 -0
- package/dist/runner/setup.mjs +22 -0
- package/dist/runner/types.d.mts +3 -0
- package/dist/runner/types.mjs +0 -2
- package/dist/setup.d.mts +98 -0
- package/dist/setup.mjs +3 -0
- package/dist/status.d.mts +4 -4
- package/dist/status.mjs +8 -7
- package/dist/sync.d.mts +18 -0
- package/dist/sync.mjs +137 -7
- package/dist/tickets/github-setup.d.mts +2 -0
- package/dist/tickets/github-setup.mjs +50 -0
- package/dist/tickets/github.mjs +0 -2
- package/dist/tickets/index.mjs +2 -1
- package/dist/tickets/transport.mjs +1 -3
- package/dist/tickets/types.mjs +0 -2
- package/dist/tool-names.d.mts +11 -0
- package/dist/tool-names.mjs +20 -0
- package/dist/tools.d.mts +56 -0
- package/dist/tools.mjs +76 -0
- package/docs/builds.md +103 -51
- package/docs/cli.md +42 -42
- package/docs/configuration.md +34 -32
- package/docs/design.md +1 -1
- package/docs/developing.md +143 -68
- package/docs/existing-repo.md +20 -9
- package/docs/github/by-hand.md +321 -0
- package/docs/github/reference.md +65 -61
- package/docs/github/setup.md +83 -267
- package/docs/glossary.md +5 -4
- package/docs/limitations.md +12 -10
- package/docs/plugins.md +9 -14
- package/docs/quick-start.md +62 -105
- package/docs/removing.md +36 -16
- package/docs/skills.md +47 -37
- package/docs/updating.md +2 -6
- package/docs/workflow.md +13 -12
- package/package.json +1 -1
- package/poller.Dockerfile +10 -18
- package/rules.md +14 -12
- package/settings.schema.json +24 -0
- package/skills/factory-build/SKILL.md +1 -1
- package/skills/factory-trace/SKILL.md +79 -0
- package/workflows/factory-build.yml +5 -4
- package/workflows/factory-deps-auto-merge.yml +3 -2
- package/workflows/factory-poller.yml +46 -0
package/docs/quick-start.md
CHANGED
|
@@ -1,33 +1,25 @@
|
|
|
1
1
|
# Quick start
|
|
2
2
|
|
|
3
|
-
|
|
4
|
-
|
|
5
|
-
|
|
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).
|
|
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.
|
|
15
|
+
- Node 22.18 or later.
|
|
18
16
|
|
|
19
|
-
|
|
20
|
-
|
|
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.
|
|
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
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
|
|
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
|
|
83
|
-
|
|
52
|
+
file, such as `CLAUDE.md`, names. If it names none, add your test and lint
|
|
53
|
+
commands there now.
|
|
84
54
|
|
|
85
|
-
|
|
86
|
-
|
|
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 `
|
|
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
|
-
|
|
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
|
-
|
|
113
|
-
|
|
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`.
|
|
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
|
-
|
|
122
|
-
|
|
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
|
-
|
|
96
|
+
**It worked when** the ticket has a number. This page uses 12.
|
|
132
97
|
|
|
133
98
|
## 5. Refine it
|
|
134
99
|
|
|
135
|
-
In
|
|
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
|
|
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
|
-
|
|
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
|
-
|
|
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.
|
|
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
|
|
197
|
-
|
|
|
198
|
-
| A
|
|
199
|
-
| The session stops and says it needs you
|
|
200
|
-
| The session was closed or crashed partway
|
|
201
|
-
| You want to change what was decided
|
|
202
|
-
| CI fails on the pull request
|
|
203
|
-
| The session does not know the factory's skills
|
|
204
|
-
| Anything else
|
|
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
|
|
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
|
-
|
|
212
|
-
|
|
213
|
-
|
|
214
|
-
|
|
215
|
-
|
|
216
|
-
|
|
217
|
-
|
|
218
|
-
|
|
219
|
-
|
|
220
|
-
|
|
221
|
-
|
|
222
|
-
|
|
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`,
|
|
16
|
-
|
|
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
|
|
26
|
-
|
|
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
|
-
|
|
34
|
-
|
|
35
|
-
|
|
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
|
|
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
|
-
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
|
|
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
|
|
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` |
|
|
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
|
|
124
|
-
change
|
|
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
|
|
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`
|
|
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,
|
|
221
|
-
|
|
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
|
|
256
|
-
changed, drives the states the change is about, and judges them
|
|
257
|
-
rules, your `design-guide` when you wrote one, and what
|
|
258
|
-
|
|
259
|
-
|
|
260
|
-
|
|
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
|
|
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
|
|
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
|
|
113
|
-
|
|
114
|
-
|
|
115
|
-
|
|
116
|
-
|
|
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
|
|
189
|
-
see, and is not small, carries the `spec`
|
|
190
|
-
section of plain "When this, then that"
|
|
191
|
-
into an OpenSpec change, builds to
|
|
192
|
-
`openspec/specs/` in the same pull request, so
|
|
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
package/poller.Dockerfile
CHANGED
|
@@ -1,21 +1,13 @@
|
|
|
1
|
-
# The poller's image
|
|
2
|
-
#
|
|
3
|
-
#
|
|
4
|
-
#
|
|
5
|
-
# the
|
|
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
|
-
|
|
11
|
-
|
|
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", "
|
|
13
|
+
CMD ["node", "node_modules/@davidbyoung/software-factory/bin/factory.js", "poller"]
|