@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.
Files changed (51) hide show
  1. package/agents/factory-ticket-readiness.md +20 -15
  2. package/dist/board.d.mts +1 -1
  3. package/dist/board.mjs +3 -4
  4. package/dist/cli.mjs +17 -4
  5. package/dist/code-host/github.mjs +2 -0
  6. package/dist/code-host/types.d.mts +4 -0
  7. package/dist/commands.d.mts +7 -2
  8. package/dist/commands.mjs +86 -16
  9. package/dist/config.d.mts +3 -4
  10. package/dist/config.mjs +7 -8
  11. package/dist/init.d.mts +11 -0
  12. package/dist/init.mjs +56 -1
  13. package/dist/lib/work-status.d.mts +5 -5
  14. package/dist/lib/work-status.mjs +7 -8
  15. package/dist/merge-policy.mjs +7 -3
  16. package/dist/pr.d.mts +8 -6
  17. package/dist/pr.mjs +39 -22
  18. package/dist/review-verdict.d.mts +22 -4
  19. package/dist/review-verdict.mjs +55 -17
  20. package/dist/specs/index.d.mts +6 -0
  21. package/dist/specs/index.mjs +15 -0
  22. package/dist/specs/openspec.d.mts +2 -0
  23. package/dist/specs/openspec.mjs +78 -0
  24. package/dist/specs/types.d.mts +53 -0
  25. package/dist/specs/types.mjs +4 -0
  26. package/dist/ticket.d.mts +3 -1
  27. package/dist/ticket.mjs +36 -3
  28. package/dist/tickets/github-access.d.mts +5 -0
  29. package/dist/tickets/github-access.mjs +22 -0
  30. package/dist/tickets/github.mjs +2 -0
  31. package/dist/tickets/types.d.mts +4 -0
  32. package/dist/tool-names.d.mts +2 -0
  33. package/dist/tool-names.mjs +3 -0
  34. package/dist/tools.d.mts +2 -0
  35. package/dist/tools.mjs +3 -0
  36. package/docs/builds.md +4 -1
  37. package/docs/cli.md +19 -4
  38. package/docs/configuration.md +50 -38
  39. package/docs/developing.md +104 -59
  40. package/docs/existing-repo.md +4 -3
  41. package/docs/github/setup.md +20 -3
  42. package/docs/glossary.md +7 -6
  43. package/docs/limitations.md +8 -5
  44. package/docs/updating.md +18 -0
  45. package/docs/workflow.md +25 -8
  46. package/package.json +1 -1
  47. package/rules.md +36 -30
  48. package/skills/factory-address-review/SKILL.md +40 -39
  49. package/skills/factory-build/SKILL.md +46 -53
  50. package/skills/factory-refine/SKILL.md +30 -22
  51. 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
+ }
@@ -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: {
@@ -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. */
@@ -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
@@ -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 the owner's review has something of theirs to answer, and 1, saying why, when it has not |
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 check` | Runs [`specs.check`](configuration.md#specscheck), the check of your written specs, and exits with its status, ending with `✓ The specs check passed.` or `✗ The specs check failed.`. Prints `specs are off` when `specs` is `none` |
228
- | `factory specs change-name N` | Prints the name of the OpenSpec change a build of N writes, always `issue-N` whatever [`code-host.branch-name`](configuration.md#code-host) says. Exits 1 with `specs are off: there is no spec change to name` when [`specs`](configuration.md#specs) is `none` |
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
@@ -542,42 +542,74 @@ marks it "not started": after 5 minutes with `own-server`, and after
542
542
 
543
543
  ### `specs`
544
544
 
545
- Whether a change your users will see also gets a written spec, kept beside
546
- your code.
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's acceptance criteria are the only
553
- spec.
554
- - **`openspec`:** a visible change that isn't
555
- [small](workflow.md#sizing-the-work-to-the-change) also writes its new
556
- behavior into `openspec/specs/`, using
557
- [OpenSpec](https://github.com/Fission-AI/OpenSpec), so that folder
558
- always describes what your project does. Install it first, with
559
- `npm install -D @fission-ai/openspec`. Without it, a build stops at its
560
- first spec step and says so.
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 sound.
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
- `npx --no-install openspec validate --all --strict --no-interactive`,
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 writing `check`
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
@@ -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
- | `approvers` in the settings | Planned, [#14](https://github.com/davidbyoung/software-factory/issues/14) |
73
- | Another ticket system, such as Jira | Not planned. The design leaves room |
74
- | A ticket system or code host named by a package, for an adapter you write yourself | Not planned. The design leaves room |
75
- | Another code host or runner | Not planned. The design leaves room |
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
- | Link text | `linkText` | What makes a merged pull request close the ticket, such as "Closes #12" |
240
- | The address of a ticket | `address` | Its page, which the views link a ticket's number to |
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
@@ -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
- - **Say who approves.** By default only the repository's owner can approve
344
- a ticket for building or give a session instructions in a comment. List
345
- the others under [`approvers`](configuration.md#approvers), _[Planned](developing.md#what-is-built)_.
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
@@ -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. When a [preset](../presets.md) you follow already sets it, init
39
- doesn't ask. Then it asks which parts you want. Each is optional and
40
- stands alone:
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 comments a session treats as instructions,
37
- and who can approve a ticket for building. By default, the repository's
38
- owner.
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. For most tickets
122
- that is the acceptance criteria. With OpenSpec turned on, a change your
123
- users will see also gets its behavior recorded in the repository.
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.