@davidbyoung/software-factory 0.1.2 → 0.1.4

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (120) hide show
  1. package/README.md +20 -20
  2. package/actions/factory-agent/action.yml +1 -1
  3. package/agents/factory-e2e-reviewer.md +102 -0
  4. package/agents/factory-test-reviewer.md +26 -64
  5. package/agents/factory-ticket-readiness.md +14 -6
  6. package/dist/agent/claude-code.d.mts +3 -0
  7. package/dist/agent/claude-code.mjs +89 -0
  8. package/dist/agent/index.d.mts +2 -0
  9. package/dist/agent/index.mjs +5 -0
  10. package/dist/board.mjs +1 -1
  11. package/dist/cli.mjs +46 -4
  12. package/dist/code-host/github-setup.d.mts +5 -0
  13. package/dist/code-host/github-setup.mjs +133 -0
  14. package/dist/code-host/github.mjs +4 -0
  15. package/dist/code-host/index.d.mts +1 -1
  16. package/dist/code-host/index.mjs +2 -1
  17. package/dist/code-host/types.d.mts +2 -0
  18. package/dist/commands.d.mts +16 -0
  19. package/dist/commands.mjs +129 -0
  20. package/dist/config.d.mts +87 -20
  21. package/dist/config.mjs +344 -89
  22. package/dist/deps.d.mts +7 -4
  23. package/dist/deps.mjs +20 -9
  24. package/dist/doctor.d.mts +9 -16
  25. package/dist/doctor.mjs +71 -68
  26. package/dist/explain.d.mts +4 -0
  27. package/dist/explain.mjs +174 -0
  28. package/dist/guard-commit.d.mts +7 -2
  29. package/dist/guard-commit.mjs +58 -21
  30. package/dist/init.d.mts +12 -14
  31. package/dist/init.mjs +194 -136
  32. package/dist/lib/default-branch.d.mts +35 -0
  33. package/dist/lib/default-branch.mjs +117 -0
  34. package/dist/lib/has-command.d.mts +5 -0
  35. package/dist/lib/has-command.mjs +8 -0
  36. package/dist/lib/listed.d.mts +2 -0
  37. package/dist/lib/listed.mjs +4 -0
  38. package/dist/lib/refined-check.d.mts +7 -0
  39. package/dist/lib/refined-check.mjs +76 -0
  40. package/dist/lib/work-status.d.mts +12 -2
  41. package/dist/lib/work-status.mjs +14 -3
  42. package/dist/parts.d.mts +18 -15
  43. package/dist/parts.mjs +15 -43
  44. package/dist/patch-coverage.d.mts +13 -0
  45. package/dist/patch-coverage.mjs +73 -0
  46. package/dist/poller.d.mts +20 -3
  47. package/dist/poller.mjs +62 -15
  48. package/dist/pr-watch.d.mts +3 -2
  49. package/dist/pr-watch.mjs +22 -5
  50. package/dist/pr.mjs +34 -2
  51. package/dist/remove.d.mts +11 -0
  52. package/dist/remove.mjs +156 -0
  53. package/dist/runner/github-actions.d.mts +1 -1
  54. package/dist/runner/github-actions.mjs +12 -0
  55. package/dist/runner/index.d.mts +1 -1
  56. package/dist/runner/index.mjs +2 -1
  57. package/dist/runner/setup.d.mts +2 -0
  58. package/dist/runner/setup.mjs +22 -0
  59. package/dist/runner/types.d.mts +3 -0
  60. package/dist/runner/types.mjs +0 -2
  61. package/dist/session-start.d.mts +23 -13
  62. package/dist/session-start.mjs +56 -44
  63. package/dist/setup.d.mts +98 -0
  64. package/dist/setup.mjs +3 -0
  65. package/dist/site/servers.d.mts +6 -2
  66. package/dist/site/servers.mjs +14 -9
  67. package/dist/site.mjs +2 -2
  68. package/dist/status.d.mts +4 -4
  69. package/dist/status.mjs +8 -7
  70. package/dist/sync.d.mts +26 -2
  71. package/dist/sync.mjs +177 -13
  72. package/dist/ticket.mjs +19 -1
  73. package/dist/tickets/github-setup.d.mts +2 -0
  74. package/dist/tickets/github-setup.mjs +50 -0
  75. package/dist/tickets/github.mjs +0 -2
  76. package/dist/tickets/index.mjs +2 -1
  77. package/dist/tickets/transport.mjs +1 -3
  78. package/dist/tickets/types.mjs +0 -2
  79. package/dist/tool-names.d.mts +11 -0
  80. package/dist/tool-names.mjs +20 -0
  81. package/dist/tools.d.mts +56 -0
  82. package/dist/tools.mjs +76 -0
  83. package/docs/builds.md +111 -59
  84. package/docs/cli.md +106 -69
  85. package/docs/configuration.md +489 -171
  86. package/docs/design.md +18 -5
  87. package/docs/developing.md +179 -73
  88. package/docs/existing-repo.md +25 -12
  89. package/docs/github/by-hand.md +334 -0
  90. package/docs/github/reference.md +76 -67
  91. package/docs/github/setup.md +105 -286
  92. package/docs/glossary.md +18 -7
  93. package/docs/limitations.md +39 -12
  94. package/docs/plugins.md +305 -56
  95. package/docs/quick-start.md +85 -100
  96. package/docs/removing.md +37 -17
  97. package/docs/skills.md +121 -62
  98. package/docs/updating.md +150 -9
  99. package/docs/workflow.md +23 -19
  100. package/package.json +1 -1
  101. package/poller.Dockerfile +10 -18
  102. package/review.md +20 -11
  103. package/rules.md +36 -30
  104. package/settings.schema.json +313 -69
  105. package/skills/factory-address-review/SKILL.md +50 -30
  106. package/skills/factory-build/SKILL.md +76 -23
  107. package/skills/factory-deps/SKILL.md +46 -21
  108. package/skills/factory-design/SKILL.md +17 -8
  109. package/skills/factory-diagnose/SKILL.md +22 -20
  110. package/skills/factory-mutate/SKILL.md +38 -24
  111. package/skills/factory-refine/SKILL.md +55 -31
  112. package/skills/factory-resolve-conflicts/SKILL.md +76 -34
  113. package/skills/factory-trace/SKILL.md +80 -0
  114. package/workflows/factory-build.yml +6 -5
  115. package/workflows/factory-conflicts.yml +8 -8
  116. package/workflows/factory-deps-auto-merge.yml +3 -2
  117. package/workflows/factory-deps.yml +1 -1
  118. package/workflows/factory-poller.yml +46 -0
  119. package/workflows/factory-review.yml +1 -1
  120. package/skills/factory-address-review/patch-coverage.py +0 -68
@@ -1,33 +1,26 @@
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, say how your code is checked, write one
6
+ ticket, and answer a question or two. It needs no board, no secrets, and
7
+ nothing to host.
7
8
 
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.
9
+ A word you do not know is in the [glossary](glossary.md).
11
10
 
12
11
  ## You need
13
12
 
14
13
  - A repository on a supported code host, cloned on your machine, with the
15
14
  code host's command-line tool signed in.
16
15
  - A supported coding agent, signed in.
17
- - Node 22.18 or later. Check with `node --version`.
16
+ - Node 22.18 or later.
18
17
 
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`.
18
+ [What you need](github/setup.md#what-you-need) names the supported tools
19
+ and how to check each. A repository with no `package.json` works too:
20
+ [read this first](existing-repo.md#a-repository-that-is-not-javascript).
25
21
 
26
22
  ## 1. Install
27
23
 
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
24
  Once on your machine, so you can type `factory`:
32
25
 
33
26
  ```bash
@@ -41,8 +34,7 @@ npm install --save-dev @davidbyoung/software-factory
41
34
  ```
42
35
 
43
36
  **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.
37
+ its commands.
46
38
 
47
39
  ## 2. Set it up
48
40
 
@@ -50,50 +42,47 @@ expected.
50
42
  factory init
51
43
  ```
52
44
 
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.
45
+ It shows what it found and asks which optional parts you want. For this
46
+ first ticket, uncheck every part. It then lists everything it will do, and
47
+ once you tell it to go ahead, writes your settings file,
48
+ `.claude/factory.yaml`, and the instructions and checks your coding agent
49
+ follows. It commits nothing. [What it changes](removing.md) lists every
50
+ file.
56
51
 
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.
52
+ **It worked when** the checks `init` prints last all show ✓, or `-` for a
53
+ part you left off. `factory doctor` runs them again at any time.
65
54
 
66
- **It worked when** the checks it prints last all show ✓. Run them again at
67
- any time with `factory doctor`.
55
+ **Then say how a change is checked.** `init` ends with a list headed "Left
56
+ to do", and one line of it comes before your first build:
68
57
 
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
58
+ ```text
59
+ Add the commands that check a change, under commands.gate in .claude/factory.yaml
79
60
  ```
80
61
 
81
- 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.
84
-
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:
62
+ A build runs these commands, in order, before it opens its pull request,
63
+ and cannot finish without them. Add
64
+ [`commands.gate`](configuration.md#commandsgate) to
65
+ `.claude/factory.yaml`, with your own test and lint commands in place of
66
+ these:
87
67
 
88
68
  ```yaml
89
- before-commit:
90
- - npm run lint
69
+ commands:
70
+ # What a build runs to check its change, in order.
71
+ gate:
72
+ - npm test
73
+ - npm run lint
91
74
  ```
92
75
 
76
+ A repository with no tests yet lists the checks it does have, such as a
77
+ formatter or a compile, and adds its tests to the gate when there are
78
+ some.
79
+
80
+ **It worked when** `factory gate` runs each command and ends without a
81
+ line that starts `gate failed on`.
82
+
93
83
  ## 3. Merge the setup
94
84
 
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:
85
+ Commit what `init` wrote on a branch and push it:
97
86
 
98
87
  ```bash
99
88
  git switch -c set-up-factory
@@ -102,24 +91,26 @@ git commit -m "Set up the software factory"
102
91
  git push -u origin set-up-factory
103
92
  ```
104
93
 
105
- Then bring your main branch up to date:
94
+ Open a pull request for the branch on your code host and merge it, as for
95
+ any change. Then bring your default branch up to date. Here it is called
96
+ `main`:
106
97
 
107
98
  ```bash
108
99
  git switch main
109
100
  git pull
110
101
  ```
111
102
 
112
- Your coding agent loads the factory from the files in your repository, so
113
- start a new session after this step.
103
+ Start a new session of your coding agent, which loads the factory from the
104
+ files now in your repository.
114
105
 
115
106
  **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.
107
+ `factory-refine` and `factory-build`.
118
108
 
119
109
  ## 4. Open a ticket
120
110
 
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.
111
+ Open a ticket in your ticket system: on GitHub, an issue in your
112
+ repository. Say three things: what you want, why, and how you will know it
113
+ is done. A few sentences is enough.
123
114
 
124
115
  ```text
125
116
  Title: Show the opening hours in the footer
@@ -128,17 +119,17 @@ The hours are only on the contact page, and people ask for them.
128
119
  Done when: every page's footer shows the same hours the contact page does.
129
120
  ```
130
121
 
131
- Note its number. This page uses 12.
122
+ **It worked when** the ticket has a number. This page uses 12.
132
123
 
133
124
  ## 5. Refine it
134
125
 
135
- In a session of your coding agent, in your repository, say:
126
+ In the session, say:
136
127
 
137
128
  ```text
138
129
  refine ticket 12
139
130
  ```
140
131
 
141
- The session reads the ticket and the code it touches. Then it asks you the
132
+ The session reads the ticket and the code it touches, then asks you the
142
133
  decisions that are yours, each as a choice with its recommendation first:
143
134
 
144
135
  ```text
@@ -148,8 +139,7 @@ Where should the hours come from?
148
139
  ```
149
140
 
150
141
  **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.
142
+ of exactly what "done" means, and the session says it is ready to build.
153
143
 
154
144
  ## 6. Build it
155
145
 
@@ -159,22 +149,14 @@ In the same session, or a new one:
159
149
  build ticket 12
160
150
  ```
161
151
 
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.
152
+ Telling a session to build a ticket is how you approve it. The session
153
+ makes a branch, writes a test and then the change, and opens a pull
154
+ request that closes the ticket. Expect minutes, not seconds.
155
+ [Workflow](workflow.md#from-a-ticket-to-a-merge) has each step.
175
156
 
176
157
  **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.
158
+ built, and says how it checked it. This page uses 15 for the pull
159
+ request's number.
178
160
 
179
161
  ## 7. Read it and merge
180
162
 
@@ -189,34 +171,37 @@ answer your comments:
189
171
  address the review on pull request 15
190
172
  ```
191
173
 
174
+ **It worked when** the pull request is merged and ticket 12 is closed.
192
175
  That is the whole loop: **ticket, refine, build, read, merge.**
193
176
 
194
177
  ## If something goes wrong
195
178
 
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 |
179
+ | What happened | What to do |
180
+ | ---------------------------------------------- | ------------------------------------------------------------------------------------------- |
181
+ | A test or a check fails during the build | Nothing. The session sees the output, fixes the cause, and tries again |
182
+ | 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 |
183
+ | The build stops on `commands.gate is not set` | Add your test and lint commands, as in step 2, then ask it to build ticket 12 again |
184
+ | The session was closed or crashed partway | Ask a new session to build ticket 12. It picks up the branch it made |
185
+ | You want to change what was decided | Ask a session to refine ticket 12 again, or edit the ticket |
186
+ | CI fails on the pull request | Ask a session to address the review on pull request 15. It reads the failure and fixes it |
187
+ | The session does not know the factory's skills | The setup is not merged, or the session started before it was. See step 3 |
188
+ | Anything else | Run `factory doctor`. It says what is wrong, and what to do about it |
205
189
 
206
190
  ## What to add next
207
191
 
208
- Everything above runs on your machine while you watch. Each part below is
192
+ Everything above runs on your machine while you watch. Each of these is
209
193
  optional, stands alone, and can come later.
210
194
 
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.
195
+ - **An automated review, a board, builds in the cloud, builds that start
196
+ from the board, and pull requests that merge themselves.** Run
197
+ `factory init` again and check the parts you want. It asks for a token
198
+ or two and sets everything else up.
199
+ [Setting up on GitHub](github/setup.md#run-factory-init) says what each
200
+ part gives you and what it asks.
201
+ - **A command before every commit a session makes,** such as your linter:
202
+ a few lines under
203
+ [`commands.before-commit`](configuration.md#commandsbefore-commit).
204
+ - **Your own reviewers,** so a change to your content or your design is
205
+ read by an expert agent: a few lines under
206
+ [`plugins`](configuration.md#plugins), which [Plug-ins](plugins.md)
207
+ 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,16 +44,38 @@ 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
 
57
76
  - **If builds are running,** let them finish or stop them first. Open
58
77
  tickets and pull requests stay exactly as they are.
59
- - **If you made the review's verdict a required check** on your main
78
+ - **If you made the review's verdict a required check** on your default
60
79
  branch, remove that requirement first, or every pull request waits on it
61
80
  forever.
62
81
  - **Deleting a label removes it from every ticket.** Keep the labels if
@@ -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.