@davidbyoung/software-factory 0.1.5 → 0.1.6

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 (43) hide show
  1. package/README.md +9 -8
  2. package/dist/cli.mjs +12 -0
  3. package/dist/config.d.mts +57 -3
  4. package/dist/config.mjs +268 -18
  5. package/dist/deps.d.mts +6 -4
  6. package/dist/deps.mjs +29 -7
  7. package/dist/doctor.d.mts +3 -0
  8. package/dist/doctor.mjs +7 -4
  9. package/dist/explain.d.mts +12 -1
  10. package/dist/explain.mjs +47 -32
  11. package/dist/init.mjs +6 -4
  12. package/dist/lib/default-branch.d.mts +1 -1
  13. package/dist/lib/default-branch.mjs +2 -2
  14. package/dist/preset-commands.d.mts +65 -0
  15. package/dist/preset-commands.mjs +1148 -0
  16. package/dist/preset.d.mts +169 -0
  17. package/dist/preset.mjs +550 -0
  18. package/dist/remove.mjs +34 -1
  19. package/dist/session-start.d.mts +3 -0
  20. package/dist/session-start.mjs +12 -1
  21. package/dist/sync.d.mts +42 -7
  22. package/dist/sync.mjs +165 -31
  23. package/docs/builds.md +12 -11
  24. package/docs/cli.md +21 -2
  25. package/docs/configuration.md +65 -13
  26. package/docs/developing.md +9 -2
  27. package/docs/github/by-hand.md +5 -5
  28. package/docs/github/reference.md +2 -17
  29. package/docs/github/setup.md +1 -1
  30. package/docs/glossary.md +12 -2
  31. package/docs/limitations.md +3 -0
  32. package/docs/plugins.md +16 -5
  33. package/docs/presets.md +410 -0
  34. package/docs/quick-start.md +20 -17
  35. package/docs/skills.md +21 -16
  36. package/docs/updating.md +14 -7
  37. package/docs/workflow.md +12 -13
  38. package/package.json +1 -1
  39. package/settings.schema.json +52 -3
  40. package/skills/factory-deps/SKILL.md +23 -12
  41. package/skills/factory-design/SKILL.md +1 -1
  42. package/skills/factory-resolve-conflicts/SKILL.md +6 -0
  43. package/workflows/factory-claude-review.yml +7 -2
package/dist/sync.d.mts CHANGED
@@ -1,4 +1,5 @@
1
- import { type Settings } from "./config.mts";
1
+ import { type Resolved, type Settings } from "./config.mts";
2
+ import { type Replaced } from "./preset.mts";
2
3
  /** The package's own folder: the parent of `src/`, or of `dist/` once
3
4
  * compiled. */
4
5
  export declare const PACKAGE: string;
@@ -58,27 +59,61 @@ export declare function withImport(text: string | null): string;
58
59
  /** `CLAUDE.md` without the rules' import, nor the blank line `withImport`
59
60
  * put before it, or null when nothing else is left. */
60
61
  export declare function withoutImport(text: string): string | null;
61
- export declare function lockText(version: string, files: string[]): string;
62
- export declare function lockedFiles(text: string | null): string[];
62
+ export type LockParts = {
63
+ version: string;
64
+ presets: {
65
+ name: string;
66
+ version: string;
67
+ }[];
68
+ hash: string;
69
+ /** The settings in effect, as `factory config explain` prints them. */
70
+ settings: string[];
71
+ overridden: Record<string, Replaced[]>;
72
+ files: string[];
73
+ };
74
+ export declare function lockText(l: LockParts): string;
75
+ /** The files a lock lists, from any release's lock. One that a merge left
76
+ * with conflict markers is read line by line, from each side's `files`. */
77
+ export declare function lockedFiles(text: string | null, load: (t: string) => unknown): string[];
78
+ /** The dependency auto-merge workflow with each preset's package held back
79
+ * as the factory's own is, so a preset update waits for a person. */
80
+ export declare function withPresetPackages(text: string, packages: string[], file: string): string;
63
81
  export type Plan = {
64
82
  /** Path from the root, and its text, for each file a sync writes. */
65
83
  write: Map<string, string>;
66
- /** Paths the lock lists that this version no longer writes. */
84
+ /** Paths the lock lists that this version no longer writes, and the
85
+ * choices file once its last choice is dropped. */
67
86
  remove: string[];
87
+ /** A line for each preset file left as it is. */
88
+ kept: string[];
89
+ /** A line for each choice dropped. */
90
+ dropped: string[];
68
91
  };
69
92
  /** What a sync of `root` from `pkg` writes and deletes, in a repository
70
93
  * whose default branch is `branch`. */
71
- export declare function plan(pkg: string, root: string, s: Settings, branch: string): Plan;
94
+ export declare function plan(pkg: string, root: string, r: Resolved, branch: string): Promise<Plan>;
72
95
  /** The paths whose content a sync would change, in the plan's order. */
73
96
  export declare function differences(root: string, p: Plan): string[];
74
97
  export declare function main(argv: string[], d: {
75
98
  root: string;
76
99
  pkg: string;
77
- settings: () => Promise<Settings>;
100
+ settings: () => Promise<Resolved>;
101
+ /** Why the lock is stale, or null when it is current. */
102
+ stale: () => Promise<string | null>;
78
103
  /** The repository's default branch, or null when it cannot be told. */
79
- defaultBranch: () => Promise<string | null>;
104
+ defaultBranch: (s: Settings) => Promise<string | null>;
80
105
  out: (line: string) => void;
81
106
  err: (line: string) => void;
82
107
  }): Promise<number>;
108
+ /** The sync of the repository at `root`. */
109
+ export declare const syncDeps: (root: string) => {
110
+ root: string;
111
+ pkg: string;
112
+ settings: () => Promise<Resolved>;
113
+ stale: () => Promise<string | null>;
114
+ defaultBranch: (s: Settings) => Promise<string | null>;
115
+ out: (line: string) => void;
116
+ err: (line: string) => void;
117
+ };
83
118
  export declare function run(argv: string[]): Promise<number>;
84
119
  export {};
package/dist/sync.mjs CHANGED
@@ -1,8 +1,10 @@
1
1
  // Writes the factory's skills, agents, rules, review instructions,
2
2
  // workflows, and the actions they call from the package into the
3
- // repository, its hook entries into `.claude/settings.json`, the rules'
4
- // import into `CLAUDE.md`, and
5
- // `.claude/factory.lock`: the factory's version and the files it wrote.
3
+ // repository, the agents and skills its presets ship, its hook entries
4
+ // into `.claude/settings.json`, the rules' import into `CLAUDE.md`, and
5
+ // `.claude/factory.lock`: the factory's version, the presets, the settings
6
+ // in effect, and the files it wrote. Every other command reads the
7
+ // settings from the lock.
6
8
  //
7
9
  // factory sync # write what differs
8
10
  // factory sync --check # write nothing; exit 1 naming what differs
@@ -15,7 +17,8 @@
15
17
  import { existsSync, mkdirSync, readdirSync, readFileSync, realpathSync, rmSync, statSync, writeFileSync, } from "node:fs";
16
18
  import { dirname, join, relative, sep } from "node:path";
17
19
  import { fileURLToPath } from "node:url";
18
- import { defaultDeps, loadSettings, repoRoot, RULE_NUMBERS, } from "./config.mjs";
20
+ import { filesDeps, repoRoot, resolveFiles, RULE_NUMBERS, staleOf, defaultDeps, } from "./config.mjs";
21
+ import { CHOICES_FILE, choicesText, settingsHash, staleChoices, } from "./preset.mjs";
19
22
  import { branchDeps, CANNOT_TELL, defaultBranch, } from "./lib/default-branch.mjs";
20
23
  /** The package's own folder: the parent of `src/`, or of `dist/` once
21
24
  * compiled. */
@@ -348,27 +351,102 @@ export function withoutImport(text) {
348
351
  const after = lines.join("\n");
349
352
  return after.trim() ? after : null;
350
353
  }
351
- export function lockText(version, files) {
354
+ /** A key or a value as YAML: plain where it reads back as the same text,
355
+ * quoted as JSON otherwise. */
356
+ const scalar = (v) => typeof v === "string" &&
357
+ /^[A-Za-z0-9_./][A-Za-z0-9_./ -]*$/.test(v) &&
358
+ !/ $/.test(v) &&
359
+ !/^(true|false|null|yes|no|on|off|~|[-+.\d][\d._eE+-]*)$/i.test(v)
360
+ ? v
361
+ : JSON.stringify(v);
362
+ export function lockText(l) {
363
+ const replaced = Object.entries(l.overridden);
352
364
  return [
353
- "# Written by `factory sync`: the factory's version and the files it",
354
- "# wrote. Do not edit.",
355
- `version: ${version}`,
365
+ "# Written by `factory sync`: the factory's version, the presets, the",
366
+ "# settings in effect, and the files it wrote. Do not edit.",
367
+ `version: ${l.version}`,
368
+ ...(l.presets.length
369
+ ? [
370
+ "presets:",
371
+ ...l.presets.flatMap((p) => [
372
+ ` - name: ${JSON.stringify(p.name)}`,
373
+ ` version: ${scalar(p.version)}`,
374
+ ]),
375
+ ]
376
+ : ["presets: []"]),
377
+ `settings-hash: ${l.hash}`,
378
+ "settings:",
379
+ ...l.settings.map((line) => ` ${line}`),
380
+ ...(replaced.length
381
+ ? [
382
+ "overridden:",
383
+ ...replaced.flatMap(([key, values]) => [
384
+ ` ${scalar(key)}:`,
385
+ ...values.flatMap((r) => [
386
+ ` - from: ${JSON.stringify(r.from)}`,
387
+ ` value: ${JSON.stringify(r.value)}`,
388
+ ]),
389
+ ]),
390
+ ]
391
+ : ["overridden: {}"]),
356
392
  "files:",
357
- ...files.map((f) => ` - ${f}`),
393
+ ...l.files.map((f) => ` - ${f}`),
358
394
  "",
359
395
  ].join("\n");
360
396
  }
361
- export function lockedFiles(text) {
397
+ /** The files a lock lists, from any release's lock. One that a merge left
398
+ * with conflict markers is read line by line, from each side's `files`. */
399
+ export function lockedFiles(text, load) {
362
400
  if (!text)
363
401
  return [];
402
+ try {
403
+ const o = load(text);
404
+ return Array.isArray(o?.files) ? o.files.map(String) : [];
405
+ }
406
+ catch {
407
+ const out = [];
408
+ let inFiles = false;
409
+ for (const line of text.split("\n")) {
410
+ if (/^files:/.test(line))
411
+ inFiles = true;
412
+ else if (/^\S/.test(line) && !/^(<{7}|={7}|>{7})/.test(line))
413
+ inFiles = false;
414
+ const item = inFiles ? /^ {2}- (.+)$/.exec(line)?.[1] : undefined;
415
+ if (item && !out.includes(item))
416
+ out.push(item);
417
+ }
418
+ return out;
419
+ }
420
+ }
421
+ const AUTO_MERGE_WORKFLOW = "workflows/factory-deps-auto-merge.yml";
422
+ const FACTORY_EXCLUSION = "!contains(steps.meta.outputs.dependency-names, 'davidbyoung/software-factory')";
423
+ /** The dependency auto-merge workflow with each preset's package held back
424
+ * as the factory's own is, so a preset update waits for a person. */
425
+ export function withPresetPackages(text, packages, file) {
426
+ if (!packages.length)
427
+ return text;
428
+ const at = text.split(FACTORY_EXCLUSION).length - 1;
429
+ if (at !== 1)
430
+ throw new Error(`${file}: expected one line holding back the factory, to hold back the presets too`);
364
431
  return text
365
432
  .split("\n")
366
- .map((l) => /^ {2}- (.+)$/.exec(l)?.[1])
367
- .filter((f) => Boolean(f));
433
+ .map((line) => {
434
+ if (line.trim() !== FACTORY_EXCLUSION)
435
+ return line;
436
+ const indent = line.slice(0, line.indexOf("!"));
437
+ return [
438
+ `${line} &&`,
439
+ ...packages.map((p, i) => `${indent}!contains(steps.meta.outputs.dependency-names, '${p}')${i < packages.length - 1 ? " &&" : ""}`),
440
+ ].join("\n");
441
+ })
442
+ .join("\n");
368
443
  }
369
444
  /** What a sync of `root` from `pkg` writes and deletes, in a repository
370
445
  * whose default branch is `branch`. */
371
- export function plan(pkg, root, s, branch) {
446
+ export async function plan(pkg, root, r, branch) {
447
+ const { load } = await import("js-yaml");
448
+ const { explainLines, markerOf } = await import("./explain.mjs");
449
+ const s = r.settings;
372
450
  const manifest = JSON.parse(readFileSync(join(pkg, "package.json"), "utf8"));
373
451
  const read = (p) => existsSync(join(root, p)) ? readFileSync(join(root, p), "utf8") : null;
374
452
  const write = new Map();
@@ -383,15 +461,55 @@ export function plan(pkg, root, s, branch) {
383
461
  ? withMinutes(text, s.sessionMinutes[kind], from)
384
462
  : from === POLLER_WORKFLOW
385
463
  ? withSchedule(text, s.builds.pollMinutes, from)
386
- : withRules(text, s.rules, from));
464
+ : from === AUTO_MERGE_WORKFLOW
465
+ ? withPresetPackages(text, [...new Set(r.presets.map((p) => p.pkg))], from)
466
+ : withRules(text, s.rules, from));
467
+ }
468
+ // A preset's agent or skill, unless the factory's own file or one the
469
+ // repository wrote itself is at its path: those always stay.
470
+ const previous = lockedFiles(read(LOCK), load);
471
+ const kept = [];
472
+ for (const [to, { from, source }] of r.resolution.files) {
473
+ if (write.has(to))
474
+ kept.push(`kept ${to}, the factory's own, over ${from}`);
475
+ else if (existsSync(join(root, to)) && !previous.includes(to))
476
+ kept.push(`kept ${to}, this repository's own, over ${from}`);
477
+ else
478
+ write.set(to, readFileSync(source, "utf8"));
387
479
  }
388
480
  const launcher = launcherPath(pkg, root, manifest.name);
389
481
  write.set(SETTINGS_JSON, withHooks(read(SETTINGS_JSON), launcher));
390
482
  write.set(CLAUDE_MD, withImport(read(CLAUDE_MD)));
391
483
  const files = [...write.keys()].filter((p) => p !== SETTINGS_JSON && p !== CLAUDE_MD);
392
- write.set(LOCK, lockText(manifest.version, files));
393
- const remove = lockedFiles(read(LOCK)).filter((p) => !write.has(p) && existsSync(join(root, p)));
394
- return { write, remove };
484
+ // A choice whose preset is gone, or no longer sets its key, is dropped.
485
+ const stale = staleChoices(r.choices, r.presets.map((p) => p.name), r.resolution.setBy);
486
+ const choices = { ...r.choices };
487
+ for (const c of stale)
488
+ delete choices[c.key];
489
+ const chosen = stale.length ? choicesText(choices) : r.choicesText;
490
+ const remove = [];
491
+ if (stale.length) {
492
+ if (chosen === null)
493
+ remove.push(CHOICES_FILE);
494
+ else
495
+ write.set(CHOICES_FILE, chosen);
496
+ }
497
+ const settings = await explainLines(s, markerOf(r.resolution), (p) => r.exists(p) || write.has(p));
498
+ write.set(LOCK, lockText({
499
+ version: manifest.version,
500
+ presets: r.presets.map((p) => ({ name: p.name, version: p.version })),
501
+ hash: settingsHash(r.ownText, chosen),
502
+ settings,
503
+ overridden: Object.fromEntries(r.resolution.overridden),
504
+ files,
505
+ }));
506
+ remove.unshift(...previous.filter((p) => !write.has(p) && existsSync(join(root, p))));
507
+ return {
508
+ write,
509
+ remove: remove.filter((p) => existsSync(join(root, p))),
510
+ kept,
511
+ dropped: stale.map((c) => `dropped the choice for ${c.key}: ${c.reason}`),
512
+ };
395
513
  }
396
514
  /** The paths whose content a sync would change, in the plan's order. */
397
515
  export function differences(root, p) {
@@ -401,13 +519,25 @@ export function differences(root, p) {
401
519
  return !existsSync(at) || readFileSync(at, "utf8") !== text;
402
520
  })
403
521
  .map(([path]) => path);
404
- return [...changed, ...p.remove];
522
+ // The lock comes last, as it records everything before it.
523
+ return [
524
+ ...changed.filter((path) => path !== LOCK),
525
+ ...p.remove,
526
+ ...changed.filter((path) => path === LOCK),
527
+ ];
405
528
  }
406
529
  export async function main(argv, d) {
407
530
  const check = argv.includes("--check");
408
- let s;
531
+ let r;
409
532
  try {
410
- s = await d.settings();
533
+ if (check) {
534
+ const reason = await d.stale();
535
+ if (reason) {
536
+ d.err(reason);
537
+ return 1;
538
+ }
539
+ }
540
+ r = await d.settings();
411
541
  }
412
542
  catch (e) {
413
543
  d.err(e instanceof Error ? e.message : String(e));
@@ -415,12 +545,12 @@ export async function main(argv, d) {
415
545
  }
416
546
  // Nothing is written with a guessed name: a push trigger that names the
417
547
  // wrong branch never runs.
418
- const branch = await d.defaultBranch();
548
+ const branch = await d.defaultBranch(r.settings);
419
549
  if (branch === null) {
420
550
  d.err(CANNOT_TELL);
421
551
  return 1;
422
552
  }
423
- const p = plan(d.pkg, d.root, s, branch);
553
+ const p = await plan(d.pkg, d.root, r, branch);
424
554
  const differ = differences(d.root, p);
425
555
  if (check) {
426
556
  if (differ.length === 0)
@@ -431,6 +561,8 @@ export async function main(argv, d) {
431
561
  d.err("Run `npx --no-install factory sync` and commit the result.");
432
562
  return 1;
433
563
  }
564
+ for (const line of [...p.kept, ...p.dropped])
565
+ d.out(line);
434
566
  for (const path of differ) {
435
567
  const at = join(d.root, path);
436
568
  const text = p.write.get(path);
@@ -446,14 +578,16 @@ export async function main(argv, d) {
446
578
  }
447
579
  return 0;
448
580
  }
581
+ /** The sync of the repository at `root`. */
582
+ export const syncDeps = (root) => ({
583
+ root,
584
+ pkg: PACKAGE,
585
+ settings: () => resolveFiles(filesDeps(root)),
586
+ stale: () => staleOf(defaultDeps(root)),
587
+ defaultBranch: (s) => defaultBranch(branchDeps(root, process.env, async () => s)),
588
+ out: (line) => console.log(line),
589
+ err: (line) => console.error(line),
590
+ });
449
591
  export async function run(argv) {
450
- const root = repoRoot();
451
- return main(argv, {
452
- root,
453
- pkg: PACKAGE,
454
- settings: () => loadSettings(defaultDeps(root)),
455
- defaultBranch: () => defaultBranch(branchDeps(root)),
456
- out: (line) => console.log(line),
457
- err: (line) => console.error(line),
458
- });
592
+ return main(argv, syncDeps(repoRoot()));
459
593
  }
package/docs/builds.md CHANGED
@@ -1,7 +1,8 @@
1
1
  # Builds in the cloud
2
2
 
3
3
  A build is one session taking one approved ticket to a pull request. You
4
- can always build a ticket by asking a session on your machine. A build in
4
+ can always build a ticket by running `/factory-build N` in a session on
5
+ your machine. A build in
5
6
  the cloud does the same with nobody at the keyboard: it runs on your code
6
7
  host's cloud runner, and you read its log or its pull request afterward.
7
8
 
@@ -11,24 +12,24 @@ and the [reference](github/reference.md#workflows) has what runs there.
11
12
 
12
13
  ## Three ways a build starts
13
14
 
14
- | You | The build runs | You need |
15
- | ----------------------------------- | --------------------------------------- | ----------------------------------------------------------------- |
16
- | Ask a session: "build ticket 12" | In that session, wherever you opened it | Nothing |
17
- | Run `factory build 12` | In the cloud | Builds in the cloud set up |
18
- | Move the ticket to Ready on a board | In the cloud, at the poller's next pass | Builds in the cloud set up, and [the poller](#the-poller) running |
15
+ | What you do | Where the build runs | What you need |
16
+ | ------------------------------------ | --------------------------------------- | ----------------------------------------------------------------- |
17
+ | Run `/factory-build 12` in a session | In that session, wherever you opened it | Nothing |
18
+ | Run `factory build 12` | In the cloud | Builds in the cloud set up |
19
+ | Move the ticket to Ready on a board | In the cloud, at the poller's next pass | Builds in the cloud set up, and [the poller](#the-poller) running |
19
20
 
20
21
  Which of the last two you use is
21
22
  [`builds.trigger`](configuration.md#builds) in your
22
23
  [settings](configuration.md#builds):
23
24
 
24
- | `trigger` | Moving a ticket to Ready |
25
+ | `trigger` | What moving a ticket to Ready does |
25
26
  | --------------- | ----------------------------------------------------------------------------------------------------------------- |
26
27
  | `manual` | Records your approval and starts nothing. The default |
27
28
  | `own-server` | Starts a build within a minute, through the poller you host |
28
29
  | `github-action` | Starts one at the next pass of a schedule on the cloud runner, every `poll-minutes` minutes, with nothing to host |
29
30
 
30
- `manual` is a fine place to stay. Asking a session and running
31
- `factory build` work whatever the trigger.
31
+ `manual` is a fine place to stay. Running `/factory-build N` in a session
32
+ and running `factory build N` work whatever the trigger.
32
33
 
33
34
  ## What a build in the cloud does
34
35
 
@@ -269,10 +270,10 @@ hour.
269
270
  ## No trigger: `manual`
270
271
 
271
272
  Nothing watches the board. Moving a ticket to Ready records your approval
272
- and starts nothing. Ask a session:
273
+ and starts nothing. In a session, type:
273
274
 
274
275
  ```text
275
- build ticket 12
276
+ /factory-build 12
276
277
  ```
277
278
 
278
279
  The session claims the ticket, which moves it to "building" on the board,
package/docs/cli.md CHANGED
@@ -21,8 +21,8 @@ A table with a State column has commands still to come, marked
21
21
  **Planned**; every command in a table without one is built.
22
22
  [What is built](developing.md#what-is-built) lists the parts.
23
23
 
24
- The skills are not commands: you ask a session for one in plain words,
25
- such as "refine ticket 12". [Skills](skills.md) lists them.
24
+ The skills are not `factory` commands: you type one in a session as a
25
+ slash command, such as `/factory-refine 12`. [Skills](skills.md) lists them.
26
26
 
27
27
  ## Setting up
28
28
 
@@ -68,6 +68,25 @@ A new version is installed with npm and applied with `factory sync`, as
68
68
  [Updating](updating.md) says. [Removing](removing.md) says what `remove`
69
69
  deletes and what it leaves to you.
70
70
 
71
+ ## Presets
72
+
73
+ A [preset](presets.md) is an npm package of settings that several
74
+ repositories share, listed under
75
+ [`presets`](configuration.md#presets).
76
+
77
+ | Command | When you run it |
78
+ | ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
79
+ | `factory preset add NAME` | To follow a preset. It shows what would change and asks before changing anything |
80
+ | `factory preset remove NAME` | To stop following one, the same way |
81
+ | `factory preset choices` | To see where two of your presets disagree, and choose which one this repository follows |
82
+ | `factory preset choose KEY PRESET` | To record one of those choices without questions, from a session or a script, as [Your choices](presets.md#your-choices) shows |
83
+ | `factory preset check` | In a preset's own package, before publishing it |
84
+ | `factory preset changes REF` | To see what the presets' update changed since `REF`, a git branch, tag, or commit such as `origin/main`. The [`factory-deps`](skills.md#factory-deps) skill posts it on each preset update |
85
+
86
+ `add` and `remove` ask only in a terminal. Elsewhere they print what would
87
+ change and stop, unless given `--yes`; `--dry-run` prints it and changes
88
+ nothing.
89
+
71
90
  ## Run for you
72
91
 
73
92
  The rest are run by the skills, the hooks, and the workflows, not by you.
@@ -24,7 +24,8 @@ and look up any other setting under [Every setting](#every-setting).
24
24
  that writes to the board.
25
25
  - **`factory sync`:** a command you run. It copies the factory's skills,
26
26
  agents, rules, and workflows into your repository, choosing which ones
27
- from this file. It has nothing to do with the board sync.
27
+ from this file, and writes the settings in effect into
28
+ `.claude/factory.lock`. It has nothing to do with the board sync.
28
29
  - **Skill and agent:** a skill is a set of instructions a session follows,
29
30
  and an agent is a separate reviewer a session launches to read something
30
31
  and report back.
@@ -64,6 +65,20 @@ The [glossary](glossary.md) has the rest.
64
65
 
65
66
  - **Your comments are kept.** `factory init` writes a comment above each
66
67
  section, and updates never remove yours.
68
+ - **Every command reads the lock, not this file.** `factory sync` combines
69
+ the factory's defaults, any [`presets`](#presets) you list, and this
70
+ file, and writes every setting the factory will use, defaults included,
71
+ into `.claude/factory.lock`, which you commit and never edit. Until you
72
+ sync after a change, every command stops and says so, but the ones that
73
+ fix or report it: `factory sync`, `factory doctor`,
74
+ `factory config check`, and the `factory preset` commands.
75
+
76
+ ```text
77
+ .claude/factory.yaml changed since the last sync. Run: npx --no-install factory sync
78
+ ```
79
+
80
+ [`factory config explain`](cli.md) prints the settings in effect, each
81
+ marked with where its value came from.
67
82
 
68
83
  ## The shortest file
69
84
 
@@ -72,7 +87,7 @@ version: 2
72
87
  repository: your-name/your-repo
73
88
  ```
74
89
 
75
- With only this, the factory refines a ticket when you ask a session to,
90
+ With only this, the factory refines a ticket when you run `/factory-refine N` in a session,
76
91
  nothing merges without you, and there is no board. Before a session can
77
92
  build a ticket, you also need to tell it how to check a change:
78
93
  [`commands.gate`](#commandsgate), below.
@@ -101,10 +116,10 @@ factory sync
101
116
  ```
102
117
 
103
118
  `factory config check` prints nothing when the file is valid, and names
104
- the setting when it is not. `factory sync` then rewrites the copied files
105
- that depend on what you changed, and lists each file it wrote. A change
106
- under `plugins` alone needs no `factory sync`, since the factory reads
107
- your plugins from this file each time.
119
+ the setting when it is not. `factory sync` then rewrites the lock and the
120
+ copied files that depend on what you changed, and lists each file it
121
+ wrote. Every change needs it, one under `plugins` included, as
122
+ [How the file works](#how-the-file-works) says.
108
123
 
109
124
  ## Every setting
110
125
 
@@ -131,6 +146,29 @@ It is written down rather than worked out from your checkout, because the
131
146
  [poller](#builds), which watches your board from outside any checkout,
132
147
  needs it too.
133
148
 
149
+ ### `presets`
150
+
151
+ Settings shared by several repositories, each an npm package your team
152
+ publishes, listed in the order they apply: a later preset wins over an
153
+ earlier one, and your own settings in this file win over every preset's.
154
+
155
+ ```yaml
156
+ presets:
157
+ - "@acme/factory-preset" # what every Acme repository shares
158
+ - "@acme/factory-preset/node" # extra settings for its Node repositories
159
+ ```
160
+
161
+ - **Default:** none.
162
+ - **Add or remove one** with `factory preset add NAME` or
163
+ `factory preset remove NAME`, which install or uninstall the package,
164
+ edit this list, and sync. A name that starts with `@` must be quoted.
165
+ - **A preset can't set** `repository`, `auto-merge.allow`, or
166
+ `auto-merge.commands`, and can't list other presets
167
+ ([why](presets.md#what-a-preset-cant-set)).
168
+
169
+ [Presets](presets.md) says how they combine, how to choose between two
170
+ that disagree, and how to write one.
171
+
134
172
  ### `tickets`
135
173
 
136
174
  Where your tickets live, and which board shows them.
@@ -149,7 +187,7 @@ tickets:
149
187
 
150
188
  Without a board, `factory status` still shows every ticket's state, which
151
189
  the factory keeps in comments on the ticket. Builds then start only when
152
- you ask a session to build a ticket.
190
+ you run `/factory-build N` in a session.
153
191
 
154
192
  One board can show tickets from several repositories. Give each
155
193
  repository the same `board`. Each repository's board sync,
@@ -278,8 +316,8 @@ builds:
278
316
 
279
317
  The three triggers:
280
318
 
281
- - **`manual`:** nothing watches the board. You ask a session to build a
282
- ticket, such as "work ticket 12".
319
+ - **`manual`:** nothing watches the board. You build a ticket by running
320
+ `/factory-build 12` in a session.
283
321
  - **`own-server`:** a small program you host, the poller, checks the board
284
322
  once a minute and starts a cloud build for each ticket in Ready.
285
323
  [Hosting the poller](builds.md#hosting-the-poller-own-server) shows how
@@ -583,7 +621,7 @@ session-minutes:
583
621
  build: 300
584
622
  ```
585
623
 
586
- | Setting | The session | Default |
624
+ | Setting | Limits the session that is | Default |
587
625
  | -------------- | --------------------------------------------------------- | ------- |
588
626
  | `build` | Building a ticket | `230` |
589
627
  | `conflicts` | Fixing a pull request's conflicts with the default branch | `110` |
@@ -636,11 +674,25 @@ agent at `.claude/agents/NAME.md`:
636
674
  - **`factory plugins`** prints every plugin the factory will use, its own
637
675
  included, one per line: skill or agent, its name, its role, and its
638
676
  files or labels. `factory plugins reviewer` prints one role's.
677
+ - **A plugin can come from a [preset](#presets),** which ships its agent
678
+ or skill too. To leave out one that a preset adds to a list, name it
679
+ here with `off: true`:
680
+
681
+ ```yaml
682
+ plugins:
683
+ build:
684
+ reviewers:
685
+ - agent: acme-security-reviewer
686
+ off: true
687
+ ```
688
+
639
689
  - **`factory config check`** stops on an agent in a role that takes a
640
690
  skill, or the other way round; on `files` or `labels` in a role that
641
691
  doesn't take them; on a builder with no `labels`; on a build reviewer or
642
- resolver with no `files`; and on a skill or agent whose file doesn't
643
- exist. It warns on a `files` pattern that matches no file.
692
+ resolver with no `files`; on a skill or agent whose file doesn't
693
+ exist and no preset ships; and on `off: true` for a plugin no preset
694
+ names, where the fix is to delete that entry. It warns on a `files`
695
+ pattern that matches no file.
644
696
 
645
697
  #### `plugins.refine`
646
698
 
@@ -845,7 +897,7 @@ you. Each line it prints is shown as a reason.
845
897
  What a held pull request says, one line for each file or command that held
846
898
  it:
847
899
 
848
- | It says | Because |
900
+ | The status says | Why |
849
901
  | -------------------------------------- | ----------------------------------------------- |
850
902
  | `PATH: the factory's own files` | The file is one of the factory's, listed above |
851
903
  | `PATH: held by auto-merge.deny` | The file matches `deny` |
@@ -509,7 +509,10 @@ this repository's own reviewer, reads a changed page as that person.
509
509
  - **A page says who it is for and what they will have at the end,** in its
510
510
  first lines.
511
511
  - **Lead with the command that does it.** The same steps by hand go on a
512
- page of their own, linked once.
512
+ page of their own, linked once. A step that runs a skill shows its slash
513
+ command, such as `/factory-refine 12`, not only words to say to a
514
+ session: words leave the session to pick the skill, and leave the reader
515
+ not knowing which one ran.
513
516
  - **Say only what the reader must do or decide.** What a command does for
514
517
  them is one sentence, and a link to the page that lists it.
515
518
  - **A setting links to its entry in `docs/configuration.md` where a page
@@ -522,4 +525,8 @@ this repository's own reviewer, reads a changed page as that person.
522
525
  person doing each thing, and an example where the rule is abstract. A
523
526
  word the factory gives its own meaning, such as "the sync" or "a
524
527
  session", is explained or linked where the page first uses it. A table
525
- cell reads as part of a sentence, and no column repeats another.
528
+ cell reads as part of a sentence, and no column repeats another. A
529
+ column header names what its cells hold, such as "What it does" or
530
+ "Without one", and reads on its own: not a pronoun or a clipped phrase,
531
+ such as "It" or "Left out", that makes sense only once a cell is read
532
+ into it.
@@ -186,12 +186,12 @@ prints the run's link, with no session open on your machine.
186
186
  `sync` already wrote the workflows these use, and each does nothing until
187
187
  it has work and its secrets:
188
188
 
189
- | Workflow | Runs a Claude Code session that |
189
+ | Workflow | What its Claude Code session does |
190
190
  | ----------------------- | ------------------------------------------------------------------------------------ |
191
- | `factory-build.yml` | builds a ticket |
192
- | `factory-review.yml` | answers a review you submit on a pull request |
193
- | `factory-conflicts.yml` | resolves a conflict between a pull request and your default branch |
194
- | `factory-deps.yml` | moves Dependabot's pull requests along, written once `.github/dependabot.yml` exists |
191
+ | `factory-build.yml` | Builds a ticket |
192
+ | `factory-review.yml` | Answers a review you submit on a pull request |
193
+ | `factory-conflicts.yml` | Resolves a conflict between a pull request and your default branch |
194
+ | `factory-deps.yml` | Moves Dependabot's pull requests along, written once `.github/dependabot.yml` exists |
195
195
 
196
196
  1. **Store your Claude token** as `CLAUDE_CODE_OAUTH_TOKEN`.
197
197
  2. **Store a GitHub token that can push**, as `FACTORY_BUILD_TOKEN`. With
@@ -187,23 +187,8 @@ you set yourself alone.
187
187
 
188
188
  ## Skills in Claude Code
189
189
 
190
- In Claude Code a skill is also a slash command: type `/` and its name,
191
- with the ticket or pull request number after it. Asking in plain words
192
- calls the same skill.
193
-
194
- | Type | Same as asking |
195
- | -------------------------------- | ---------------------------------- |
196
- | `/factory-refine 12` | "refine ticket 12" |
197
- | `/factory-build 12` | "build ticket 12" |
198
- | `/factory-address-review 280` | "address the review on 280" |
199
- | `/factory-resolve-conflicts 280` | "resolve the conflicts on 280" |
200
- | `/factory-diagnose` | "diagnose this failing test" |
201
- | `/factory-mutate` | "mutate this test" |
202
- | `/factory-deps` | "fix the dependency pull requests" |
203
- | `/factory-design` | "mock up a new about page" |
204
-
205
- Typing `/factory` in a session lists them, which is also how to check that
206
- a session picked the factory up.
190
+ In Claude Code each skill is a slash command, such as `/factory-refine 12`.
191
+ [Skills](../skills.md#at-a-glance) lists every one with what it does.
207
192
 
208
193
  **Where the files live.** `sync` writes the factory's skills to
209
194
  `.claude/skills/factory-*/` and its agents to