@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/removing.md
ADDED
|
@@ -0,0 +1,76 @@
|
|
|
1
|
+
# What it changes, and removing it
|
|
2
|
+
|
|
3
|
+
What the factory adds to your repository, your code host, and your board,
|
|
4
|
+
and how to undo it. Read this before you install, and again if you decide
|
|
5
|
+
to take it out. On GitHub with Claude Code,
|
|
6
|
+
[the reference](github/reference.md#what-setup-adds) names every file,
|
|
7
|
+
hook, label, and setting.
|
|
8
|
+
|
|
9
|
+
## What it adds
|
|
10
|
+
|
|
11
|
+
- **In your repository:** its settings file, `.claude/factory.yaml`, and a
|
|
12
|
+
lock file beside it; its own skills, agents, rules, and CI workflows, all
|
|
13
|
+
named `factory-...`; one line in your agent's instructions file that
|
|
14
|
+
imports its rules; and a few hooks in your agent's settings that guard
|
|
15
|
+
every session. If you had no `package.json`, setup adds a small one to
|
|
16
|
+
install the factory with.
|
|
17
|
+
- **On your code host:** the secrets you create for the parts you turn on;
|
|
18
|
+
the labels and statuses that say who merges a pull request and whether
|
|
19
|
+
the automated review found it ready; comments on the tickets it works;
|
|
20
|
+
and one "Follow-ups" ticket.
|
|
21
|
+
- **On your board,** if you have one: three fields, Session, Runs in, and
|
|
22
|
+
Cost, which `factory init` adds when the board lacks
|
|
23
|
+
them, and the board's own Status, which the sync sets. `init` adds any of
|
|
24
|
+
the six columns the board lacked.
|
|
25
|
+
- **Outside both,** only if builds start from your board: the poller,
|
|
26
|
+
wherever you host it.
|
|
27
|
+
|
|
28
|
+
## What it never touches
|
|
29
|
+
|
|
30
|
+
Your code, your tickets, and your pull requests. Your own skills, agents,
|
|
31
|
+
plug-ins, and CI workflows, which the factory never writes to.
|
|
32
|
+
|
|
33
|
+
Two files belong to you, and removing the factory leaves them: the CI
|
|
34
|
+
workflow that runs the automated review, which you edit to install your
|
|
35
|
+
project, and the review notes you write for it.
|
|
36
|
+
|
|
37
|
+
## Removing it _[Planned](developing.md#what-is-built)_
|
|
38
|
+
|
|
39
|
+
Until `factory remove` is built, delete by hand what
|
|
40
|
+
[the reference](github/reference.md#what-setup-adds) lists.
|
|
41
|
+
|
|
42
|
+
```bash
|
|
43
|
+
factory remove
|
|
44
|
+
```
|
|
45
|
+
|
|
46
|
+
```bash
|
|
47
|
+
npm uninstall @davidbyoung/software-factory
|
|
48
|
+
```
|
|
49
|
+
|
|
50
|
+
The first command removes everything it added to your repository and
|
|
51
|
+
prints what is left for you to remove by hand: secrets, labels, and
|
|
52
|
+
anything outside the repository. It commits nothing. Review the changes,
|
|
53
|
+
commit them on a branch, and merge.
|
|
54
|
+
|
|
55
|
+
## Before you remove it
|
|
56
|
+
|
|
57
|
+
- **If builds are running,** let them finish or stop them first. Open
|
|
58
|
+
tickets and pull requests stay exactly as they are.
|
|
59
|
+
- **If you made the review's verdict a required check** on your main
|
|
60
|
+
branch, remove that requirement first, or every pull request waits on it
|
|
61
|
+
forever.
|
|
62
|
+
- **Deleting a label removes it from every ticket.** Keep the labels if
|
|
63
|
+
you want their history.
|
|
64
|
+
- **The comments it posted on tickets stay.** They hold each ticket's
|
|
65
|
+
history.
|
|
66
|
+
|
|
67
|
+
## Undoing one part, not all of it
|
|
68
|
+
|
|
69
|
+
Each optional part can be turned off by itself. Remove its key from
|
|
70
|
+
`.claude/factory.yaml`, then:
|
|
71
|
+
|
|
72
|
+
```bash
|
|
73
|
+
factory sync
|
|
74
|
+
```
|
|
75
|
+
|
|
76
|
+
That deletes the CI workflows the part used. Delete its secret afterward.
|
package/docs/skills.md
ADDED
|
@@ -0,0 +1,270 @@
|
|
|
1
|
+
# Skills
|
|
2
|
+
|
|
3
|
+
A skill is a set of instructions an agent session follows when you ask for
|
|
4
|
+
it. An agent, in this page's sense, is a separate reviewer a session
|
|
5
|
+
launches, which reads and reports and changes nothing. This page covers
|
|
6
|
+
every skill and agent the factory brings.
|
|
7
|
+
|
|
8
|
+
You call a skill by asking a session in plain words, such as "refine ticket
|
|
9
|
+
12". Your coding agent may also have a shorter way to call one by name; on
|
|
10
|
+
Claude Code it is a slash command, as
|
|
11
|
+
[the reference](github/reference.md#skills-in-claude-code) shows.
|
|
12
|
+
|
|
13
|
+
## Which ones a repository gets
|
|
14
|
+
|
|
15
|
+
The factory's core is what its own steps call, and every repository gets
|
|
16
|
+
it. Everything else is written only when a setting or a file turns it on,
|
|
17
|
+
and `factory sync` removes it again when that is undone.
|
|
18
|
+
|
|
19
|
+
| Skill or agent | Written |
|
|
20
|
+
| --------------------------- | ------------------------------------ |
|
|
21
|
+
| `factory-refine` | Always |
|
|
22
|
+
| `factory-build` | Always |
|
|
23
|
+
| `factory-address-review` | Always |
|
|
24
|
+
| `factory-resolve-conflicts` | Always |
|
|
25
|
+
| `factory-diagnose` | Always |
|
|
26
|
+
| `factory-mutate` | Always |
|
|
27
|
+
| `factory-ticket-readiness` | Always |
|
|
28
|
+
| `factory-test-reviewer` | Always |
|
|
29
|
+
| `factory-design` | With `site` in your settings |
|
|
30
|
+
| `factory-ui-reviewer` | With `site` in your settings |
|
|
31
|
+
| `factory-deps` | With a `.github/dependabot.yml` file |
|
|
32
|
+
|
|
33
|
+
## At a glance
|
|
34
|
+
|
|
35
|
+
| Ask a session | Skill | It does |
|
|
36
|
+
| ---------------------------------- | --------------------------- | --------------------------------------------------------------------------------------------------- |
|
|
37
|
+
| "refine ticket 12" | `factory-refine` | Turns a ticket into a spec a builder can start from |
|
|
38
|
+
| "build ticket 12" | `factory-build` | Builds a ticket to a reviewed pull request |
|
|
39
|
+
| "address the review on 280" | `factory-address-review` | Works a pull request's review until it can merge |
|
|
40
|
+
| "resolve the conflicts on 280" | `factory-resolve-conflicts` | Merges your main branch into a pull request and settles the conflicts |
|
|
41
|
+
| "diagnose this failing test" | `factory-diagnose` | Finds a bug's cause before any code changes |
|
|
42
|
+
| "mutate this test" | `factory-mutate` | Proves a test can fail |
|
|
43
|
+
| "fix the dependency pull requests" | `factory-deps` | Moves dependency pull requests toward merged |
|
|
44
|
+
| "mock up a new about page" | `factory-design` | Designs a visible change to a website, with mockups |
|
|
45
|
+
| "trace this rule change" | `factory-trace` | _[Planned](developing.md#what-is-built)_: Traces a change to the rules through every kind of change |
|
|
46
|
+
|
|
47
|
+
## `factory-refine`
|
|
48
|
+
|
|
49
|
+
**What it does.** Turns a ticket into something a session can build without
|
|
50
|
+
asking anything. It works in two roles: a product manager, who challenges
|
|
51
|
+
the ask and brings you only the decisions that are yours, and a tech lead,
|
|
52
|
+
who settles everything the code and the rules can answer.
|
|
53
|
+
|
|
54
|
+
**When to use it.** On any ticket before it is built. A ticket with no
|
|
55
|
+
acceptance criteria cannot be built; `factory-build` sends it here.
|
|
56
|
+
|
|
57
|
+
**What it reads.** The ticket and its comments, the open tickets that touch
|
|
58
|
+
the same code, the code itself, your project's instructions for the agent
|
|
59
|
+
(`CLAUDE.md` files, on Claude Code), and the existing
|
|
60
|
+
spec when `specs` is on.
|
|
61
|
+
|
|
62
|
+
**What it writes.**
|
|
63
|
+
|
|
64
|
+
- The ticket's body: your text first, untouched, then Decisions and
|
|
65
|
+
Acceptance criteria, or a Spec when the change is visible and not small.
|
|
66
|
+
- Marker comments that move the ticket to "refining" and show it waiting on
|
|
67
|
+
you.
|
|
68
|
+
- A blocked-by relationship for each ticket that must be built first.
|
|
69
|
+
- For a decision about the look, mockups from your
|
|
70
|
+
[`mockups` plug-in](plugins.md), if you have one.
|
|
71
|
+
|
|
72
|
+
**How it asks.** In the session if you are there: each decision as a
|
|
73
|
+
choice, the recommended answer first. Otherwise as one comment on the
|
|
74
|
+
ticket, where anything you leave alone goes ahead as written.
|
|
75
|
+
|
|
76
|
+
**What it never does.** Move the ticket to Ready unasked. Edit a round of
|
|
77
|
+
questions once posted. Ask you something the code or the rules already
|
|
78
|
+
answer. Ask more than five questions: more than that means the ticket is
|
|
79
|
+
several tickets, and it proposes the split.
|
|
80
|
+
|
|
81
|
+
**Its check.** The built-in `factory-ticket-readiness` agent reads the
|
|
82
|
+
result cold, at most twice, and lists what a builder would still have to
|
|
83
|
+
ask.
|
|
84
|
+
|
|
85
|
+
## `factory-build`
|
|
86
|
+
|
|
87
|
+
**What it does.** Takes an approved ticket to a reviewed pull request.
|
|
88
|
+
|
|
89
|
+
1. Claims the ticket, so no other session builds it.
|
|
90
|
+
2. Makes a branch from your main branch, named for the ticket.
|
|
91
|
+
3. Builds to the acceptance criteria: the test first where there is a
|
|
92
|
+
defect to reproduce or a behavior to add, then the change.
|
|
93
|
+
4. Proves each new test can fail, and has `factory-test-reviewer` read the
|
|
94
|
+
tests.
|
|
95
|
+
5. Has each [`reviewer` plug-in](plugins.md) that applies read the change,
|
|
96
|
+
and fixes what they find.
|
|
97
|
+
6. Runs the checks your project's instructions name.
|
|
98
|
+
7. Opens a draft pull request that closes the ticket, saying what changed,
|
|
99
|
+
how it was checked, and what each reviewer found.
|
|
100
|
+
8. Marks it ready once CI passes on the pushed commit, then works the
|
|
101
|
+
review with `factory-address-review`.
|
|
102
|
+
|
|
103
|
+
**When to use it.** On a ticket that has acceptance criteria and your
|
|
104
|
+
approval. Telling a session "build ticket 12" is approval. So is moving the ticket
|
|
105
|
+
to Ready.
|
|
106
|
+
|
|
107
|
+
**What it reads.** The ticket, its Decisions, and your project's
|
|
108
|
+
instructions beside the code it changes.
|
|
109
|
+
|
|
110
|
+
**What it writes.** A branch, commits, a draft pull request, a claim
|
|
111
|
+
comment on the ticket, a note of what the build cost, and a line on the
|
|
112
|
+
[follow-ups ticket](workflow.md#follow-ups) for anything small it noticed
|
|
113
|
+
and did not fix.
|
|
114
|
+
|
|
115
|
+
**When it stops.** On a question only you can answer, a step only you can
|
|
116
|
+
do, an open blocker, or a gate that will not pass. It releases the ticket
|
|
117
|
+
and says why. The ticket stays in "building", waiting on you.
|
|
118
|
+
|
|
119
|
+
**What it never does.** Commit on your main branch. Merge. Turn auto-merge
|
|
120
|
+
on. Add the label that overrides a review's verdict. Guess at a decision
|
|
121
|
+
the ticket left open. Reopen a decision the ticket settled.
|
|
122
|
+
|
|
123
|
+
**Defaults you can change,** _[Planned](developing.md#what-is-built)_. `rules.small-change-lines`, default 30: a
|
|
124
|
+
change under it takes the lighter path [Workflow](workflow.md) describes.
|
|
125
|
+
|
|
126
|
+
## `factory-address-review`
|
|
127
|
+
|
|
128
|
+
**What it does.** Works everything standing between a pull request and its
|
|
129
|
+
merge: the threads from the automated review, your own comments, failed
|
|
130
|
+
checks, patch coverage, and a conflict with your main branch.
|
|
131
|
+
|
|
132
|
+
**When to use it.** After every push to a branch with an open pull request.
|
|
133
|
+
The session that built the pull request runs it without being asked.
|
|
134
|
+
|
|
135
|
+
**How it treats a finding.**
|
|
136
|
+
|
|
137
|
+
- A finding is confirmed by a repro, not by reading. It builds the smallest
|
|
138
|
+
input that should trigger it and runs the real code.
|
|
139
|
+
- It takes the finding and designs its own fix, and says in the reply when
|
|
140
|
+
that differs from what was suggested.
|
|
141
|
+
- Every thread gets a reply before it is resolved, accepted or rejected.
|
|
142
|
+
- A rejection cites evidence: a quoted source or a failing repro.
|
|
143
|
+
|
|
144
|
+
**Also a job in the cloud.** The job that starts when you review a pull
|
|
145
|
+
request runs it too, answering your review: it checks first that there is
|
|
146
|
+
something to do, and starts no session when there is not.
|
|
147
|
+
|
|
148
|
+
**What it writes.** Commits on the branch, a reply on each thread, and one
|
|
149
|
+
report.
|
|
150
|
+
|
|
151
|
+
**When it stops.** After two rounds (`rules.review-rounds`, _[Planned](developing.md#what-is-built)_), whatever
|
|
152
|
+
is still in dispute goes to you instead of through another round.
|
|
153
|
+
|
|
154
|
+
**What it never does.** Resolve a thread it neither fixed nor disproved.
|
|
155
|
+
Dismiss a failing test as flaky without reproducing it. Merge.
|
|
156
|
+
|
|
157
|
+
## `factory-diagnose`
|
|
158
|
+
|
|
159
|
+
**What it does.** Finds the cause of a bug, a failing or flaky test, or a
|
|
160
|
+
slowdown, before changing any code. It starts by building one command that
|
|
161
|
+
fails on the exact symptom, shrinks it, ranks the possible causes, and
|
|
162
|
+
tests them one change at a time.
|
|
163
|
+
|
|
164
|
+
**When to use it.** When something is broken, failing, flaky, or slow, and
|
|
165
|
+
the cause is not already known.
|
|
166
|
+
|
|
167
|
+
**What it never does.** Change code before it can make the failure happen
|
|
168
|
+
on demand. Fix two things at once.
|
|
169
|
+
|
|
170
|
+
## `factory-mutate`
|
|
171
|
+
|
|
172
|
+
**What it does.** Proves a test can fail. It breaks the code under test one
|
|
173
|
+
way at a time and watches the test go red, then puts the code back and
|
|
174
|
+
confirms the working tree is clean.
|
|
175
|
+
|
|
176
|
+
**When to use it.** For a test written after the code it tests, or one
|
|
177
|
+
never seen failing for the right reason. A test that passes either way
|
|
178
|
+
locks nothing in.
|
|
179
|
+
|
|
180
|
+
**What it never does.** Leave a mutation in place.
|
|
181
|
+
|
|
182
|
+
## `factory-deps`
|
|
183
|
+
|
|
184
|
+
**What it does.** Moves every open dependency pull request one step closer
|
|
185
|
+
to merged: resolves a conflict with your main branch, fixes failing checks,
|
|
186
|
+
does the migration a major version asks for, and opens a ticket for
|
|
187
|
+
anything it cannot fix.
|
|
188
|
+
|
|
189
|
+
**When to use it.** When dependency pull requests are stuck, or from the
|
|
190
|
+
job in the cloud that runs it for you. It is written, with its two
|
|
191
|
+
workflows, only to a repository that has a `.github/dependabot.yml`. A
|
|
192
|
+
security update GitHub opens in a repository without that file waits for
|
|
193
|
+
you: nothing moves it along or lets it merge itself.
|
|
194
|
+
|
|
195
|
+
**What it never does.** Merge. Make only the changes CI caught when a
|
|
196
|
+
migration guide calls for more.
|
|
197
|
+
|
|
198
|
+
## `factory-design`
|
|
199
|
+
|
|
200
|
+
**What it does.** Designs a visible change to a website as a designer
|
|
201
|
+
would: one recommended design in real content, built from your site and
|
|
202
|
+
pictured by `factory site compare` at your widths in light and dark,
|
|
203
|
+
reviewed by `factory-ui-reviewer` before you see it, and shown beside the
|
|
204
|
+
page as it is. It reads your `design-guide` when you wrote one, and who
|
|
205
|
+
your visitors are from your project's own instructions.
|
|
206
|
+
|
|
207
|
+
**When to use it.** When asked to redesign or restyle a page, and from
|
|
208
|
+
`factory-refine` when a decision changes how something looks. A
|
|
209
|
+
repository with `site` in its settings gets it as its
|
|
210
|
+
[`mockups` plug-in](plugins.md) without listing it; one without `site`
|
|
211
|
+
does not get it at all.
|
|
212
|
+
|
|
213
|
+
**What it never does.** Make a mockup of a change with no look to choose,
|
|
214
|
+
or one made by editing a running page instead of building it. Leave a
|
|
215
|
+
scratch worktree behind.
|
|
216
|
+
|
|
217
|
+
## `factory-trace` _[Planned](developing.md#what-is-built)_
|
|
218
|
+
|
|
219
|
+
**What it does.** A rule written for one kind of change can be wrong for
|
|
220
|
+
every other kind. Before a change to the rules, a skill, or an agent is
|
|
221
|
+
marked ready, this has a fresh agent trace each kind of change your
|
|
222
|
+
repository gets through the rules as they would stand, and report any kind
|
|
223
|
+
that got heavier, lighter, or ambiguous, and any two rules that now
|
|
224
|
+
disagree.
|
|
225
|
+
|
|
226
|
+
**What it reads.** `.claude/change-types.md`, your list of the kinds of
|
|
227
|
+
change your repository gets, each with a real example.
|
|
228
|
+
|
|
229
|
+
## `factory-resolve-conflicts`
|
|
230
|
+
|
|
231
|
+
**What it does.** Merges your main branch into a pull request that conflicts
|
|
232
|
+
with it, runs the gate, and pushes the merge. It never rebases or forces a
|
|
233
|
+
push. When the two sides of a conflict contradict each other, it pushes
|
|
234
|
+
nothing, comments why, and opens a ticket, because which side wins is your
|
|
235
|
+
decision.
|
|
236
|
+
|
|
237
|
+
**When to use it.** Ask it for one pull request ("resolve the conflicts on
|
|
238
|
+
280"). `factory-address-review` calls it when the pull request it is
|
|
239
|
+
working conflicts. A job in the cloud also runs it as the conflict sweep, after each
|
|
240
|
+
push to your default branch and nightly, over every pull request that
|
|
241
|
+
conflicts. The sweep checks first that there is something to do, and starts
|
|
242
|
+
no session when there is not.
|
|
243
|
+
|
|
244
|
+
## The built-in agents
|
|
245
|
+
|
|
246
|
+
### `factory-ticket-readiness`
|
|
247
|
+
|
|
248
|
+
Reads a refined ticket cold, as the session that will build it, and lists
|
|
249
|
+
every question it would still have to ask. `factory-refine` runs it.
|
|
250
|
+
Read-only.
|
|
251
|
+
|
|
252
|
+
### `factory-ui-reviewer`
|
|
253
|
+
|
|
254
|
+
Reads a change to how a website looks or responds. It runs
|
|
255
|
+
`factory site compare`, reads the before and after pictures of the pages that
|
|
256
|
+
changed, drives the states the change is about, and judges them against built-in
|
|
257
|
+
rules, your `design-guide` when you wrote one, and what your `checks` printed.
|
|
258
|
+
It is listed under `plugins` like a reviewer of your own, with the `files` that
|
|
259
|
+
should trigger it, and is written only to a repository with `site` in its
|
|
260
|
+
settings. Read-only, and slow.
|
|
261
|
+
|
|
262
|
+
### `factory-test-reviewer`
|
|
263
|
+
|
|
264
|
+
Reads new or changed tests the way a test engineer reviews a pull request:
|
|
265
|
+
one behavior per test, each able to fail, found the way a user would find
|
|
266
|
+
it, with no waits on a timer. `factory-build` runs it. Read-only, and it
|
|
267
|
+
does not run the suite.
|
|
268
|
+
|
|
269
|
+
It takes its specifics from your project's instructions beside your tests. Without one,
|
|
270
|
+
it applies only those general rules.
|
package/docs/updating.md
ADDED
|
@@ -0,0 +1,108 @@
|
|
|
1
|
+
# Updating _[Planned](developing.md#what-is-built)_
|
|
2
|
+
|
|
3
|
+
Nothing on this page works until the package is published. Until then, a
|
|
4
|
+
new version reaches your repository the way it was installed, and
|
|
5
|
+
`factory sync` applies it.
|
|
6
|
+
|
|
7
|
+
**When a new version is released, a pull request appears in your
|
|
8
|
+
repository. You read it and merge it.** That is all you have to do.
|
|
9
|
+
|
|
10
|
+
## What happens
|
|
11
|
+
|
|
12
|
+
1. Dependabot's weekly run finds the new version and opens one pull
|
|
13
|
+
request for it, as it does for any package. Its group for the factory
|
|
14
|
+
([on GitHub](github/reference.md#dependency-bots)) keeps the pull
|
|
15
|
+
request to the factory alone.
|
|
16
|
+
2. `factory-deps`, which already looks after Dependabot's pull requests,
|
|
17
|
+
runs `factory sync` on its branch and adds what it wrote as a second
|
|
18
|
+
commit. Until it has, CI's `factory sync --check` fails.
|
|
19
|
+
3. You read it and merge it. It never merges itself, whatever your
|
|
20
|
+
`auto-merge` settings allow.
|
|
21
|
+
4. Everyone working on the repository, you included, pulls and runs
|
|
22
|
+
`npm ci`, as after any dependency change.
|
|
23
|
+
|
|
24
|
+
## What the pull request holds
|
|
25
|
+
|
|
26
|
+
- **The new version**, in `package.json`, the lockfile, and
|
|
27
|
+
`.claude/factory.lock`.
|
|
28
|
+
- **The factory's files, rewritten.** Its skills, agents, rules, and CI
|
|
29
|
+
workflows live in your repository, so the diff shows exactly which
|
|
30
|
+
instruction changed.
|
|
31
|
+
- **A comment from `factory-deps`** listing the files the sync changed,
|
|
32
|
+
and anything the release notes say to do by hand, first.
|
|
33
|
+
|
|
34
|
+
An update changes the instructions your sessions follow and the code that
|
|
35
|
+
runs with your tokens. Read it as carefully as you would read code.
|
|
36
|
+
|
|
37
|
+
## Doing it yourself
|
|
38
|
+
|
|
39
|
+
To update now instead of waiting for Dependabot:
|
|
40
|
+
|
|
41
|
+
```bash
|
|
42
|
+
npm install --save-dev @davidbyoung/software-factory@latest
|
|
43
|
+
factory sync
|
|
44
|
+
```
|
|
45
|
+
|
|
46
|
+
Commit both on a branch and open a pull request. To see whether you are
|
|
47
|
+
behind without changing anything:
|
|
48
|
+
|
|
49
|
+
```bash
|
|
50
|
+
factory doctor
|
|
51
|
+
```
|
|
52
|
+
|
|
53
|
+
## Staying on a version, or going back
|
|
54
|
+
|
|
55
|
+
- **To stay where you are,** close the update pull request. Dependabot
|
|
56
|
+
opens a new one for the next release.
|
|
57
|
+
- **To go back,** revert the update's pull request. The version and the
|
|
58
|
+
files go back together.
|
|
59
|
+
|
|
60
|
+
## Without Dependabot
|
|
61
|
+
|
|
62
|
+
Update by hand as above. `factory-deps` and its workflows are written only
|
|
63
|
+
once `.github/dependabot.yml` exists.
|
|
64
|
+
|
|
65
|
+
## The commands
|
|
66
|
+
|
|
67
|
+
| Command | When |
|
|
68
|
+
| ---------------- | ---------------------------------------------------------- |
|
|
69
|
+
| `factory sync` | After you edit `.claude/factory.yaml`, to apply the change |
|
|
70
|
+
| `factory doctor` | To see whether you are behind, or why something is off |
|
|
71
|
+
|
|
72
|
+
`factory sync` rewrites the factory's files to match your
|
|
73
|
+
settings and the installed version.
|
|
74
|
+
|
|
75
|
+
## On a team
|
|
76
|
+
|
|
77
|
+
Decide who merges updates, and tell them these pull requests are theirs.
|
|
78
|
+
An update changes how everyone's sessions behave, so one person should
|
|
79
|
+
read each one. After it merges, everyone pulls and runs `npm ci`. Until
|
|
80
|
+
they do, `factory doctor` and the start of each session
|
|
81
|
+
tell them their installed version is behind the repository's; the
|
|
82
|
+
session's start also says so, naming `npm ci`, when `node_modules` does
|
|
83
|
+
not match `package-lock.json`.
|
|
84
|
+
|
|
85
|
+
## When something goes wrong
|
|
86
|
+
|
|
87
|
+
| What you see | What happened | What to do |
|
|
88
|
+
| --------------------------------------------------------------------------- | --------------------------------------------------------------------- | -------------------------------------------------------------------------- |
|
|
89
|
+
| CI fails with "the factory's files are out of sync" | A factory file was edited by hand, or settings changed without a sync | Run `factory sync` and commit the result |
|
|
90
|
+
| `factory doctor` says your installed version is older than the repository's | You pulled an update and have not installed it | Run `npm ci` |
|
|
91
|
+
| The update pull request conflicts with your main branch | Something else changed the same file | `factory-deps` resolves it on its next run, or close it and update by hand |
|
|
92
|
+
|
|
93
|
+
## Never edit a factory file
|
|
94
|
+
|
|
95
|
+
Every file named `factory-...`, and the factory's rules, are written by
|
|
96
|
+
the factory. An edit made to one would be lost on the next update, so CI
|
|
97
|
+
fails when one differs from what the installed version would write.
|
|
98
|
+
|
|
99
|
+
To change what the factory does:
|
|
100
|
+
|
|
101
|
+
- **For your repository only:** say so in your own instructions for the
|
|
102
|
+
agent, which win over the factory's rules, or, _[Planned](developing.md#what-is-built)_, change the value under
|
|
103
|
+
[`rules`](configuration.md#rules) in your settings.
|
|
104
|
+
- **For everyone:** change it in the factory, and it reaches you as an
|
|
105
|
+
update.
|
|
106
|
+
|
|
107
|
+
[Why it works this way](design.md) explains why the files are copied in
|
|
108
|
+
and what the three version numbers are.
|
package/docs/workflow.md
ADDED
|
@@ -0,0 +1,195 @@
|
|
|
1
|
+
# Workflow
|
|
2
|
+
|
|
3
|
+
How a ticket moves from an idea to a merged pull request, who moves it at
|
|
4
|
+
each step, and what the factory will not do on its own.
|
|
5
|
+
|
|
6
|
+
## From a ticket to a merge
|
|
7
|
+
|
|
8
|
+
| Step | Who | Where it runs | What comes out |
|
|
9
|
+
| ----------------- | -------------------------------------------------- | -------------------------------------------------- | ----------------------------------------------------------------------------- |
|
|
10
|
+
| Write a ticket | You | Your ticket system | A ticket saying what, why, and when it is done |
|
|
11
|
+
| Refine it | A session you start | Your machine, in your coding agent | The ticket rewritten into acceptance criteria, after you answer its decisions |
|
|
12
|
+
| Approve it | **You** | A session, or your board | Tell a session to build it, or move its card to Ready |
|
|
13
|
+
| Build it | A session | Your machine, or the cloud when started from Ready | A tested change in a pull request that closes the ticket |
|
|
14
|
+
| Review it | The automated review, if you set it up | Your CI | Comments and a verdict on the pull request |
|
|
15
|
+
| Answer the review | The session that built it | Where it was built | Each comment fixed, or rejected with evidence |
|
|
16
|
+
| Merge it | **You**, or the merge policy for files you allowed | Your code host | The change on your main branch, and the ticket closed |
|
|
17
|
+
|
|
18
|
+
Everything a session does, it does as you: through your account on the
|
|
19
|
+
code host and your coding agent's subscription, on your machine or in the
|
|
20
|
+
cloud. No step needs a service of the factory's own.
|
|
21
|
+
|
|
22
|
+
## The six states
|
|
23
|
+
|
|
24
|
+
A ticket is always in one of six states. They are fixed: you cannot add one
|
|
25
|
+
or reorder them. Your board shows them as columns, and which column shows
|
|
26
|
+
which state is your repository's choice
|
|
27
|
+
([`tickets.columns`](configuration.md#ticketscolumns)). The table gives the
|
|
28
|
+
default names.
|
|
29
|
+
|
|
30
|
+
A state with no column of its own shows in the column of the nearest earlier
|
|
31
|
+
state that has one, and a ticket is shown in the `ready` column only when it
|
|
32
|
+
is approved. A board without a `ready` column approves a build by telling a
|
|
33
|
+
session to build the ticket, or by running
|
|
34
|
+
`factory build N`.
|
|
35
|
+
|
|
36
|
+
| State | Board column | It means |
|
|
37
|
+
| -------- | ------------- | ----------------------------------------------------------------------------- |
|
|
38
|
+
| backlog | Backlog | Nothing is happening |
|
|
39
|
+
| refining | In refinement | A session is turning it into a spec, or the spec is written and waits for you |
|
|
40
|
+
| ready | Ready | You approved it for a build from the board |
|
|
41
|
+
| building | In progress | A session has claimed it, or a build ended without a pull request merging |
|
|
42
|
+
| review | In review | A pull request that closes it is open |
|
|
43
|
+
| done | Done | The ticket is closed |
|
|
44
|
+
|
|
45
|
+
```text
|
|
46
|
+
backlog → refining → ready → building → review → done
|
|
47
|
+
↑
|
|
48
|
+
the one move that is yours
|
|
49
|
+
```
|
|
50
|
+
|
|
51
|
+
## Who moves a ticket
|
|
52
|
+
|
|
53
|
+
| Move | Who |
|
|
54
|
+
| ------------------ | ---------------------------------------------------------------- |
|
|
55
|
+
| backlog → refining | The session you ask to refine it |
|
|
56
|
+
| refining → ready | **You**, by moving the card, or by telling a session to build it |
|
|
57
|
+
| ready → building | The session that claims it |
|
|
58
|
+
| building → review | Opening the pull request |
|
|
59
|
+
| review → done | The merge, which closes the ticket |
|
|
60
|
+
|
|
61
|
+
Approving a ticket is the only move a person has to make. A session moves
|
|
62
|
+
the card to Ready only when you ask it to, as your own move.
|
|
63
|
+
|
|
64
|
+
## What is fixed
|
|
65
|
+
|
|
66
|
+
These hold in every repository. They are not settings.
|
|
67
|
+
|
|
68
|
+
- **A ticket only moves forward on its own.** When the next step is yours,
|
|
69
|
+
it stays where it is and the board says "Waiting on you". Only you move a
|
|
70
|
+
ticket back.
|
|
71
|
+
- **Nothing retries by itself.** A build that stopped, failed to start, or
|
|
72
|
+
whose pull request you closed stays in "building", waiting on you. Moving
|
|
73
|
+
it to Ready again retries it.
|
|
74
|
+
- **The order does not change.** A repository cannot add a state or reorder
|
|
75
|
+
them. A team that wants a security review between building and review adds
|
|
76
|
+
a [reviewer](plugins.md), not a column.
|
|
77
|
+
- **One session holds a ticket at a time.** The claim is a comment on the
|
|
78
|
+
ticket. A second session that tries is told who holds it and stops.
|
|
79
|
+
|
|
80
|
+
## The board
|
|
81
|
+
|
|
82
|
+
The factory writes four fields of the board: its Status, and three of its
|
|
83
|
+
own. Anything you type into the
|
|
84
|
+
last three is overwritten on the next sync.
|
|
85
|
+
|
|
86
|
+
| Field | Shows |
|
|
87
|
+
| ------- | ------------------------------------------------------------------------------------- |
|
|
88
|
+
| Status | The column |
|
|
89
|
+
| Session | Which session is on the ticket, "actions, starting", or "Waiting on you" |
|
|
90
|
+
| Runs in | Whether that session is on a machine or in the cloud |
|
|
91
|
+
| Cost | An estimate of what refining and building the ticket used, summed across its sessions |
|
|
92
|
+
|
|
93
|
+
Sessions never write the board directly. They post marker comments on the
|
|
94
|
+
ticket, and one job in the cloud, the board sync, reads those and sets the
|
|
95
|
+
fields.
|
|
96
|
+
That is why a ticket's history survives even if the board is rebuilt.
|
|
97
|
+
|
|
98
|
+
`factory status` prints the same picture in a terminal.
|
|
99
|
+
|
|
100
|
+
## Tickets that wait on another
|
|
101
|
+
|
|
102
|
+
When building one ticket first would break another, or mean redoing work,
|
|
103
|
+
the second is recorded as blocked by the first, using the ticket system's
|
|
104
|
+
own relationship between tickets. A build never starts on a ticket with an open blocker, and
|
|
105
|
+
starts within a minute of the blocker closing if the ticket is in Ready.
|
|
106
|
+
|
|
107
|
+
Two tickets touching the same file is not a blocker. That is a merge
|
|
108
|
+
conflict, and the session that owns the pull request resolves it.
|
|
109
|
+
|
|
110
|
+
## Sizing the work to the change
|
|
111
|
+
|
|
112
|
+
A change under about 30 lines outside tests, adding no new component and no
|
|
113
|
+
new state, is **small**. It skips the heavier steps: no separate spec, no
|
|
114
|
+
readiness read, and one test that reproduces the defect or checks the
|
|
115
|
+
change. The first message of the work says which path it is taking, so you
|
|
116
|
+
can overrule it before it starts.
|
|
117
|
+
|
|
118
|
+
The number is `rules.small-change-lines` in your
|
|
119
|
+
[settings](configuration.md), _[Planned](developing.md#what-is-built)_; until it is built, it is 30.
|
|
120
|
+
|
|
121
|
+
## Follow-ups
|
|
122
|
+
|
|
123
|
+
A session building one ticket often notices something else: a test that
|
|
124
|
+
cannot fail, a stale sentence, a button under its size floor. It does not
|
|
125
|
+
stop to fix it, and it does not open a ticket for it. It adds a line to the
|
|
126
|
+
repository's **follow-ups ticket**, which is an ordinary ticket whose body
|
|
127
|
+
is a checklist:
|
|
128
|
+
|
|
129
|
+
```text
|
|
130
|
+
Follow-ups
|
|
131
|
+
|
|
132
|
+
- [ ] src/pages/about.tsx: The heading skips from level 1 to level 3.
|
|
133
|
+
- [ ] scripts/release.sh: The usage text still names a flag that was removed.
|
|
134
|
+
- [ ] tests/search.spec.ts: This test passes even when search returns nothing.
|
|
135
|
+
```
|
|
136
|
+
|
|
137
|
+
There is one per repository, it carries the `follow-up` label, and there is
|
|
138
|
+
nothing to configure. When you approve it, a session fixes every unchecked
|
|
139
|
+
line on one branch, one commit per line, in one pull request.
|
|
140
|
+
|
|
141
|
+
**Why a checklist and not a ticket each.** Every ticket costs the same
|
|
142
|
+
steps whatever its size: refining, your approval, a branch, a pull request,
|
|
143
|
+
a review, and a merge. For a one-line fix that is all overhead. Twenty
|
|
144
|
+
small fixes on one checklist cost you one approval and one pull request.
|
|
145
|
+
|
|
146
|
+
**What becomes a line, and what gets its own ticket.**
|
|
147
|
+
|
|
148
|
+
| The session noticed | It becomes |
|
|
149
|
+
| -------------------------------------------------------- | ----------------------------------------------------- |
|
|
150
|
+
| Something small that breaks a rule your guides state | A line |
|
|
151
|
+
| Something that needs your call before it can be fixed | A line that says "Needs a decision:" and the question |
|
|
152
|
+
| Something that would change what your users see | Its own ticket |
|
|
153
|
+
| Something you asked for | Its own ticket |
|
|
154
|
+
| Something that breaks no rule, or needs measuring to see | Nothing |
|
|
155
|
+
|
|
156
|
+
Every line names the file it is about, says what is wrong, and says which
|
|
157
|
+
rule it breaks, so it can be fixed as written.
|
|
158
|
+
|
|
159
|
+
## Who merges
|
|
160
|
+
|
|
161
|
+
Every pull request gets one of two labels:
|
|
162
|
+
|
|
163
|
+
- **`merge: automatic`**: every file is allowed by your
|
|
164
|
+
[`auto-merge`](configuration.md#auto-merge) settings, and none of the
|
|
165
|
+
commands you listed there held it. It merges itself once every check
|
|
166
|
+
passes.
|
|
167
|
+
- **`merge: manual`**: anything else. It waits for a person to merge it,
|
|
168
|
+
and a "Who merges" status on the pull request says what held it and
|
|
169
|
+
why.
|
|
170
|
+
|
|
171
|
+
Two more things guard a merge:
|
|
172
|
+
|
|
173
|
+
- **"Review verdict"** is a status, which you can make required on your
|
|
174
|
+
main branch, that passes only when the automated
|
|
175
|
+
review of the newest commit said it is ready, or an approver overrode it
|
|
176
|
+
with the `verdict: override` label. Sessions never add that label.
|
|
177
|
+
- **Every review thread must be resolved.** A session answers each one,
|
|
178
|
+
fixed or rejected with evidence, before resolving it.
|
|
179
|
+
|
|
180
|
+
Both the labeling and the verdict run from your main branch's copy of the
|
|
181
|
+
rules, so a pull request cannot change how it is judged.
|
|
182
|
+
|
|
183
|
+
A session never merges, never turns auto-merge on, and never overrides a
|
|
184
|
+
verdict.
|
|
185
|
+
|
|
186
|
+
## A change your users will see
|
|
187
|
+
|
|
188
|
+
With `specs: openspec`, a change that adds or alters behavior someone can
|
|
189
|
+
see, and is not small, carries the `spec` label. Its ticket holds a "Spec"
|
|
190
|
+
section of plain "When this, then that" lines. The build turns those lines
|
|
191
|
+
into an OpenSpec change, builds to them, and folds them into
|
|
192
|
+
`openspec/specs/` in the same pull request, so that folder always describes
|
|
193
|
+
what the project does now.
|
|
194
|
+
|
|
195
|
+
With `specs: none`, the ticket's acceptance criteria are the whole spec.
|