@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/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
|
-
#
|
|
1
|
+
# Software factory
|
|
2
2
|
|
|
3
|
-
|
|
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.
|