@davidbyoung/software-factory 0.1.10 → 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 +3 -4
- package/dist/cli.mjs +17 -4
- package/dist/code-host/github.mjs +2 -0
- package/dist/code-host/types.d.mts +4 -0
- package/dist/commands.d.mts +7 -2
- package/dist/commands.mjs +86 -16
- package/dist/config.d.mts +3 -4
- package/dist/config.mjs +7 -8
- package/dist/init.d.mts +11 -0
- package/dist/init.mjs +56 -1
- 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/pr.d.mts +8 -6
- package/dist/pr.mjs +39 -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 +3 -1
- package/dist/ticket.mjs +36 -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 +4 -1
- package/docs/cli.md +19 -4
- package/docs/configuration.md +50 -38
- package/docs/developing.md +104 -59
- package/docs/existing-repo.md +4 -3
- package/docs/github/setup.md +20 -3
- package/docs/glossary.md +7 -6
- package/docs/limitations.md +8 -5
- package/docs/updating.md +18 -0
- package/docs/workflow.md +25 -8
- package/package.json +1 -1
- package/rules.md +36 -30
- package/skills/factory-address-review/SKILL.md +40 -39
- package/skills/factory-build/SKILL.md +46 -53
- package/skills/factory-refine/SKILL.md +30 -22
- package/skills/factory-resolve-conflicts/SKILL.md +8 -7
|
@@ -0,0 +1,22 @@
|
|
|
1
|
+
// Whether an account can write to a GitHub repository: the one lookup both
|
|
2
|
+
// GitHub adapters ask when they decide whose words count as instructions.
|
|
3
|
+
import { statusOf } from "./transport.mjs";
|
|
4
|
+
/** Whether `login` can write to `repository` (owner/name), counting every
|
|
5
|
+
* grant: repository, team, organization, and enterprise. Rejects when
|
|
6
|
+
* GitHub cannot say, so a failed lookup is never read as "yes". */
|
|
7
|
+
export async function writeAccess(t, repository, login) {
|
|
8
|
+
const API = `repos/${repository}`;
|
|
9
|
+
try {
|
|
10
|
+
const answer = await t.rest("GET", `${API}/collaborators/${encodeURIComponent(login)}/permission`);
|
|
11
|
+
return answer.permission === "admin" || answer.permission === "write";
|
|
12
|
+
}
|
|
13
|
+
catch (error) {
|
|
14
|
+
if (statusOf(error) !== 404)
|
|
15
|
+
throw error;
|
|
16
|
+
// A token that cannot see a private repository gets a 404 for every
|
|
17
|
+
// name, so a 404 means "no such account" only when the repository can
|
|
18
|
+
// be read.
|
|
19
|
+
await t.rest("GET", API);
|
|
20
|
+
return false;
|
|
21
|
+
}
|
|
22
|
+
}
|
package/dist/tickets/github.mjs
CHANGED
|
@@ -7,6 +7,7 @@ import { rmSync, writeFileSync } from "node:fs";
|
|
|
7
7
|
import { tmpdir } from "node:os";
|
|
8
8
|
import { dirname, join } from "node:path";
|
|
9
9
|
import { NotFoundError, } from "./types.mjs";
|
|
10
|
+
import { writeAccess } from "./github-access.mjs";
|
|
10
11
|
import { statusOf } from "./transport.mjs";
|
|
11
12
|
import { sameName } from "../lib/work-status.mjs";
|
|
12
13
|
const toComment = (raw) => ({
|
|
@@ -346,6 +347,7 @@ export function githubTickets(o) {
|
|
|
346
347
|
await issue(n);
|
|
347
348
|
}
|
|
348
349
|
},
|
|
350
|
+
mayDecide: (author) => writeAccess(t, o.repository, author),
|
|
349
351
|
linkText: (n) => `Closes #${n}`,
|
|
350
352
|
address: (n) => `https://github.com/${o.repository}/issues/${n}`,
|
|
351
353
|
board: {
|
package/dist/tickets/types.d.mts
CHANGED
|
@@ -178,6 +178,10 @@ export type Tickets = {
|
|
|
178
178
|
open(ticket: NewTicket): Promise<number>;
|
|
179
179
|
addLabel(ticket: number, label: string): Promise<void>;
|
|
180
180
|
removeLabel(ticket: number, label: string): Promise<void>;
|
|
181
|
+
/** Whether a comment by `author` may decide on a ticket: an answer to a
|
|
182
|
+
* question, taken as an instruction. Rejects when the system cannot
|
|
183
|
+
* say. */
|
|
184
|
+
mayDecide(author: string): Promise<boolean>;
|
|
181
185
|
/** What makes a merged pull request close the ticket. */
|
|
182
186
|
linkText(ticket: number): string;
|
|
183
187
|
/** The address of the ticket's page. */
|
package/dist/tool-names.d.mts
CHANGED
|
@@ -3,6 +3,8 @@ export type Built = {
|
|
|
3
3
|
/** Each ticket system, with the keys it adds under `tickets`. */
|
|
4
4
|
tickets: Readonly<Record<string, readonly string[]>>;
|
|
5
5
|
runner: readonly string[];
|
|
6
|
+
/** Each spec tool, with the check \`specs.check\` defaults to. */
|
|
7
|
+
specs: Readonly<Record<string, string>>;
|
|
6
8
|
};
|
|
7
9
|
export declare const BUILT: Built;
|
|
8
10
|
/** The words every command fails with for a name that is not built, such
|
package/dist/tool-names.mjs
CHANGED
|
@@ -8,6 +8,9 @@ export const BUILT = {
|
|
|
8
8
|
codeHost: ["github"],
|
|
9
9
|
tickets: { github: [] },
|
|
10
10
|
runner: ["github-actions"],
|
|
11
|
+
specs: {
|
|
12
|
+
openspec: "npx --no-install openspec validate --all --strict --no-interactive",
|
|
13
|
+
},
|
|
11
14
|
};
|
|
12
15
|
/** The words every command fails with for a name that is not built, such
|
|
13
16
|
* as `tickets.type "jira" is not supported. "github" is the only ticket
|
package/dist/tools.d.mts
CHANGED
|
@@ -5,6 +5,7 @@ import type { Part } from "./parts.mts";
|
|
|
5
5
|
import { type Runner } from "./runner/index.mts";
|
|
6
6
|
import type { Chosen, SecretStep, SetupContext, SetupStep, ToolSetup } from "./setup.mts";
|
|
7
7
|
import { type Tickets } from "./tickets/index.mts";
|
|
8
|
+
import { type SpecTools } from "./specs/index.mts";
|
|
8
9
|
import { type Built } from "./tool-names.mts";
|
|
9
10
|
export type Tool = {
|
|
10
11
|
label: string;
|
|
@@ -31,6 +32,7 @@ export type Registry = {
|
|
|
31
32
|
agent: Record<string, Tool & {
|
|
32
33
|
agent: Agent;
|
|
33
34
|
}>;
|
|
35
|
+
specs: SpecTools;
|
|
34
36
|
};
|
|
35
37
|
export declare const TOOLS: Registry;
|
|
36
38
|
/** The names and keys the settings accept, as `config.mts` checks them. */
|
package/dist/tools.mjs
CHANGED
|
@@ -12,6 +12,7 @@ import { githubTicketsSetup } from "./tickets/github-setup.mjs";
|
|
|
12
12
|
import { openTickets } from "./tickets/index.mjs";
|
|
13
13
|
import { ghTransport } from "./tickets/transport.mjs";
|
|
14
14
|
import { githubActionsSetup } from "./runner/setup.mjs";
|
|
15
|
+
import { specTools } from "./specs/index.mjs";
|
|
15
16
|
import { BUILT } from "./tool-names.mjs";
|
|
16
17
|
export const TOOLS = {
|
|
17
18
|
codeHost: {
|
|
@@ -50,6 +51,7 @@ export const TOOLS = {
|
|
|
50
51
|
agent: claudeCodeAgent(spawn),
|
|
51
52
|
},
|
|
52
53
|
},
|
|
54
|
+
specs: specTools(),
|
|
53
55
|
};
|
|
54
56
|
/** The names and keys the settings accept, as `config.mts` checks them. */
|
|
55
57
|
export function builtOf(r) {
|
|
@@ -57,6 +59,7 @@ export function builtOf(r) {
|
|
|
57
59
|
codeHost: Object.keys(r.codeHost),
|
|
58
60
|
tickets: Object.fromEntries(Object.entries(r.tickets).map(([name, t]) => [name, t.keys])),
|
|
59
61
|
runner: Object.keys(r.runner),
|
|
62
|
+
specs: Object.fromEntries(Object.entries(r.specs).map(([name, t]) => [name, t.defaultCheck])),
|
|
60
63
|
};
|
|
61
64
|
}
|
|
62
65
|
/** The tools in use, in the order setup asks for them. */
|
package/docs/builds.md
CHANGED
|
@@ -64,7 +64,10 @@ stores it.
|
|
|
64
64
|
commits name your coding agent as their author and that account as their
|
|
65
65
|
committer, and its pull request and comments are that account's. When the token is yours, that is you. A team that wants an
|
|
66
66
|
agent account makes one on the code host, gives it write access, and stores
|
|
67
|
-
its token instead. Nothing else changes.
|
|
67
|
+
its token instead. Nothing else changes. An agent account can write to the
|
|
68
|
+
repository, so it counts as an approver, but every comment it posts
|
|
69
|
+
carries the factory's mark, and a session never takes a marked comment as
|
|
70
|
+
an instruction.
|
|
68
71
|
|
|
69
72
|
**Signed commits.** With a signing key stored as a secret, the build signs
|
|
70
73
|
each commit, and the code host shows it as verified when the key belongs to
|
package/docs/cli.md
CHANGED
|
@@ -140,6 +140,7 @@ ticket system would swallow, name it, and post nothing.
|
|
|
140
140
|
| Command | What it does |
|
|
141
141
|
| ---------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
142
142
|
| `factory ticket view N` | Prints ticket N: its title, state, labels, body, and comments with their IDs and authors |
|
|
143
|
+
| `factory ticket answers N` | Prints each comment on N that counts as an answer: its author can write to the repository, and it is not the factory's own. Says so when there is none |
|
|
143
144
|
| `factory ticket view N --field NAME` | Prints one of `title`, `state`, `labels` (one per line), or `body`, and nothing else |
|
|
144
145
|
| `factory ticket list` | Lists the open tickets: number, title, and labels, separated by tabs |
|
|
145
146
|
| `factory ticket list --label LABEL` | Only those with the label. `--title "TITLE"` keeps those whose title is exactly that |
|
|
@@ -186,13 +187,13 @@ ticket system.
|
|
|
186
187
|
| `factory pr for-branch BRANCH` | The newest pull request from BRANCH, open or not: `#N open`, `#N merged`, or `#N closed`, or `none` when there has been none |
|
|
187
188
|
| `factory pr wait-checks N` | Waits for every CI run on the pushed commit. Prints `success`, `failure:` with the failed checks, or `no checks` |
|
|
188
189
|
| `factory pr ready N` | Marks a draft ready for review. When `commit.gpgsign` is `true`, refuses while the code host shows a commit as not verified |
|
|
189
|
-
| `factory pr comments N` | N's conversation comments: ID, author, time, and first line. `--author LOGIN`, `--contains TEXT`, and `--json`, which prints each comment's `id`, `user.login`, `body`, and `created_at`
|
|
190
|
+
| `factory pr comments N` | N's conversation comments: ID, author, time, and first line. `--author LOGIN`, `--contains TEXT`, `--from-approvers`, which keeps the comments whose author can write to the repository, and `--json`, which prints each comment's `id`, `user.login`, `body`, and `created_at` |
|
|
190
191
|
| `factory pr comment N --body-file FILE` | Posts a conversation comment and prints its ID. Refuses a bare tag-like `<word>`, as `ticket comment` does |
|
|
191
192
|
| `factory pr comment-view ID` | Prints one conversation comment's body |
|
|
192
193
|
| `factory pr label N --add LABEL` | Adds a label to N. `--remove LABEL` takes one off |
|
|
193
194
|
| `factory pr watch N` | Waits until N needs attention, says why, and exits |
|
|
194
195
|
| `factory pr watch N --release` | Stops watching N |
|
|
195
|
-
| `factory pr review-pending N REVIEW` | Exits 0 when
|
|
196
|
+
| `factory pr review-pending N REVIEW` | Exits 0 when an approver's review has something of theirs to answer, and 1, saying why, when it has not |
|
|
196
197
|
| `factory pr conflicts` | The pull requests the conflict sweep takes, one number a line; exits 0 when there is one and 1 when none |
|
|
197
198
|
| `factory pr open --title TITLE --body-file FILE` | Opens a draft pull request from the current branch into the default branch and prints its number. `--base BRANCH` names another base, and `--ready` opens it ready for review. Fails in the code host's own words when the branch has nothing new or already has one open |
|
|
198
199
|
| `factory pr view N --field FIELD` | Prints one field of N: `head` (its last commit, in full), `branch`, `base`, `title`, `body`, `state`, or `mergeable` (`dirty` for a conflict, `unknown` until the code host has worked it out) |
|
|
@@ -224,10 +225,24 @@ You can run them too.
|
|
|
224
225
|
| `factory gate` | Runs each [`commands.gate`](configuration.md#commandsgate) command in order, printing `$` and the command before each. Stops at the first that fails, with `✗ The gate failed on:` and the command. Ends with `✓ Every gate command passed.` and exits 0 when every command passes, and exits 1 at the first that fails or when no gate is set |
|
|
225
226
|
| `factory test-one FILE [NAME]` | Runs [`commands.test-one`](configuration.md#commandstest-one), one test file alone or the one test NAME in it, and exits with its status |
|
|
226
227
|
| `factory end-to-end FILE [--times K]` | Runs [`commands.end-to-end`](configuration.md#commandsend-to-end), one end-to-end spec alone, and exits with its status. With `--times K`, K times in a row, stopping at the first run that fails. Ends with `✓ The test passed.` or `✗ The test failed.` |
|
|
227
|
-
| `factory specs
|
|
228
|
-
| `factory specs
|
|
228
|
+
| `factory specs list` | Prints each spec your spec tool keeps, one per line with its file, or `none yet` |
|
|
229
|
+
| `factory specs new N` | Starts ticket N's spec: with OpenSpec, it creates `openspec/changes/issue-N/`. Then it prints each file to write or update there, which part of the ticket goes in it, and, last, the command to run once they are written. It writes none of them itself, and run again, it prints them again |
|
|
230
|
+
| `factory specs check` | Runs [`specs.check`](configuration.md#specscheck), the check of your written specs, ending with `✓ The specs check passed.` or `✗ The specs check failed.` |
|
|
231
|
+
| `factory specs finish N` | With OpenSpec, folds ticket N's spec into `openspec/specs/`, ending with `✓ Folded ticket N's spec into openspec/specs/.` It changes files and commits nothing |
|
|
229
232
|
| `factory default-branch` | Prints the name of your repository's default branch, which nothing in the factory assumes is `main` |
|
|
230
233
|
|
|
234
|
+
With [`specs: none`](configuration.md#specs), each of the four
|
|
235
|
+
`factory specs` commands prints
|
|
236
|
+
`- No spec tool (specs: none): each ticket holds its own spec.` and
|
|
237
|
+
exits 0. Otherwise each exits 0 when it worked and 1 when it didn't, and
|
|
238
|
+
says why on its last line: `new` when your spec tool isn't installed, which
|
|
239
|
+
`factory init` fixes, and `finish` when ticket N has no spec started,
|
|
240
|
+
which `factory specs new N` fixes.
|
|
241
|
+
|
|
242
|
+
A build runs `new` before it writes any code, and `finish` just before
|
|
243
|
+
its last commit, so you rarely run those two yourself. `list` is the one
|
|
244
|
+
to know: it names the spec to read before you change what it describes.
|
|
245
|
+
|
|
231
246
|
`factory default-branch` asks, in turn, the event of the workflow run it
|
|
232
247
|
is in, `origin/HEAD` in your checkout, and the code host, whose answer it
|
|
233
248
|
writes to `origin/HEAD` so the next run asks nobody. A checkout with no
|
package/docs/configuration.md
CHANGED
|
@@ -542,42 +542,74 @@ marks it "not started": after 5 minutes with `own-server`, and after
|
|
|
542
542
|
|
|
543
543
|
### `specs`
|
|
544
544
|
|
|
545
|
-
|
|
546
|
-
|
|
545
|
+
Which spec tool your project uses, if any. Either way, refinement writes
|
|
546
|
+
a [Spec, a design, and a list of tasks](workflow.md#a-change-your-users-will-see)
|
|
547
|
+
into the ticket of each change your users will see. A spec tool also
|
|
548
|
+
keeps the Spec in your repository.
|
|
547
549
|
|
|
548
550
|
```yaml
|
|
551
|
+
# The default: refinement writes the Spec into the ticket, and nothing is
|
|
552
|
+
# kept in your repository. Leaving the line out means the same.
|
|
553
|
+
specs: none
|
|
554
|
+
```
|
|
555
|
+
|
|
556
|
+
```yaml
|
|
557
|
+
# Each build also writes the ticket's Spec into openspec/specs/.
|
|
549
558
|
specs: openspec
|
|
550
559
|
```
|
|
551
560
|
|
|
552
|
-
- **`none`,** the default: the ticket
|
|
553
|
-
|
|
554
|
-
- **`openspec`:**
|
|
555
|
-
[
|
|
556
|
-
|
|
557
|
-
|
|
558
|
-
|
|
559
|
-
|
|
560
|
-
|
|
561
|
+
- **`none`,** the default: the ticket is the only place the Spec is
|
|
562
|
+
written down.
|
|
563
|
+
- **`openspec`:** each build also writes the ticket's Spec into
|
|
564
|
+
`openspec/specs/`, using [OpenSpec](https://github.com/Fission-AI/OpenSpec),
|
|
565
|
+
so that folder always describes what your project does, readable
|
|
566
|
+
without opening a ticket.
|
|
567
|
+
|
|
568
|
+
**`factory init` asks, and writes the answer here.** It asks "Which spec
|
|
569
|
+
tool do you use?" when `.claude/factory.yaml` has no `specs` line and no
|
|
570
|
+
[preset](presets.md) sets one. With `openspec`, init installs OpenSpec as
|
|
571
|
+
a development dependency, `npm install --save-dev @fission-ai/openspec`,
|
|
572
|
+
whenever your `package.json` doesn't list it, and prints
|
|
573
|
+
`Installed @fission-ai/openspec.` It worked when that line prints and
|
|
574
|
+
`package.json` lists the package. So to turn OpenSpec on later, write
|
|
575
|
+
`specs: openspec` and run `factory init` again. A re-run is safe: it
|
|
576
|
+
keeps every setting you have, asks again only which parts you want,
|
|
577
|
+
with yours already checked, and shows everything it will do before it
|
|
578
|
+
does it.
|
|
579
|
+
|
|
580
|
+
**Without OpenSpec installed,** a build stops at its first spec step and
|
|
581
|
+
says to run `factory init`.
|
|
582
|
+
|
|
583
|
+
`factory specs list` prints the specs your repository keeps, one per
|
|
584
|
+
line with its file, which is what to read before changing what a spec
|
|
585
|
+
describes. The build runs `factory specs new`, `check`, and `finish`
|
|
586
|
+
itself; [Your repository's commands](cli.md#your-repositorys-commands)
|
|
587
|
+
says what each prints.
|
|
561
588
|
|
|
562
589
|
#### `specs.check`
|
|
563
590
|
|
|
564
|
-
The command that checks your written specs are
|
|
591
|
+
The command that checks your written specs are well formed, such as
|
|
592
|
+
that every requirement has a scenario. To set it, write `specs` as a
|
|
593
|
+
block: its `type` is the tool the one-line form names, so
|
|
594
|
+
`specs: openspec` and the block below make the same choice.
|
|
565
595
|
`factory specs check` runs it, and so does a build each time it writes a
|
|
566
|
-
spec.
|
|
596
|
+
spec. It belongs only with `type: openspec`.
|
|
567
597
|
|
|
568
598
|
```yaml
|
|
569
599
|
specs:
|
|
570
600
|
type: openspec
|
|
601
|
+
# Optional: this is the default.
|
|
571
602
|
check: npx --no-install openspec validate --all --strict --no-interactive
|
|
572
603
|
```
|
|
573
604
|
|
|
574
|
-
- **Default:** the command above,
|
|
575
|
-
|
|
576
|
-
with `type: openspec`, so most repositories leave it out.
|
|
605
|
+
- **Default:** the command above, so most repositories leave `check`
|
|
606
|
+
out and write only `specs: openspec`.
|
|
577
607
|
- **It runs with `DO_NOT_TRACK=1` set,** so OpenSpec collects no usage
|
|
578
608
|
statistics.
|
|
579
|
-
- **With `specs: none`** there is nothing to check, and
|
|
580
|
-
fails `factory config check`.
|
|
609
|
+
- **With `specs: none`** there is nothing to check, and a `check` line
|
|
610
|
+
fails `factory config check`: delete it when you switch to `none`.
|
|
611
|
+
|
|
612
|
+
It worked when `factory specs check` ends with `✓ The specs check passed.`
|
|
581
613
|
|
|
582
614
|
### `commands`
|
|
583
615
|
|
|
@@ -1140,26 +1172,6 @@ pr-review:
|
|
|
1140
1172
|
removes the workflow.
|
|
1141
1173
|
- `factory review tools` prints everything the reviewer may use.
|
|
1142
1174
|
|
|
1143
|
-
### `approvers`
|
|
1144
|
-
|
|
1145
|
-
_[Planned](developing.md#what-is-built)_: `factory config check` refuses
|
|
1146
|
-
this setting until it is built.
|
|
1147
|
-
|
|
1148
|
-
The people whose comments a session takes as instructions, and whose move
|
|
1149
|
-
of a ticket to Ready counts as approving it. Everyone else's comments are
|
|
1150
|
-
read as information.
|
|
1151
|
-
|
|
1152
|
-
```yaml
|
|
1153
|
-
approvers:
|
|
1154
|
-
- your-name
|
|
1155
|
-
- a-teammate
|
|
1156
|
-
```
|
|
1157
|
-
|
|
1158
|
-
- **Default:** the repository's owner, so a repository with one person
|
|
1159
|
-
leaves it out.
|
|
1160
|
-
- **If a name is wrong,** that person's comments are treated as
|
|
1161
|
-
information, and a ticket they approve is not built.
|
|
1162
|
-
|
|
1163
1175
|
### `rules`
|
|
1164
1176
|
|
|
1165
1177
|
Two numbers the factory's rules use, for a repository that wants
|
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
|
@@ -340,9 +340,10 @@ names each file.
|
|
|
340
340
|
acts as the one account that owns its token: yours, or an account you
|
|
341
341
|
create for the team's builds
|
|
342
342
|
([Secrets](github/by-hand.md#secrets)).
|
|
343
|
-
- **
|
|
344
|
-
|
|
345
|
-
|
|
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.
|
|
346
347
|
- **One version for everyone.** The version is pinned in
|
|
347
348
|
`package-lock.json`. After an update merges, each person pulls and runs
|
|
348
349
|
`npm ci`. `factory doctor` says so when the installed
|
package/docs/github/setup.md
CHANGED
|
@@ -35,9 +35,26 @@ number, so ticket 12 is built on a branch named `12`. Press Enter to
|
|
|
35
35
|
keep it, or type your team's pattern, such as `feature/{user}/{ticket}`,
|
|
36
36
|
where `{user}` is your GitHub account;
|
|
37
37
|
[`code-host`](../configuration.md#code-host) lists what a pattern can
|
|
38
|
-
hold.
|
|
39
|
-
|
|
40
|
-
|
|
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:
|
|
41
58
|
|
|
42
59
|
| Part | What you get |
|
|
43
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.
|