@davidbyoung/software-factory 0.0.0-stage → 0.1.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (141) hide show
  1. package/.claude-plugin/plugin.json +5 -0
  2. package/LICENSE +21 -0
  3. package/README.md +135 -2
  4. package/actions/factory-agent/action.yml +218 -0
  5. package/agents/factory-test-reviewer.md +129 -0
  6. package/agents/factory-ticket-readiness.md +107 -0
  7. package/agents/factory-ui-reviewer.md +160 -0
  8. package/bin/factory.js +45 -0
  9. package/bin/launch.js +67 -0
  10. package/dist/board.d.mts +128 -0
  11. package/dist/board.mjs +456 -0
  12. package/dist/build.d.mts +18 -0
  13. package/dist/build.mjs +60 -0
  14. package/dist/cli.d.mts +17 -0
  15. package/dist/cli.mjs +264 -0
  16. package/dist/code-host/github.d.mts +118 -0
  17. package/dist/code-host/github.mjs +419 -0
  18. package/dist/code-host/index.d.mts +9 -0
  19. package/dist/code-host/index.mjs +18 -0
  20. package/dist/code-host/types.d.mts +205 -0
  21. package/dist/code-host/types.mjs +12 -0
  22. package/dist/config.d.mts +166 -0
  23. package/dist/config.mjs +548 -0
  24. package/dist/deps.d.mts +32 -0
  25. package/dist/deps.mjs +126 -0
  26. package/dist/doctor.d.mts +34 -0
  27. package/dist/doctor.mjs +188 -0
  28. package/dist/guard-commit.d.mts +41 -0
  29. package/dist/guard-commit.mjs +209 -0
  30. package/dist/guard-permission.d.mts +15 -0
  31. package/dist/guard-permission.mjs +52 -0
  32. package/dist/guard-ticket-text.d.mts +27 -0
  33. package/dist/guard-ticket-text.mjs +288 -0
  34. package/dist/guard.d.mts +4 -0
  35. package/dist/guard.mjs +37 -0
  36. package/dist/init.d.mts +58 -0
  37. package/dist/init.mjs +556 -0
  38. package/dist/lib/clock.d.mts +14 -0
  39. package/dist/lib/clock.mjs +36 -0
  40. package/dist/lib/gh.d.mts +28 -0
  41. package/dist/lib/gh.mjs +92 -0
  42. package/dist/lib/glob.d.mts +2 -0
  43. package/dist/lib/glob.mjs +41 -0
  44. package/dist/lib/pricing.d.mts +25 -0
  45. package/dist/lib/pricing.mjs +77 -0
  46. package/dist/lib/usage.d.mts +34 -0
  47. package/dist/lib/usage.mjs +128 -0
  48. package/dist/lib/work-status.d.mts +251 -0
  49. package/dist/lib/work-status.mjs +510 -0
  50. package/dist/merge-policy.d.mts +66 -0
  51. package/dist/merge-policy.mjs +146 -0
  52. package/dist/parts.d.mts +39 -0
  53. package/dist/parts.mjs +138 -0
  54. package/dist/poller.d.mts +61 -0
  55. package/dist/poller.mjs +247 -0
  56. package/dist/pr-watch.d.mts +45 -0
  57. package/dist/pr-watch.mjs +244 -0
  58. package/dist/pr.d.mts +65 -0
  59. package/dist/pr.mjs +571 -0
  60. package/dist/review-cost.d.mts +18 -0
  61. package/dist/review-cost.mjs +95 -0
  62. package/dist/review-tools.d.mts +5 -0
  63. package/dist/review-tools.mjs +46 -0
  64. package/dist/review-verdict.d.mts +50 -0
  65. package/dist/review-verdict.mjs +171 -0
  66. package/dist/reviewers.d.mts +54 -0
  67. package/dist/reviewers.mjs +312 -0
  68. package/dist/runner/github-actions.d.mts +12 -0
  69. package/dist/runner/github-actions.mjs +97 -0
  70. package/dist/runner/index.d.mts +9 -0
  71. package/dist/runner/index.mjs +22 -0
  72. package/dist/runner/types.d.mts +60 -0
  73. package/dist/runner/types.mjs +7 -0
  74. package/dist/session-start.d.mts +20 -0
  75. package/dist/session-start.mjs +115 -0
  76. package/dist/site/capture.d.mts +44 -0
  77. package/dist/site/capture.mjs +114 -0
  78. package/dist/site/measure.d.mts +83 -0
  79. package/dist/site/measure.mjs +225 -0
  80. package/dist/site/pages.d.mts +10 -0
  81. package/dist/site/pages.mjs +71 -0
  82. package/dist/site/pixels.d.mts +47 -0
  83. package/dist/site/pixels.mjs +157 -0
  84. package/dist/site/servers.d.mts +47 -0
  85. package/dist/site/servers.mjs +141 -0
  86. package/dist/site.d.mts +60 -0
  87. package/dist/site.mjs +341 -0
  88. package/dist/status.d.mts +100 -0
  89. package/dist/status.mjs +514 -0
  90. package/dist/sync.d.mts +59 -0
  91. package/dist/sync.mjs +292 -0
  92. package/dist/ticket.d.mts +61 -0
  93. package/dist/ticket.mjs +562 -0
  94. package/dist/tickets/github.d.mts +128 -0
  95. package/dist/tickets/github.mjs +491 -0
  96. package/dist/tickets/index.d.mts +15 -0
  97. package/dist/tickets/index.mjs +27 -0
  98. package/dist/tickets/transport.d.mts +42 -0
  99. package/dist/tickets/transport.mjs +158 -0
  100. package/dist/tickets/types.d.mts +191 -0
  101. package/dist/tickets/types.mjs +76 -0
  102. package/docs/builds.md +227 -0
  103. package/docs/cli.md +221 -0
  104. package/docs/configuration.md +809 -0
  105. package/docs/design.md +106 -0
  106. package/docs/developing.md +400 -0
  107. package/docs/existing-repo.md +138 -0
  108. package/docs/github/reference.md +288 -0
  109. package/docs/github/setup.md +312 -0
  110. package/docs/glossary.md +106 -0
  111. package/docs/limitations.md +115 -0
  112. package/docs/plugins.md +192 -0
  113. package/docs/quick-start.md +222 -0
  114. package/docs/removing.md +76 -0
  115. package/docs/skills.md +270 -0
  116. package/docs/updating.md +108 -0
  117. package/docs/workflow.md +195 -0
  118. package/package.json +67 -4
  119. package/poller.Dockerfile +21 -0
  120. package/review.md +170 -0
  121. package/rules.md +313 -0
  122. package/settings.schema.json +411 -0
  123. package/skills/factory-address-review/SKILL.md +547 -0
  124. package/skills/factory-address-review/patch-coverage.py +68 -0
  125. package/skills/factory-build/SKILL.md +412 -0
  126. package/skills/factory-deps/SKILL.md +185 -0
  127. package/skills/factory-design/SKILL.md +159 -0
  128. package/skills/factory-diagnose/SKILL.md +93 -0
  129. package/skills/factory-mutate/SKILL.md +76 -0
  130. package/skills/factory-refine/SKILL.md +417 -0
  131. package/skills/factory-resolve-conflicts/SKILL.md +235 -0
  132. package/workflows/factory-board-sync.yml +91 -0
  133. package/workflows/factory-build.yml +72 -0
  134. package/workflows/factory-check.yml +37 -0
  135. package/workflows/factory-claude-review.yml +133 -0
  136. package/workflows/factory-conflicts.yml +69 -0
  137. package/workflows/factory-deps-auto-merge.yml +43 -0
  138. package/workflows/factory-deps.yml +59 -0
  139. package/workflows/factory-merge-policy.yml +121 -0
  140. package/workflows/factory-review-verdict.yml +54 -0
  141. 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.0.0-stage",
4
- "stub": true,
5
- "description": "Temporary package placeholder for staged publishing"
6
- }
3
+ "version": "0.1.1",
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.