@davidbyoung/software-factory 0.1.9 → 0.1.11
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/agents/factory-ticket-readiness.md +20 -15
- package/dist/board.d.mts +1 -1
- package/dist/board.mjs +4 -7
- package/dist/cli.mjs +23 -1
- package/dist/code-host/github.d.mts +1 -1
- package/dist/code-host/github.mjs +31 -2
- package/dist/code-host/types.d.mts +20 -1
- package/dist/code-host/types.mjs +8 -0
- package/dist/columns-suggest.d.mts +25 -5
- package/dist/columns-suggest.mjs +117 -21
- package/dist/commands.d.mts +8 -2
- package/dist/commands.mjs +92 -8
- package/dist/config.d.mts +19 -7
- package/dist/config.mjs +109 -30
- package/dist/doctor.mjs +1 -2
- package/dist/explain.mjs +7 -1
- package/dist/init.d.mts +19 -0
- package/dist/init.mjs +139 -23
- package/dist/lib/gh.d.mts +6 -0
- package/dist/lib/gh.mjs +11 -1
- package/dist/lib/listed.d.mts +3 -2
- package/dist/lib/listed.mjs +5 -4
- package/dist/lib/work-status.d.mts +5 -5
- package/dist/lib/work-status.mjs +7 -8
- package/dist/merge-policy.mjs +7 -3
- package/dist/poller.d.mts +1 -1
- package/dist/poller.mjs +9 -6
- package/dist/pr.d.mts +8 -6
- package/dist/pr.mjs +47 -22
- package/dist/review-verdict.d.mts +22 -4
- package/dist/review-verdict.mjs +55 -17
- package/dist/specs/index.d.mts +6 -0
- package/dist/specs/index.mjs +15 -0
- package/dist/specs/openspec.d.mts +2 -0
- package/dist/specs/openspec.mjs +78 -0
- package/dist/specs/types.d.mts +53 -0
- package/dist/specs/types.mjs +4 -0
- package/dist/ticket.d.mts +6 -1
- package/dist/ticket.mjs +62 -3
- package/dist/tickets/github-access.d.mts +5 -0
- package/dist/tickets/github-access.mjs +22 -0
- package/dist/tickets/github.mjs +2 -0
- package/dist/tickets/types.d.mts +4 -0
- package/dist/tool-names.d.mts +2 -0
- package/dist/tool-names.mjs +3 -0
- package/dist/tools.d.mts +2 -0
- package/dist/tools.mjs +3 -0
- package/docs/builds.md +30 -14
- package/docs/cli.md +48 -30
- package/docs/configuration.md +237 -73
- package/docs/developing.md +104 -59
- package/docs/existing-repo.md +51 -29
- package/docs/github/by-hand.md +13 -1
- package/docs/github/setup.md +26 -2
- package/docs/glossary.md +7 -6
- package/docs/limitations.md +8 -5
- package/docs/presets.md +15 -3
- package/docs/updating.md +147 -2
- package/docs/workflow.md +26 -9
- package/package.json +1 -1
- package/rules.md +36 -30
- package/settings.schema.json +14 -9
- package/skills/factory-address-review/SKILL.md +40 -39
- package/skills/factory-build/SKILL.md +77 -52
- package/skills/factory-deps/SKILL.md +6 -4
- package/skills/factory-refine/SKILL.md +30 -22
- package/skills/factory-resolve-conflicts/SKILL.md +8 -7
package/docs/developing.md
CHANGED
|
@@ -30,51 +30,51 @@ completes with the files the version writes ([Updating](updating.md)).
|
|
|
30
30
|
The factory is the npm package `@davidbyoung/software-factory`. Parts not
|
|
31
31
|
marked working below exist only in these docs.
|
|
32
32
|
|
|
33
|
-
| Part | State
|
|
34
|
-
| ---------------------------------------------------------------------------------------------------------------- |
|
|
35
|
-
| Refining, building, and working a pull request's review | Working
|
|
36
|
-
| The board, its sync, and `status` | Working
|
|
37
|
-
| Builds from the board, with a poller you host | Working
|
|
38
|
-
| Builds that run in GitHub Actions, started by a command | Working
|
|
39
|
-
| Starting builds from the board, and the review, conflict, and dependency runs, in GitHub Actions | Working
|
|
40
|
-
| Who merges, and the review's verdict | Working
|
|
41
|
-
| The labels `merge: manual` and `verdict: override` | Working
|
|
42
|
-
| These docs | Working
|
|
43
|
-
| `.claude/factory.yaml`, and the factory's files kept apart from the host's | Working
|
|
44
|
-
| The follow-ups ticket as one checklist | Working
|
|
45
|
-
| The `factory` tool, `sync`, and the package folder | Working
|
|
46
|
-
| A global `factory` command that runs each repository's own copy | Working
|
|
47
|
-
| The automated review as one of the factory's workflows, and [`pr-review`](configuration.md#pr-review) | Working
|
|
48
|
-
| Nothing in the package names the repository it was drawn out of, checked in the folder and the packed tarball | Working
|
|
49
|
-
| The `factory-` names and the `FACTORY_` secrets | Working
|
|
50
|
-
| Ticket commands that go through one interface | Working
|
|
51
|
-
| The code host and the runner, each behind one interface | Working
|
|
52
|
-
| A published package | Working
|
|
53
|
-
| Updates through Dependabot, which `factory-deps` completes with `factory sync` | Working
|
|
54
|
-
| `factory board --dry-run` | Working
|
|
55
|
-
| Your own column names on a board | Working
|
|
56
|
-
| `init` suggesting a board's columns through the coding agent | Working
|
|
57
|
-
| Refinement's factory fields in your ticket fields, suggested by `init` | Working
|
|
58
|
-
| A UI reviewer for any website | Working
|
|
59
|
-
| Built-in measurements for any website | Working
|
|
60
|
-
| A design skill for any website | Working
|
|
61
|
-
| `init`, which can be re-run, and `doctor` | Working
|
|
62
|
-
| A second repository set up and removed from the quick start alone | Working
|
|
63
|
-
| `factory remove` | Working
|
|
64
|
-
| Starting builds from a scheduled workflow, `factory poller --once`, and a poller built from an installed package | Working
|
|
65
|
-
| [`rules`](configuration.md#rules) in the settings, `factory config explain`, and the `factory-trace` skill | Working
|
|
66
|
-
| Settings version 2: commands, a spec check, and plugins grouped by phase | Working
|
|
67
|
-
| `factory gate`, `test-one`, `end-to-end`, and `specs check`, which run the settings' commands | Working
|
|
68
|
-
| The default branch read from Git and the code host, never assumed, and `factory default-branch` | Working
|
|
69
|
-
| A refiner, a prover, test reviewers, and conflict resolvers of your own, and `factory-e2e-reviewer` | Working
|
|
70
|
-
| `factory ticket refined` refusing a ticket a build could not read | Working
|
|
71
|
-
| No skill, agent, rule, or review instruction names a stack, checked by a test | Working
|
|
72
|
-
|
|
|
73
|
-
|
|
|
74
|
-
|
|
|
75
|
-
| Another
|
|
76
|
-
| Each tool's setup, checks, and removal declared by the tool | Working
|
|
77
|
-
| Sharing plugins between repositories | Not planned
|
|
33
|
+
| Part | State |
|
|
34
|
+
| ---------------------------------------------------------------------------------------------------------------- | --------------------------------------------------- |
|
|
35
|
+
| Refining, building, and working a pull request's review | Working |
|
|
36
|
+
| The board, its sync, and `status` | Working |
|
|
37
|
+
| Builds from the board, with a poller you host | Working |
|
|
38
|
+
| Builds that run in GitHub Actions, started by a command | Working |
|
|
39
|
+
| Starting builds from the board, and the review, conflict, and dependency runs, in GitHub Actions | Working |
|
|
40
|
+
| Who merges, and the review's verdict | Working |
|
|
41
|
+
| The labels `merge: manual` and `verdict: override` | Working |
|
|
42
|
+
| These docs | Working |
|
|
43
|
+
| `.claude/factory.yaml`, and the factory's files kept apart from the host's | Working |
|
|
44
|
+
| The follow-ups ticket as one checklist | Working |
|
|
45
|
+
| The `factory` tool, `sync`, and the package folder | Working |
|
|
46
|
+
| A global `factory` command that runs each repository's own copy | Working |
|
|
47
|
+
| The automated review as one of the factory's workflows, and [`pr-review`](configuration.md#pr-review) | Working |
|
|
48
|
+
| Nothing in the package names the repository it was drawn out of, checked in the folder and the packed tarball | Working |
|
|
49
|
+
| The `factory-` names and the `FACTORY_` secrets | Working |
|
|
50
|
+
| Ticket commands that go through one interface | Working |
|
|
51
|
+
| The code host and the runner, each behind one interface | Working |
|
|
52
|
+
| A published package | Working |
|
|
53
|
+
| Updates through Dependabot, which `factory-deps` completes with `factory sync` | Working |
|
|
54
|
+
| `factory board --dry-run` | Working |
|
|
55
|
+
| Your own column names on a board | Working |
|
|
56
|
+
| `init` suggesting a board's columns through the coding agent | Working |
|
|
57
|
+
| Refinement's factory fields in your ticket fields, suggested by `init` | Working |
|
|
58
|
+
| A UI reviewer for any website | Working |
|
|
59
|
+
| Built-in measurements for any website | Working |
|
|
60
|
+
| A design skill for any website | Working |
|
|
61
|
+
| `init`, which can be re-run, and `doctor` | Working |
|
|
62
|
+
| A second repository set up and removed from the quick start alone | Working |
|
|
63
|
+
| `factory remove` | Working |
|
|
64
|
+
| Starting builds from a scheduled workflow, `factory poller --once`, and a poller built from an installed package | Working |
|
|
65
|
+
| [`rules`](configuration.md#rules) in the settings, `factory config explain`, and the `factory-trace` skill | Working |
|
|
66
|
+
| Settings version 2: commands, a spec check, and plugins grouped by phase | Working |
|
|
67
|
+
| `factory gate`, `test-one`, `end-to-end`, and `specs check`, which run the settings' commands | Working |
|
|
68
|
+
| The default branch read from Git and the code host, never assumed, and `factory default-branch` | Working |
|
|
69
|
+
| A refiner, a prover, test reviewers, and conflict resolvers of your own, and `factory-e2e-reviewer` | Working |
|
|
70
|
+
| `factory ticket refined` refusing a ticket a build could not read | Working |
|
|
71
|
+
| No skill, agent, rule, or review instruction names a stack, checked by a test | Working |
|
|
72
|
+
| Another ticket system, such as Jira | Not planned. The design leaves room |
|
|
73
|
+
| A ticket system or code host named by a package, for an adapter you write yourself | Not planned. The design leaves room |
|
|
74
|
+
| Another code host or runner | Not planned. The design leaves room |
|
|
75
|
+
| Another spec tool, such as Spec Kit | Not planned. An adapter under `src/specs/` adds one |
|
|
76
|
+
| Each tool's setup, checks, and removal declared by the tool | Working |
|
|
77
|
+
| Sharing plugins between repositories | Not planned |
|
|
78
78
|
|
|
79
79
|
When a part is built, its pull request updates this table, and corrects any
|
|
80
80
|
page the build had to differ from. [The CLI](cli.md) marks each command
|
|
@@ -224,20 +224,21 @@ the work to that type's adapter.** An adapter is one module in
|
|
|
224
224
|
`factory config check` and every ticket command with
|
|
225
225
|
`tickets.type "X" is not supported. "github" is the only ticket system built.`
|
|
226
226
|
|
|
227
|
-
| Operation | In `Tickets` | What it returns or does
|
|
228
|
-
| ----------------------- | ------------------------- |
|
|
229
|
-
| Read a ticket | `read` | Its number, title, state (`open` or `closed`), when it closed, labels, body, and comments, each with its ID, author, time, and body
|
|
230
|
-
| List open tickets | `listOpen` | Number, title, and labels, for every open ticket however many there are
|
|
231
|
-
| Read everything at once | `readAll` | Every open ticket and the 30 closed ones most recently updated, as `read` returns each; with the board group, each carries its card. Optional: see below
|
|
232
|
-
| Write a ticket's body | `writeBody` |
|
|
233
|
-
| Comment | `comment` | Returns the comment's ID. Hidden markers pass through unchanged
|
|
234
|
-
| Edit a comment | `editComment` | By its ID
|
|
235
|
-
| Delete a comment | `deleteComment` | By its ID
|
|
236
|
-
| Not found | `NotFoundError` | Reading a ticket that does not exist, or editing or deleting a comment that is gone, throws this, so a caller can tell it from any other failure
|
|
237
|
-
| Open a ticket | `open` | With a title, a body, and labels. Returns its number
|
|
238
|
-
| Add or remove a label | `addLabel`, `removeLabel` |
|
|
239
|
-
|
|
|
240
|
-
|
|
|
227
|
+
| Operation | In `Tickets` | What it returns or does |
|
|
228
|
+
| ----------------------- | ------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
229
|
+
| Read a ticket | `read` | Its number, title, state (`open` or `closed`), when it closed, labels, body, and comments, each with its ID, author, time, and body |
|
|
230
|
+
| List open tickets | `listOpen` | Number, title, and labels, for every open ticket however many there are |
|
|
231
|
+
| Read everything at once | `readAll` | Every open ticket and the 30 closed ones most recently updated, as `read` returns each; with the board group, each carries its card. Optional: see below |
|
|
232
|
+
| Write a ticket's body | `writeBody` | |
|
|
233
|
+
| Comment | `comment` | Returns the comment's ID. Hidden markers pass through unchanged |
|
|
234
|
+
| Edit a comment | `editComment` | By its ID |
|
|
235
|
+
| Delete a comment | `deleteComment` | By its ID |
|
|
236
|
+
| Not found | `NotFoundError` | Reading a ticket that does not exist, or editing or deleting a comment that is gone, throws this, so a caller can tell it from any other failure |
|
|
237
|
+
| Open a ticket | `open` | With a title, a body, and labels. Returns its number |
|
|
238
|
+
| Add or remove a label | `addLabel`, `removeLabel` | |
|
|
239
|
+
| Who may decide | `mayDecide` | Whether a comment's author may decide on a ticket, so `factory ticket answers` takes their comment as an answer. GitHub's asks whether they can write to the repository. Rejects when it cannot say |
|
|
240
|
+
| Link text | `linkText` | What makes a merged pull request close the ticket, such as "Closes #12" |
|
|
241
|
+
| The address of a ticket | `address` | Its page, which the views link a ticket's number to |
|
|
241
242
|
|
|
242
243
|
"Read everything at once" has a default, `readAll` in
|
|
243
244
|
`src/tickets/types.mts`, built from `listOpen` and `read`, so a new adapter
|
|
@@ -396,6 +397,50 @@ variables, and reach pull requests through the code host.
|
|
|
396
397
|
The in-memory runner is `tests/memory-runner.ts`, and GitHub Actions' has
|
|
397
398
|
its own tests against faked replies.
|
|
398
399
|
|
|
400
|
+
## Adding a spec tool
|
|
401
|
+
|
|
402
|
+
A spec tool keeps a copy of each ticket's Spec in the repository. Only
|
|
403
|
+
OpenSpec is built. The settings name it with
|
|
404
|
+
[`specs`](configuration.md#specs), and `src/specs/index.mts` hands a
|
|
405
|
+
command the adapter of that name: one module in `src/specs/` that
|
|
406
|
+
implements the `SpecTool` type in `src/specs/types.mts`. `none` needs no
|
|
407
|
+
adapter. Any other value fails `factory config check` with
|
|
408
|
+
`specs must be one of none, openspec`, which lists a new tool once its
|
|
409
|
+
adapter is registered.
|
|
410
|
+
|
|
411
|
+
**Nothing runs a spec tool except its adapter.** A skill never runs
|
|
412
|
+
`openspec` or any other tool's command. It runs `factory specs list`,
|
|
413
|
+
`new N`, `check`, and `finish N` ([Your repository's
|
|
414
|
+
commands](cli.md#your-repositorys-commands)), which print one line and
|
|
415
|
+
exit 0 with no spec tool, so a skill need not ask which is set. A test
|
|
416
|
+
fails when a factory skill, agent, rule, review instruction, workflow,
|
|
417
|
+
or action runs OpenSpec itself.
|
|
418
|
+
|
|
419
|
+
| What it gives | In `SpecTool` | OpenSpec's |
|
|
420
|
+
| ----------------------------- | --------------------------------- | ------------------------------------------------------------------------------------------------------------ |
|
|
421
|
+
| Its name in init's messages | `name` | `OpenSpec` |
|
|
422
|
+
| Its option in init's question | `label` | `OpenSpec: each ticket holds its spec, and each build also keeps it in openspec/specs/` |
|
|
423
|
+
| How init installs it | `install` | `npm install --save-dev @fission-ai/openspec`, when `package.json` lists it in neither kind of dependency |
|
|
424
|
+
| The check by default | `defaultCheck` | `npx --no-install openspec validate --all --strict --no-interactive` |
|
|
425
|
+
| Its environment | `env` | `DO_NOT_TRACK=1`, so it collects no usage statistics |
|
|
426
|
+
| Its files that are process | `processFiles` | `openspec/config.yaml`, which the merge policy always holds for the owner, whichever tool the settings name |
|
|
427
|
+
| Whether it runs | `runs` | `npx --no-install openspec --version` exits 0 |
|
|
428
|
+
| The specs it keeps | `list` | Each folder under `openspec/specs/` with a `spec.md` |
|
|
429
|
+
| A ticket's spec | `folder`, `started`, `start` | A change, `openspec/changes/issue-N/`, started with `openspec new change` |
|
|
430
|
+
| The files to write | `files`, `then` | The proposal, the spec deltas, and, for a ticket with the `spec` label, the design and tasks; then the check |
|
|
431
|
+
| Folding it in | `finished`, `finish`, `foldsInto` | `openspec archive`, into `openspec/specs/`; a change already archived counts as folded |
|
|
432
|
+
|
|
433
|
+
Other tools fill these differently: one that keeps a feature's spec in a
|
|
434
|
+
single page marks that page `update` rather than `new`, one with no
|
|
435
|
+
check of its own names a skill on the "Then:" line, and one that is not
|
|
436
|
+
an npm package installs with its own command. `tests/memory-tools.ts`
|
|
437
|
+
holds such a tool, `pagesSpecTool`, and the command and init tests run
|
|
438
|
+
against it too, so nothing outside `src/specs/` assumes OpenSpec.
|
|
439
|
+
|
|
440
|
+
A tool's own process, such as Spec Kit's `/speckit.clarify` or EGM's
|
|
441
|
+
review, is not part of the adapter: a team that wants it sets it as a
|
|
442
|
+
[plugin](plugins.md), as the refiner or a reviewer.
|
|
443
|
+
|
|
399
444
|
## Setting a tool up
|
|
400
445
|
|
|
401
446
|
A tool is a code host, a ticket system, a runner, or a coding agent. Each
|
package/docs/existing-repo.md
CHANGED
|
@@ -51,16 +51,34 @@ complete settings file for a PHP library.
|
|
|
51
51
|
## You already have a board
|
|
52
52
|
|
|
53
53
|
A ticket is always in one of six [states](workflow.md#the-six-states),
|
|
54
|
-
and the factory shows each state as a column of your board.
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
|
|
54
|
+
and the factory shows each state as a column of your board. The settings
|
|
55
|
+
call the states `backlog`, `refining`, `ready`, `building`, `review`, and
|
|
56
|
+
`done`, in that order. `factory init` saves which of your columns shows
|
|
57
|
+
each in [`tickets.columns`](configuration.md#ticketscolumns), always all
|
|
58
|
+
six, and every factory command needs all six there.
|
|
59
59
|
|
|
60
60
|
When you run `factory init`, step 2 of the
|
|
61
|
-
[quick start](quick-start.md#2-set-it-up), it lists your boards to choose
|
|
62
|
-
one you choose has
|
|
63
|
-
|
|
61
|
+
[quick start](quick-start.md#2-set-it-up), it lists your boards to choose
|
|
62
|
+
from. If the one you choose already has the factory's own columns,
|
|
63
|
+
Backlog, In refinement, Ready, In progress, In review, and Done, init
|
|
64
|
+
asks nothing and saves them. Capitals don't matter, so your
|
|
65
|
+
"In Progress" is its "In progress":
|
|
66
|
+
|
|
67
|
+
```text
|
|
68
|
+
? Which board? Use an existing one: Shop board (#3)
|
|
69
|
+
|
|
70
|
+
Board 3 has a column for each of the factory's six states:
|
|
71
|
+
|
|
72
|
+
State Column
|
|
73
|
+
backlog Backlog
|
|
74
|
+
refining In refinement
|
|
75
|
+
ready Ready
|
|
76
|
+
building In Progress
|
|
77
|
+
review In review
|
|
78
|
+
done Done
|
|
79
|
+
```
|
|
80
|
+
|
|
81
|
+
If it lacks any, init asks your coding agent, Claude Code, which of your
|
|
64
82
|
columns shows each state, and shows you the answer before it changes
|
|
65
83
|
anything. This is one short request with no tools, made with the sign-in
|
|
66
84
|
Claude Code already has, and it sends your column names and nothing else.
|
|
@@ -74,8 +92,8 @@ Asking Claude Code which of them shows each of the factory's six states...
|
|
|
74
92
|
|
|
75
93
|
State Column
|
|
76
94
|
backlog Todo
|
|
77
|
-
refining
|
|
78
|
-
ready
|
|
95
|
+
refining none, shows in Todo
|
|
96
|
+
ready none
|
|
79
97
|
building In Progress
|
|
80
98
|
review Code review
|
|
81
99
|
done Done
|
|
@@ -89,12 +107,11 @@ Asking Claude Code which of them shows each of the factory's six states...
|
|
|
89
107
|
A state with no column shows its tickets in the column of the state
|
|
90
108
|
before it, so here a ticket being refined stays in Todo. With no column
|
|
91
109
|
for ready, you start each build with `/factory-build N` in a session,
|
|
92
|
-
rather than by moving its ticket on the board.
|
|
93
|
-
|
|
94
|
-
|
|
110
|
+
rather than by moving its ticket on the board. So init offers no column
|
|
111
|
+
for ready only when [`builds.trigger`](configuration.md#builds) is
|
|
112
|
+
`manual`, the setting for builds that start when you ask.
|
|
95
113
|
|
|
96
|
-
- **Yes** saves the table in your settings, `.claude/factory.yaml
|
|
97
|
-
only the states whose column isn't the factory's own name:
|
|
114
|
+
- **Yes** saves the table in your settings, `.claude/factory.yaml`:
|
|
98
115
|
|
|
99
116
|
```yaml
|
|
100
117
|
tickets:
|
|
@@ -103,7 +120,9 @@ ready only when builds start when you ask.
|
|
|
103
120
|
backlog: Todo
|
|
104
121
|
refining: none
|
|
105
122
|
ready: none
|
|
123
|
+
building: In Progress
|
|
106
124
|
review: Code review
|
|
125
|
+
done: Done
|
|
107
126
|
```
|
|
108
127
|
|
|
109
128
|
- **Change some** lets you pick the states to change from a list, then,
|
|
@@ -111,11 +130,11 @@ ready only when builds start when you ask.
|
|
|
111
130
|
factory's name, which init adds to your board. Each state needs a column
|
|
112
131
|
of its own: two states can't share one.
|
|
113
132
|
- **No** adds each of the factory's six columns your board lacks, here
|
|
114
|
-
Backlog, In refinement, Ready, and In review, and saves
|
|
115
|
-
Todo, In Progress, Code review, and Done columns
|
|
116
|
-
Done are used, since their names match. The
|
|
117
|
-
in Todo and Code review: nothing moves or
|
|
118
|
-
them to one of its columns.
|
|
133
|
+
Backlog, In refinement, Ready, and In review, and saves the six
|
|
134
|
+
factory names. Your Todo, In Progress, Code review, and Done columns
|
|
135
|
+
stay. In Progress and Done are used, since their names match. The
|
|
136
|
+
factory ignores the tickets in Todo and Code review: nothing moves or
|
|
137
|
+
builds them until you move them to one of its columns.
|
|
119
138
|
|
|
120
139
|
Init ends by running its checks. When the columns are right, you see:
|
|
121
140
|
|
|
@@ -131,14 +150,16 @@ one column for two states. It prints why. Then do one of these, and run
|
|
|
131
150
|
|
|
132
151
|
- sign in to Claude Code, by running `claude` once;
|
|
133
152
|
- write a `columns` block like the one above in `.claude/factory.yaml`
|
|
134
|
-
yourself, with
|
|
135
|
-
[`tickets.columns`](configuration.md#ticketscolumns) describes
|
|
136
|
-
|
|
153
|
+
yourself, with all six states, beside your `board`, as
|
|
154
|
+
[`tickets.columns`](configuration.md#ticketscolumns) describes. When
|
|
155
|
+
`factory config check` ends with `✓ The settings are valid.`, init
|
|
156
|
+
won't ask;
|
|
137
157
|
- add the six columns to your board yourself, so init has nothing to ask.
|
|
138
158
|
|
|
139
|
-
Running init again is safe: it keeps what your settings already say.
|
|
140
|
-
|
|
141
|
-
|
|
159
|
+
Running init again is safe: it keeps what your settings already say. If
|
|
160
|
+
the block leaves a state out, every factory command stops and names it,
|
|
161
|
+
and running init asks you only for that state. If you change your
|
|
162
|
+
board's columns later, edit the block, or delete it and run
|
|
142
163
|
`factory init` again for a new suggestion.
|
|
143
164
|
|
|
144
165
|
Init suggests one column for each state. When two of your columns mean the
|
|
@@ -319,9 +340,10 @@ names each file.
|
|
|
319
340
|
acts as the one account that owns its token: yours, or an account you
|
|
320
341
|
create for the team's builds
|
|
321
342
|
([Secrets](github/by-hand.md#secrets)).
|
|
322
|
-
- **
|
|
323
|
-
|
|
324
|
-
|
|
343
|
+
- **Anyone who can write to the repository is obeyed.** A session takes
|
|
344
|
+
instructions from a review or a comment by an account with write
|
|
345
|
+
access, and from nobody else. There is nothing to list: give a
|
|
346
|
+
teammate write access, and their reviews are answered.
|
|
325
347
|
- **One version for everyone.** The version is pinned in
|
|
326
348
|
`package-lock.json`. After an update merges, each person pulls and runs
|
|
327
349
|
`npm ci`. `factory doctor` says so when the installed
|
package/docs/github/by-hand.md
CHANGED
|
@@ -34,6 +34,9 @@ If you followed the quick start, this is done.
|
|
|
34
34
|
```yaml
|
|
35
35
|
version: 2
|
|
36
36
|
repository: your-name/your-repo
|
|
37
|
+
code-host:
|
|
38
|
+
type: github
|
|
39
|
+
branch-name: "{ticket}"
|
|
37
40
|
```
|
|
38
41
|
|
|
39
42
|
2. Write the factory's files:
|
|
@@ -163,11 +166,20 @@ what each column means.
|
|
|
163
166
|
Runs in, a single select with the options Local and Actions; and Cost, a
|
|
164
167
|
Number. A field the sync does not find, it skips.
|
|
165
168
|
4. **Point the settings at it,** with the Project's number under
|
|
166
|
-
[`tickets`](../configuration.md#tickets)
|
|
169
|
+
[`tickets`](../configuration.md#tickets), and which column shows each
|
|
170
|
+
state under [`tickets.columns`](../configuration.md#ticketscolumns),
|
|
171
|
+
here the columns step 2 added:
|
|
167
172
|
|
|
168
173
|
```yaml
|
|
169
174
|
tickets:
|
|
170
175
|
board: 7
|
|
176
|
+
columns:
|
|
177
|
+
backlog: Backlog
|
|
178
|
+
refining: In refinement
|
|
179
|
+
ready: Ready
|
|
180
|
+
building: In progress
|
|
181
|
+
review: In review
|
|
182
|
+
done: Done
|
|
171
183
|
```
|
|
172
184
|
|
|
173
185
|
Then `factory board check` shows how it reads your
|
package/docs/github/setup.md
CHANGED
|
@@ -29,8 +29,32 @@ In your repository, with the package
|
|
|
29
29
|
factory init
|
|
30
30
|
```
|
|
31
31
|
|
|
32
|
-
It shows what it found, then asks
|
|
33
|
-
|
|
32
|
+
It shows what it found, then asks what to name the branch a session
|
|
33
|
+
pushes when it builds a ticket, offering `{ticket}`, the ticket's
|
|
34
|
+
number, so ticket 12 is built on a branch named `12`. Press Enter to
|
|
35
|
+
keep it, or type your team's pattern, such as `feature/{user}/{ticket}`,
|
|
36
|
+
where `{user}` is your GitHub account;
|
|
37
|
+
[`code-host`](../configuration.md#code-host) lists what a pattern can
|
|
38
|
+
hold.
|
|
39
|
+
|
|
40
|
+
Next it asks which spec tool you use:
|
|
41
|
+
|
|
42
|
+
```text
|
|
43
|
+
? Which spec tool do you use?
|
|
44
|
+
❯ None: each ticket holds its own spec
|
|
45
|
+
OpenSpec: each ticket holds its spec, and each build also keeps it in openspec/specs/
|
|
46
|
+
```
|
|
47
|
+
|
|
48
|
+
Choose **None** unless you want a folder in your repository that always
|
|
49
|
+
describes what your project does, readable without opening a ticket:
|
|
50
|
+
that is what OpenSpec adds. Choose **OpenSpec** and init installs it for
|
|
51
|
+
you, printing `Installed @fission-ai/openspec.` once it has. Your answer is written to `.claude/factory.yaml` as
|
|
52
|
+
[`specs`](../configuration.md#specs).
|
|
53
|
+
|
|
54
|
+
Init skips the branch-name question when your `.claude/factory.yaml`, or
|
|
55
|
+
a [preset](../presets.md) you follow, sets `code-host.branch-name`, and
|
|
56
|
+
the spec tool question when they set `specs`. Then it asks
|
|
57
|
+
which parts you want. Each is optional and stands alone:
|
|
34
58
|
|
|
35
59
|
| Part | What you get |
|
|
36
60
|
| ----------------------------------------------- | ------------------------------------------------------------------------------ |
|
package/docs/glossary.md
CHANGED
|
@@ -33,9 +33,9 @@ written so each item can be checked. Refining a ticket produces it.
|
|
|
33
33
|
something and report back. It changes nothing. The factory brings four,
|
|
34
34
|
and you can add your own.
|
|
35
35
|
|
|
36
|
-
**Approver.** A person whose
|
|
37
|
-
|
|
38
|
-
|
|
36
|
+
**Approver.** A person whose words a session treats as instructions:
|
|
37
|
+
anyone whose account can write to the repository. Who can approve a
|
|
38
|
+
ticket for building is whoever your board lets move it to Ready.
|
|
39
39
|
|
|
40
40
|
**Automated review.** A review of every pull request by the coding agent,
|
|
41
41
|
run in CI once the pull request is marked ready. It comments on what it
|
|
@@ -118,9 +118,10 @@ your machine or in the cloud.
|
|
|
118
118
|
for the factory's own. You call one by typing its name as a slash command,
|
|
119
119
|
such as `/factory-refine 12`.
|
|
120
120
|
|
|
121
|
-
**Spec.** A written statement of what a change must do.
|
|
122
|
-
|
|
123
|
-
|
|
121
|
+
**Spec.** A written statement of what a change must do. A change your
|
|
122
|
+
users will see gets a Spec section of "When this, then that" lines in
|
|
123
|
+
its ticket; every other ticket has acceptance criteria. With OpenSpec
|
|
124
|
+
turned on, the Spec is also kept in the repository.
|
|
124
125
|
|
|
125
126
|
**Ticket.** One item in the ticket system: a piece of work, with what,
|
|
126
127
|
why, and when it is done.
|
package/docs/limitations.md
CHANGED
|
@@ -27,9 +27,11 @@ as a code host's billing or what its workflows can see, are in
|
|
|
27
27
|
there. A change to those settings is a person's to make.
|
|
28
28
|
- **One ticket, one repository.** A change that spans repositories is two
|
|
29
29
|
tickets.
|
|
30
|
-
- **
|
|
31
|
-
|
|
32
|
-
|
|
30
|
+
- **Review by teams is your code host's to enforce.** A session obeys
|
|
31
|
+
anyone who can write to the repository. Required reviewers for a
|
|
32
|
+
folder, and a number of approvals before a merge, are rules you set on
|
|
33
|
+
the code host, and the factory's pull requests are held by them like
|
|
34
|
+
any other.
|
|
33
35
|
- **The order of the workflow is fixed.** A [plugin](plugins.md) of
|
|
34
36
|
yours can replace how a ticket is refined, how a ticket with one of your
|
|
35
37
|
labels is built, how a test is proved able to fail, which agents review
|
|
@@ -127,8 +129,9 @@ as a code host's billing or what its workflows can see, are in
|
|
|
127
129
|
- **It amplifies the checks it is given.** A repository with weak tests gets
|
|
128
130
|
confident, wrong pull requests faster.
|
|
129
131
|
- **Ticket text, review comments, and changelogs are read by sessions.**
|
|
130
|
-
Only an approver's
|
|
131
|
-
|
|
132
|
+
Only an approver's words are treated as instructions, and that rests on
|
|
133
|
+
who your code host says can write to the repository. Give write access
|
|
134
|
+
as carefully as you would give a session its orders.
|
|
132
135
|
- **An update delivers instructions that run with your tokens.** Read update
|
|
133
136
|
pull requests as carefully as code.
|
|
134
137
|
- **It sits on tools that change.** Several parts work around how today's
|
package/docs/presets.md
CHANGED
|
@@ -18,9 +18,11 @@ It has two readers:
|
|
|
18
18
|
Without a preset, every repository's
|
|
19
19
|
[`.claude/factory.yaml`](configuration.md) repeats the same lines, such as
|
|
20
20
|
the board's number in [`tickets.board`](configuration.md#tickets), the
|
|
21
|
-
size limit in [`rules.small-change-lines`](configuration.md#rules),
|
|
22
|
-
|
|
23
|
-
|
|
21
|
+
size limit in [`rules.small-change-lines`](configuration.md#rules), the
|
|
22
|
+
way your team names branches in
|
|
23
|
+
[`code-host.branch-name`](configuration.md#code-host), and the same
|
|
24
|
+
[reviewer plugins](plugins.md#reviewer), your own agents that read every
|
|
25
|
+
change. Changing one of them means a pull request in every
|
|
24
26
|
repository, and nothing shows which ones have fallen behind.
|
|
25
27
|
|
|
26
28
|
With a preset, a repository names it under
|
|
@@ -298,6 +300,16 @@ maintains the preset.
|
|
|
298
300
|
tickets:
|
|
299
301
|
type: github
|
|
300
302
|
board: 7
|
|
303
|
+
columns:
|
|
304
|
+
backlog: Backlog
|
|
305
|
+
refining: In refinement
|
|
306
|
+
ready: Ready
|
|
307
|
+
building: In progress
|
|
308
|
+
review: In review
|
|
309
|
+
done: Done
|
|
310
|
+
code-host:
|
|
311
|
+
type: github
|
|
312
|
+
branch-name: "feature/{user}/{ticket}"
|
|
301
313
|
rules:
|
|
302
314
|
small-change-lines: 40
|
|
303
315
|
plugins:
|