@davidbyoung/software-factory 0.0.0-stage → 0.1.0
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/.claude-plugin/plugin.json +5 -0
- package/LICENSE +21 -0
- package/README.md +135 -2
- package/actions/factory-agent/action.yml +218 -0
- package/agents/factory-test-reviewer.md +129 -0
- package/agents/factory-ticket-readiness.md +107 -0
- package/agents/factory-ui-reviewer.md +160 -0
- package/bin/factory.js +45 -0
- package/bin/launch.js +67 -0
- package/dist/board.d.mts +128 -0
- package/dist/board.mjs +456 -0
- package/dist/build.d.mts +18 -0
- package/dist/build.mjs +60 -0
- package/dist/cli.d.mts +17 -0
- package/dist/cli.mjs +264 -0
- package/dist/code-host/github.d.mts +118 -0
- package/dist/code-host/github.mjs +419 -0
- package/dist/code-host/index.d.mts +9 -0
- package/dist/code-host/index.mjs +18 -0
- package/dist/code-host/types.d.mts +205 -0
- package/dist/code-host/types.mjs +12 -0
- package/dist/config.d.mts +166 -0
- package/dist/config.mjs +548 -0
- package/dist/deps.d.mts +32 -0
- package/dist/deps.mjs +126 -0
- package/dist/doctor.d.mts +34 -0
- package/dist/doctor.mjs +188 -0
- package/dist/guard-commit.d.mts +41 -0
- package/dist/guard-commit.mjs +205 -0
- package/dist/guard-permission.d.mts +15 -0
- package/dist/guard-permission.mjs +52 -0
- package/dist/guard-ticket-text.d.mts +27 -0
- package/dist/guard-ticket-text.mjs +288 -0
- package/dist/guard.d.mts +4 -0
- package/dist/guard.mjs +37 -0
- package/dist/init.d.mts +58 -0
- package/dist/init.mjs +556 -0
- package/dist/lib/clock.d.mts +14 -0
- package/dist/lib/clock.mjs +36 -0
- package/dist/lib/gh.d.mts +28 -0
- package/dist/lib/gh.mjs +92 -0
- package/dist/lib/glob.d.mts +2 -0
- package/dist/lib/glob.mjs +41 -0
- package/dist/lib/pricing.d.mts +25 -0
- package/dist/lib/pricing.mjs +77 -0
- package/dist/lib/usage.d.mts +34 -0
- package/dist/lib/usage.mjs +128 -0
- package/dist/lib/work-status.d.mts +251 -0
- package/dist/lib/work-status.mjs +510 -0
- package/dist/merge-policy.d.mts +66 -0
- package/dist/merge-policy.mjs +146 -0
- package/dist/parts.d.mts +39 -0
- package/dist/parts.mjs +138 -0
- package/dist/poller.d.mts +61 -0
- package/dist/poller.mjs +247 -0
- package/dist/pr-watch.d.mts +45 -0
- package/dist/pr-watch.mjs +244 -0
- package/dist/pr.d.mts +65 -0
- package/dist/pr.mjs +571 -0
- package/dist/review-cost.d.mts +18 -0
- package/dist/review-cost.mjs +95 -0
- package/dist/review-tools.d.mts +5 -0
- package/dist/review-tools.mjs +46 -0
- package/dist/review-verdict.d.mts +50 -0
- package/dist/review-verdict.mjs +171 -0
- package/dist/reviewers.d.mts +54 -0
- package/dist/reviewers.mjs +312 -0
- package/dist/runner/github-actions.d.mts +12 -0
- package/dist/runner/github-actions.mjs +97 -0
- package/dist/runner/index.d.mts +9 -0
- package/dist/runner/index.mjs +22 -0
- package/dist/runner/types.d.mts +60 -0
- package/dist/runner/types.mjs +7 -0
- package/dist/session-start.d.mts +20 -0
- package/dist/session-start.mjs +115 -0
- package/dist/site/capture.d.mts +44 -0
- package/dist/site/capture.mjs +114 -0
- package/dist/site/measure.d.mts +83 -0
- package/dist/site/measure.mjs +225 -0
- package/dist/site/pages.d.mts +10 -0
- package/dist/site/pages.mjs +71 -0
- package/dist/site/pixels.d.mts +47 -0
- package/dist/site/pixels.mjs +157 -0
- package/dist/site/servers.d.mts +47 -0
- package/dist/site/servers.mjs +141 -0
- package/dist/site.d.mts +60 -0
- package/dist/site.mjs +341 -0
- package/dist/status.d.mts +100 -0
- package/dist/status.mjs +514 -0
- package/dist/sync.d.mts +59 -0
- package/dist/sync.mjs +292 -0
- package/dist/ticket.d.mts +61 -0
- package/dist/ticket.mjs +562 -0
- package/dist/tickets/github.d.mts +128 -0
- package/dist/tickets/github.mjs +491 -0
- package/dist/tickets/index.d.mts +15 -0
- package/dist/tickets/index.mjs +27 -0
- package/dist/tickets/transport.d.mts +42 -0
- package/dist/tickets/transport.mjs +158 -0
- package/dist/tickets/types.d.mts +191 -0
- package/dist/tickets/types.mjs +76 -0
- package/docs/builds.md +227 -0
- package/docs/cli.md +221 -0
- package/docs/configuration.md +809 -0
- package/docs/design.md +106 -0
- package/docs/developing.md +400 -0
- package/docs/existing-repo.md +138 -0
- package/docs/github/reference.md +288 -0
- package/docs/github/setup.md +312 -0
- package/docs/glossary.md +106 -0
- package/docs/limitations.md +115 -0
- package/docs/plugins.md +192 -0
- package/docs/quick-start.md +222 -0
- package/docs/removing.md +76 -0
- package/docs/skills.md +270 -0
- package/docs/updating.md +108 -0
- package/docs/workflow.md +195 -0
- package/package.json +67 -4
- package/poller.Dockerfile +21 -0
- package/review.md +170 -0
- package/rules.md +313 -0
- package/settings.schema.json +411 -0
- package/skills/factory-address-review/SKILL.md +547 -0
- package/skills/factory-address-review/patch-coverage.py +68 -0
- package/skills/factory-build/SKILL.md +412 -0
- package/skills/factory-deps/SKILL.md +185 -0
- package/skills/factory-design/SKILL.md +159 -0
- package/skills/factory-diagnose/SKILL.md +93 -0
- package/skills/factory-mutate/SKILL.md +76 -0
- package/skills/factory-refine/SKILL.md +417 -0
- package/skills/factory-resolve-conflicts/SKILL.md +235 -0
- package/workflows/factory-board-sync.yml +91 -0
- package/workflows/factory-build.yml +72 -0
- package/workflows/factory-check.yml +37 -0
- package/workflows/factory-claude-review.yml +133 -0
- package/workflows/factory-conflicts.yml +69 -0
- package/workflows/factory-deps-auto-merge.yml +43 -0
- package/workflows/factory-deps.yml +59 -0
- package/workflows/factory-merge-policy.yml +121 -0
- package/workflows/factory-review-verdict.yml +54 -0
- package/workflows/factory-review.yml +75 -0
package/package.json
CHANGED
|
@@ -1,6 +1,69 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@davidbyoung/software-factory",
|
|
3
|
-
"version": "0.
|
|
4
|
-
"
|
|
5
|
-
"
|
|
6
|
-
|
|
3
|
+
"version": "0.1.0",
|
|
4
|
+
"description": "Refines, builds, and reviews tickets with Claude Code sessions, from a board to a merged pull request.",
|
|
5
|
+
"license": "MIT",
|
|
6
|
+
"repository": {
|
|
7
|
+
"type": "git",
|
|
8
|
+
"url": "git+https://github.com/davidbyoung/software-factory.git"
|
|
9
|
+
},
|
|
10
|
+
"type": "module",
|
|
11
|
+
"engines": {
|
|
12
|
+
"node": ">=22.18"
|
|
13
|
+
},
|
|
14
|
+
"bin": {
|
|
15
|
+
"factory": "bin/factory.js"
|
|
16
|
+
},
|
|
17
|
+
"files": [
|
|
18
|
+
"bin",
|
|
19
|
+
"dist",
|
|
20
|
+
"skills",
|
|
21
|
+
"agents",
|
|
22
|
+
"rules.md",
|
|
23
|
+
"review.md",
|
|
24
|
+
"workflows",
|
|
25
|
+
"actions",
|
|
26
|
+
"poller.Dockerfile",
|
|
27
|
+
".claude-plugin",
|
|
28
|
+
"docs",
|
|
29
|
+
"settings.schema.json"
|
|
30
|
+
],
|
|
31
|
+
"scripts": {
|
|
32
|
+
"test": "vitest run",
|
|
33
|
+
"typecheck": "tsc --noEmit",
|
|
34
|
+
"format": "prettier --write .",
|
|
35
|
+
"format:check": "prettier --check .",
|
|
36
|
+
"check": "prettier --check . && tsc --noEmit && vitest run",
|
|
37
|
+
"prepack": "tsc -p tsconfig.build.json",
|
|
38
|
+
"pack-check": "node tests/pack-check.mts",
|
|
39
|
+
"site-check": "node --test tests/site-check.mts"
|
|
40
|
+
},
|
|
41
|
+
"dependencies": {
|
|
42
|
+
"@inquirer/prompts": "^8.8.0",
|
|
43
|
+
"axe-core": "^4.14.0",
|
|
44
|
+
"js-yaml": "^5.5.0",
|
|
45
|
+
"pngjs": "^7.0.0",
|
|
46
|
+
"yaml": "^2.9.1"
|
|
47
|
+
},
|
|
48
|
+
"devDependencies": {
|
|
49
|
+
"@types/js-yaml": "^4.0.9",
|
|
50
|
+
"@types/node": "^22.18.0",
|
|
51
|
+
"@types/pngjs": "^6.0.5",
|
|
52
|
+
"ajv": "^8.20.0",
|
|
53
|
+
"playwright": "^1.65.0",
|
|
54
|
+
"prettier": "^3.10.0",
|
|
55
|
+
"typescript": "^5.9.3",
|
|
56
|
+
"vitest": "^5.1.0"
|
|
57
|
+
},
|
|
58
|
+
"peerDependencies": {
|
|
59
|
+
"playwright": "*"
|
|
60
|
+
},
|
|
61
|
+
"peerDependenciesMeta": {
|
|
62
|
+
"playwright": {
|
|
63
|
+
"optional": true
|
|
64
|
+
}
|
|
65
|
+
},
|
|
66
|
+
"publishConfig": {
|
|
67
|
+
"access": "public"
|
|
68
|
+
}
|
|
69
|
+
}
|
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
# The poller's image. It copies only the poller and the modules it imports:
|
|
2
|
+
# the shared work-status rules, the GitHub ticket adapter with its `fetch`
|
|
3
|
+
# transport, GitHub as the code host, and GitHub Actions as the runner, each
|
|
4
|
+
# with the interface it fills. No npm install and no build, so
|
|
5
|
+
# the repository's build variables are not needed here, and the `factory`
|
|
6
|
+
# launcher is not used. A test fails when the poller imports a file not
|
|
7
|
+
# copied below.
|
|
8
|
+
FROM node:22-slim
|
|
9
|
+
WORKDIR /app
|
|
10
|
+
COPY src/poller.mts src/poller.mts
|
|
11
|
+
COPY src/lib/work-status.mts src/lib/work-status.mts
|
|
12
|
+
COPY src/lib/gh.mts src/lib/gh.mts
|
|
13
|
+
COPY src/tickets/types.mts src/tickets/types.mts
|
|
14
|
+
COPY src/tickets/transport.mts src/tickets/transport.mts
|
|
15
|
+
COPY src/tickets/github.mts src/tickets/github.mts
|
|
16
|
+
COPY src/code-host/types.mts src/code-host/types.mts
|
|
17
|
+
COPY src/code-host/github.mts src/code-host/github.mts
|
|
18
|
+
COPY src/runner/types.mts src/runner/types.mts
|
|
19
|
+
COPY src/runner/github-actions.mts src/runner/github-actions.mts
|
|
20
|
+
USER node
|
|
21
|
+
CMD ["node", "src/poller.mts"]
|
package/review.md
ADDED
|
@@ -0,0 +1,170 @@
|
|
|
1
|
+
# Reviewing a pull request
|
|
2
|
+
|
|
3
|
+
You are reviewing a pull request in this repository as a careful senior
|
|
4
|
+
engineer would. The maintainer's local Claude session reads every comment you
|
|
5
|
+
leave, verifies it, and either fixes it or replies with evidence that it is
|
|
6
|
+
wrong. Every review thread must be resolved before the pull request can
|
|
7
|
+
merge, so each comment you post costs a round trip. Post only what you would
|
|
8
|
+
defend.
|
|
9
|
+
|
|
10
|
+
## Before you review
|
|
11
|
+
|
|
12
|
+
1. Read `CLAUDE.md`, `AGENTS.md`, and every area guide "Rules by area" in
|
|
13
|
+
`CLAUDE.md` lists, in full. They are the project's rules, and most
|
|
14
|
+
findings worth raising break one of them. Then read
|
|
15
|
+
`.github/review-notes.md` when it exists: what this repository's review
|
|
16
|
+
checks beyond this file.
|
|
17
|
+
2. Find what to review. List the pull request's comments, with the REPO and
|
|
18
|
+
PR NUMBER you were given. These reads go through `gh`, never the
|
|
19
|
+
factory's own commands: the checkout is the pull request's head, so its
|
|
20
|
+
commands are the code under review and could change what you see.
|
|
21
|
+
|
|
22
|
+
```bash
|
|
23
|
+
gh pr view PR_NUMBER --json comments
|
|
24
|
+
gh api repos/REPO/pulls/PR_NUMBER/comments --paginate
|
|
25
|
+
```
|
|
26
|
+
|
|
27
|
+
Your earlier summaries contain `<!-- claude-review sha=SHA -->`. If one
|
|
28
|
+
exists and that SHA is an ancestor of the head
|
|
29
|
+
(`git merge-base --is-ancestor SHA HEAD`), compare
|
|
30
|
+
`git merge-base SHA origin/main` with `git merge-base HEAD origin/main`.
|
|
31
|
+
If they differ, main was merged in since that review, so review
|
|
32
|
+
`git diff origin/main...HEAD`, the pull request's own changes as they
|
|
33
|
+
now stand. If they match, review only `git diff SHA...HEAD`. Otherwise
|
|
34
|
+
review the whole pull request, `git diff origin/main...HEAD`. Use
|
|
35
|
+
`origin/main` rather than the base SHA you were given, which comes from
|
|
36
|
+
the event and can be older than a merge from main.
|
|
37
|
+
|
|
38
|
+
If that SHA is the head itself, this is a re-run after the author
|
|
39
|
+
replied without pushing. There is no new code: read the replies since
|
|
40
|
+
that summary, and post a summary whose verdict says whether anything you
|
|
41
|
+
raised is still unsettled.
|
|
42
|
+
|
|
43
|
+
3. Read the earlier review threads, including resolved ones, and the replies
|
|
44
|
+
in them. Do not raise a finding that is already in a thread, or a Low
|
|
45
|
+
already listed in an earlier summary. A thread the
|
|
46
|
+
author rejected with evidence stays rejected unless the new commits change
|
|
47
|
+
the facts; if you still disagree, say so once in the summary, with your
|
|
48
|
+
evidence, rather than opening a new thread.
|
|
49
|
+
|
|
50
|
+
4. Read what the pull request was asked to do. Its body, and the issues it
|
|
51
|
+
closes:
|
|
52
|
+
|
|
53
|
+
```bash
|
|
54
|
+
gh pr view PR_NUMBER --json body,closingIssuesReferences
|
|
55
|
+
gh api graphql -F n=ISSUE_NUMBER -f query='query($n: Int!) { repository(owner: "OWNER", name: "NAME") { issue(number: $n) { body } } }' --jq .data.repository.issue.body
|
|
56
|
+
```
|
|
57
|
+
|
|
58
|
+
OWNER and NAME are the two halves of REPO.
|
|
59
|
+
|
|
60
|
+
The issue's "Spec" and "Acceptance criteria" sections are what the
|
|
61
|
+
change must do, and its "Decisions" are settled. An issue with neither
|
|
62
|
+
is held only to what it plainly asks for: a fix it suggests is not a
|
|
63
|
+
criterion. The follow-ups issue, closed or only linked, is held to the lines the
|
|
64
|
+
body says this pull request built. A pull request that closes no issue,
|
|
65
|
+
such as a source audit, has only its body to go by.
|
|
66
|
+
|
|
67
|
+
## What to look for
|
|
68
|
+
|
|
69
|
+
- **Correctness.** A defect a user would hit, a regression, a race, data
|
|
70
|
+
that is silently dropped.
|
|
71
|
+
- **What it was asked to do.** A Spec line or criterion from step 4 that
|
|
72
|
+
the whole pull request, `git diff origin/main...HEAD`, does not meet, or
|
|
73
|
+
meets only in part, is a finding, since the merge closes the issue as
|
|
74
|
+
done: High when a visitor would see the gap, Medium otherwise. Behavior
|
|
75
|
+
no line asked for is Medium, unless the body or the owner's comments on
|
|
76
|
+
the pull request explain it. Quote the line either way.
|
|
77
|
+
- **Tests that cannot fail.** A test whose name and body disagree, a
|
|
78
|
+
negative assertion with nothing proving the page got there, a check that
|
|
79
|
+
holds whatever the code does. Say which change to the code would leave it
|
|
80
|
+
green.
|
|
81
|
+
- **The project's rules** in those files, quoting the rule
|
|
82
|
+
you are citing.
|
|
83
|
+
- **What `.github/review-notes.md` asks for**, when it exists.
|
|
84
|
+
|
|
85
|
+
Leave out style preferences the project's rules do not ask for, anything the
|
|
86
|
+
linter or type checker would catch, and praise.
|
|
87
|
+
|
|
88
|
+
## Prove it before you post
|
|
89
|
+
|
|
90
|
+
You have the project installed, and can run the commands the repository's
|
|
91
|
+
settings allow you, such as its unit tests, the type check, or lint. A
|
|
92
|
+
command you are not allowed is denied: do without it, and say what you
|
|
93
|
+
could not check. Use them to settle a specific suspicion, and
|
|
94
|
+
only then: a finding that comes with what you ran and what happened gets
|
|
95
|
+
fixed the first time, and one that does not costs a round trip. Read the
|
|
96
|
+
surrounding code and the other callers too.
|
|
97
|
+
|
|
98
|
+
**Do not run the test suite, the type check or lint as a routine pass.** CI
|
|
99
|
+
runs all three on every push, and its results are on the pull request. Run
|
|
100
|
+
one only for one of the checks below, and only the narrowest form of it: a
|
|
101
|
+
single test file, not the suite.
|
|
102
|
+
|
|
103
|
+
- **A new or changed test**: break the code it covers in the smallest way
|
|
104
|
+
that removes the behavior its name claims, run just that test file, with
|
|
105
|
+
the command `.github/review-notes.md` gives, and see whether it fails. If it stays green, that
|
|
106
|
+
is a finding: give the change and the passing output.
|
|
107
|
+
- **A suspected bug**: write a few lines under `/tmp` that call the code
|
|
108
|
+
with the input you suspect, run them with `node`, and report the result.
|
|
109
|
+
If the code behaves, drop the finding.
|
|
110
|
+
- **A test that waits on timing** (a debounce, a transition, an effect):
|
|
111
|
+
run it with `{ repeats: 50 }` added. A failure is the finding. Do not do
|
|
112
|
+
this for tests that do not wait on anything.
|
|
113
|
+
- **A suggestion block**: apply it, run the type check, lint on the file,
|
|
114
|
+
and the affected tests, where you are allowed them, and post it only if
|
|
115
|
+
they pass.
|
|
116
|
+
- **A claim about the codebase**, such as an unused export or a broken
|
|
117
|
+
caller: confirm it with the type check or a test.
|
|
118
|
+
|
|
119
|
+
Write scratch files under `/tmp`, never in the repository. Undo each edit to
|
|
120
|
+
a repository file with `git checkout -- PATH` on that file alone, before the
|
|
121
|
+
next check, so each starts from the pull request as it is. Never run
|
|
122
|
+
`git checkout -- .`: the action restores `CLAUDE.md` and its other
|
|
123
|
+
instruction files from the base branch, so the pull request cannot rewrite
|
|
124
|
+
your rules, and a blanket checkout would put the pull request's version back.
|
|
125
|
+
Your changes are never pushed.
|
|
126
|
+
The end-to-end tests are out of reach, since they need a build and a
|
|
127
|
+
browser; CI runs them.
|
|
128
|
+
|
|
129
|
+
**Verify before you post** in every case. A finding that a minute with the
|
|
130
|
+
repository would disprove is noise.
|
|
131
|
+
|
|
132
|
+
## How to post
|
|
133
|
+
|
|
134
|
+
Each High or Medium finding about specific lines is one inline comment, made with
|
|
135
|
+
`mcp__github_inline_comment__create_inline_comment` with `confirmed: true`
|
|
136
|
+
on the right-hand side of the diff. In each one:
|
|
137
|
+
|
|
138
|
+
- Start with a severity: **High** (a user-visible defect, or a test that
|
|
139
|
+
hides one) or **Medium** (maintainability, a rule broken). A **Low** goes
|
|
140
|
+
in the summary, never inline: an inline comment opens a thread, and the
|
|
141
|
+
merge waits on every thread.
|
|
142
|
+
- Say what is wrong, why it matters here, and the fix.
|
|
143
|
+
- Include a ```suggestion block only when the fix is a drop-in replacement
|
|
144
|
+
for exactly the lines the comment covers. It replaces the whole range, so
|
|
145
|
+
get the indentation and every line right. Otherwise describe the fix.
|
|
146
|
+
- Do not put an HTML comment in an inline comment. The tool strips it, and
|
|
147
|
+
a suggestion block that quoted one would commit the line without it.
|
|
148
|
+
|
|
149
|
+
Then post exactly one summary with `gh pr comment`, whatever you found:
|
|
150
|
+
|
|
151
|
+
- A one-line verdict: ready to merge, or not.
|
|
152
|
+
- Findings that are not about specific lines, such as a missing test, or
|
|
153
|
+
something across several files, and every Low, marked as one.
|
|
154
|
+
- Any earlier rejection you still disagree with, and why.
|
|
155
|
+
- If you found nothing, say so in one line.
|
|
156
|
+
- End with the verdict marker, on a line of its own, then
|
|
157
|
+
`<!-- claude-review sha=HEAD_SHA -->`, using the head SHA you were given.
|
|
158
|
+
The next review starts from it.
|
|
159
|
+
- `<!-- review-verdict: ready -->` only when your one-line verdict is ready
|
|
160
|
+
to merge: no High or Medium finding, inline or in the summary, still
|
|
161
|
+
needs a change, and you dispute no earlier rejection. A Low never holds
|
|
162
|
+
the verdict.
|
|
163
|
+
- `<!-- review-verdict: changes -->` in every other case.
|
|
164
|
+
|
|
165
|
+
A workflow reads the marker for this commit and posts it as the
|
|
166
|
+
`Review verdict` status, which the merge requires. Write exactly one, and
|
|
167
|
+
never `ready` in a summary whose verdict is not.
|
|
168
|
+
|
|
169
|
+
Do not approve or request changes, and do not post anything except these
|
|
170
|
+
comments.
|
package/rules.md
ADDED
|
@@ -0,0 +1,313 @@
|
|
|
1
|
+
# The factory's rules
|
|
2
|
+
|
|
3
|
+
The process rules that hold in any repository the factory builds.
|
|
4
|
+
`CLAUDE.md` imports this file, and says what is the repository's own under
|
|
5
|
+
a heading of the same name with ": this repository" added. Where the two
|
|
6
|
+
differ, `CLAUDE.md` wins.
|
|
7
|
+
|
|
8
|
+
Tickets are read and written only through `npx --no-install factory ticket`,
|
|
9
|
+
and a pull request's conversation comments and labels through
|
|
10
|
+
`factory pr`, so the rules and skills hold whatever the ticket system.
|
|
11
|
+
|
|
12
|
+
## Small changes
|
|
13
|
+
|
|
14
|
+
A change is small when it changes under about 30 lines outside tests,
|
|
15
|
+
specs, and content, and adds no component and no state, whether or not a
|
|
16
|
+
visitor sees it: a style tweak, a bug fix, a link, or a line of copy. Its
|
|
17
|
+
size decides, not its kind; content the repository reviews by what changed
|
|
18
|
+
instead is named in "Small changes: this repository" in `CLAUDE.md`. A
|
|
19
|
+
follow-ups build is sized by its lines: when every line is small, its one
|
|
20
|
+
review is a small one. The process around a small change has cost far
|
|
21
|
+
more than the change: on one ticket, under 20 changed lines took a 27
|
|
22
|
+
minute read by the UI reviewer and an 8 minute `factory-ticket-readiness`
|
|
23
|
+
read, and on another one link took an OpenSpec change, eight mutations, and
|
|
24
|
+
two reviewers.
|
|
25
|
+
|
|
26
|
+
This section is the one statement of the small path; other guides point
|
|
27
|
+
here rather than restate it.
|
|
28
|
+
|
|
29
|
+
- **Say the size first.** The first message of the work names the path,
|
|
30
|
+
such as "small: one test, red first, one UI reviewer read", so the
|
|
31
|
+
owner can overrule it before the work starts rather than halfway through.
|
|
32
|
+
- **No `spec` label**, even when a visitor sees it: the issue's acceptance
|
|
33
|
+
criteria are the spec. No OpenSpec change either, unless the change makes
|
|
34
|
+
a line of `openspec/specs/` false, as renaming a label a spec quotes
|
|
35
|
+
would. That issue also carries a Spec section of the changed line, and
|
|
36
|
+
the build archives a proposal and spec delta in the same pull request,
|
|
37
|
+
which then waits for the owner. A fix that restores what a spec says
|
|
38
|
+
changes no line of it.
|
|
39
|
+
- **No `factory-ticket-readiness` read and no `factory-test-reviewer` read**, with two
|
|
40
|
+
exceptions that keep `factory-test-reviewer`: a change to tests alone, the one
|
|
41
|
+
kind it exists for, and code that builds what is sent to an outside
|
|
42
|
+
service, which "Small changes: this repository" in `CLAUDE.md` names,
|
|
43
|
+
since a broken payload loses data without a sound.
|
|
44
|
+
- **Tests.** A bug fix gets one test that reproduces the defect. A style
|
|
45
|
+
tweak gets one only when it sets what a check in the repository's design
|
|
46
|
+
guide measures, which "Small changes: this repository" in `CLAUDE.md`
|
|
47
|
+
names, preferably as one assertion added to an existing test; any other
|
|
48
|
+
look change gets no new test, and the review's screenshots are its
|
|
49
|
+
check. Any other small change, such as a link or a script's behavior,
|
|
50
|
+
gets one test that checks it.
|
|
51
|
+
- **One proof per test** that it can fail: its red run before the change,
|
|
52
|
+
or for a test written after, one mutation, the edit that undoes the
|
|
53
|
+
change, not one per way the code could break. A script proves each
|
|
54
|
+
behavior this way: script defects here have been silent data loss.
|
|
55
|
+
- **Choices.** One that is not layout, such as which page, what label, or
|
|
56
|
+
what it links to, is asked in plain English, saying what a visitor would
|
|
57
|
+
see. A layout or style choice gets no mockup round: build the
|
|
58
|
+
recommendation, put the UI reviewer's screenshots of it in the pull
|
|
59
|
+
request body, and leave the pull request a draft for the owner to mark
|
|
60
|
+
ready once they have seen it, since a page change can otherwise merge
|
|
61
|
+
itself.
|
|
62
|
+
- For a visible change, a UI reviewer read pointed at the states the change
|
|
63
|
+
touched, not every size and scheme, and told the change is small. The UI
|
|
64
|
+
reviewer is `factory-ui-reviewer` where the repository lists it, and
|
|
65
|
+
otherwise the repository's own, among its reviewer plug-ins
|
|
66
|
+
(`npx --no-install factory plugins reviewer`).
|
|
67
|
+
- The gate and CI stay. The pull request says it took this path.
|
|
68
|
+
|
|
69
|
+
## Branching, pushing, and review
|
|
70
|
+
|
|
71
|
+
`main` is protected: no direct pushes, no bypass, CI must pass, and every
|
|
72
|
+
review thread must be resolved before a merge. Work accordingly rather than
|
|
73
|
+
discovering it at push time.
|
|
74
|
+
|
|
75
|
+
- **Never commit on `main`.** If `main` is checked out, create a branch from
|
|
76
|
+
the latest origin/main first and say which branch you made. Reuse the
|
|
77
|
+
current feature branch when one is already checked out; a feature usually
|
|
78
|
+
spans several commits.
|
|
79
|
+
- **Push the branch after each coherent change.** Small commits are the point;
|
|
80
|
+
do not batch a session's work into one.
|
|
81
|
+
- **Open pull requests as drafts, and mark them ready once.** A draft gets
|
|
82
|
+
no automated review, so it costs nothing while work continues. Every push
|
|
83
|
+
to a PR that is marked ready triggers a billed review, so the session that
|
|
84
|
+
built it, wherever it ran, marks it ready once: when the gate passes,
|
|
85
|
+
everything is pushed, GitHub shows the pushed commit as the head, and
|
|
86
|
+
every CI run on it has passed or been skipped
|
|
87
|
+
(`npx --no-install factory pr wait-checks N`, then
|
|
88
|
+
`npx --no-install factory pr ready N`).
|
|
89
|
+
It stays a draft for the owner to mark ready in two cases: a small change
|
|
90
|
+
whose build made a layout or style choice, with the UI reviewer's
|
|
91
|
+
screenshots in the body ("Small changes" above), and a pull request the
|
|
92
|
+
owner has said they want to see first. A skill that runs as parallel
|
|
93
|
+
slices, which cannot stay to work a review, leaves its own a draft too.
|
|
94
|
+
CI runs the full suite on a draft for free, so a session runs only the
|
|
95
|
+
end-to-end specs it added or changed.
|
|
96
|
+
- **The session that built a PR watches it until it merges or closes.** It
|
|
97
|
+
has the context to fix what comes in. The desktop app's PR monitor does not
|
|
98
|
+
connect in local sessions here, so once the PR is ready, or left a draft
|
|
99
|
+
for the owner to mark ready (above), a local session runs `npx --no-install factory pr watch N` in the background. That exits when a
|
|
100
|
+
check fails, a review or comment lands, or a conflict appears, which wakes
|
|
101
|
+
the session. Work what it reports, then run it again, until it prints
|
|
102
|
+
`merged` or `closed`. A session that stops watching an open PR first runs
|
|
103
|
+
it with `--release`. A run in GitHub Actions, which nothing can wake
|
|
104
|
+
later, works its review under `factory-address-review`, waiting with
|
|
105
|
+
`npx --no-install factory pr state N --wait`, and does not run it, since
|
|
106
|
+
nothing can wake it once it stops.
|
|
107
|
+
- **A pull request that resolves an issue closes it.** When asked to open
|
|
108
|
+
one, start the body with `Closes #N` for each issue the branch resolves,
|
|
109
|
+
so the merge closes them. Check that GitHub registered the link.
|
|
110
|
+
- **After pushing, check for review automatically.** The `Claude review`
|
|
111
|
+
workflow reviews every push to a PR. If an open PR exists for the branch,
|
|
112
|
+
wait for the review of that push, then work it with the `factory-address-review` skill
|
|
113
|
+
without being asked. If no PR exists yet, say so in one line: review begins
|
|
114
|
+
when the user opens one.
|
|
115
|
+
- **A conflict with main is fixed through the `factory-resolve-conflicts` skill.** Its
|
|
116
|
+
sweep runs after each merge into main and nightly, on every ready pull
|
|
117
|
+
request that conflicts, and a session working a pull request with
|
|
118
|
+
`factory-address-review` runs its conflict fix before anything else. When the two
|
|
119
|
+
sides contradict, it pushes nothing, comments why, and opens an issue.
|
|
120
|
+
- **An issue is built in GitHub Actions by moving its card to Ready** on
|
|
121
|
+
the board, the GitHub Project whose number
|
|
122
|
+
`npx --no-install factory config get tickets.board` prints: the
|
|
123
|
+
`ready-poller` worker dispatches the "Factory build" workflow within
|
|
124
|
+
about a minute, the same run that `npx --no-install factory build N`
|
|
125
|
+
starts by hand. A local build starts by telling a session to work the
|
|
126
|
+
issue.
|
|
127
|
+
The poller skips a card whose blocker is open and starts it within a
|
|
128
|
+
minute of the blocker closing. A card moves only forward on its own,
|
|
129
|
+
except the follow-ups issue when a pull request merged part of it,
|
|
130
|
+
which goes to Backlog: a
|
|
131
|
+
build that ends without a merge stays In progress, and a finished
|
|
132
|
+
refinement stays In refinement, both "Waiting on you", and nothing
|
|
133
|
+
retries on its own. The board-sync workflow alone writes Status,
|
|
134
|
+
Session, and Runs in, with one exception: a local session moves the
|
|
135
|
+
card to Ready with `npx --no-install factory ticket ready N` when the
|
|
136
|
+
owner asks it to. `npx --no-install factory status` shows the
|
|
137
|
+
same in the terminal.
|
|
138
|
+
- **No thread stays unresolved.** The ruleset blocks a merge while any review
|
|
139
|
+
thread is open. Each one ends fixed, or rejected with evidence, and
|
|
140
|
+
resolved. After two rounds, whatever is still in dispute goes to the user
|
|
141
|
+
rather than through another round.
|
|
142
|
+
- Report the branch, what was pushed, and the state of any threads. Never
|
|
143
|
+
claim a review is clean when none has run yet.
|
|
144
|
+
- **Say where unfinished work lives.** When a turn ends with uncommitted
|
|
145
|
+
changes, or commits on a branch with no open PR, the last line names the
|
|
146
|
+
branch and says which. Work has been lost by sitting on a branch the user
|
|
147
|
+
thought was already in a PR.
|
|
148
|
+
|
|
149
|
+
## What merges without the owner
|
|
150
|
+
|
|
151
|
+
A pull request merges itself only when the merge-policy workflow labels it
|
|
152
|
+
`merge: automatic` and every gate passes on its newest commit,
|
|
153
|
+
`Review verdict` included. The agents' own rules always wait for the
|
|
154
|
+
owner. Its `Who merges` status in the checks list says which, and why.
|
|
155
|
+
|
|
156
|
+
Agents never merge, enable auto-merge, or add the `verdict: override`
|
|
157
|
+
label, the owner's pass of the verdict for one commit; `factory pr label`
|
|
158
|
+
and `factory ticket label` refuse it, and the guard hook stops the ordinary
|
|
159
|
+
ways of adding it around them. Both workflows run from main's copy,
|
|
160
|
+
so a pull request cannot change how it is judged, and changes to them are
|
|
161
|
+
always the owner's.
|
|
162
|
+
|
|
163
|
+
## Spec track
|
|
164
|
+
|
|
165
|
+
The spec track applies only when
|
|
166
|
+
`npx --no-install factory config get specs` prints `openspec`. Then the GitHub
|
|
167
|
+
issue is the spec: `factory-refine` writes it, the owner approves it by
|
|
168
|
+
moving its card to Ready or telling a session to build it, and
|
|
169
|
+
`factory-build` turns it into an OpenSpec change, builds it, and archives it
|
|
170
|
+
into `openspec/specs/` in the same pull request. `openspec/specs/` is the
|
|
171
|
+
current description of what the repository does; a change to it starts by
|
|
172
|
+
reading its spec.
|
|
173
|
+
|
|
174
|
+
A change that adds or alters behavior a visitor can see carries the
|
|
175
|
+
`spec` label, which `factory-refine` adds, unless it is small ("Small
|
|
176
|
+
changes" above). Everything else, such as copy, bug fixes that
|
|
177
|
+
restore intended behavior, style tweaks, tooling, CI, and docs, builds
|
|
178
|
+
from the issue's "Acceptance criteria" with no spec files and no "For the
|
|
179
|
+
builder" section, since the area's `CLAUDE.md` says how it is built. A
|
|
180
|
+
small change that makes a spec line false is the one exception ("Small
|
|
181
|
+
changes" above). Neither skill removes `spec` or adds it back once
|
|
182
|
+
the owner removed it: both act through the owner's GitHub account, so a
|
|
183
|
+
label already decided is the owner's call.
|
|
184
|
+
|
|
185
|
+
OpenSpec collects anonymous usage statistics unless told not to. Run it with
|
|
186
|
+
`DO_NOT_TRACK=1`.
|
|
187
|
+
|
|
188
|
+
## Issues that wait on another
|
|
189
|
+
|
|
190
|
+
A build order stated only in prose is one nothing reads: the poller starts
|
|
191
|
+
a build within a minute of a card moving to Ready, and it and `factory-build`
|
|
192
|
+
stop only on a recorded relationship. So whoever opens or refines an issue records each
|
|
193
|
+
blocker as a blocked-by relationship, and says why in the issue's
|
|
194
|
+
body (under Decisions, for a refined issue).
|
|
195
|
+
|
|
196
|
+
An issue is blocked by another when building it first would break it, or
|
|
197
|
+
would mean redoing work. Touching the same file does not count: that is a
|
|
198
|
+
merge conflict, and the `factory-resolve-conflicts` conflict sweep resolves those.
|
|
199
|
+
|
|
200
|
+
To record that issue N is blocked by issue M, list what N waits on, and
|
|
201
|
+
remove one, in any session:
|
|
202
|
+
|
|
203
|
+
```bash
|
|
204
|
+
npx --no-install factory ticket block N --by M
|
|
205
|
+
npx --no-install factory ticket blockers N
|
|
206
|
+
npx --no-install factory ticket unblock N --by M
|
|
207
|
+
```
|
|
208
|
+
|
|
209
|
+
`blockers` prints one line per ticket N waits on, its number and whether
|
|
210
|
+
it is open. A ticket system without blockers says so: check with
|
|
211
|
+
`npx --no-install factory ticket supports blockers`.
|
|
212
|
+
|
|
213
|
+
## Follow-ups
|
|
214
|
+
|
|
215
|
+
A follow-up is something noticed while doing other work: a reviewer finding
|
|
216
|
+
the builder left for the owner, a defect spotted out of scope, a symptom
|
|
217
|
+
from a review session, or a check to run later. One issue per follow-up once
|
|
218
|
+
sent twenty of them through the full refine, label, build, and merge path
|
|
219
|
+
in one day, while one follow-ups build made eight of them one pull request.
|
|
220
|
+
|
|
221
|
+
So a follow-up is a line on the open follow-ups issue, not an issue of its
|
|
222
|
+
own. There is at most one open follow-ups issue, titled "Follow-ups" and
|
|
223
|
+
labeled `follow-up`, holding a checklist. A line leads with the file or
|
|
224
|
+
page it is about:
|
|
225
|
+
|
|
226
|
+
```
|
|
227
|
+
- [ ] <file or page>: <what is wrong, as a visitor or a maintainer sees it>. Found by <who> while building #N. <The rule it breaks, by its section in the guide that states it (an area's guide under "Rules by area" in CLAUDE.md, CLAUDE.md, or this file), or "Needs a decision: <the question>".>
|
|
228
|
+
```
|
|
229
|
+
|
|
230
|
+
It is added with the file and the rest of the line as two arguments, and
|
|
231
|
+
the script opens the issue when none is open:
|
|
232
|
+
|
|
233
|
+
```bash
|
|
234
|
+
npx --no-install factory follow-up FILE "What is wrong. Found by WHO while building #N. The rule it breaks."
|
|
235
|
+
```
|
|
236
|
+
|
|
237
|
+
A reviewer that does not know the issue or pull request number writes
|
|
238
|
+
`#N` as it stands, and whoever appends the line fills it in.
|
|
239
|
+
|
|
240
|
+
A placeholder or tag name in issue or comment text, such as `<slug>` or
|
|
241
|
+
`<code>`, goes in backticks: GitHub drops an unknown tag and renders a
|
|
242
|
+
real one. `factory ticket edit`, `comment`, and `open`, and
|
|
243
|
+
`factory pr comment`, refuse a body that has one bare, and name it. A
|
|
244
|
+
hook refuses the same in text sent to GitHub directly, as the
|
|
245
|
+
`factory guard ticket-text` command describes.
|
|
246
|
+
|
|
247
|
+
- A line whose fix the guides determine, such as a target under its floor,
|
|
248
|
+
a contrast failure, a test that cannot fail, or a stale sentence, needs
|
|
249
|
+
no refinement: it is buildable as written.
|
|
250
|
+
- A line whose fix the guides do not determine says "Needs a decision:"
|
|
251
|
+
with the question, and `factory-refine` asks only about those lines. A
|
|
252
|
+
builder that meets such a line without the phrase adds it and leaves
|
|
253
|
+
the line unchecked.
|
|
254
|
+
- A follow-up gets its own issue only when it would need the `spec` label,
|
|
255
|
+
because it adds or alters behavior a visitor can see, or would make a
|
|
256
|
+
line of `openspec/specs/` false. A request from the owner is always its
|
|
257
|
+
own issue.
|
|
258
|
+
- The `factory-resolve-conflicts` conflict stop keeps opening its own issue: which side
|
|
259
|
+
wins is the owner's decision, and nothing else records it.
|
|
260
|
+
|
|
261
|
+
The follow-ups issue builds as one branch and one pull request, one commit
|
|
262
|
+
per line, once the owner approves it, by moving its card to Ready or
|
|
263
|
+
telling a session to build it. The pull request closes it with `Closes #N`
|
|
264
|
+
only when every line is checked; otherwise it starts with `Part of #N`,
|
|
265
|
+
and the unchecked lines wait there. The sync reads `Part of #N` as a
|
|
266
|
+
partial build, so any other link to the follow-ups issue words it
|
|
267
|
+
differently. It has no OpenSpec change. `factory-build` appends a line and
|
|
268
|
+
builds the issue; `factory-refine` refines it per line. Its lines can be
|
|
269
|
+
about anything, so the one pull request waits for the owner when any line
|
|
270
|
+
touches a file that does, and gets the fresh-agent trace ("Changing the
|
|
271
|
+
process") when any line edits a rule.
|
|
272
|
+
|
|
273
|
+
**Not everything noticed is a follow-up.** What breaks no rule in the
|
|
274
|
+
guides, and what a visitor or a maintainer would not notice without
|
|
275
|
+
measuring, gets no line and no fix. Once, every line left on a follow-ups
|
|
276
|
+
issue came from reviewing the previous batch's fixes, including a 1 px
|
|
277
|
+
jump, and each line's fix was reviewed in turn, so the list kept refilling
|
|
278
|
+
itself. A Low review
|
|
279
|
+
finding the builder left undone is not a follow-up either.
|
|
280
|
+
|
|
281
|
+
## Changing the process
|
|
282
|
+
|
|
283
|
+
The factory's skills, agents, rules, review instructions, and workflows
|
|
284
|
+
under `.claude/` and `.github/` are copies, written by `factory sync` from
|
|
285
|
+
the factory's package. Change the source in the package, run
|
|
286
|
+
`npx --no-install factory sync`, and commit both: the gate and CI fail
|
|
287
|
+
when a copy differs from its source.
|
|
288
|
+
|
|
289
|
+
A rule written for the change in front of its author can be wrong for
|
|
290
|
+
every other kind. Once, the step that adds the `spec` label kept adding
|
|
291
|
+
it to small changes after the table that defines the label stopped, and
|
|
292
|
+
"content is never small" would have sent a typo fix through two reviewer
|
|
293
|
+
agents. So a change to `CLAUDE.md`, this file, a skill, an agent,
|
|
294
|
+
`.github/factory-review.md`, `.github/review-notes.md`, a workflow,
|
|
295
|
+
`openspec/config.yaml`, the settings in `.claude/factory.yaml`, or the
|
|
296
|
+
code that decides what runs and who merges (the factory's own commands,
|
|
297
|
+
and the scripts "Changing the process: this
|
|
298
|
+
repository" in `CLAUDE.md` names)
|
|
299
|
+
that alters what triggers a step, who runs or when,
|
|
300
|
+
gets a read from a fresh agent before its pull request is marked
|
|
301
|
+
ready. Give it the branch and `.claude/change-types.md`. It traces each
|
|
302
|
+
kind through the rules as they will stand, and reports a kind that got
|
|
303
|
+
heavier, lighter, or ambiguous, and any two rules that now disagree. Fix
|
|
304
|
+
what holds up. A change to wording alone needs no trace.
|
|
305
|
+
|
|
306
|
+
## Stepping back from a rabbit hole
|
|
307
|
+
|
|
308
|
+
When one function or file has taken three or more rounds of corrective
|
|
309
|
+
work for the same class of defect, stop fixing it. Write down what the
|
|
310
|
+
custom code does that matters, which maintained library covers it, and
|
|
311
|
+
what that library would not cover, and whether that gap is still the
|
|
312
|
+
reason for the custom code, before touching it again. Re-read a "we had
|
|
313
|
+
to build this" comment before trusting it.
|