@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.
- package/README.md +20 -20
- package/actions/factory-agent/action.yml +1 -1
- package/agents/factory-e2e-reviewer.md +102 -0
- package/agents/factory-test-reviewer.md +26 -64
- package/agents/factory-ticket-readiness.md +14 -6
- 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 +46 -4
- 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/commands.d.mts +16 -0
- package/dist/commands.mjs +129 -0
- package/dist/config.d.mts +87 -20
- package/dist/config.mjs +344 -89
- package/dist/deps.d.mts +7 -4
- package/dist/deps.mjs +20 -9
- package/dist/doctor.d.mts +9 -16
- package/dist/doctor.mjs +71 -68
- package/dist/explain.d.mts +4 -0
- package/dist/explain.mjs +174 -0
- package/dist/guard-commit.d.mts +7 -2
- package/dist/guard-commit.mjs +58 -21
- package/dist/init.d.mts +12 -14
- package/dist/init.mjs +194 -136
- package/dist/lib/default-branch.d.mts +35 -0
- package/dist/lib/default-branch.mjs +117 -0
- 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/refined-check.d.mts +7 -0
- package/dist/lib/refined-check.mjs +76 -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/patch-coverage.d.mts +13 -0
- package/dist/patch-coverage.mjs +73 -0
- package/dist/poller.d.mts +20 -3
- package/dist/poller.mjs +62 -15
- package/dist/pr-watch.d.mts +3 -2
- package/dist/pr-watch.mjs +22 -5
- package/dist/pr.mjs +34 -2
- 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/session-start.d.mts +23 -13
- package/dist/session-start.mjs +56 -44
- package/dist/setup.d.mts +98 -0
- package/dist/setup.mjs +3 -0
- package/dist/site/servers.d.mts +6 -2
- package/dist/site/servers.mjs +14 -9
- package/dist/site.mjs +2 -2
- package/dist/status.d.mts +4 -4
- package/dist/status.mjs +8 -7
- package/dist/sync.d.mts +26 -2
- package/dist/sync.mjs +177 -13
- package/dist/ticket.mjs +19 -1
- 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 +111 -59
- package/docs/cli.md +106 -69
- package/docs/configuration.md +489 -171
- package/docs/design.md +18 -5
- package/docs/developing.md +179 -73
- package/docs/existing-repo.md +25 -12
- package/docs/github/by-hand.md +334 -0
- package/docs/github/reference.md +76 -67
- package/docs/github/setup.md +105 -286
- package/docs/glossary.md +18 -7
- package/docs/limitations.md +39 -12
- package/docs/plugins.md +305 -56
- package/docs/quick-start.md +85 -100
- package/docs/removing.md +37 -17
- package/docs/skills.md +121 -62
- package/docs/updating.md +150 -9
- package/docs/workflow.md +23 -19
- package/package.json +1 -1
- package/poller.Dockerfile +10 -18
- package/review.md +20 -11
- package/rules.md +36 -30
- package/settings.schema.json +313 -69
- package/skills/factory-address-review/SKILL.md +50 -30
- package/skills/factory-build/SKILL.md +76 -23
- package/skills/factory-deps/SKILL.md +46 -21
- package/skills/factory-design/SKILL.md +17 -8
- package/skills/factory-diagnose/SKILL.md +22 -20
- package/skills/factory-mutate/SKILL.md +38 -24
- package/skills/factory-refine/SKILL.md +55 -31
- package/skills/factory-resolve-conflicts/SKILL.md +76 -34
- package/skills/factory-trace/SKILL.md +80 -0
- package/workflows/factory-build.yml +6 -5
- package/workflows/factory-conflicts.yml +8 -8
- package/workflows/factory-deps-auto-merge.yml +3 -2
- package/workflows/factory-deps.yml +1 -1
- package/workflows/factory-poller.yml +46 -0
- package/workflows/factory-review.yml +1 -1
- package/skills/factory-address-review/patch-coverage.py +0 -68
package/docs/github/setup.md
CHANGED
|
@@ -1,9 +1,10 @@
|
|
|
1
1
|
# Setting up on GitHub, with Claude Code
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
For someone setting the factory up with GitHub as the code host, GitHub
|
|
4
4
|
Issues for tickets, a GitHub Project for the board, GitHub Actions for
|
|
5
|
-
builds in the cloud, and Claude Code as the coding agent. One command
|
|
6
|
-
|
|
5
|
+
builds in the cloud, and Claude Code as the coding agent. One command sets
|
|
6
|
+
up the parts you choose. This page says what it asks you, and the little
|
|
7
|
+
it leaves for you to do.
|
|
7
8
|
|
|
8
9
|
## What you need
|
|
9
10
|
|
|
@@ -14,299 +15,117 @@ all of it; the rest of the page is the same setup by hand.
|
|
|
14
15
|
| Claude Code, signed in | `claude --version` | [Install it](https://claude.com/claude-code), run `claude`, and sign in |
|
|
15
16
|
| Node 22.18 or later | `node --version` | [nodejs.org](https://nodejs.org) |
|
|
16
17
|
|
|
17
|
-
##
|
|
18
|
+
## Run `factory init`
|
|
18
19
|
|
|
19
|
-
In your repository, with the package
|
|
20
|
+
In your repository, with the package
|
|
21
|
+
[installed](../quick-start.md#1-install):
|
|
20
22
|
|
|
21
23
|
```bash
|
|
22
24
|
factory init
|
|
23
25
|
```
|
|
24
26
|
|
|
25
|
-
It
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
and
|
|
31
|
-
|
|
32
|
-
|
|
27
|
+
It shows what it found, then asks which parts you want. Each is optional
|
|
28
|
+
and stands alone:
|
|
29
|
+
|
|
30
|
+
| Part | What you get |
|
|
31
|
+
| ----------------------------------------------- | ------------------------------------------------------------------------------ |
|
|
32
|
+
| An automated review of every pull request | Claude reads each pull request once it is ready, comments, and gives a verdict |
|
|
33
|
+
| A board | A GitHub Project showing each ticket's state, its session, and its cost |
|
|
34
|
+
| Builds in the cloud | A ticket builds in GitHub Actions, with no session open on your machine |
|
|
35
|
+
| Builds that start when you move a card to Ready | Moving a ticket's card to Ready on the board builds it |
|
|
36
|
+
| Pull requests that merge themselves | A pull request that touches only files you listed merges once its checks pass |
|
|
37
|
+
| Signed commits from cloud builds | A build's commits show as "Verified" |
|
|
38
|
+
|
|
39
|
+
On a first run the first three start checked. With none checked, you get
|
|
40
|
+
the basics: refining and building tickets in a Claude Code session on your
|
|
41
|
+
machine, which is all the [quick start](../quick-start.md) needs.
|
|
42
|
+
|
|
43
|
+
It then asks only what your parts need:
|
|
44
|
+
|
|
45
|
+
| It asks | For | What you do |
|
|
46
|
+
| ------------------------------------- | --------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------- |
|
|
47
|
+
| Which board | A board | Choose a new one, made with the factory's columns, or a Project you already have |
|
|
48
|
+
| Which files may merge without you | Pull requests that merge themselves | Type their patterns, such as `docs/**`. Start with a short list |
|
|
49
|
+
| Where the poller runs | Builds that start from the board | Choose a schedule on GitHub Actions or a server you host. [Builds in the cloud](../builds.md) compares them |
|
|
50
|
+
| The token `claude setup-token` prints | The review, and builds in the cloud | It runs the command for you. Follow what it says, then paste the token it prints |
|
|
51
|
+
| A GitHub access token | A board, builds in the cloud, and pull requests that merge themselves | It opens GitHub's page with the right scopes checked. Choose an expiry, generate the token, and paste it |
|
|
52
|
+
|
|
53
|
+
A token is typed into a masked prompt and goes straight to your
|
|
54
|
+
repository's secrets on GitHub. It is never printed or written to a file.
|
|
55
|
+
Leave a prompt empty to skip it, and run `init` again when you have the
|
|
56
|
+
token.
|
|
57
|
+
|
|
58
|
+
Before it changes anything, it lists everything it will do and asks "Go
|
|
59
|
+
ahead?". Then it does the rest itself: it writes the settings and the
|
|
60
|
+
factory's files, gives the board its columns and fields, stores each
|
|
61
|
+
secret, makes the signing key, allows auto-merge on the repository, and
|
|
62
|
+
requires the review's verdict before a merge to your default branch. It
|
|
63
|
+
commits nothing. [What it changes](../removing.md) lists every file.
|
|
64
|
+
|
|
65
|
+
**It worked when** the checks it prints last all show ✓, or `-` for a part
|
|
66
|
+
you left off.
|
|
67
|
+
|
|
68
|
+
## What is left for you
|
|
69
|
+
|
|
70
|
+
`init` ends with this list, under "Left to do":
|
|
71
|
+
|
|
72
|
+
| If you chose | Do this |
|
|
73
|
+
| -------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
|
|
74
|
+
| Anything, while your settings name no gate | Add the commands that check a change, such as your tests and linter, under [`commands.gate`](../configuration.md#commandsgate). A build cannot finish without them |
|
|
75
|
+
| Anything | Commit what it wrote on a branch, open a pull request, and merge it, as in [step 3 of the quick start](../quick-start.md#3-merge-the-setup) |
|
|
76
|
+
| The automated review | Install the Claude GitHub App on the repository, from <https://github.com/apps/claude>. The review posts its comments through it |
|
|
77
|
+
| Builds from the board, on a server you host | Run the poller's image with the four values `init` prints. [Hosting the poller](../builds.md#hosting-the-poller-own-server) has the steps |
|
|
78
|
+
| Signed commits, and it could not add the key | Add the public key it prints to the GitHub account that made the access token you pasted: Settings, "SSH and GPG keys", "New SSH key", key type "Signing Key" |
|
|
79
|
+
|
|
80
|
+
## Optional: tune it
|
|
81
|
+
|
|
82
|
+
Each is a few lines in `.claude/factory.yaml`, merged like any change.
|
|
83
|
+
|
|
84
|
+
- **Let the review run your tests.** `init` writes
|
|
85
|
+
[`ci-review`](../configuration.md#ci-review) with no commands, so the
|
|
86
|
+
reviewer reads the pull request and runs nothing of yours. To let it
|
|
87
|
+
confirm a finding by running something, list each command:
|
|
88
|
+
|
|
89
|
+
```yaml
|
|
90
|
+
ci-review:
|
|
91
|
+
commands:
|
|
92
|
+
- npm test
|
|
93
|
+
- npx tsc --noEmit
|
|
94
|
+
```
|
|
95
|
+
|
|
96
|
+
- **Run a command before every commit a session makes,** such as your
|
|
97
|
+
linter, under
|
|
98
|
+
[`commands.before-commit`](../configuration.md#commandsbefore-commit):
|
|
99
|
+
|
|
100
|
+
```yaml
|
|
101
|
+
commands:
|
|
102
|
+
before-commit:
|
|
103
|
+
- npm run lint
|
|
104
|
+
```
|
|
105
|
+
|
|
106
|
+
- **Tell the reviewer what your `CLAUDE.md` does not say** about your
|
|
107
|
+
project, in a file you write, `.github/review-notes.md`. The reviewer
|
|
108
|
+
reads it when it exists.
|
|
109
|
+
|
|
110
|
+
[Configuration](../configuration.md) has every setting.
|
|
111
|
+
|
|
112
|
+
## Changing it later
|
|
113
|
+
|
|
114
|
+
Run `factory init` again to turn a part on or off. It starts from what you
|
|
33
115
|
have, and does not ask again for a secret that is already set.
|
|
34
116
|
|
|
35
|
-
A token is typed into a masked prompt and goes straight to GitHub; it is
|
|
36
|
-
never printed or written to a file.
|
|
37
|
-
|
|
38
|
-
## Setting it up by hand
|
|
39
|
-
|
|
40
|
-
For anyone who cannot run `init`, or who wants to see what it does. Do
|
|
41
|
-
[the basics](#the-basics), then only the parts you want, in the order they
|
|
42
|
-
appear.
|
|
43
|
-
|
|
44
|
-
### Choose what you want
|
|
45
|
-
|
|
46
|
-
The basics are all the [quick start](../quick-start.md) needs. Everything
|
|
47
|
-
else is optional, and each part stands alone.
|
|
48
|
-
|
|
49
|
-
| Part | What you get | What it takes |
|
|
50
|
-
| --------------------------------------------------------------------------- | ------------------------------------------------------------------------------- | ------------------------------------------------------------------ |
|
|
51
|
-
| [The basics](#the-basics) | Refining and building tickets in a Claude Code session on your machine | A settings file and one command |
|
|
52
|
-
| [The automated review](#the-automated-review) | Claude reads every pull request once it is ready, comments, and gives a verdict | The Claude GitHub App, a workflow file, and your Claude token |
|
|
53
|
-
| [A board](#a-board) | A GitHub Project showing each ticket's state, its session, and its cost | A Project, one setting, and a GitHub token |
|
|
54
|
-
| [Builds in the cloud](#builds-in-the-cloud) | A ticket builds in GitHub Actions, with no session open on your machine | Your Claude token and a GitHub token |
|
|
55
|
-
| [Pull requests that merge themselves](#pull-requests-that-merge-themselves) | A pull request that touches only files you listed merges once its checks pass | A list of files, one repository setting, and a second GitHub token |
|
|
56
|
-
| [Signed commits from cloud builds](#signed-commits-from-cloud-builds) | A build's commits show as "Verified" | A signing key |
|
|
57
|
-
|
|
58
|
-
Every part's secrets are gathered in [Secrets](#secrets), so you can make
|
|
59
|
-
them all at once.
|
|
60
|
-
|
|
61
|
-
### The basics
|
|
62
|
-
|
|
63
|
-
If you followed the quick start, this is done.
|
|
64
|
-
|
|
65
|
-
1. Write `.claude/factory.yaml`, with your repository's owner and name:
|
|
66
|
-
|
|
67
|
-
```yaml
|
|
68
|
-
version: 1
|
|
69
|
-
repository: your-name/your-repo
|
|
70
|
-
```
|
|
71
|
-
|
|
72
|
-
2. Write the factory's files:
|
|
73
|
-
|
|
74
|
-
```bash
|
|
75
|
-
factory sync
|
|
76
|
-
```
|
|
77
|
-
|
|
78
|
-
It writes the skills, agents, and rules Claude Code loads, under
|
|
79
|
-
`.claude/`; adds hook entries to `.claude/settings.json`; adds one line
|
|
80
|
-
to `CLAUDE.md`; and writes the workflows under `.github/workflows/`.
|
|
81
|
-
[What lives where](reference.md) names each.
|
|
82
|
-
|
|
83
|
-
3. Say in your `CLAUDE.md` how to check a change, such as the commands for
|
|
84
|
-
your tests and linter. A build runs them.
|
|
85
|
-
4. Optionally, list commands to run before every commit a session makes:
|
|
86
|
-
|
|
87
|
-
```yaml
|
|
88
|
-
before-commit:
|
|
89
|
-
- npm run lint
|
|
90
|
-
```
|
|
91
|
-
|
|
92
|
-
5. Check, commit, and merge:
|
|
93
|
-
|
|
94
|
-
```bash
|
|
95
|
-
factory sync --check
|
|
96
|
-
factory config check
|
|
97
|
-
git switch -c set-up-factory && git add -A
|
|
98
|
-
git commit -m "Set up the software factory"
|
|
99
|
-
git push -u origin set-up-factory
|
|
100
|
-
gh pr create --fill
|
|
101
|
-
```
|
|
102
|
-
|
|
103
|
-
Merge the pull request on GitHub, then `git switch main && git pull`,
|
|
104
|
-
and start a new Claude Code session.
|
|
105
|
-
|
|
106
|
-
**It worked when** typing `/factory` in the new session offers
|
|
107
|
-
`/factory-refine` and `/factory-build`.
|
|
108
|
-
|
|
109
|
-
Every part below is turned on the same way: add its settings to
|
|
110
|
-
`.claude/factory.yaml`, run `factory sync`, do the steps
|
|
111
|
-
the part lists, and merge what `sync` wrote.
|
|
112
|
-
|
|
113
|
-
### The automated review
|
|
114
|
-
|
|
115
|
-
Claude reads every pull request once it is marked ready, comments on what
|
|
116
|
-
it finds, and posts a verdict. The session that built the pull request
|
|
117
|
-
answers each comment, fixing it or rejecting it with evidence.
|
|
118
|
-
|
|
119
|
-
It is on while `.claude/factory.yaml` has
|
|
120
|
-
[`ci-review`](../configuration.md#ci-review), which `init` writes when you
|
|
121
|
-
choose it. Three files have similar names, and `sync` writes all three:
|
|
122
|
-
|
|
123
|
-
| File | What it is |
|
|
124
|
-
| ---------------------------------------------- | ---------------------------------------------------------- |
|
|
125
|
-
| `.github/workflows/factory-claude-review.yml` | The workflow that runs the review |
|
|
126
|
-
| `.github/factory-review.md` | The review's instructions |
|
|
127
|
-
| `.github/workflows/factory-review-verdict.yml` | Turns each review's summary into a "Review verdict" status |
|
|
128
|
-
|
|
129
|
-
1. **Install the Claude GitHub App** on the repository, from
|
|
130
|
-
<https://github.com/apps/claude>. The review posts its comments through
|
|
131
|
-
it. Or run `/install-github-app` in Claude Code, which installs the app
|
|
132
|
-
and also stores the Claude token for you.
|
|
133
|
-
2. **Store your Claude token** as `CLAUDE_CODE_OAUTH_TOKEN`
|
|
134
|
-
([Secrets](#secrets)), unless step 1 did.
|
|
135
|
-
3. **Write `ci-review` in `.claude/factory.yaml`,** with the commands the
|
|
136
|
-
reviewer may run to confirm a finding, such as your tests, and run
|
|
137
|
-
`factory sync`. The workflow installs your project with
|
|
138
|
-
`npm ci`, and chooses the model from `FACTORY_BUILD_MODEL`
|
|
139
|
-
([Variables](reference.md#workflows)) when it is set.
|
|
140
|
-
4. **Optionally, write `.github/review-notes.md`:** what a reviewer must
|
|
141
|
-
know about your project that your `CLAUDE.md` does not say. The
|
|
142
|
-
reviewer reads it when it exists.
|
|
143
|
-
5. **To make the verdict count,** add "Review verdict" to the required
|
|
144
|
-
status checks of your default branch: Settings, then Rules or Branches.
|
|
145
|
-
Until you do, it is information only.
|
|
146
|
-
|
|
147
|
-
### A board
|
|
148
|
-
|
|
149
|
-
A GitHub Project that shows each ticket's state as a column, which session
|
|
150
|
-
has it, and what it has cost. [Workflow](../workflow.md#the-board) says
|
|
151
|
-
what each column means.
|
|
152
|
-
|
|
153
|
-
1. **Create a Project** under the account or the organization that owns the
|
|
154
|
-
repository: its Projects tab, "New project", Board layout. Link it to
|
|
155
|
-
the repository from the Project's menu, so it shows on the repository's
|
|
156
|
-
Projects tab. Its number is the last part of its address.
|
|
157
|
-
2. **Give it the factory's columns:** Backlog, In refinement, Ready, In
|
|
158
|
-
progress, In review, and Done, in its Status field. A new Project starts
|
|
159
|
-
with Todo, In Progress, and Done. To keep columns of your own, map them
|
|
160
|
-
under [`tickets.columns`](../configuration.md#ticketscolumns) instead.
|
|
161
|
-
3. **Give it the three fields the sync writes:** Session, a Text field;
|
|
162
|
-
Runs in, a single select with the options Local and Actions; and Cost, a
|
|
163
|
-
Number. A field the sync does not find, it skips.
|
|
164
|
-
4. **Point the settings at it:**
|
|
165
|
-
|
|
166
|
-
```yaml
|
|
167
|
-
tickets:
|
|
168
|
-
board: 7
|
|
169
|
-
```
|
|
170
|
-
|
|
171
|
-
Then `factory board check` shows how it reads your
|
|
172
|
-
columns.
|
|
173
|
-
|
|
174
|
-
5. **Store a GitHub token** as `FACTORY_BOARD_TOKEN` ([Secrets](#secrets)).
|
|
175
|
-
6. **Run `factory sync`.** It writes the board-sync
|
|
176
|
-
workflow, the only thing that writes to the board. It never creates,
|
|
177
|
-
renames, or removes a column or field.
|
|
178
|
-
|
|
179
|
-
### Builds in the cloud
|
|
180
|
-
|
|
181
|
-
`factory build 12` builds ticket 12 in GitHub Actions and
|
|
182
|
-
prints the run's link, with no session open on your machine.
|
|
183
|
-
|
|
184
|
-
`sync` already wrote the workflows these use, and each does nothing until
|
|
185
|
-
it has work and its secrets:
|
|
186
|
-
|
|
187
|
-
| Workflow | Runs a Claude Code session that |
|
|
188
|
-
| ----------------------- | ------------------------------------------------------------------------------------ |
|
|
189
|
-
| `factory-build.yml` | builds a ticket |
|
|
190
|
-
| `factory-review.yml` | answers a review you submit on a pull request |
|
|
191
|
-
| `factory-conflicts.yml` | resolves a conflict between a pull request and your main branch |
|
|
192
|
-
| `factory-deps.yml` | moves Dependabot's pull requests along, written once `.github/dependabot.yml` exists |
|
|
193
|
-
|
|
194
|
-
1. **Store your Claude token** as `CLAUDE_CODE_OAUTH_TOKEN`.
|
|
195
|
-
2. **Store a GitHub token that can push**, as `FACTORY_BUILD_TOKEN`. With
|
|
196
|
-
a board, `FACTORY_BOARD_TOKEN` stands in for it when it has the
|
|
197
|
-
`workflow` scope, so one token does both ([Secrets](#secrets)).
|
|
198
|
-
|
|
199
|
-
A build may run for 230 minutes, which
|
|
200
|
-
[`session-minutes`](../configuration.md#session-minutes) changes; GitHub
|
|
201
|
-
stops any job at six hours.
|
|
202
|
-
|
|
203
|
-
#### Starting builds from the board
|
|
204
|
-
|
|
205
|
-
To have a ticket build when you move its card to Ready, set
|
|
206
|
-
`builds.trigger: own-server` and run the poller, a small program that
|
|
207
|
-
watches the board and starts each build. [Builds in the cloud](../builds.md)
|
|
208
|
-
explains how to host it and what it costs.
|
|
209
|
-
|
|
210
|
-
### Pull requests that merge themselves
|
|
211
|
-
|
|
212
|
-
A pull request that touches only files you listed as safe merges once
|
|
213
|
-
every check passes. Everything else still waits for you. Turn this on
|
|
214
|
-
last: it is only as safe as your tests and the review. Start with a short
|
|
215
|
-
list, such as documentation.
|
|
216
|
-
|
|
217
|
-
1. **List the files** under `auto-merge.allow`, with exceptions under
|
|
218
|
-
`deny`. [Configuration](../configuration.md#auto-merge) explains the
|
|
219
|
-
rules. `sync` then writes the merge-policy workflow, which labels each
|
|
220
|
-
pull request `merge: automatic` or `merge: manual` and says why.
|
|
221
|
-
2. **Allow auto-merge** on the repository: Settings, General, "Allow
|
|
222
|
-
auto-merge".
|
|
223
|
-
3. **Store a GitHub token** as `FACTORY_AUTOMERGE_TOKEN` ([Secrets](#secrets)).
|
|
224
|
-
|
|
225
|
-
### Signed commits from cloud builds
|
|
226
|
-
|
|
227
|
-
Without a key, a build's commits are unsigned.
|
|
228
|
-
|
|
229
|
-
1. Make a key for this and nothing else, with no passphrase:
|
|
230
|
-
|
|
231
|
-
```bash
|
|
232
|
-
ssh-keygen -t ed25519 -N "" -C "factory builds" -f factory-signing-key
|
|
233
|
-
```
|
|
234
|
-
|
|
235
|
-
2. Add `factory-signing-key.pub` to the GitHub account whose token the
|
|
236
|
-
builds use: Settings, "SSH and GPG keys", "New SSH key", key type
|
|
237
|
-
"Signing Key".
|
|
238
|
-
3. Store the private half, then delete both files:
|
|
239
|
-
|
|
240
|
-
```bash
|
|
241
|
-
gh secret set FACTORY_SIGNING_KEY < factory-signing-key
|
|
242
|
-
rm factory-signing-key factory-signing-key.pub
|
|
243
|
-
```
|
|
244
|
-
|
|
245
|
-
Anything that can run a workflow in the repository can read the key, as
|
|
246
|
-
it can the build token. Removing the public key from the account ends its
|
|
247
|
-
use.
|
|
248
|
-
|
|
249
|
-
### Secrets
|
|
250
|
-
|
|
251
|
-
Everything here is stored on the repository with `gh secret set NAME`,
|
|
252
|
-
which asks for the value. Nothing the factory runs on your machine needs
|
|
253
|
-
one; each is for something that runs in GitHub Actions.
|
|
254
|
-
|
|
255
|
-
| Secret | Needed for | Make it |
|
|
256
|
-
| ------------------------- | -------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
257
|
-
| `CLAUDE_CODE_OAUTH_TOKEN` | The automated review, and builds in the cloud | `claude setup-token`, on your machine. It bills your Claude subscription |
|
|
258
|
-
| `FACTORY_BOARD_TOKEN` | A board. Also builds in the cloud, when `FACTORY_BUILD_TOKEN` is not set | [A classic token](https://github.com/settings/tokens/new?scopes=repo,project,workflow&description=factory%20board) with `repo`, `project`, and `workflow` |
|
|
259
|
-
| `FACTORY_BUILD_TOKEN` | Builds in the cloud. Optional with a board token; used instead of it when both are set | [A classic token](https://github.com/settings/tokens/new?scopes=repo,workflow&description=factory%20builds) with `repo` and `workflow` |
|
|
260
|
-
| `FACTORY_AUTOMERGE_TOKEN` | Pull requests that merge themselves | [A classic token](https://github.com/settings/tokens/new?scopes=repo&description=factory%20auto-merge) with `repo` |
|
|
261
|
-
| `FACTORY_SIGNING_KEY` | Signed commits from cloud builds | [The steps above](#signed-commits-from-cloud-builds) |
|
|
262
|
-
|
|
263
|
-
Each token link opens GitHub's page with the scopes checked; choose an
|
|
264
|
-
expiry date and generate it. The account that makes a token is the one
|
|
265
|
-
its work is done as, and must be able to write the repository, and the
|
|
266
|
-
Project for the board token.
|
|
267
|
-
|
|
268
|
-
**One GitHub token is enough for everything.** Make one classic token with
|
|
269
|
-
`repo` and `workflow`, and `project` when you have a board, and store it
|
|
270
|
-
under each name your parts read; `init` does the same. Any workflow a pull
|
|
271
|
-
request from the repository adds can read every secret, so separate tokens
|
|
272
|
-
protect little.
|
|
273
|
-
|
|
274
|
-
Builds and auto-merge also take a fine-grained token instead: read and
|
|
275
|
-
write access to Contents, Pull requests, Issues, and Workflows for builds,
|
|
276
|
-
and to Contents and Pull requests for auto-merge. The board token must be
|
|
277
|
-
classic.
|
|
278
|
-
|
|
279
|
-
To set the ones you need in one go, paste each value when asked:
|
|
280
|
-
|
|
281
117
|
```bash
|
|
282
|
-
|
|
283
|
-
gh secret set CLAUDE_CODE_OAUTH_TOKEN
|
|
284
|
-
gh secret set FACTORY_BOARD_TOKEN
|
|
285
|
-
gh secret set FACTORY_AUTOMERGE_TOKEN
|
|
118
|
+
factory doctor
|
|
286
119
|
```
|
|
287
120
|
|
|
288
|
-
|
|
289
|
-
|
|
290
|
-
|
|
291
|
-
|
|
292
|
-
|
|
293
|
-
the [Claude Console](https://platform.claude.com) as `ANTHROPIC_API_KEY`.
|
|
294
|
-
A workflow uses it when `CLAUDE_CODE_OAUTH_TOKEN` is not set.
|
|
295
|
-
- **The model a cloud session uses:** `gh variable set FACTORY_BUILD_MODEL`.
|
|
296
|
-
This is a variable, not a secret.
|
|
297
|
-
|
|
298
|
-
Everything the factory owns starts with `FACTORY_`. The other two keep the
|
|
299
|
-
names Claude's GitHub Action gives them, since your other workflows may
|
|
300
|
-
use them too.
|
|
121
|
+
runs the checks again at any time: the settings, the factory's files, the
|
|
122
|
+
installed version, who the GitHub CLI is signed in as, that each secret
|
|
123
|
+
your parts read is set, and the board's columns. GitHub never lets a
|
|
124
|
+
secret be read back, so a wrong one shows when the first run that needs it
|
|
125
|
+
fails, naming it.
|
|
301
126
|
|
|
302
|
-
|
|
303
|
-
|
|
304
|
-
```bash
|
|
305
|
-
factory doctor
|
|
306
|
-
```
|
|
127
|
+
## Doing it by hand
|
|
307
128
|
|
|
308
|
-
|
|
309
|
-
|
|
310
|
-
|
|
311
|
-
back, so a secret is checked only for being set: a wrong one shows when
|
|
312
|
-
the first run that needs it fails, naming it.
|
|
129
|
+
[Setting up on GitHub by hand](by-hand.md) has every step `init` takes,
|
|
130
|
+
and every secret with the scopes it needs, for anyone who cannot run
|
|
131
|
+
`init` or wants to see what it does.
|
package/docs/glossary.md
CHANGED
|
@@ -9,17 +9,17 @@ is today.
|
|
|
9
9
|
|
|
10
10
|
**Code host.** Where your repository lives, with its pull requests, their
|
|
11
11
|
reviews, the checks on each commit, and the secrets your CI reads. Today:
|
|
12
|
-
GitHub. `code-host.type` names it.
|
|
12
|
+
GitHub. [`code-host.type`](configuration.md#code-host) names it.
|
|
13
13
|
|
|
14
14
|
**Ticket system.** Where your tickets live. Today: GitHub Issues.
|
|
15
|
-
`tickets.type` names it.
|
|
15
|
+
[`tickets.type`](configuration.md#tickets) names it.
|
|
16
16
|
|
|
17
17
|
**Board.** A view of every ticket's state, one column per state, which the
|
|
18
18
|
factory keeps up to date. Optional. Today: a GitHub Project.
|
|
19
19
|
|
|
20
20
|
**Cloud runner.** Where work runs with no one at a keyboard: cloud builds,
|
|
21
21
|
the automated review, the board sync, and the factory's other CI jobs.
|
|
22
|
-
Today: GitHub Actions. `builds.runner` names it.
|
|
22
|
+
Today: GitHub Actions. [`builds.runner`](configuration.md#builds) names it.
|
|
23
23
|
|
|
24
24
|
**Coding agent.** The AI tool that runs sessions: it reads your code,
|
|
25
25
|
follows the factory's skills, and writes the change. Today: Claude Code.
|
|
@@ -30,7 +30,7 @@ follows the factory's skills, and writes the change. Today: Claude Code.
|
|
|
30
30
|
written so each item can be checked. Refining a ticket produces it.
|
|
31
31
|
|
|
32
32
|
**Agent (reviewer).** A separate reviewer that a session launches to read
|
|
33
|
-
something and report back. It changes nothing. The factory brings
|
|
33
|
+
something and report back. It changes nothing. The factory brings four,
|
|
34
34
|
and you can add your own.
|
|
35
35
|
|
|
36
36
|
**Approver.** A person whose comments a session treats as instructions,
|
|
@@ -57,6 +57,10 @@ your board.
|
|
|
57
57
|
written into your repository by `factory sync`. You do not
|
|
58
58
|
edit them.
|
|
59
59
|
|
|
60
|
+
**Default branch.** The branch your pull requests merge into, often
|
|
61
|
+
called `main`. The factory reads its name from your checkout or your code
|
|
62
|
+
host, and assumes none.
|
|
63
|
+
|
|
60
64
|
**Dependency bot.** A tool that opens pull requests when a dependency has
|
|
61
65
|
a new version.
|
|
62
66
|
|
|
@@ -64,8 +68,9 @@ a new version.
|
|
|
64
68
|
small problems sessions noticed while doing other work.
|
|
65
69
|
|
|
66
70
|
**Gate.** The commands that must pass before a session calls a task done,
|
|
67
|
-
such as your tests and linter. Yours,
|
|
68
|
-
|
|
71
|
+
such as your tests and linter. Yours, listed under
|
|
72
|
+
[`commands.gate`](configuration.md#commandsgate) in your settings and run
|
|
73
|
+
by `factory gate`. A build cannot finish without one.
|
|
69
74
|
|
|
70
75
|
**Hook.** A command the coding agent runs at a set moment in a session,
|
|
71
76
|
such as before a shell command. The factory uses hooks to block risky
|
|
@@ -83,7 +88,8 @@ does, in the repository. Optional.
|
|
|
83
88
|
set moment.
|
|
84
89
|
|
|
85
90
|
**Poller.** A small program that watches your board and starts a cloud
|
|
86
|
-
build for each ticket moved to Ready
|
|
91
|
+
build for each ticket moved to Ready, on a server you host or on a
|
|
92
|
+
schedule in the cloud.
|
|
87
93
|
|
|
88
94
|
**Refine.** To turn a ticket into acceptance criteria, settling the
|
|
89
95
|
decisions with you along the way.
|
|
@@ -98,6 +104,11 @@ your machine or in the cloud.
|
|
|
98
104
|
for the factory's own. You call one by asking a session in plain words,
|
|
99
105
|
such as "refine ticket 12".
|
|
100
106
|
|
|
107
|
+
**Slot.** One of the seven moments where the factory calls a plug-in, such
|
|
108
|
+
as `reviewer`, for an agent that reads a finished change, or `refiner`,
|
|
109
|
+
for a skill that refines a ticket in place of the factory's own.
|
|
110
|
+
[Plug-ins](plugins.md#the-slots) lists them.
|
|
111
|
+
|
|
101
112
|
**Spec.** A written statement of what a change must do. For most tickets
|
|
102
113
|
that is the acceptance criteria. With OpenSpec turned on, a change your
|
|
103
114
|
users will see also gets its behavior recorded in the repository.
|
package/docs/limitations.md
CHANGED
|
@@ -11,10 +11,15 @@ as a code host's billing or what its workflows can see, are in
|
|
|
11
11
|
|
|
12
12
|
- **One tool of each kind.** The factory reaches the code host, the ticket
|
|
13
13
|
system, the board, and the cloud runner each through one interface, and
|
|
14
|
-
the settings name which one you use
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
|
|
14
|
+
the settings name which one you use
|
|
15
|
+
([`code-host.type`](configuration.md#code-host),
|
|
16
|
+
[`tickets.type`](configuration.md#tickets), and
|
|
17
|
+
[`builds.runner`](configuration.md#builds)). Each has one implementation
|
|
18
|
+
today, GitHub's, and no other is planned. A ticket system or code host
|
|
19
|
+
named by a package, for an adapter you write yourself, is not planned
|
|
20
|
+
either; the design leaves room. The skills are written for one coding
|
|
21
|
+
agent, Claude Code. [The glossary](glossary.md) says which tool each
|
|
22
|
+
word means today.
|
|
18
23
|
- **It needs Node and a `package.json`,** even in a repository written in
|
|
19
24
|
another language.
|
|
20
25
|
- **A build never changes the coding agent's settings files,** which hold
|
|
@@ -25,8 +30,28 @@ as a code host's billing or what its workflows can see, are in
|
|
|
25
30
|
- **It is written for one approver.** `approvers` lets a team list several
|
|
26
31
|
people (_[Planned](developing.md#what-is-built)_), but review by teams, required reviewers per folder, and monorepos
|
|
27
32
|
with several owners are not designed.
|
|
28
|
-
- **The order of the workflow is fixed.**
|
|
29
|
-
|
|
33
|
+
- **The order of the workflow is fixed.** A [plug-in](plugins.md) of
|
|
34
|
+
yours can replace how a ticket is refined, how a ticket with one of your
|
|
35
|
+
labels is built, how a test is proved able to fail, which agents review
|
|
36
|
+
the tests, and how a generated file is rebuilt after a conflict, and you
|
|
37
|
+
can add reviewers and turn written specs off. The six states and their
|
|
38
|
+
order still cannot change: you cannot add a state, leave one out, or
|
|
39
|
+
reorder them ([why](design.md#the-order-of-the-workflow-is-fixed)).
|
|
40
|
+
- **A build needs a gate you wrote.** With nothing under
|
|
41
|
+
[`commands.gate`](configuration.md#commandsgate), `factory gate` fails
|
|
42
|
+
and a build stops there. The factory cannot guess how your repository is
|
|
43
|
+
checked.
|
|
44
|
+
- **A renamed default branch is read under its old name** until
|
|
45
|
+
`git remote set-head origin --auto` runs in the checkout, which keeps
|
|
46
|
+
the name in `origin/HEAD`. The factory reads the name there before it
|
|
47
|
+
asks the code host, so a stale one gives a stale answer: the commit hook
|
|
48
|
+
then guards the old branch and not the new one. After the rename, run
|
|
49
|
+
that command in each checkout, then `factory sync`, which writes the
|
|
50
|
+
name into two workflows.
|
|
51
|
+
- **One lock file is rebuilt for you after a conflict,** the one
|
|
52
|
+
[`commands.relock`](configuration.md#commandsrelock) rebuilds, npm's by
|
|
53
|
+
default. A second, such as another package manager's beside the
|
|
54
|
+
factory's own, needs a [resolver](plugins.md#resolver) of yours.
|
|
30
55
|
- **On a board with no refining column, a ticket cannot be sent back to the
|
|
31
56
|
backlog by moving its card.** The card already shows in the backlog column
|
|
32
57
|
while a ticket is being refined, so the move says nothing.
|
|
@@ -50,8 +75,8 @@ as a code host's billing or what its workflows can see, are in
|
|
|
50
75
|
package.
|
|
51
76
|
- **Nothing retries on its own.** A build that stops waits for you.
|
|
52
77
|
- **A cloud build's commits are unsigned unless you give it a signing
|
|
53
|
-
key.**
|
|
54
|
-
|
|
78
|
+
key.** `factory init` makes one when you choose that part
|
|
79
|
+
([Setting up on GitHub](github/setup.md#run-factory-init)).
|
|
55
80
|
- **A cloud build cannot be steered.** You can read its log as it runs, and
|
|
56
81
|
cancel it, but not answer it: where it would ask, it stops and reports.
|
|
57
82
|
- **Nothing watches a pull request after its cloud build ends.** Your own
|
|
@@ -68,12 +93,16 @@ as a code host's billing or what its workflows can see, are in
|
|
|
68
93
|
person's, but the factory has only run against a person's.
|
|
69
94
|
- **Your board's own automations,** such as moving a closed ticket to Done.
|
|
70
95
|
They may fight the board sync.
|
|
71
|
-
- **
|
|
72
|
-
dependency bot.
|
|
96
|
+
- **A factory update reaching a repository through its dependency bot.**
|
|
73
97
|
- **Glob patterns standing in for today's regular expressions** in the
|
|
74
98
|
merge policy. They could match differently. The switch compares the old and new
|
|
75
99
|
decision on recent pull requests.
|
|
76
100
|
- **A scheduled job as the poller,** including what it costs.
|
|
101
|
+
- **A default branch not called `main`.** The name is read, never assumed,
|
|
102
|
+
and the tests run with a branch called `develop`, but no repository with
|
|
103
|
+
one has run the factory.
|
|
104
|
+
- **A refiner, a prover, or a resolver of your own.** The settings accept
|
|
105
|
+
each and the skills call them, but no repository has run one.
|
|
77
106
|
- **Windows.** The tool and its hooks need only Node, but nothing here has
|
|
78
107
|
been run on Windows.
|
|
79
108
|
- **Adding the factory's columns to a board you already have.**
|
|
@@ -107,8 +136,6 @@ as a code host's billing or what its workflows can see, are in
|
|
|
107
136
|
one account's login.
|
|
108
137
|
- **An update delivers instructions that run with your tokens.** Read update
|
|
109
138
|
pull requests as carefully as code.
|
|
110
|
-
- **The poller keeps its hourly cap in memory.** A restart forgets how many
|
|
111
|
-
builds it started in the last hour.
|
|
112
139
|
- **It sits on tools that change.** Several parts work around how today's
|
|
113
140
|
coding agent and code host behave.
|
|
114
141
|
- **Publishing cannot be undone.** A public release needs a history and
|