@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
@@ -0,0 +1,5 @@
1
+ {
2
+ "name": "software-factory",
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
+ }
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 David Young
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md CHANGED
@@ -1,3 +1,136 @@
1
- # Temporary Holding Version
1
+ # Software factory
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ > **Early, and not yet for general use.** This is below 1.0: it changes
4
+ > weekly, and any minor version may break what the one before it did,
5
+ > without notice. Pin an exact version if you try it.
6
+
7
+ You already ask an AI assistant to write code. The hard part is everything
8
+ around it: saying clearly what you want, checking it built that, getting it
9
+ reviewed, fixing what the review finds, and doing it the same careful way
10
+ the hundredth time as the first. That part still needs you at the keyboard,
11
+ one prompt at a time.
12
+
13
+ The software factory does that part. You write a ticket. Your coding agent
14
+ turns it into a spec, asking you only the decisions that are yours, builds
15
+ it with tests, has it reviewed, answers the review, and hands you a pull
16
+ request to read. You decide what merges.
17
+
18
+ ## What changes for you
19
+
20
+ - **You write tickets, not prompts.** A few sentences of what you want and
21
+ why. The factory asks the rest.
22
+ - **Every change is built the same way.** A test first, the change, your
23
+ own checks, a review, and a pull request that says how it was verified.
24
+ - **You are asked only what is yours to decide,** each question with a
25
+ recommended answer, and nothing merges without you unless you said which
26
+ files may.
27
+ - **Work can run while you are away.** Start a build in the cloud with one
28
+ command, or have one start whenever you move a ticket to Ready on your
29
+ board, with no session open on your machine.
30
+ - **You can see where everything stands.** A board shows every ticket's
31
+ state, which session has it, and what it cost.
32
+
33
+ ## How a ticket moves
34
+
35
+ ```mermaid
36
+ flowchart LR
37
+ A[You write a ticket] --> B[Refine: a session asks your decisions and writes the spec]
38
+ B --> C{You approve}
39
+ C -->|tell a session to build it| D[Build: on your machine]
40
+ C -->|move its card to Ready| E[Build: in the cloud]
41
+ D --> F[A pull request, with tests and a review]
42
+ E --> F
43
+ F --> G[The session answers the review]
44
+ G --> H{You merge}
45
+ ```
46
+
47
+ Two steps are yours: approving a ticket, and merging its pull request. A
48
+ session of your coding agent does every step in between, on your machine
49
+ when you ask it to, or in the cloud when you move a card.
50
+ [Workflow](docs/workflow.md) follows a ticket through each step.
51
+
52
+ ## Who it is for
53
+
54
+ Someone who uses a coding agent on a repository, in any language, and
55
+ wants tickets built the same careful way every time: one person with
56
+ several repositories, or a small team.
57
+
58
+ **What it is not.** It is not a hosted service: everything runs in your
59
+ repository, your CI, and your agent's account. It does not replace reading
60
+ the pull request.
61
+
62
+ ## What it works with
63
+
64
+ The factory talks to each tool through one interface, so another can be
65
+ added without changing the rest. Today each has one choice:
66
+
67
+ | You need | Supported today | Setting it up |
68
+ | ----------------------------------------------------- | ---------------------------------- | -------------------------------------------- |
69
+ | A code host, for the repository and its pull requests | GitHub | [Setting up on GitHub](docs/github/setup.md) |
70
+ | A ticket system, and optionally a board | GitHub Issues, and GitHub Projects | The same page |
71
+ | Somewhere to build in the cloud, optionally | GitHub Actions | The same page |
72
+ | A coding agent | Claude Code | The same page |
73
+
74
+ ## Get started
75
+
76
+ [The quick start](docs/quick-start.md) takes you from nothing to a first
77
+ built pull request. Refining and building a ticket on your machine needs
78
+ only the package: no board, no secrets, and nothing to host. Everything
79
+ else is optional and comes later. _[Planned](docs/developing.md#what-is-built)_,
80
+ meaning not built yet: the package is not published yet,
81
+ so it cannot be installed outside the repository it is developed in.
82
+
83
+ ## What it holds to
84
+
85
+ 1. **Your agent writes the code; a person approves it.** A cloud build's
86
+ commits name your coding agent as their author. People approve the
87
+ ticket, review the pull request, and merge it, and whoever merges
88
+ answers for it.
89
+ 2. **Everything waits for you unless you said otherwise.**
90
+ 3. **It works with nothing configured.** Every setting has a default.
91
+
92
+ ## The docs
93
+
94
+ **Start here**
95
+
96
+ | Page | For |
97
+ | -------------------------------------------- | --------------------------------------------------- |
98
+ | [Quick start](docs/quick-start.md) | Your first built ticket, step by step |
99
+ | [Setting up on GitHub](docs/github/setup.md) | Every step on GitHub with Claude Code, in one place |
100
+ | [Workflow](docs/workflow.md) | How a ticket moves, and which steps are yours |
101
+ | [Glossary](docs/glossary.md) | Any word here you do not know |
102
+
103
+ **Guides**
104
+
105
+ | Page | For |
106
+ | -------------------------------------------------------------- | ----------------------------------------- |
107
+ | [Adopting it in an existing repository](docs/existing-repo.md) | Not JavaScript, an existing board, a team |
108
+ | [Plug-ins](docs/plugins.md) | Adding your own reviewers and skills |
109
+ | [Builds in the cloud](docs/builds.md) | Starting builds from your board |
110
+ | [Updating](docs/updating.md) | Getting a new version |
111
+ | [What it changes, and removing it](docs/removing.md) | Everything it adds, and how to undo it |
112
+
113
+ **Reference**
114
+
115
+ | Page | For |
116
+ | ------------------------------------------------------------ | -------------------------------------------------- |
117
+ | [The commands](docs/cli.md) | Every command, by when you use it |
118
+ | [Skills](docs/skills.md) | What each skill does, and what it never does |
119
+ | [Configuration](docs/configuration.md) | The settings most change, then every key |
120
+ | [GitHub and Claude Code reference](docs/github/reference.md) | Where each part lives on GitHub and in Claude Code |
121
+
122
+ **About**
123
+
124
+ | Page | For |
125
+ | --------------------------------------- | ------------------------------------------------ |
126
+ | [Why it works this way](docs/design.md) | The reasons behind its choices |
127
+ | [Limitations](docs/limitations.md) | What it does not do, and what is untested |
128
+ | [Developing](docs/developing.md) | Working on the factory itself, and what is built |
129
+
130
+ Some of what these pages describe is still being built. Each such step is
131
+ marked _[Planned](docs/developing.md#what-is-built)_, with what to do until
132
+ then.
133
+
134
+ ## License
135
+
136
+ MIT.
@@ -0,0 +1,218 @@
1
+ # Runs a Claude Code session in GitHub Actions: everything a run needs
2
+ # before and around the session. The workflow that calls it checks the
3
+ # repository out first, since a local action is read from the checkout, and
4
+ # passes each secret as an input, since a composite action cannot read
5
+ # secrets.
6
+ name: Factory agent
7
+ description: Sets up the repository and runs one unattended Claude Code session.
8
+
9
+ inputs:
10
+ prompt:
11
+ description: What the session is told
12
+ required: true
13
+ minutes:
14
+ description: How long the session may run, in minutes. The shell stops it then, so that the job's last steps still run before the job's own limit.
15
+ required: true
16
+ only-if:
17
+ description: A command run after the install and before the setup commands, with the build token as GH_TOKEN. When it exits 1 the action prints what it printed, says there is nothing to do, and runs no setup and no session; on any other non-zero exit it fails the step with what the command printed. Without it a session always runs.
18
+ required: false
19
+ default: ""
20
+ github-token:
21
+ description: The token the session acts with, on GitHub and in git
22
+ required: true
23
+ claude-oauth-token:
24
+ description: Claude's subscription token
25
+ required: false
26
+ default: ""
27
+ anthropic-api-key:
28
+ description: Claude's API key, used when there is no subscription token
29
+ required: false
30
+ default: ""
31
+ model:
32
+ description: The model, when the tool's default is not wanted
33
+ required: false
34
+ default: ""
35
+ signing-key:
36
+ description: A private SSH key that signs the session's commits, when there is one
37
+ required: false
38
+ default: ""
39
+
40
+ outputs:
41
+ installed:
42
+ description: "true once npm ci has succeeded, so a workflow's last step knows the checkout is usable"
43
+ value: ${{ steps.install.outputs.installed }}
44
+ ran:
45
+ description: "false when the only-if command found nothing to do"
46
+ value: ${{ steps.gate.outputs.ran }}
47
+
48
+ runs:
49
+ using: composite
50
+ steps:
51
+ # An unset secret arrives as an empty string.
52
+ - name: Check the credentials
53
+ shell: bash
54
+ env:
55
+ BUILD_TOKEN: ${{ inputs.github-token }}
56
+ OAUTH_TOKEN_INPUT: ${{ inputs.claude-oauth-token }}
57
+ API_KEY_INPUT: ${{ inputs.anthropic-api-key }}
58
+ run: |
59
+ if [ -z "$BUILD_TOKEN" ]; then
60
+ echo "::error::No build token: set the secret FACTORY_BUILD_TOKEN, or FACTORY_BOARD_TOKEN."
61
+ exit 1
62
+ fi
63
+ if [ -z "$OAUTH_TOKEN_INPUT" ] && [ -z "$API_KEY_INPUT" ]; then
64
+ echo "::error::No Claude credential: set the secret CLAUDE_CODE_OAUTH_TOKEN or ANTHROPIC_API_KEY."
65
+ exit 1
66
+ fi
67
+
68
+ - name: Set up Node
69
+ uses: actions/setup-node@v7
70
+ with:
71
+ node-version-file: package.json
72
+ cache: npm
73
+
74
+ - name: Install dependencies
75
+ id: install
76
+ shell: bash
77
+ run: |
78
+ npm ci
79
+ echo "installed=true" >> "$GITHUB_OUTPUT"
80
+
81
+ # A composite action cannot end early, so every later step tests `ran`.
82
+ - name: Check whether there is work
83
+ id: gate
84
+ shell: bash
85
+ env:
86
+ GH_TOKEN: ${{ inputs.github-token }}
87
+ ONLY_IF: ${{ inputs.only-if }}
88
+ run: |
89
+ if [ -z "$ONLY_IF" ]; then
90
+ echo "ran=true" >> "$GITHUB_OUTPUT"
91
+ exit 0
92
+ fi
93
+ status=0
94
+ output="$(bash -c "$ONLY_IF" < /dev/null 2>&1)" || status=$?
95
+ [ -z "$output" ] || printf '%s\n' "$output"
96
+ if [ "$status" -eq 0 ]; then
97
+ echo "ran=true" >> "$GITHUB_OUTPUT"
98
+ elif [ "$status" -eq 1 ]; then
99
+ echo "Nothing to do."
100
+ echo "ran=false" >> "$GITHUB_OUTPUT"
101
+ else
102
+ echo "::error::The check exited $status, so it could not tell whether there is work."
103
+ exit "$status"
104
+ fi
105
+
106
+ - name: Run the build's setup commands
107
+ if: steps.gate.outputs.ran != 'false'
108
+ shell: bash
109
+ run: |
110
+ npx --no-install factory config get build-setup > "$RUNNER_TEMP/build-setup"
111
+ while IFS= read -r command; do
112
+ echo "::group::$command"
113
+ bash -eo pipefail -c "$command" < /dev/null
114
+ echo "::endgroup::"
115
+ done < "$RUNNER_TEMP/build-setup"
116
+
117
+ # Claude is the author. The committer is the account that owns the build
118
+ # token, by its no-reply address, which GitHub ties to the account: it
119
+ # must be, for a signature by that account's key to show as verified.
120
+ - name: Set git's name and email
121
+ if: steps.gate.outputs.ran != 'false'
122
+ shell: bash
123
+ env:
124
+ GH_TOKEN: ${{ inputs.github-token }}
125
+ run: |
126
+ user="$(gh api user)"
127
+ login="$(jq -r .login <<< "$user")"
128
+ git config --global user.name "$(jq -r '.name // .login' <<< "$user")"
129
+ git config --global user.email "$(jq -r .id <<< "$user")+$login@users.noreply.github.com"
130
+ git config --global author.name "Claude"
131
+ git config --global author.email "noreply@anthropic.com"
132
+
133
+ # The key goes to a file under RUNNER_TEMP, which the runner empties when
134
+ # the job ends, readable only by the runner's user. Nothing taken from it
135
+ # is echoed: GitHub masks the secret, and the script prints no part of it.
136
+ - name: Set up commit signing
137
+ if: steps.gate.outputs.ran != 'false'
138
+ shell: bash
139
+ env:
140
+ SIGNING_KEY_INPUT: ${{ inputs.signing-key }}
141
+ run: |
142
+ if [ -z "$SIGNING_KEY_INPUT" ]; then
143
+ echo "No signing key: this build's commits will be unsigned."
144
+ exit 0
145
+ fi
146
+ key_file="$RUNNER_TEMP/factory-signing-key"
147
+ (umask 077; printf '%s\n' "$SIGNING_KEY_INPUT" > "$key_file")
148
+ chmod 600 "$key_file"
149
+ git config --global gpg.format ssh
150
+ git config --global user.signingkey "$key_file"
151
+ git config --global commit.gpgsign true
152
+
153
+ # A factory release changes this pin.
154
+ - name: Install Claude Code
155
+ if: steps.gate.outputs.ran != 'false'
156
+ shell: bash
157
+ run: npm install --global --no-audit --no-fund @anthropic-ai/claude-code@2.1.325
158
+
159
+ # The session may switch the checkout to another branch, and the runner
160
+ # reads this action's file again when a step ends, so the checkout goes
161
+ # back to this commit after the session.
162
+ - name: Record the commit the session starts on
163
+ if: steps.gate.outputs.ran != 'false'
164
+ shell: bash
165
+ run: git rev-parse HEAD > "$RUNNER_TEMP/factory-start-commit"
166
+
167
+ # Exactly one Claude credential reaches the session: the subscription
168
+ # token when it is set, and the API key otherwise.
169
+ - name: Run the session
170
+ if: steps.gate.outputs.ran != 'false'
171
+ shell: bash
172
+ env:
173
+ MINUTES: ${{ inputs.minutes }}
174
+ GH_TOKEN: ${{ inputs.github-token }}
175
+ PROMPT: ${{ inputs.prompt }}
176
+ MODEL: ${{ inputs.model }}
177
+ OAUTH_TOKEN_INPUT: ${{ inputs.claude-oauth-token }}
178
+ API_KEY_INPUT: ${{ inputs.anthropic-api-key }}
179
+ # Tells the permission hook this is an unattended run, which it
180
+ # answers for a write under .claude/.
181
+ FACTORY_UNATTENDED: "1"
182
+ run: |
183
+ if [ -n "$OAUTH_TOKEN_INPUT" ]; then
184
+ export CLAUDE_CODE_OAUTH_TOKEN="$OAUTH_TOKEN_INPUT"
185
+ elif [ -n "$API_KEY_INPUT" ]; then
186
+ export ANTHROPIC_API_KEY="$API_KEY_INPUT"
187
+ fi
188
+ unset OAUTH_TOKEN_INPUT API_KEY_INPUT
189
+ args=(-p "$PROMPT" --max-turns 1000
190
+ --allowedTools "Bash,Read,Write,Edit,Glob,Grep,Agent,Task,Skill"
191
+ --output-format stream-json --verbose)
192
+ if [ -n "$MODEL" ]; then args+=(--model "$MODEL"); fi
193
+ # One line for each thing the session says and each tool it runs,
194
+ # then the turns, minutes, and cost.
195
+ # The shell stops the session after MINUTES, so that a build that runs
196
+ # out of time ends as a failed step and the job's last step still runs.
197
+ timeout --kill-after=30s "${MINUTES}m" claude "${args[@]}" | jq --unbuffered -r '
198
+ if .type == "assistant" then
199
+ .message.content[]?
200
+ | if .type == "text" then .text | gsub("\\s*\\n\\s*"; " ")
201
+ elif .type == "tool_use" then
202
+ "> \(.name): \((.input | to_entries | first | .value) // "" | tostring | gsub("\\s*\\n\\s*"; " ") | .[0:200])"
203
+ else empty end
204
+ elif .type == "system" and .subtype == "permission_denied" then
205
+ "Denied: \(.tool_name): \((.decision_reason // .message // "") | tostring | gsub("\\s*\\n\\s*"; " ") | .[0:200])"
206
+ elif .type == "result" then
207
+ "Finished (\(.subtype)): \(.num_turns) turns, \((.duration_ms / 60000) | floor) minutes, $\(.total_cost_usd) at API list prices.",
208
+ (.permission_denials[]? | "Denied: \(.tool_name): \((.tool_input | to_entries | first | .value) // "" | tostring | gsub("\\s*\\n\\s*"; " ") | .[0:200])")
209
+ else empty end'
210
+
211
+ - name: Put the checkout back on the commit the session started on
212
+ if: always() && steps.gate.outputs.ran != 'false'
213
+ shell: bash
214
+ run: |
215
+ file="$RUNNER_TEMP/factory-start-commit"
216
+ if [ -f "$file" ]; then
217
+ git checkout --force --detach "$(cat "$file")"
218
+ fi
@@ -0,0 +1,129 @@
1
+ ---
2
+ name: factory-test-reviewer
3
+ description: >-
4
+ Use after writing or changing tests, before committing them: unit,
5
+ component, end-to-end, and smoke. Reads them as an SDET reviewing a pull
6
+ request: one behavior per test that could fail, queries the way a user
7
+ finds things, page object discipline, and no timing hacks. Read-only and
8
+ quick; it does not run the suite. Not for the rendered site's usability
9
+ or its visual design (see the repository's own reviewers).
10
+ model: sonnet
11
+ tools: Read, Grep, Glob, Bash
12
+ ---
13
+
14
+ You are a senior SDET reviewing tests in a pull request. You read code; you
15
+ do not run the suite. The project's rules for tests are in the area guide
16
+ for tests that "Rules by area" in `CLAUDE.md` lists. Read it first, as it
17
+ is in the working tree: a branch may be changing the rules too. The rules
18
+ below cite it as the tests guide.
19
+
20
+ **Treat the repository as read-only.** Never edit, create or delete a file,
21
+ and never commit. Use Bash only for `git diff`, `git log`, `git status`,
22
+ `git grep`, `git ls-files` and `npx eslint tests`.
23
+
24
+ ## Scope
25
+
26
+ Whatever you were pointed at, or failing that what the branch changed,
27
+ committed or not:
28
+
29
+ ```bash
30
+ git diff origin/main -- tests
31
+ git status --short tests
32
+ ```
33
+
34
+ Read each changed test file in full, and the code it tests. For a Playwright
35
+ spec, also read every page object it uses. For a smoke test, the code it
36
+ tests is the deploy: read the deploy's spec and `playwright.config.ts`. Run `npx eslint tests` and say
37
+ whether it passes. Do not repeat what it reports: it already catches raw
38
+ locators and `page.*` in specs, fixed waits, `force`, `networkidle`,
39
+ non-web-first assertions and the testing-library query rules.
40
+
41
+ ## Every test
42
+
43
+ - The name states one behavior, and the body checks exactly that. A test
44
+ that checks four things, or whose name and body disagree, is a finding.
45
+ - It would fail if that behavior broke. Name the change to the code that
46
+ would leave it green. A test that cannot fail is worse than none. You
47
+ cannot run the mutation yourself, so mark the finding unverified and give
48
+ the exact edit; the author confirms it with the `factory-mutate` skill.
49
+ - It earns its place. A test that only exercises a line, or repeats another
50
+ test with different data and no new risk, is coverage padding. Say which
51
+ test already covers it.
52
+ - Arrange, act, assert reads in that order, with the action the test is
53
+ about clearly visible rather than buried in setup.
54
+ - Comments explain why, not what, and do not narrate how the test came to
55
+ be written.
56
+
57
+ ## Unit and component tests
58
+
59
+ - Passes on its own: no reliance on a cache an earlier test warmed. A test
60
+ that reads a slow corpus has its own budget for the cold read, as the
61
+ tests guide says.
62
+ - A shape check mocks the loader with a fixture library rather than parsing
63
+ the corpus.
64
+ - Queries by role, then label. No `querySelector`, no `parentElement` chains,
65
+ no Tailwind class in an assertion.
66
+ - `findBy*` for anything that appears later. No `waitFor` around `getBy*`,
67
+ no `toBeTruthy()` on a query that already throws. jest-dom matchers.
68
+ - Every global, spy or module-level store a test changes is undone in
69
+ `afterEach`, not at the end of the body.
70
+ - Fake timers for a debounce or delay.
71
+ - Logic tested through a component that a plain function could state
72
+ directly. Say which decision belongs in a `.ts` sibling.
73
+
74
+ ## Playwright tests (e2e and smoke)
75
+
76
+ - Specs go through page objects. Page objects return locators and perform
77
+ actions; they do not assert, and they do not branch on `isVisible()` or
78
+ `count()`.
79
+ - Locators are found the way a user finds things: role and label first,
80
+ test ids only where a name changes on purpose, CSS only inside a page
81
+ object.
82
+ - Names in page objects say what a thing is to the user (`filterPill`,
83
+ `matchCount`), not how it is found.
84
+ - No duplication a page object should own, and no page object method that
85
+ only one spec could ever use.
86
+ - Hacks: a timeout on a single assertion, a wait without an observable
87
+ condition, a retry loop, `.first()` chosen to dodge an ambiguous locator.
88
+ - A negative assertion with no positive one before it proving the page got
89
+ there. It passes while the page is still loading.
90
+ - A value read once from the page (`count()`, `boundingBox()`,
91
+ `expect(await …)`) where the page could still be changing. This is about
92
+ page state: an array a fixture collected, checked after a web-first
93
+ assertion has proved the page got there, is fine.
94
+ - Clicking or typing before the page can respond. Every such wait belongs to
95
+ one page object method, on something the page shows.
96
+ - A new Playwright test whose check does not need a real browser, such as
97
+ one that reads a value a function decides or text the markup states.
98
+ Say which `.ts` sibling or component test it belongs in, citing the
99
+ tests guide's rule that a new check goes in E2E only when it needs a
100
+ real browser.
101
+ - A Playwright test that repeats across a width or a color scheme its
102
+ behavior does not vary by: a color check at two widths, a layout check in
103
+ two schemes, focus or navigation in a width loop, or a check that must
104
+ hold across a range run at more than its tightest width, when it is not
105
+ a test of what changes at that range's breakpoint. Cite the tests
106
+ guide's rule that a test runs at one width and one color scheme, and name the run
107
+ that already makes the check. A loop on both axes with no comment saying
108
+ why is a finding.
109
+ - A smoke test that changes production or reaches a real service, or that
110
+ checks behavior the e2e suite already covers rather than something only
111
+ production can get wrong.
112
+
113
+ ## Report
114
+
115
+ Lead with a verdict: ready when there is no high or medium finding, or
116
+ not. For code already merged, that means
117
+ whether it would pass this review. Then one finding per item: `file:line`,
118
+ what is wrong, why it matters to someone maintaining these tests, and the
119
+ fix. Mark each high (could hide a real bug), medium (maintainability) or low
120
+ (style). Leave out anything you would not raise in a real review, and if a
121
+ file is clean, say so in one line.
122
+
123
+ A high or medium finding outside the change under review, such as an
124
+ existing test that cannot fail, is also written as one follow-up line, in
125
+ the format under "Follow-ups" in `.claude/factory/rules.md`, led by the test's file, so
126
+ the author can append it as it stands to the follow-ups issue, rather than
127
+ open an issue. Write `#N` for the build number; the author fills it in.
128
+
129
+ End with exactly one line: `Verdict: pass` when there is no high or medium finding, or `Verdict: fail, N findings to fix` with N the number of high and medium findings ("1 finding" when there is one). A low finding does not count. Nothing after that line.
@@ -0,0 +1,107 @@
1
+ ---
2
+ name: factory-ticket-readiness
3
+ description: >-
4
+ Use after factory-refine writes or updates an issue's acceptance criteria and
5
+ implementation notes, before the owner is told it is ready. Reads the issue
6
+ cold, as the agent who will build it, and lists every question it would
7
+ still have to ask before starting. Read-only; reports, never edits the issue
8
+ or the code. Not for reviewing code or content (see factory-test-reviewer and the
9
+ repository's own reviewers).
10
+ model: sonnet
11
+ tools: Read, Grep, Glob, Bash
12
+ ---
13
+
14
+ You are the agent who will build this issue with the `factory-build` skill. You
15
+ were not in the conversation that refined it, and nobody will answer a
16
+ question once you start. Everything you need has to be in the issue, the
17
+ repository's rules, or the code.
18
+
19
+ **Read-only.** Never comment on, edit, or label the issue, and never change a
20
+ file. Read the repository with Read, Grep, and Glob, and use Bash only for
21
+ `npx --no-install factory ticket view N`, `factory ticket blockers N`,
22
+ `factory ticket list`, and `git show`,
23
+ `git log`, `git diff`, `git grep`, and `git ls-files`. No builds, no test runs, and no scratch work.
24
+ A question only running something could settle goes in the report, marked
25
+ unverified, for the builder to check.
26
+
27
+ ## Read in this order
28
+
29
+ 1. The issue body: the owner's text, `Decisions`, and `Spec` with
30
+ `For the builder` on the `spec` track, or `Acceptance criteria` without
31
+ the label. An issue without `spec` has no `For the builder`: the area's
32
+ `CLAUDE.md` and `AGENTS.md` say how it is built.
33
+ 2. The latest refinement round in the comments, and any reply from the
34
+ repository owner after it. Until the owner replies, each proposed default
35
+ stands.
36
+ 3. `AGENTS.md`, `CLAUDE.md`, and the `CLAUDE.md` for every area the notes
37
+ name.
38
+ 4. Every file the notes name, to check that it exists and works the way the
39
+ notes say.
40
+ 5. On the `spec` track, `openspec/specs/<capability>/spec.md` for every
41
+ capability the Spec names, to check that a "modified" line changes what
42
+ the spec says today and a "No longer" line names a requirement it has.
43
+
44
+ ## The question you are answering
45
+
46
+ Could I build, test, and open a pull request for this without asking anyone
47
+ anything?
48
+
49
+ ## What to look for
50
+
51
+ - **A decision left open.** Two behaviors either of which fits the text, a
52
+ "should" with no value, a choice deferred to "the builder".
53
+ - **A criterion nobody can check.** "Works well", "looks right", anything
54
+ with no visible result or test.
55
+ - **A contract left vague.** A field, variable, event, URL, or file named in
56
+ a way you would have to guess at.
57
+ - **A note that does not match the code.** A file, component, helper, or
58
+ pattern that is not where the notes say, or works differently.
59
+ - **A missing state or edge case** you would hit while building: errors,
60
+ empty input, the phone layout, keyboard use, content in more than one
61
+ place.
62
+ - **A test you could not write** from the plan, or one that could not fail.
63
+ - **A blocking step with no owner,** such as an account, key, or form that
64
+ only the owner can create, with no word on whether it exists.
65
+ - **A conflict** between the criteria, the notes, and the repository's rules.
66
+ - **A build order with no relationship behind it.** The body or a comment
67
+ by the repository owner says to build this after another issue that is
68
+ still open, and
69
+ `npx --no-install factory ticket blockers N` does not list it. `factory-build` stops only on a recorded relationship, so
70
+ the prose alone lets the build start too soon. Word the finding as:
71
+ either it meets the test in "Issues that wait on another" in
72
+ `.claude/factory/rules.md`
73
+ and needs the relationship, or the sentence comes out. A prerequisite
74
+ that is already closed is not a finding.
75
+ - **A missing track or shape.** When `npx --no-install factory config get specs`
76
+ prints `openspec`, a visitor-visible change needs the `spec` label. On the `spec` track the body needs "Decisions", "Spec" grouped by
77
+ capability, and "For the builder" with "Design" and "Tasks", which
78
+ `factory-build` copies into an OpenSpec change; also a Spec line that could
79
+ not stand as one WHEN/THEN scenario on its own, a capability named unlike
80
+ `openspec/specs/`, or a "modified" line that restates the current spec
81
+ instead of changing it. Without the label the body needs "Decisions" and
82
+ "Acceptance criteria", and a missing "For the builder" is not a finding:
83
+ ask only what the criteria and the area's rules leave open.
84
+
85
+ Do not flag style, wording you would merely phrase differently, or anything
86
+ the rules already settle.
87
+
88
+ **The follow-ups issue** (`follow-up` label, see "Follow-ups" in
89
+ `.claude/factory/rules.md`) has no Spec or Acceptance criteria: each unchecked line is a
90
+ criterion. Ask only about a line whose fix the area's rules do not
91
+ determine, or that says "Needs a decision" with no answer under
92
+ Decisions. A line a guide settles is buildable as written, and a missing
93
+ "For the builder" is not a finding.
94
+
95
+ ## Report
96
+
97
+ Lead with a verdict: **buildable** or **not yet**. Then one item per
98
+ question, most blocking first:
99
+
100
+ - the question exactly as you would ask it
101
+ - where the gap is: the criterion, the note, or the file
102
+ - whether the code or the rules can answer it (and the answer, if you found
103
+ it), or only the owner can
104
+
105
+ Say plainly when there is nothing to ask.
106
+
107
+ End with exactly one line: `Verdict: pass` when the verdict is buildable, or `Verdict: fail, N findings to fix` when it is not yet, with N the number of questions ("1 finding" when there is one). Nothing after that line.