@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/rules.md
CHANGED
|
@@ -120,12 +120,13 @@ discovering it at push time.
|
|
|
120
120
|
- **An issue is built in GitHub Actions by moving its card to Ready** on
|
|
121
121
|
the board, the GitHub Project whose number
|
|
122
122
|
`npx --no-install factory config get tickets.board` prints: the
|
|
123
|
-
|
|
124
|
-
|
|
125
|
-
|
|
123
|
+
poller dispatches the "Factory build" workflow, within about a minute
|
|
124
|
+
when you host it (`builds.trigger: own-server`) or at its next scheduled
|
|
125
|
+
pass (`github-action`), the same run that
|
|
126
|
+
`npx --no-install factory build N` starts by hand. A local build starts by telling a session to work the
|
|
126
127
|
issue.
|
|
127
|
-
The poller skips a card whose blocker is open and starts it
|
|
128
|
-
|
|
128
|
+
The poller skips a card whose blocker is open and starts it at its first
|
|
129
|
+
pass after the blocker closes. A card moves only forward on its own,
|
|
129
130
|
except the follow-ups issue when a pull request merged part of it,
|
|
130
131
|
which goes to Backlog: a
|
|
131
132
|
build that ends without a merge stays In progress, and a finished
|
|
@@ -188,7 +189,7 @@ OpenSpec collects anonymous usage statistics unless told not to. Run it with
|
|
|
188
189
|
## Issues that wait on another
|
|
189
190
|
|
|
190
191
|
A build order stated only in prose is one nothing reads: the poller starts
|
|
191
|
-
a build within
|
|
192
|
+
a build within minutes of a card moving to Ready, and it and `factory-build`
|
|
192
193
|
stop only on a recorded relationship. So whoever opens or refines an issue records each
|
|
193
194
|
blocker as a blocked-by relationship, and says why in the issue's
|
|
194
195
|
body (under Decisions, for a refined issue).
|
|
@@ -284,7 +285,8 @@ The factory's skills, agents, rules, review instructions, and workflows
|
|
|
284
285
|
under `.claude/` and `.github/` are copies, written by `factory sync` from
|
|
285
286
|
the factory's package. Change the source in the package, run
|
|
286
287
|
`npx --no-install factory sync`, and commit both: the gate and CI fail
|
|
287
|
-
when a copy differs from its source
|
|
288
|
+
when a copy differs from what `sync` writes from its source and the
|
|
289
|
+
settings.
|
|
288
290
|
|
|
289
291
|
A rule written for the change in front of its author can be wrong for
|
|
290
292
|
every other kind. Once, the step that adds the `spec` label kept adding
|
|
@@ -297,11 +299,11 @@ code that decides what runs and who merges (the factory's own commands,
|
|
|
297
299
|
and the scripts "Changing the process: this
|
|
298
300
|
repository" in `CLAUDE.md` names)
|
|
299
301
|
that alters what triggers a step, who runs or when,
|
|
300
|
-
|
|
301
|
-
ready
|
|
302
|
-
|
|
303
|
-
|
|
304
|
-
|
|
302
|
+
is traced with the `factory-trace` skill before its pull request is
|
|
303
|
+
marked ready: a fresh agent walks each kind in `.claude/change-types.md`
|
|
304
|
+
through the rules as they will stand, and reports a kind that got heavier,
|
|
305
|
+
lighter, or ambiguous, and any two rules that now disagree. Fix what holds
|
|
306
|
+
up. A change to wording alone needs no trace.
|
|
305
307
|
|
|
306
308
|
## Stepping back from a rabbit hole
|
|
307
309
|
|
package/settings.schema.json
CHANGED
|
@@ -85,6 +85,9 @@
|
|
|
85
85
|
},
|
|
86
86
|
"session-minutes": {
|
|
87
87
|
"$ref": "#/definitions/session-minutes"
|
|
88
|
+
},
|
|
89
|
+
"rules": {
|
|
90
|
+
"$ref": "#/definitions/rules"
|
|
88
91
|
}
|
|
89
92
|
},
|
|
90
93
|
"definitions": {
|
|
@@ -199,6 +202,10 @@
|
|
|
199
202
|
"runner": {
|
|
200
203
|
"enum": ["github-actions"],
|
|
201
204
|
"description": "Where an unattended build runs. Default: github-actions."
|
|
205
|
+
},
|
|
206
|
+
"poll-minutes": {
|
|
207
|
+
"enum": [5, 10, 15, 30, 60],
|
|
208
|
+
"description": "How often the scheduled poller checks the board, in minutes, with builds.trigger: github-action. Default: 5."
|
|
202
209
|
}
|
|
203
210
|
}
|
|
204
211
|
},
|
|
@@ -406,6 +413,23 @@
|
|
|
406
413
|
"description": "Work on the dependency pull requests. Default: 50."
|
|
407
414
|
}
|
|
408
415
|
}
|
|
416
|
+
},
|
|
417
|
+
"rules": {
|
|
418
|
+
"type": "object",
|
|
419
|
+
"description": "Numbers the process rules use, for a repository that wants different ones.",
|
|
420
|
+
"additionalProperties": false,
|
|
421
|
+
"properties": {
|
|
422
|
+
"small-change-lines": {
|
|
423
|
+
"type": "integer",
|
|
424
|
+
"minimum": 1,
|
|
425
|
+
"description": "A change under this many lines outside tests, specs, and content, adding no component and no state, takes the lighter path. Default: 30."
|
|
426
|
+
},
|
|
427
|
+
"review-rounds": {
|
|
428
|
+
"type": "integer",
|
|
429
|
+
"minimum": 1,
|
|
430
|
+
"description": "Rounds a session works a review before it hands what is left to you. Default: 2."
|
|
431
|
+
}
|
|
432
|
+
}
|
|
409
433
|
}
|
|
410
434
|
}
|
|
411
435
|
}
|
|
@@ -20,7 +20,7 @@ nonzero with the error: that is a failed read, never an empty answer.
|
|
|
20
20
|
card stays where it is until the claim moves it.
|
|
21
21
|
|
|
22
22
|
- **GitHub Actions:** the owner moves the issue's card to Ready on the
|
|
23
|
-
board, and the
|
|
23
|
+
board, and the poller posts a start comment and dispatches
|
|
24
24
|
"Factory build" with the issue's number; or a person runs
|
|
25
25
|
`npx --no-install factory build N`, or "Run workflow" on the Actions
|
|
26
26
|
tab. The two are the same run. The run's prompt says so. There is no
|
|
@@ -0,0 +1,79 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: factory-trace
|
|
3
|
+
description: Trace a change to the process through every kind of change the repository gets, with one fresh agent, and report each kind that got heavier, lighter, or ambiguous and any two rules that now disagree. Use before a pull request is marked ready when it changes the rules, a skill, an agent, or a workflow in a way that alters what triggers a step, who runs, or when, and when asked to trace a rule change. A change of wording alone needs no trace.
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# Tracing a change to the process
|
|
7
|
+
|
|
8
|
+
A rule written for the change in front of its author can be wrong for
|
|
9
|
+
every other kind. Once, the step that adds the `spec` label kept adding it
|
|
10
|
+
to small changes after the table that defines the label stopped. This skill
|
|
11
|
+
has a reader who did not write the change walk each kind of change through
|
|
12
|
+
the rules as the branch leaves them, before the pull request is marked
|
|
13
|
+
ready.
|
|
14
|
+
|
|
15
|
+
## 1. Read the kinds of change
|
|
16
|
+
|
|
17
|
+
The kinds are in `.claude/change-types.md`, one row each with a real
|
|
18
|
+
example.
|
|
19
|
+
|
|
20
|
+
**When the file is missing,** start no agent. The pull request is not
|
|
21
|
+
marked ready untraced: leave it a draft, say on it that the trace needs
|
|
22
|
+
the file, and show its shape there, for the owner to write:
|
|
23
|
+
|
|
24
|
+
```markdown
|
|
25
|
+
# Change types
|
|
26
|
+
|
|
27
|
+
| Kind | Example |
|
|
28
|
+
| -------------------------------------------------- | ---------------------------------------- |
|
|
29
|
+
| A small bug fix with no change to what a user sees | the guard passing an empty settings file |
|
|
30
|
+
| Docs only | the quick start's install line |
|
|
31
|
+
```
|
|
32
|
+
|
|
33
|
+
Each kind names a change the repository really gets, and each example is
|
|
34
|
+
one that happened. The file lists kinds and nothing more: each kind's
|
|
35
|
+
path is read from the rules, so the file never restates them.
|
|
36
|
+
|
|
37
|
+
## 2. Start one fresh agent
|
|
38
|
+
|
|
39
|
+
The branch is the current one, and its base is the default branch,
|
|
40
|
+
`origin/main` unless the pull request says otherwise. Start one
|
|
41
|
+
`general-purpose` agent, and give it only this:
|
|
42
|
+
|
|
43
|
+
> The branch BRANCH changes this repository's process: its rules, skills,
|
|
44
|
+
> agents, or workflows. Read what it changes with
|
|
45
|
+
> `git diff BASE...BRANCH`, then read the rules, skills, and agents as the
|
|
46
|
+
> branch leaves them, starting from `CLAUDE.md` and what it imports.
|
|
47
|
+
>
|
|
48
|
+
> For each kind of change in `.claude/change-types.md`, trace that kind's
|
|
49
|
+
> example through the process as it now stands, from the ticket to the
|
|
50
|
+
> merge: which steps it takes, which reviewers read it, and who merges it.
|
|
51
|
+
> Then do the same on BASE, and compare.
|
|
52
|
+
>
|
|
53
|
+
> Report one line per kind: **unchanged**, **heavier** (a step, reviewer,
|
|
54
|
+
> or wait it did not have), **lighter** (one it lost), or **ambiguous**
|
|
55
|
+
> (two readings of the rules give different paths). For every kind that is
|
|
56
|
+
> not unchanged, name the rule, by its file and section, that makes it so.
|
|
57
|
+
> Then list any two rules that now disagree, quoting both. Where the
|
|
58
|
+
> repository's `CLAUDE.md` asks more of this trace, do that too. Read
|
|
59
|
+
> only; change nothing.
|
|
60
|
+
|
|
61
|
+
Give it nothing else from this session: what the author meant is what the
|
|
62
|
+
trace tests.
|
|
63
|
+
|
|
64
|
+
## 3. Report
|
|
65
|
+
|
|
66
|
+
The agent's report is the result, unedited.
|
|
67
|
+
|
|
68
|
+
**When the branch has an open pull request,** which
|
|
69
|
+
`npx --no-install factory pr state` names on its first line, post the
|
|
70
|
+
report there, so the owner reads it before merging:
|
|
71
|
+
|
|
72
|
+
```bash
|
|
73
|
+
npx --no-install factory pr comment N --body-file trace.md
|
|
74
|
+
```
|
|
75
|
+
|
|
76
|
+
Otherwise give it in the session.
|
|
77
|
+
|
|
78
|
+
Then fix what holds up, and say in the pull request which findings were
|
|
79
|
+
fixed and why any were not. A change of wording alone needs no trace.
|
|
@@ -1,6 +1,7 @@
|
|
|
1
|
-
# Builds one ticket in GitHub Actions, with the factory-build skill, when
|
|
2
|
-
#
|
|
3
|
-
#
|
|
1
|
+
# Builds one ticket in GitHub Actions, with the factory-build skill, when the
|
|
2
|
+
# poller starts it for a card moved to Ready, or a person does:
|
|
3
|
+
# `npx --no-install factory build N`, or "Run workflow" on the Actions tab
|
|
4
|
+
# with the ticket's number.
|
|
4
5
|
#
|
|
5
6
|
# The build acts as whoever owns its token, on GitHub and in git: the secret
|
|
6
7
|
# FACTORY_BUILD_TOKEN, or FACTORY_BOARD_TOKEN when that is not set. The
|
|
@@ -52,7 +53,7 @@ jobs:
|
|
|
52
53
|
prompt: |
|
|
53
54
|
Build ticket #${{ inputs.ticket }} of this repository with the factory-build skill. You are running unattended in GitHub Actions, in a fresh checkout of the default branch with its dependencies installed and the commands under `build-setup` in `.claude/factory.yaml` already run. Nobody can answer a question here: where the skill would ask its user, stop and report instead.
|
|
54
55
|
|
|
55
|
-
|
|
56
|
+
The poller started this build for a card moved to Ready, or a person did with `factory build ${{ inputs.ticket }}` or the Actions tab's "Run workflow": the skill's start in GitHub Actions, under "How a build starts" in `.claude/skills/factory-build/SKILL.md`, which has no start check. This is a session nobody can wake later: once the pull request is marked ready, wait for its review with `npx --no-install factory pr state PR --wait`, where PR is its number, and work it with the factory-address-review skill. Do not start `factory pr watch`.
|
|
56
57
|
|
|
57
58
|
How: use the Skill tool to invoke `factory-build` with "#${{ inputs.ticket }}". If the Skill tool is unavailable, read `.claude/skills/factory-build/SKILL.md` and follow it exactly. When its claim prints `held by`, stop and post nothing. When it prints `blocked by`, stop and post the skill's report for it, since nothing else on the ticket says why this run stopped. Follow every stop the skill names. Read `CLAUDE.md`, and `AGENTS.md` where there is one, before building.
|
|
58
59
|
|
|
@@ -32,11 +32,12 @@ jobs:
|
|
|
32
32
|
# the production smoke tests would never run on a dependency bump.
|
|
33
33
|
#
|
|
34
34
|
# Never a major, whose migration the owner reads first, and never the
|
|
35
|
-
# factory itself, which changes the instructions every session follows
|
|
35
|
+
# factory itself, which changes the instructions every session follows:
|
|
36
|
+
# its package or its poller's image, whose names both hold the match.
|
|
36
37
|
- name: Enable auto-merge
|
|
37
38
|
if: >-
|
|
38
39
|
steps.meta.outputs.update-type != 'version-update:semver-major' &&
|
|
39
|
-
!contains(steps.meta.outputs.dependency-names, '
|
|
40
|
+
!contains(steps.meta.outputs.dependency-names, 'davidbyoung/software-factory')
|
|
40
41
|
run: gh pr merge --auto --squash "$PR_URL"
|
|
41
42
|
env:
|
|
42
43
|
PR_URL: ${{ github.event.pull_request.html_url }}
|
|
@@ -0,0 +1,46 @@
|
|
|
1
|
+
# Starts a build for each ticket moved to Ready, for a repository with no
|
|
2
|
+
# server to host the poller: one pass of it on a schedule, which
|
|
3
|
+
# `factory sync` sets from `builds.poll-minutes`. Each build it starts is a
|
|
4
|
+
# run of factory-build.yml of its own, so builds still run side by side.
|
|
5
|
+
#
|
|
6
|
+
# GitHub's own token cannot reach a user's Project, so the pass reads the
|
|
7
|
+
# board, comments, and starts builds with FACTORY_BOARD_TOKEN, the token
|
|
8
|
+
# the board sync already uses. A schedule runs the default branch's copy.
|
|
9
|
+
name: Factory poller
|
|
10
|
+
|
|
11
|
+
on:
|
|
12
|
+
schedule:
|
|
13
|
+
- cron: "*/5 * * * *"
|
|
14
|
+
workflow_dispatch:
|
|
15
|
+
|
|
16
|
+
permissions:
|
|
17
|
+
contents: read
|
|
18
|
+
|
|
19
|
+
# A late run waits for the one before it, so two passes never read the
|
|
20
|
+
# same Ready card before either has posted its start comment.
|
|
21
|
+
concurrency:
|
|
22
|
+
group: factory-poller
|
|
23
|
+
cancel-in-progress: false
|
|
24
|
+
|
|
25
|
+
jobs:
|
|
26
|
+
poll:
|
|
27
|
+
name: Start the Ready tickets
|
|
28
|
+
runs-on: ubuntu-latest
|
|
29
|
+
timeout-minutes: 10
|
|
30
|
+
steps:
|
|
31
|
+
- name: Checkout
|
|
32
|
+
uses: actions/checkout@v7
|
|
33
|
+
|
|
34
|
+
- name: Set up Node
|
|
35
|
+
uses: actions/setup-node@v7
|
|
36
|
+
with:
|
|
37
|
+
node-version: 22
|
|
38
|
+
cache: npm
|
|
39
|
+
|
|
40
|
+
- name: Install dependencies
|
|
41
|
+
run: npm ci --ignore-scripts
|
|
42
|
+
|
|
43
|
+
- name: Start the Ready tickets
|
|
44
|
+
env:
|
|
45
|
+
FACTORY_BOARD_TOKEN: ${{ secrets.FACTORY_BOARD_TOKEN }}
|
|
46
|
+
run: npx --no-install factory poller --once
|