@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/docs/glossary.md
ADDED
|
@@ -0,0 +1,106 @@
|
|
|
1
|
+
# Glossary
|
|
2
|
+
|
|
3
|
+
The words these docs use, in plain terms. The factory works through a few
|
|
4
|
+
kinds of tool, each behind one interface, and these pages name the kind,
|
|
5
|
+
not the tool. Where a word stands for a tool, its entry says which one it
|
|
6
|
+
is today.
|
|
7
|
+
|
|
8
|
+
## The tools
|
|
9
|
+
|
|
10
|
+
**Code host.** Where your repository lives, with its pull requests, their
|
|
11
|
+
reviews, the checks on each commit, and the secrets your CI reads. Today:
|
|
12
|
+
GitHub. `code-host.type` names it.
|
|
13
|
+
|
|
14
|
+
**Ticket system.** Where your tickets live. Today: GitHub Issues.
|
|
15
|
+
`tickets.type` names it.
|
|
16
|
+
|
|
17
|
+
**Board.** A view of every ticket's state, one column per state, which the
|
|
18
|
+
factory keeps up to date. Optional. Today: a GitHub Project.
|
|
19
|
+
|
|
20
|
+
**Cloud runner.** Where work runs with no one at a keyboard: cloud builds,
|
|
21
|
+
the automated review, the board sync, and the factory's other CI jobs.
|
|
22
|
+
Today: GitHub Actions. `builds.runner` names it.
|
|
23
|
+
|
|
24
|
+
**Coding agent.** The AI tool that runs sessions: it reads your code,
|
|
25
|
+
follows the factory's skills, and writes the change. Today: Claude Code.
|
|
26
|
+
|
|
27
|
+
## The words
|
|
28
|
+
|
|
29
|
+
**Acceptance criteria.** The list in a ticket that says what "done" means,
|
|
30
|
+
written so each item can be checked. Refining a ticket produces it.
|
|
31
|
+
|
|
32
|
+
**Agent (reviewer).** A separate reviewer that a session launches to read
|
|
33
|
+
something and report back. It changes nothing. The factory brings three,
|
|
34
|
+
and you can add your own.
|
|
35
|
+
|
|
36
|
+
**Approver.** A person whose comments a session treats as instructions,
|
|
37
|
+
and who can approve a ticket for building. By default, the repository's
|
|
38
|
+
owner.
|
|
39
|
+
|
|
40
|
+
**Automated review.** A review of every pull request by the coding agent,
|
|
41
|
+
run in CI once the pull request is marked ready. It comments on what it
|
|
42
|
+
finds and gives a verdict. Optional.
|
|
43
|
+
|
|
44
|
+
**Board sync.** The job that sets each ticket's column and fields on the
|
|
45
|
+
board. It is the only thing that writes to the board.
|
|
46
|
+
|
|
47
|
+
**Build.** One session taking one approved ticket to a pull request.
|
|
48
|
+
|
|
49
|
+
**Claim.** A comment a session posts on a ticket before it starts, so no
|
|
50
|
+
other session builds the same one.
|
|
51
|
+
|
|
52
|
+
**Cloud build.** A build that runs on the cloud runner instead of your
|
|
53
|
+
machine. You start one with a command, or by moving a ticket to Ready on
|
|
54
|
+
your board.
|
|
55
|
+
|
|
56
|
+
**Copied files.** The factory's skills, agents, rules, and CI workflows,
|
|
57
|
+
written into your repository by `factory sync`. You do not
|
|
58
|
+
edit them.
|
|
59
|
+
|
|
60
|
+
**Dependency bot.** A tool that opens pull requests when a dependency has
|
|
61
|
+
a new version.
|
|
62
|
+
|
|
63
|
+
**Follow-ups ticket.** One ordinary ticket whose body is a checklist of
|
|
64
|
+
small problems sessions noticed while doing other work.
|
|
65
|
+
|
|
66
|
+
**Gate.** The commands that must pass before a session calls a task done,
|
|
67
|
+
such as your tests and linter. Yours, named in your instructions for the
|
|
68
|
+
agent; without any, a session checks with the tests it wrote.
|
|
69
|
+
|
|
70
|
+
**Hook.** A command the coding agent runs at a set moment in a session,
|
|
71
|
+
such as before a shell command. The factory uses hooks to block risky
|
|
72
|
+
commits.
|
|
73
|
+
|
|
74
|
+
**Local session.** A session on your own machine.
|
|
75
|
+
|
|
76
|
+
**Marker.** A hidden line in a comment the factory posts on a ticket,
|
|
77
|
+
recording what happened. The board is worked out from these.
|
|
78
|
+
|
|
79
|
+
**OpenSpec.** A tool that keeps a written description of what a project
|
|
80
|
+
does, in the repository. Optional.
|
|
81
|
+
|
|
82
|
+
**Plug-in.** One of your own skills or agents that the factory calls at a
|
|
83
|
+
set moment.
|
|
84
|
+
|
|
85
|
+
**Poller.** A small program that watches your board and starts a cloud
|
|
86
|
+
build for each ticket moved to Ready.
|
|
87
|
+
|
|
88
|
+
**Refine.** To turn a ticket into acceptance criteria, settling the
|
|
89
|
+
decisions with you along the way.
|
|
90
|
+
|
|
91
|
+
**Review verdict.** A status on a pull request that says whether the
|
|
92
|
+
automated review of the newest commit found it ready.
|
|
93
|
+
|
|
94
|
+
**Session.** One conversation with the coding agent in your repository, on
|
|
95
|
+
your machine or in the cloud.
|
|
96
|
+
|
|
97
|
+
**Skill.** A set of instructions a session follows, named `factory-...`
|
|
98
|
+
for the factory's own. You call one by asking a session in plain words,
|
|
99
|
+
such as "refine ticket 12".
|
|
100
|
+
|
|
101
|
+
**Spec.** A written statement of what a change must do. For most tickets
|
|
102
|
+
that is the acceptance criteria. With OpenSpec turned on, a change your
|
|
103
|
+
users will see also gets its behavior recorded in the repository.
|
|
104
|
+
|
|
105
|
+
**Ticket.** One item in the ticket system: a piece of work, with what,
|
|
106
|
+
why, and when it is done.
|
|
@@ -0,0 +1,115 @@
|
|
|
1
|
+
# Limitations
|
|
2
|
+
|
|
3
|
+
What the factory does not do, what it assumes that nobody has tested, and
|
|
4
|
+
the risks that come with it. Read this before relying on it.
|
|
5
|
+
|
|
6
|
+
The limits that come from today's tools rather than from the factory, such
|
|
7
|
+
as a code host's billing or what its workflows can see, are in
|
|
8
|
+
[the GitHub and Claude Code reference](github/reference.md#limits).
|
|
9
|
+
|
|
10
|
+
## What it does not do
|
|
11
|
+
|
|
12
|
+
- **One tool of each kind.** The factory reaches the code host, the ticket
|
|
13
|
+
system, the board, and the cloud runner each through one interface, and
|
|
14
|
+
the settings name which one you use (`code-host.type`, `tickets.type`,
|
|
15
|
+
and `builds.runner`). Each has one implementation today, GitHub's, and no
|
|
16
|
+
other is planned. The skills are written for one coding agent, Claude
|
|
17
|
+
Code. [The glossary](glossary.md) says which tool each word means today.
|
|
18
|
+
- **It needs Node and a `package.json`,** even in a repository written in
|
|
19
|
+
another language.
|
|
20
|
+
- **A build never changes the coding agent's settings files,** which hold
|
|
21
|
+
the hooks that guard the run. It may write the factory's other files
|
|
22
|
+
there. A change to those settings is a person's to make.
|
|
23
|
+
- **One ticket, one repository.** A change that spans repositories is two
|
|
24
|
+
tickets.
|
|
25
|
+
- **It is written for one approver.** `approvers` lets a team list several
|
|
26
|
+
people (_[Planned](developing.md#what-is-built)_), but review by teams, required reviewers per folder, and monorepos
|
|
27
|
+
with several owners are not designed.
|
|
28
|
+
- **The order of the workflow is fixed.** You can turn written specs off and
|
|
29
|
+
add reviewers. You cannot add a state or reorder them.
|
|
30
|
+
- **On a board with no refining column, a ticket cannot be sent back to the
|
|
31
|
+
backlog by moving its card.** The card already shows in the backlog column
|
|
32
|
+
while a ticket is being refined, so the move says nothing.
|
|
33
|
+
- **The UI reviewer needs Playwright.** The repository installs it, and its
|
|
34
|
+
browser.
|
|
35
|
+
- **It cannot see a page behind a sign-in.** It compares one site at one
|
|
36
|
+
address.
|
|
37
|
+
- **What the measurements do not cover.** Elements that overlap or are cut
|
|
38
|
+
off, and how far a page moves while it loads, are for the pictures and the
|
|
39
|
+
agent. The contrast of a control's edge is not measured, since axe-core has
|
|
40
|
+
no rule for it. Frames inside a page are left out, and so is a view whose
|
|
41
|
+
pictures did not change. axe-core's target size is WCAG 2.5.8's 24 px, not a
|
|
42
|
+
larger floor of your own.
|
|
43
|
+
- **A state that takes a click to reach is the agent's to drive,** not the
|
|
44
|
+
command's.
|
|
45
|
+
- **No budgets.** What each ticket cost is recorded. Nothing caps it.
|
|
46
|
+
- **Without the global install, the command needs `--no-install`.**
|
|
47
|
+
Another package on npm is called `factory`. Where this one is not
|
|
48
|
+
installed, `npx` without `--no-install` offers to download and run that
|
|
49
|
+
one instead, so `npx --no-install factory` fails rather than run another
|
|
50
|
+
package.
|
|
51
|
+
- **Nothing retries on its own.** A build that stops waits for you.
|
|
52
|
+
- **A cloud build's commits are unsigned unless you give it a signing
|
|
53
|
+
key.** [Signed commits from cloud builds](github/setup.md#signed-commits-from-cloud-builds)
|
|
54
|
+
says how.
|
|
55
|
+
- **A cloud build cannot be steered.** You can read its log as it runs, and
|
|
56
|
+
cancel it, but not answer it: where it would ask, it stops and reports.
|
|
57
|
+
- **Nothing watches a pull request after its cloud build ends.** Your own
|
|
58
|
+
review comments are answered by a session you open, or by a cloud session
|
|
59
|
+
started for your review, which has only the pull request and the ticket
|
|
60
|
+
to go on.
|
|
61
|
+
- **A cloud build runs for up to 230 minutes by default**
|
|
62
|
+
([`session-minutes`](configuration.md#session-minutes)), and its minutes
|
|
63
|
+
may cost money, depending on your cloud runner and plan.
|
|
64
|
+
|
|
65
|
+
## What nobody has tested
|
|
66
|
+
|
|
67
|
+
- **A board owned by an organization.** It is read the same way as a
|
|
68
|
+
person's, but the factory has only run against a person's.
|
|
69
|
+
- **Your board's own automations,** such as moving a closed ticket to Done.
|
|
70
|
+
They may fight the board sync.
|
|
71
|
+
- **Installing an unpublished or private package** in CI and from a
|
|
72
|
+
dependency bot.
|
|
73
|
+
- **Glob patterns standing in for today's regular expressions** in the
|
|
74
|
+
merge policy. They could match differently. The switch compares the old and new
|
|
75
|
+
decision on recent pull requests.
|
|
76
|
+
- **A scheduled job as the poller,** including what it costs.
|
|
77
|
+
- **Windows.** The tool and its hooks need only Node, but nothing here has
|
|
78
|
+
been run on Windows.
|
|
79
|
+
- **Adding the factory's columns to a board you already have.**
|
|
80
|
+
- **Whether your coding agent's plan permits automated builds this way.**
|
|
81
|
+
The automated review runs on a subscription token in the one repository
|
|
82
|
+
that uses it. Check your plan's terms.
|
|
83
|
+
|
|
84
|
+
## What was tested, and found not to work
|
|
85
|
+
|
|
86
|
+
- **Node will not run TypeScript from inside `node_modules`.** A published
|
|
87
|
+
package has to ship compiled JavaScript.
|
|
88
|
+
|
|
89
|
+
## Risks that do not go away
|
|
90
|
+
|
|
91
|
+
- **"Universal" is a guess until a second repository uses it.** Everything
|
|
92
|
+
here was drawn out of one repository.
|
|
93
|
+
- **A session acts as you.** That is the design: your agent writes the
|
|
94
|
+
commits, and they go out under your account. It also means the guard
|
|
95
|
+
against a session approving its own work is a tripwire, not a lock. Your
|
|
96
|
+
read of the pull request is the control.
|
|
97
|
+
- **The skills are prose, and prose is hard to test.** A change of wording
|
|
98
|
+
changes behavior in every repository that updates. The checks are a traced
|
|
99
|
+
read by a fresh agent, one real ticket, and your read of the update.
|
|
100
|
+
- **Rules that need judgment cannot be enforced.** CI can require that a
|
|
101
|
+
reviewer ran or was skipped with a reason. It cannot check the reason was
|
|
102
|
+
a good one.
|
|
103
|
+
- **It amplifies the checks it is given.** A repository with weak tests gets
|
|
104
|
+
confident, wrong pull requests faster.
|
|
105
|
+
- **Ticket text, review comments, and changelogs are read by sessions.**
|
|
106
|
+
Only an approver's comments are treated as instructions, and that rests on
|
|
107
|
+
one account's login.
|
|
108
|
+
- **An update delivers instructions that run with your tokens.** Read update
|
|
109
|
+
pull requests as carefully as code.
|
|
110
|
+
- **The poller keeps its hourly cap in memory.** A restart forgets how many
|
|
111
|
+
builds it started in the last hour.
|
|
112
|
+
- **It sits on tools that change.** Several parts work around how today's
|
|
113
|
+
coding agent and code host behave.
|
|
114
|
+
- **Publishing cannot be undone.** A public release needs a history and
|
|
115
|
+
examples free of the host repository's private tickets first.
|
package/docs/plugins.md
ADDED
|
@@ -0,0 +1,192 @@
|
|
|
1
|
+
# Plug-ins
|
|
2
|
+
|
|
3
|
+
The factory knows how to refine, build, and review a ticket. It does not
|
|
4
|
+
know your project. A plug-in is one of your own skills or agents that the
|
|
5
|
+
factory calls at a set moment, so what only your project knows is part of
|
|
6
|
+
every build.
|
|
7
|
+
|
|
8
|
+
## The idea
|
|
9
|
+
|
|
10
|
+
You write a skill or an agent the way your coding agent expects one, in
|
|
11
|
+
the folder it reads them from
|
|
12
|
+
([on Claude Code](github/reference.md#skills-in-claude-code)). Then you add
|
|
13
|
+
a few lines to `.claude/factory.yaml` saying what job it does:
|
|
14
|
+
|
|
15
|
+
```yaml
|
|
16
|
+
plugins:
|
|
17
|
+
- agent: migration-reviewer
|
|
18
|
+
role: reviewer
|
|
19
|
+
files:
|
|
20
|
+
- db/migrations/**
|
|
21
|
+
```
|
|
22
|
+
|
|
23
|
+
That is the whole of it. The factory never copies over your files, and an
|
|
24
|
+
update never touches them.
|
|
25
|
+
|
|
26
|
+
## The three roles
|
|
27
|
+
|
|
28
|
+
A role is a moment in the workflow where the factory hands off. There are
|
|
29
|
+
three. A repository can have several plug-ins in one role, or none.
|
|
30
|
+
|
|
31
|
+
### `reviewer`
|
|
32
|
+
|
|
33
|
+
Reads a finished change and reports problems.
|
|
34
|
+
|
|
35
|
+
| | |
|
|
36
|
+
| ------------------- | -------------------------------------------------------------------------------------------- |
|
|
37
|
+
| **Called** | By `factory-build`, after the change is built and before the pull request opens |
|
|
38
|
+
| **Considered when** | The change touches a file matching one of its `files` patterns |
|
|
39
|
+
| **Handed** | The branch, and which files changed |
|
|
40
|
+
| **Returns** | Findings, each with where it is and why it matters. It changes nothing |
|
|
41
|
+
| **Then** | The building session fixes what holds up, and the pull request says what each reviewer found |
|
|
42
|
+
|
|
43
|
+
Good candidates: database migrations, anything touching authentication or
|
|
44
|
+
payments, a public API that must stay backward compatible, accessibility
|
|
45
|
+
of your components, copy that has to follow a style guide.
|
|
46
|
+
|
|
47
|
+
### `mockups`
|
|
48
|
+
|
|
49
|
+
Makes pictures to choose from when a decision changes how something looks.
|
|
50
|
+
|
|
51
|
+
A repository with `site` in its settings has one already: the factory's
|
|
52
|
+
own `factory-design` skill, which `factory sync` writes, is its `mockups`
|
|
53
|
+
plug-in unless you list one of your own with this role.
|
|
54
|
+
|
|
55
|
+
| | |
|
|
56
|
+
| --------------- | ----------------------------------------------------------------------------------- |
|
|
57
|
+
| **Called** | By `factory-refine`, when one of the decisions it would bring you is about the look |
|
|
58
|
+
| **Handed** | The ticket and the decision |
|
|
59
|
+
| **Returns** | Screenshots of each option, with one recommended |
|
|
60
|
+
| **Then** | You choose, and the choice goes into the ticket |
|
|
61
|
+
| **Without one** | The decision is described in words |
|
|
62
|
+
|
|
63
|
+
### `builder`
|
|
64
|
+
|
|
65
|
+
Builds a kind of ticket the general build would do badly.
|
|
66
|
+
|
|
67
|
+
| | |
|
|
68
|
+
| ------------- | -------------------------------------------------------------------------- |
|
|
69
|
+
| **Called** | By `factory-build`, in place of its own build step |
|
|
70
|
+
| **Used when** | The ticket carries one of its `labels` |
|
|
71
|
+
| **Handed** | The ticket, already claimed, on its branch |
|
|
72
|
+
| **Returns** | The change, and a report for the pull request body |
|
|
73
|
+
| **Then** | `factory-build` carries on as usual: reviewers, the gate, the pull request |
|
|
74
|
+
|
|
75
|
+
Good candidates: work your project always does the same way, such as a new
|
|
76
|
+
API endpoint with its route, handler, schema, and docs, or a new
|
|
77
|
+
translation added to every locale file.
|
|
78
|
+
|
|
79
|
+
## `files` filters; the agent decides
|
|
80
|
+
|
|
81
|
+
`files` answers "could this reviewer matter here?" It cannot answer "does
|
|
82
|
+
it?" That judgment belongs in the agent's own description, the lines at the
|
|
83
|
+
top of its file that say when to use it:
|
|
84
|
+
|
|
85
|
+
```yaml
|
|
86
|
+
---
|
|
87
|
+
name: migration-reviewer
|
|
88
|
+
description: >-
|
|
89
|
+
Use when a change adds or alters a database migration's SQL or schema
|
|
90
|
+
operations. Not for a change to comments or formatting alone.
|
|
91
|
+
---
|
|
92
|
+
```
|
|
93
|
+
|
|
94
|
+
So a change that only fixes a typo in a migration's comment matches the
|
|
95
|
+
reviewer's files, and the building session, reading that description,
|
|
96
|
+
skips it. It says so in the pull request:
|
|
97
|
+
|
|
98
|
+
```text
|
|
99
|
+
migration-reviewer: skipped, only a comment changed.
|
|
100
|
+
```
|
|
101
|
+
|
|
102
|
+
Every matched reviewer ends up with either a run or a line like that. You
|
|
103
|
+
read the skips when you read the pull request.
|
|
104
|
+
|
|
105
|
+
**Write the description as a condition.** "Reviews database migrations"
|
|
106
|
+
says what the agent is. "Use when a change adds or alters a migration's
|
|
107
|
+
SQL" says when to call it, which is what the factory needs.
|
|
108
|
+
|
|
109
|
+
## A worked example
|
|
110
|
+
|
|
111
|
+
A team runs a web application with a large database. A migration can pass
|
|
112
|
+
every test and still take the site down: it locks a busy table, or drops a
|
|
113
|
+
column the code still running in production reads. No test catches that.
|
|
114
|
+
So the team has an agent, `migration-reviewer`, that reads a migration the
|
|
115
|
+
way their most careful database engineer would.
|
|
116
|
+
|
|
117
|
+
**1. The agent** is an ordinary agent file of the team's coding agent,
|
|
118
|
+
named `migration-reviewer`. Its description says when it applies. Its body says what to check: can it be rolled back, will it lock
|
|
119
|
+
a large table, and does it still work with the code that is live while it
|
|
120
|
+
runs.
|
|
121
|
+
|
|
122
|
+
**2. The settings** name it:
|
|
123
|
+
|
|
124
|
+
```yaml
|
|
125
|
+
plugins:
|
|
126
|
+
- agent: migration-reviewer
|
|
127
|
+
role: reviewer
|
|
128
|
+
files:
|
|
129
|
+
- db/migrations/**
|
|
130
|
+
```
|
|
131
|
+
|
|
132
|
+
**3. A session builds a ticket** that removes an unused column.
|
|
133
|
+
`factory-build` sees the change touched `db/migrations/`, reads the
|
|
134
|
+
reviewer's description, finds it applies, and launches it. The agent
|
|
135
|
+
reports that the live code still selects that column, so the migration
|
|
136
|
+
would break requests during the deploy. The session splits the work: this
|
|
137
|
+
change stops reading the column, and a follow-up drops it.
|
|
138
|
+
|
|
139
|
+
**4. The pull request** says: "`migration-reviewer`: one finding, the
|
|
140
|
+
column is still read by the running code. Split into two changes."
|
|
141
|
+
|
|
142
|
+
A second ticket fixes a typo in a migration's comment. The files match
|
|
143
|
+
again, the description does not, and the pull request says:
|
|
144
|
+
"`migration-reviewer`: skipped, only a comment changed."
|
|
145
|
+
|
|
146
|
+
The team's rules for what makes a migration safe stay in their own
|
|
147
|
+
instructions for the agent and in the agent itself. The factory holds none of them.
|
|
148
|
+
|
|
149
|
+
## Adding one
|
|
150
|
+
|
|
151
|
+
1. Write the skill or agent, and try it by hand until it does its job.
|
|
152
|
+
2. Give it a description that states when it applies.
|
|
153
|
+
3. Add it under `plugins` with its `role`, and `files` or `labels`.
|
|
154
|
+
4. Run `factory config check`. It fails if the file is missing or the
|
|
155
|
+
role is not one of the three.
|
|
156
|
+
5. Run `factory plugins` to see the list the factory will use.
|
|
157
|
+
|
|
158
|
+
No sync is needed. Plug-ins are read from your settings each time.
|
|
159
|
+
|
|
160
|
+
## What is not a plug-in
|
|
161
|
+
|
|
162
|
+
- **A skill you call yourself.** If nothing in refining, building, or
|
|
163
|
+
reviewing a ticket should call it, it needs no entry. It stays an
|
|
164
|
+
ordinary skill.
|
|
165
|
+
- **A skill another of your skills calls.** A reviewer that only your own
|
|
166
|
+
`builder` launches is that builder's business.
|
|
167
|
+
- **A rule.** "Migrations always wait for me" is `auto-merge`. "Every
|
|
168
|
+
migration needs a rollback" is a sentence in your project's instructions
|
|
169
|
+
for the agent.
|
|
170
|
+
|
|
171
|
+
## The UI reviewer
|
|
172
|
+
|
|
173
|
+
`factory-ui-reviewer` ships with the factory and is written to any repository
|
|
174
|
+
with `site` in its settings, but runs only where it is listed:
|
|
175
|
+
|
|
176
|
+
```yaml
|
|
177
|
+
plugins:
|
|
178
|
+
- agent: factory-ui-reviewer
|
|
179
|
+
role: reviewer
|
|
180
|
+
files:
|
|
181
|
+
- src/**
|
|
182
|
+
- public/**
|
|
183
|
+
```
|
|
184
|
+
|
|
185
|
+
It needs the `site` settings, which say how to start the website.
|
|
186
|
+
|
|
187
|
+
## Sharing plug-ins between repositories
|
|
188
|
+
|
|
189
|
+
Not planned. A plug-in lives in the repository that uses it. A way to
|
|
190
|
+
package a set of them, such as a design skill and a visual reviewer for
|
|
191
|
+
any website, and install it in several repositories is designed for but
|
|
192
|
+
not scheduled.
|
|
@@ -0,0 +1,222 @@
|
|
|
1
|
+
# Quick start
|
|
2
|
+
|
|
3
|
+
From nothing to a pull request built from one of your tickets. You run a
|
|
4
|
+
few commands, write one ticket, and answer a question or two; your coding
|
|
5
|
+
agent does the rest. This page needs no board, no secrets, and nothing to
|
|
6
|
+
host.
|
|
7
|
+
|
|
8
|
+
A word you do not know is in the [glossary](glossary.md). A step marked
|
|
9
|
+
_[Planned](developing.md#what-is-built)_ is not built yet, and says what to
|
|
10
|
+
do until then.
|
|
11
|
+
|
|
12
|
+
## You need
|
|
13
|
+
|
|
14
|
+
- A repository on a supported code host, cloned on your machine, with the
|
|
15
|
+
code host's command-line tool signed in.
|
|
16
|
+
- A supported coding agent, signed in.
|
|
17
|
+
- Node 22.18 or later. Check with `node --version`.
|
|
18
|
+
|
|
19
|
+
Which tools are supported, and how to check each is ready, is in
|
|
20
|
+
[What you need](github/setup.md#what-you-need) on the GitHub page.
|
|
21
|
+
|
|
22
|
+
Your repository does not have to be JavaScript. If it is not, read
|
|
23
|
+
[this section](existing-repo.md#a-repository-that-is-not-javascript)
|
|
24
|
+
first: installing adds a small `package.json`.
|
|
25
|
+
|
|
26
|
+
## 1. Install
|
|
27
|
+
|
|
28
|
+
_[Planned](developing.md#what-is-built)._ Until the package is published,
|
|
29
|
+
it cannot be installed outside the repository it is developed in.
|
|
30
|
+
|
|
31
|
+
Once on your machine, so you can type `factory`:
|
|
32
|
+
|
|
33
|
+
```bash
|
|
34
|
+
npm install -g @davidbyoung/software-factory
|
|
35
|
+
```
|
|
36
|
+
|
|
37
|
+
Then in your repository, which keeps its own version:
|
|
38
|
+
|
|
39
|
+
```bash
|
|
40
|
+
npm install --save-dev @davidbyoung/software-factory
|
|
41
|
+
```
|
|
42
|
+
|
|
43
|
+
**It worked when** `factory`, run in your repository, prints the list of
|
|
44
|
+
its commands. It exits non-zero, since no command was given; that is
|
|
45
|
+
expected.
|
|
46
|
+
|
|
47
|
+
## 2. Set it up
|
|
48
|
+
|
|
49
|
+
```bash
|
|
50
|
+
factory init
|
|
51
|
+
```
|
|
52
|
+
|
|
53
|
+
It says what it found, asks which optional parts you want, and shows
|
|
54
|
+
everything it will do before it does any of it. For this first ticket,
|
|
55
|
+
uncheck every part: the basics need none.
|
|
56
|
+
|
|
57
|
+
Told to go ahead, it writes your settings file, `.claude/factory.yaml`,
|
|
58
|
+
and the instructions your coding agent follows when it works a ticket. It
|
|
59
|
+
adds hooks: small checks your agent runs on its own, such as refusing a
|
|
60
|
+
commit on your main branch. It adds one line to your agent's instructions
|
|
61
|
+
file, such as `CLAUDE.md`, and the hooks to your agent's settings,
|
|
62
|
+
creating either file if you have none. It changes nothing else of yours,
|
|
63
|
+
and commits nothing. [What it changes](removing.md) lists every item and
|
|
64
|
+
how to undo it.
|
|
65
|
+
|
|
66
|
+
**It worked when** the checks it prints last all show ✓. Run them again at
|
|
67
|
+
any time with `factory doctor`.
|
|
68
|
+
|
|
69
|
+
**To do it by hand instead,** write the shortest settings file, with your
|
|
70
|
+
repository's owner and name, then write the factory's files:
|
|
71
|
+
|
|
72
|
+
```yaml
|
|
73
|
+
version: 1
|
|
74
|
+
repository: your-name/your-repo
|
|
75
|
+
```
|
|
76
|
+
|
|
77
|
+
```bash
|
|
78
|
+
factory sync
|
|
79
|
+
```
|
|
80
|
+
|
|
81
|
+
A build checks its change with the commands your agent's instructions
|
|
82
|
+
file names, such as your tests and your linter, so say there how to check
|
|
83
|
+
a change. Without any, it checks with the tests it wrote.
|
|
84
|
+
|
|
85
|
+
To have a command run before every commit a session makes, such as your
|
|
86
|
+
linter, list it under `before-commit` in the settings file:
|
|
87
|
+
|
|
88
|
+
```yaml
|
|
89
|
+
before-commit:
|
|
90
|
+
- npm run lint
|
|
91
|
+
```
|
|
92
|
+
|
|
93
|
+
## 3. Merge the setup
|
|
94
|
+
|
|
95
|
+
Commit what `sync` wrote on a branch, push it, then open a pull request for
|
|
96
|
+
it on your code host, as for any change, and merge it:
|
|
97
|
+
|
|
98
|
+
```bash
|
|
99
|
+
git switch -c set-up-factory
|
|
100
|
+
git add -A
|
|
101
|
+
git commit -m "Set up the software factory"
|
|
102
|
+
git push -u origin set-up-factory
|
|
103
|
+
```
|
|
104
|
+
|
|
105
|
+
Then bring your main branch up to date:
|
|
106
|
+
|
|
107
|
+
```bash
|
|
108
|
+
git switch main
|
|
109
|
+
git pull
|
|
110
|
+
```
|
|
111
|
+
|
|
112
|
+
Your coding agent loads the factory from the files in your repository, so
|
|
113
|
+
start a new session after this step.
|
|
114
|
+
|
|
115
|
+
**It worked when** the new session, asked which skills it has, lists
|
|
116
|
+
`factory-refine` and `factory-build`. A skill is a set of instructions for
|
|
117
|
+
one kind of job, such as refining a ticket.
|
|
118
|
+
|
|
119
|
+
## 4. Open a ticket
|
|
120
|
+
|
|
121
|
+
A ticket in your ticket system. Say three things: what you want, why, and
|
|
122
|
+
how you will know it is done. A few sentences is enough.
|
|
123
|
+
|
|
124
|
+
```text
|
|
125
|
+
Title: Show the opening hours in the footer
|
|
126
|
+
|
|
127
|
+
The hours are only on the contact page, and people ask for them.
|
|
128
|
+
Done when: every page's footer shows the same hours the contact page does.
|
|
129
|
+
```
|
|
130
|
+
|
|
131
|
+
Note its number. This page uses 12.
|
|
132
|
+
|
|
133
|
+
## 5. Refine it
|
|
134
|
+
|
|
135
|
+
In a session of your coding agent, in your repository, say:
|
|
136
|
+
|
|
137
|
+
```text
|
|
138
|
+
refine ticket 12
|
|
139
|
+
```
|
|
140
|
+
|
|
141
|
+
The session reads the ticket and the code it touches. Then it asks you the
|
|
142
|
+
decisions that are yours, each as a choice with its recommendation first:
|
|
143
|
+
|
|
144
|
+
```text
|
|
145
|
+
Where should the hours come from?
|
|
146
|
+
1. The settings file the contact page already reads (Recommended)
|
|
147
|
+
2. A new footer-only setting
|
|
148
|
+
```
|
|
149
|
+
|
|
150
|
+
**It worked when** the ticket ends with acceptance criteria, a checklist
|
|
151
|
+
that says exactly what "done" means, and the session says it is ready to
|
|
152
|
+
build.
|
|
153
|
+
|
|
154
|
+
## 6. Build it
|
|
155
|
+
|
|
156
|
+
In the same session, or a new one:
|
|
157
|
+
|
|
158
|
+
```text
|
|
159
|
+
build ticket 12
|
|
160
|
+
```
|
|
161
|
+
|
|
162
|
+
Telling a session to build a ticket is how you approve it.
|
|
163
|
+
|
|
164
|
+
You can watch it work. The session:
|
|
165
|
+
|
|
166
|
+
1. comments on the ticket that it has claimed it, so no other session
|
|
167
|
+
builds the same one;
|
|
168
|
+
2. makes a branch;
|
|
169
|
+
3. writes a test, then the change;
|
|
170
|
+
4. checks each commit with your `before-commit` commands, if you set any;
|
|
171
|
+
5. opens a pull request that closes the ticket, as a draft, which tells
|
|
172
|
+
people and the automated review it is not finished;
|
|
173
|
+
6. marks it ready for review once your CI passes on it, or after two
|
|
174
|
+
minutes when no CI runs on it, and answers any review it gets.
|
|
175
|
+
|
|
176
|
+
**It worked when** its last message names the pull request, says what it
|
|
177
|
+
built, and says how it checked it. Expect minutes, not seconds.
|
|
178
|
+
|
|
179
|
+
## 7. Read it and merge
|
|
180
|
+
|
|
181
|
+
Open the pull request. Its description says what changed, how it was
|
|
182
|
+
verified, and anything the session noticed and left alone. Nothing merges
|
|
183
|
+
without you.
|
|
184
|
+
|
|
185
|
+
To ask for changes, comment on the pull request, then tell a session to
|
|
186
|
+
answer your comments:
|
|
187
|
+
|
|
188
|
+
```text
|
|
189
|
+
address the review on pull request 15
|
|
190
|
+
```
|
|
191
|
+
|
|
192
|
+
That is the whole loop: **ticket, refine, build, read, merge.**
|
|
193
|
+
|
|
194
|
+
## If something goes wrong
|
|
195
|
+
|
|
196
|
+
| What happened | What to do |
|
|
197
|
+
| ------------------------------------------------ | ------------------------------------------------------------------------------------------- |
|
|
198
|
+
| A `before-commit` command fails during the build | Nothing. The session sees the output, fixes the cause, and tries again |
|
|
199
|
+
| The session stops and says it needs you | It says why, in the session and on the ticket. Answer, then ask it to build ticket 12 again |
|
|
200
|
+
| The session was closed or crashed partway | Ask a new session to build ticket 12. It picks up the branch it made |
|
|
201
|
+
| You want to change what was decided | Ask a session to refine ticket 12 again, or edit the ticket |
|
|
202
|
+
| CI fails on the pull request | Ask a session to address the review on pull request 15. It reads the failure and fixes it |
|
|
203
|
+
| The session does not know the factory's skills | The setup is not merged, or the session started before it was. See step 3 |
|
|
204
|
+
| Anything else | Run `factory doctor`. It says what is wrong, and what to do about it |
|
|
205
|
+
|
|
206
|
+
## What to add next
|
|
207
|
+
|
|
208
|
+
Everything above runs on your machine while you watch. Each part below is
|
|
209
|
+
optional, stands alone, and can come later.
|
|
210
|
+
|
|
211
|
+
| Add | So that | It asks of you |
|
|
212
|
+
| ----------------------------------- | -------------------------------------------------------------------- | --------------------------------------------- |
|
|
213
|
+
| An automated review | Every pull request is read by your coding agent before you read it | Your agent's token, stored on the code host |
|
|
214
|
+
| A board | You see every ticket's state, which session has it, and what it cost | A board, and a token that can write to it |
|
|
215
|
+
| Builds in the cloud | A ticket builds with no session open on your machine | Your agent's token, and a token that can push |
|
|
216
|
+
| Builds that start from the board | Moving a ticket to Ready builds it | A small program, the poller, that you host |
|
|
217
|
+
| Pull requests that merge themselves | Changes to files you list as safe do not wait for you | The list of files, and a token that can merge |
|
|
218
|
+
| Your own reviewers | A change to your content or your design is read by an expert agent | A few lines of settings |
|
|
219
|
+
|
|
220
|
+
Run `factory init` again and turn on the parts you want;
|
|
221
|
+
it sets up each one, tokens included. [Setting up on GitHub](github/setup.md)
|
|
222
|
+
has the same steps by hand, on one page.
|