@monte3l/groundwork 1.0.3 → 1.0.5

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 (37) hide show
  1. package/README.md +54 -12
  2. package/dist/assets.d.ts +22 -2
  3. package/dist/assets.js +40 -15
  4. package/dist/emit.js +3 -2
  5. package/dist/harness/rules.js +1 -1
  6. package/dist/main.js +5 -15
  7. package/dist/merge-json.d.ts +3 -1
  8. package/dist/merge-json.js +1 -1
  9. package/package.json +1 -1
  10. package/plugin/skills/customize/step-3-round-1.md +25 -17
  11. package/plugin/src/domain-map.ts +1 -1
  12. package/plugin/src/pack-map.ts +125 -44
  13. package/plugin/src/plugin-map.ts +1 -1
  14. package/templates/core/.claude/hooks/inject-decision-gate.mjs +4 -0
  15. package/templates/core/.claude/rules/agent-dispatch.md +46 -0
  16. package/templates/core/CLAUDE.md +41 -60
  17. package/templates/core/bin/check-exports.mjs +3 -1
  18. package/templates/core/bin/lib/harness-rules.mjs +1 -1
  19. package/templates/core/eslint.config.js +2 -0
  20. package/templates/core/vitest.config.ts +4 -3
  21. package/templates/packs/README.md +6 -3
  22. package/templates/packs/{github → claude-github}/files/.github/workflows/claude-pr-review.yml +1 -1
  23. package/templates/packs/{github → claude-github}/files/.github/workflows/claude.yml +1 -1
  24. package/templates/packs/claude-github/pack.json +19 -0
  25. package/templates/packs/github/pack.json +3 -3
  26. package/templates/packs/harness-extras/pack.json +3 -15
  27. package/templates/packs/licensing/pack.json +31 -0
  28. package/templates/packs/publishing/files/tools/release/_package-lock.json +914 -0
  29. package/templates/packs/publishing/pack.json +3 -14
  30. package/templates/packs/statusline/pack.json +31 -0
  31. package/templates/packs/supply-chain/pack.json +1 -1
  32. package/templates/packs/worktrees/pack.json +2 -1
  33. /package/templates/packs/{publishing → licensing}/files/REUSE.toml +0 -0
  34. /package/templates/packs/{publishing → licensing}/files/bin/check-license-headers.mjs +0 -0
  35. /package/templates/packs/{harness-extras → statusline}/files/.claude/hooks/statusline-layout.mjs +0 -0
  36. /package/templates/packs/{harness-extras → statusline}/files/.claude/hooks/statusline.mjs +0 -0
  37. /package/templates/packs/{harness-extras → statusline}/files/.claude/hooks/subagent-statusline.mjs +0 -0
package/README.md CHANGED
@@ -44,14 +44,53 @@ Read this project's rendered docs site at
44
44
 
45
45
  ## Quickstart
46
46
 
47
- 1. Install [Node 24+](https://nodejs.org/) and [pnpm](https://pnpm.io/installation)
48
- (see ["Requirements"](#requirements) below for exact versions).
49
- 2. Run `npx @monte3l/groundwork my-app` to bootstrap a new project
50
- named `my-app`.
51
- 3. `cd my-app`.
52
- 4. Open the `my-app` folder in Claude Code.
53
- 5. Run `/customize` -- it interviews you and tailors the baseline to your
54
- project.
47
+ Install [Node 24+](https://nodejs.org/), [pnpm](https://pnpm.io/installation)
48
+ and [Claude Code](https://docs.claude.com/en/docs/claude-code/overview) first
49
+ (see ["Requirements"](#requirements) below for exact versions). Nothing is
50
+ installed globally: `npx` and `pnpm dlx` fetch the CLI, run it once and leave
51
+ only a download cache behind.
52
+
53
+ **A new project.** Point the CLI at an empty or missing directory:
54
+
55
+ ```bash
56
+ # with npx
57
+ npx @monte3l/groundwork my-app
58
+
59
+ # or with pnpm
60
+ pnpm dlx @monte3l/groundwork my-app
61
+ ```
62
+
63
+ It writes the baseline, runs `git init` and `pnpm install`, and installs the
64
+ `/customize` skill. Add `--pack <name>` to install an optional
65
+ [pack](#packs) at the same time (`--list-packs` shows them).
66
+
67
+ **An existing project.** Run the CLI from the project's root, or pass its path.
68
+ It detects that the directory already looks like a project and switches to
69
+ adopt mode, which surveys it read-only and never overwrites a project file:
70
+
71
+ ```bash
72
+ cd path/to/your-project
73
+
74
+ # with npx
75
+ npx @monte3l/groundwork .
76
+
77
+ # or with pnpm
78
+ pnpm dlx @monte3l/groundwork .
79
+ ```
80
+
81
+ It writes a report and staged copies of what it would add under
82
+ `.groundwork/`, plus one guarded copy of the `/customize` skill.
83
+
84
+ **Then, in either case:**
85
+
86
+ ```bash
87
+ cd my-app # or stay in your existing project
88
+ claude # open the project in Claude Code
89
+ ```
90
+
91
+ Run `/customize` inside Claude Code. For a new project it interviews you and
92
+ tailors the baseline. For an existing one it first reconciles the survey
93
+ against your repo and confirms each change with you before editing anything.
55
94
 
56
95
  > [!NOTE]
57
96
  > Earlier releases shipped on other [dist-tags](https://github.com/monte3l/m3l-groundwork/blob/main/docs/glossary.md#dist-tag).
@@ -106,10 +145,13 @@ the wiring contract.
106
145
 
107
146
  | Pack | Contents |
108
147
  | ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
109
- | `harness-extras` | The compaction-handoff hook pair, a read-only Bash guard, and a five-row Claude Code status line plus a per-subagent row renderer, width-fit to the terminal. |
148
+ | `harness-extras` | The compaction-handoff hook pair and a read-only Bash guard. |
149
+ | `statusline` | A five-row Claude Code status line plus a per-subagent row renderer, width-fit to the terminal. Sets the `statusLine` and `subagentStatusLine` keys. |
110
150
  | `quality` | A per-file size ratchet gate over `src/` and `tests/`, and a read-only `type-design-analyzer` review agent. Adopt-capable, recommended for every project kind. |
111
- | `github` | Anthropic's official Claude Code GitHub Action (`@claude` mention-mode) plus an automated PR-review Action and three `gh`-CLI skills (Dependabot PR triage, scan-alert triage, PR-check watching) -- no hooks, no gate. Needs an auth secret the pack cannot create. |
112
- | `publishing` | A release pipeline (changesets version-PR / staged, provenance-attested npm publish via trusted publishing) plus SPDX license headers. Fresh mode only. |
151
+ | `claude-github` | Anthropic's official Claude Code GitHub Action as two workflows: `@claude` mention-mode and an automated PR-review comment on every pull request -- no hooks, no gate. Needs an auth secret the pack cannot create, and the review spends API credits per PR. |
152
+ | `github` | Three `gh`-CLI skills (Dependabot PR triage, scan-alert triage, PR-check watching) -- no hooks, no gate, no workflows. |
153
+ | `publishing` | A release pipeline (changesets version-PR / staged, provenance-attested npm publish via trusted publishing). Fresh mode only. |
154
+ | `licensing` | An SPDX/REUSE license-header gate (`check-license-headers.mjs`, a `lint`-group verify step) and a `REUSE.toml` template. Fresh mode only, because the one-time backfill fails an established project's `pnpm verify`. |
113
155
  | `supply-chain` | Secret scanning (`gitleaks.yml`) and an OpenSSF Scorecard run (`scorecard.yml`) for any GitHub project, published or not. Two workflows (read-only apart from the Scorecard job's `security-events` and `id-token` write), adopt-capable, recommended for every project kind. |
114
156
  | `worktrees` | Enforces that all src/tests development happens inside an isolated git worktree, on any branch, for any caller: a `working-in-worktrees` skill (start/status/sync/finish/fan-out), a dependency-install backstop hook, a guard stricter than the baseline's own branch/hub guards, and a `.worktreeinclude` copying `.env`/`.env.local`/`.env.*.local` into every worktree Claude Code creates. Changes the day-to-day workflow -- opt-in, not recommended by default. |
115
157
 
@@ -276,7 +318,7 @@ everything else that goes wrong at run time.
276
318
  | Unrecognized flag, missing flag value, repeated `--name`, missing or extra target argument | 2 | Prints the error and the usage text. |
277
319
  | `--adopt` with `--fresh` | 2 | The two are mutually exclusive. |
278
320
  | `--name` is not a valid npm package name, or a `--pack` value is not a valid pack name | 2 | Prints the rule it broke and the usage text. |
279
- | Unknown `--pack` | 2 | Lists the available packs. A retired name gets a hint: `statusline` was renamed to `harness-extras`. |
321
+ | Unknown `--pack` | 2 | Lists the available packs. |
280
322
  | `--pack` for a pack without fresh mode | 2 | Says the pack does not support fresh mode and lists its modes. |
281
323
  | Adopt mode with `--adopt` and a missing target directory, `--force` or `--pack` | 2 | Adopt never writes project files and surveys every pack itself; run `/customize` to install a pack. |
282
324
  | Windows, fresh mode | 1 | Refuses before writing anything: Linux and macOS only. Adopt mode, `--help`, `--version` and `--list-packs` still run. |
package/dist/assets.d.ts CHANGED
@@ -5,9 +5,29 @@ export interface AssetPaths {
5
5
  /** Path from the package root, in a published tarball. */
6
6
  local: string;
7
7
  }
8
- /** The vendored spelling of a stripped dotfile: `.gitignore` becomes `_gitignore`. */
8
+ /**
9
+ * The vendored spelling of a name npm strips: `.gitignore` becomes
10
+ * `_gitignore` and `package-lock.json` becomes `_package-lock.json`; every
11
+ * other name is unchanged.
12
+ *
13
+ * @example
14
+ * ```ts
15
+ * escapeDotfileName(".npmrc"); // "_npmrc"
16
+ * escapeDotfileName("package.json"); // "package.json"
17
+ * ```
18
+ */
9
19
  export declare function escapeDotfileName(name: string): string;
10
- /** Inverse of `escapeDotfileName`: `_gitignore` becomes `.gitignore`; every other name is unchanged. */
20
+ /**
21
+ * Inverse of `escapeDotfileName`: `_gitignore` becomes `.gitignore` and
22
+ * `_package-lock.json` becomes `package-lock.json`; every other name is
23
+ * unchanged.
24
+ *
25
+ * @example
26
+ * ```ts
27
+ * restoreDotfileName("_package-lock.json"); // "package-lock.json"
28
+ * restoreDotfileName("_package.json"); // "_package.json"
29
+ * ```
30
+ */
11
31
  export declare function restoreDotfileName(name: string): string;
12
32
  /** `restoreDotfileName` applied to the final segment of a `/`- or `\`-separated relative path. */
13
33
  export declare function restoreDotfilePath(relPath: string): string;
package/dist/assets.js CHANGED
@@ -20,25 +20,50 @@ import { existsSync, readFileSync } from "node:fs";
20
20
  import { dirname, join } from "node:path";
21
21
  import { fileURLToPath } from "node:url";
22
22
  /**
23
- * Files npm-family tooling strips from a tarball no matter what `files` says
24
- * (`pnpm pack` keeps `.gitignore`, `npm pack` drops it; both drop `.npmrc`).
25
- * The vendored copy stores each under `_<name-without-dot>` and the walkers
26
- * (`emit.ts`, `conflicts.ts`) restore the real name on the way out.
23
+ * File names npm-family tooling strips from a tarball, at any depth, no matter
24
+ * what `files` says (`pnpm pack` keeps `.gitignore`, `npm pack` drops it; both
25
+ * drop `.npmrc` and `package-lock.json`), each paired with the escaped name
26
+ * the vendored copy stores it under. A dotfile's escape replaces its leading
27
+ * dot with `_`; `package-lock.json` has no dot to replace, so it gains a `_`
28
+ * prefix. The walkers (`emit.ts`, `conflicts.ts`, `staging.ts`) restore the
29
+ * real name on the way out. `templates/core/package.json` is not escaped:
30
+ * npm never strips a `package.json`.
31
+ */
32
+ const ESCAPED_NAMES = new Map([
33
+ [".gitignore", "_gitignore"],
34
+ [".npmrc", "_npmrc"],
35
+ [".npmignore", "_npmignore"],
36
+ ["package-lock.json", "_package-lock.json"],
37
+ ]);
38
+ /** Escaped name to real name: the inverse of {@link ESCAPED_NAMES}. */
39
+ const RESTORED_NAMES = new Map([...ESCAPED_NAMES].map(([real, escaped]) => [escaped, real]));
40
+ /**
41
+ * The vendored spelling of a name npm strips: `.gitignore` becomes
42
+ * `_gitignore` and `package-lock.json` becomes `_package-lock.json`; every
43
+ * other name is unchanged.
44
+ *
45
+ * @example
46
+ * ```ts
47
+ * escapeDotfileName(".npmrc"); // "_npmrc"
48
+ * escapeDotfileName("package.json"); // "package.json"
49
+ * ```
27
50
  */
28
- const ESCAPED_DOTFILES = [".gitignore", ".npmrc", ".npmignore"];
29
- /** The vendored spelling of a stripped dotfile: `.gitignore` becomes `_gitignore`. */
30
51
  export function escapeDotfileName(name) {
31
- return ESCAPED_DOTFILES.includes(name)
32
- ? `_${name.slice(1)}`
33
- : name;
52
+ return ESCAPED_NAMES.get(name) ?? name;
34
53
  }
35
- /** Inverse of `escapeDotfileName`: `_gitignore` becomes `.gitignore`; every other name is unchanged. */
54
+ /**
55
+ * Inverse of `escapeDotfileName`: `_gitignore` becomes `.gitignore` and
56
+ * `_package-lock.json` becomes `package-lock.json`; every other name is
57
+ * unchanged.
58
+ *
59
+ * @example
60
+ * ```ts
61
+ * restoreDotfileName("_package-lock.json"); // "package-lock.json"
62
+ * restoreDotfileName("_package.json"); // "_package.json"
63
+ * ```
64
+ */
36
65
  export function restoreDotfileName(name) {
37
- const restored = `.${name.slice(1)}`;
38
- return name.startsWith("_") &&
39
- ESCAPED_DOTFILES.includes(restored)
40
- ? restored
41
- : name;
66
+ return RESTORED_NAMES.get(name) ?? name;
42
67
  }
43
68
  /** `restoreDotfileName` applied to the final segment of a `/`- or `\`-separated relative path. */
44
69
  export function restoreDotfilePath(relPath) {
package/dist/emit.js CHANGED
@@ -4,8 +4,9 @@
4
4
  * Copies `templates/core` into a target directory, applying token
5
5
  * substitution to both file contents and path segments (so a token in a
6
6
  * directory or file NAME, not just its content, is honored). A published
7
- * tarball stores `.gitignore`/`.npmrc` as `_gitignore`/`_npmrc` (npm strips
8
- * the real names); they are restored here -- see `assets.ts`.
7
+ * tarball stores `.gitignore`/`.npmrc`/`package-lock.json` as
8
+ * `_gitignore`/`_npmrc`/`_package-lock.json` (npm strips the real names);
9
+ * they are restored here -- see `assets.ts`.
9
10
  *
10
11
  * Every destination path is planned and `lstat`-checked before the first
11
12
  * write ({@link assertSafeEmitDestinations}), so a symlink or a misplaced
@@ -473,7 +473,7 @@ const descriptionSubstance = {
473
473
  else if (description.length > DESCRIPTION_MAX) {
474
474
  failures.push({
475
475
  subject,
476
- message: `description is ${description.length} chars; over ${DESCRIPTION_MAX} it is truncated in the skill listing`,
476
+ message: `description is ${description.length} chars; over the ${DESCRIPTION_MAX}-char Agent Skills maximum (Claude Code also truncates description + when_to_use at 1,536 in its skill listing)`,
477
477
  });
478
478
  }
479
479
  };
package/dist/main.js CHANGED
@@ -389,28 +389,18 @@ function describeInstallFailure(error) {
389
389
  return `\`pnpm install\` failed (${code})`;
390
390
  return "`pnpm install` failed";
391
391
  }
392
- // A pack that was renamed or folded into another, mapped to its successor so
393
- // an old `--pack` name gets a pointed hint rather than a bare "unknown pack".
394
- const RENAMED_PACKS = new Map([
395
- ["statusline", "harness-extras"],
396
- ]);
397
392
  /**
398
393
  * Loads one `--pack` for fresh mode -- called for every pack before any file
399
- * is written. An unknown name (with a rename hint when {@link RENAMED_PACKS}
400
- * knows its successor) or a fresh-incompatible pack is a usage error (exit
401
- * 2); a pack that exists but whose manifest fails to load propagates
402
- * `loadPack`'s own error unchanged (exit 1), since that is a broken install,
403
- * not a bad invocation.
394
+ * is written. An unknown name (the message lists the available packs) or a
395
+ * fresh-incompatible pack is a usage error (exit 2); a pack that exists but
396
+ * whose manifest fails to load propagates `loadPack`'s own error unchanged
397
+ * (exit 1), since that is a broken install, not a bad invocation.
404
398
  */
405
399
  function resolveFreshPack(name) {
406
400
  const available = listPackNames();
407
401
  if (!available.includes(name)) {
408
- const successor = RENAMED_PACKS.get(name);
409
- const hint = successor === undefined
410
- ? ""
411
- : ` -- it was renamed to "${successor}"; use --pack ${successor}`;
412
402
  const list = available.length > 0 ? available.join(", ") : "none";
413
- throw new CliUsageError(`unknown pack "${name}"${hint} (available: ${list})\n\n${USAGE}`);
403
+ throw new CliUsageError(`unknown pack "${name}" (available: ${list})\n\n${USAGE}`);
414
404
  }
415
405
  const pack = loadPack(name);
416
406
  if (!pack.manifest.modes.includes("fresh")) {
@@ -46,6 +46,8 @@ interface SettingsHookCommand {
46
46
  command: string;
47
47
  if?: string;
48
48
  timeout?: number;
49
+ /** Hook failure policy (Claude Code 2.1.295+); defaults to `"continue"`. */
50
+ onFailure?: "continue" | "block";
49
51
  }
50
52
  interface SettingsHookEntry {
51
53
  matcher?: string;
@@ -58,7 +60,7 @@ export type SettingsHooksFragment = Record<string, SettingsHookEntry[]>;
58
60
  * counts as a match -- e.g. `PreCompact`, which has none); within a matched
59
61
  * entry, only `hooks` commands not already present (compared by exact
60
62
  * `command` string) are appended. A command that matches on `command` but
61
- * differs in its other fields (`if`, `timeout`) is a hard collision, never
63
+ * differs in its other fields (`if`, `timeout`, `onFailure`) is a hard collision, never
62
64
  * a silent overwrite. An event name of `__proto__`, `constructor` or
63
65
  * `prototype` throws: the check runs per key inside the loop, before that
64
66
  * key is read or written, and nothing escapes the failed merge -- `existing`
@@ -110,7 +110,7 @@ function assertSafeKey(key, context) {
110
110
  * counts as a match -- e.g. `PreCompact`, which has none); within a matched
111
111
  * entry, only `hooks` commands not already present (compared by exact
112
112
  * `command` string) are appended. A command that matches on `command` but
113
- * differs in its other fields (`if`, `timeout`) is a hard collision, never
113
+ * differs in its other fields (`if`, `timeout`, `onFailure`) is a hard collision, never
114
114
  * a silent overwrite. An event name of `__proto__`, `constructor` or
115
115
  * `prototype` throws: the check runs per key inside the loop, before that
116
116
  * key is read or written, and nothing escapes the failed merge -- `existing`
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@monte3l/groundwork",
3
- "version": "1.0.3",
3
+ "version": "1.0.5",
4
4
  "description": "CLI that bootstraps a TypeScript project with a strict toolchain and Claude Code setup, or read-only surveys an existing one, plus a /customize plugin that tailors it to current guidance.",
5
5
  "keywords": [
6
6
  "bootstrap",
@@ -61,18 +61,21 @@ confirmed in Step 0.4:
61
61
  `recommendPacks(answers)` from `pack-map.ts` (alongside this file, same
62
62
  copy mechanism as `kind-facet-map.ts`) with the now-confirmed
63
63
  `InterviewAnswers` and compare its verdict against Step 0.4's decision.
64
- `harness-extras`, `github`, `supply-chain`, `quality`, and `worktrees`
65
- never disagree (none of the five's recommendation varies by kind or
66
- answer -- `worktrees` is always `recommended: false`, since it changes the
67
- day-to-day workflow rather than adding a nicety, and the other four are
68
- always `recommended: true`), but `publishing`'s does (recommended for
69
- `library`/`cli`, not for `frontend`/`service`) — if the comparison surfaces a real
64
+ `harness-extras`, `statusline`, `github`, `claude-github`, `supply-chain`,
65
+ `quality`, and `worktrees` never disagree (none of the seven's
66
+ recommendation varies by kind or answer -- `worktrees` is always
67
+ `recommended: false`, since it changes the day-to-day workflow rather than
68
+ adding a nicety, and `claude-github` is always `recommended: false`, since
69
+ its workflows need an auth secret and the review spends API credits on
70
+ every PR; the other five are always `recommended: true`), but `publishing`'s and `licensing`'s do (each
71
+ recommended for `library`/`cli`, not for `frontend`/`service`) — if the comparison surfaces a real
70
72
  conflict there or for any future kind-scoped pack, raise it rather than
71
73
  silently overriding the user's Step 0.4 answer, mirroring Step 4's "the
72
74
  one exception" rule for guidance findings. Before installing, check the
73
75
  pack's own `modes`: a pack whose `modes` doesn't include `"adopt"` (today,
74
76
  `publishing` — its release flow encodes decisions too project-specific to
75
- apply blind) is never auto-installed here even if staged and approved;
77
+ apply blind — and `licensing`, whose one-time SPDX header backfill fails an
78
+ established project's `pnpm verify`) is never auto-installed here even if staged and approved;
76
79
  instead, state in Step 7 that it needs a manual install (point at `.groundwork/packs/<name>/` and the pack's own `adoptNotes`, and say to strip the `.staged` suffix from every name when copying by hand and to replace every `__KEY__` token with the project's real value) and stop
77
80
  there for that pack. Before merging any staged `pack.json.staged` wiring, repeat
78
81
  the prototype-key check from Step 0.4(c): if a key of `wiring.settings`,
@@ -90,20 +93,23 @@ confirmed in Step 0.4:
90
93
  from `pack.json.staged` (the bytes Step 0.1 read) for a schema 5 or later inventory and
91
94
  from the unsuffixed `pack.json` for schema 1-4,
92
95
  against what Step 0.2's deep read already found — a `.claude/settings.json`
93
- hook fragment merges the same way the baseline's own hook entries would;
96
+ hook fragment merges the same way the baseline's own hook entries would, and when the project already registers the same hook `command` (a pack installed before it gained a key such as `onFailure`), add only the keys the fragment has and the existing registration lacks, keep every field the project already sets, and ask before changing a key both define with a different value (the CLI's `mergeSettingsHooks` never overwrites one);
94
97
  `wiring.settingsTopLevel` is a set of top-level keys (e.g. `statusLine`)
95
98
  planted whole, and only when the project doesn't already define that key —
96
99
  when it does, show the existing value and ask, since the CLI's own
97
100
  `mergeSettingsTopLevel` treats a differing value as a hard error and this
98
101
  hand-applied path must not be laxer than the automated one (also check
99
102
  `.claude/settings.local.json` and the user's `~/.claude/settings.json`,
100
- either of which can shadow a project `statusLine`). For `harness-extras`
103
+ either of which can shadow a project `statusLine`). For `statusline`
101
104
  specifically, a `statusLine`/`subagentStatusLine` collision is never a
102
- reason to fail the whole pack install: skip just those two settings keys
103
- and the three statusline scripts (`statusline.mjs`, `statusline-layout.mjs`,
104
- `subagent-statusline.mjs`) and install the pack's other artifacts (the
105
- compaction-handoff hooks and `guard-readonly-bash`) normally, stating the
106
- skip plainly in Step 7. `guard-readonly-bash.mjs` imports
105
+ reason to fail the whole pack install: skip just the colliding key and the
106
+ script that renders it (`statusline.mjs` for `statusLine`,
107
+ `subagent-statusline.mjs` for `subagentStatusLine`; `statusline-layout.mjs`
108
+ stays while either remains), install the other key normally, and skip the
109
+ whole pack only when both keys are already set, stating the skip plainly in
110
+ Step 7. The pack is separate from `harness-extras` for exactly this reason,
111
+ so a skipped status line never costs the compaction-handoff hooks or
112
+ `guard-readonly-bash`. For `harness-extras`, `guard-readonly-bash.mjs` imports
107
113
  `bin/lib/agent-roster.mjs`: when the project keeps no agents and that file is
108
114
  not being installed, skip that one hook too (the pack's `adoptNotes` allow
109
115
  it), record it in `round1.dropped` and say in Step 7 that it was skipped and
@@ -142,9 +148,11 @@ any reason goes into `round1.dropped` with that reason.
142
148
  `PluginRecommendationContext`: `chosenPacks` is whatever the packs decision
143
149
  just above actually landed on (fresh: what `--pack` installed at bootstrap
144
150
  time, detectable from the installed files -- e.g. `.changeset/config.json`
145
- means `publishing`, `.github/workflows/claude-pr-review.yml` means `github`
146
- (the only marker `plugin-map.ts` actually reads; `harness-extras` has no
147
- plugin that varies by its presence, so it needs no marker here); adopt: the
151
+ means `publishing`, `.claude/skills/watching-pr-checks/SKILL.md` means `github`
152
+ (the only marker `plugin-map.ts` actually reads; the `claude-github` pack's
153
+ `.github/workflows/claude-pr-review.yml` needs no marker, since no plugin
154
+ varies by its presence; `harness-extras` and `statusline` have
155
+ no plugin that varies by their presence, so they need no marker here); adopt: the
148
156
  packs Step 0.4(c) confirmed, revised by this step's own `recommendPacks`
149
157
  comparison if it changed anything); `hasCustomSkills` is `false` for a fresh
150
158
  bootstrap (nothing has authored a skill yet) and, for adopt mode, whatever
@@ -88,7 +88,7 @@ export const TYPESCRIPT_DOMAIN_GLOBS = [
88
88
  * `bin/lib/*.mjs` are typescript-domain globs, so without this list the
89
89
  * grader's own rules would be swept by `typescript-guidance` -- wrong,
90
90
  * because they encode Claude Code harness guidance. The Claude Code Action
91
- * workflows (`claude.yml`, and the `github` pack's automated-review
91
+ * workflows (`claude.yml`, and the `claude-github` pack's automated-review
92
92
  * `claude-pr-review.yml`) are here for the same reason against
93
93
  * `.github/workflows/*.yml`: their trigger, action pin and model choice are
94
94
  * Anthropic guidance, not toolchain. Consulted before the typescript list in
@@ -19,43 +19,61 @@ export interface PackRecommendation {
19
19
  }
20
20
 
21
21
  /**
22
- * `harness-extras`'s remaining artifacts (the compaction-handoff hook pair
23
- * and a read-only Bash guard) are harness-level, not domain-level -- they
22
+ * `harness-extras`'s remaining artifacts (the compaction-handoff hook pair,
23
+ * which carries a work summary across a compaction, and a read-only Bash
24
+ * guard for review spokes) are harness-level, not domain-level -- they
24
25
  * apply to any TypeScript project regardless of what it's building. The
25
26
  * type-design-analyzer agent and the file-budget gate it once also carried
26
- * now live in the separate `quality` pack. Its folded-in
27
- * statusLine scripts read only the stdin payload, `.git/HEAD` (via
28
- * `node:fs`, never a `git` subprocess) and `os.freemem()`/`os.totalmem()`,
29
- * and `statusLine` is the only documented surface carrying live
30
- * `context_window.used_percentage`: no hook event receives token or context
31
- * data, so "when to compact" can live nowhere else.
27
+ * now live in the separate `quality` pack, and its status-line scripts in
28
+ * the separate `statusline` pack.
32
29
  */
33
30
  function recommendHarnessExtras(): PackRecommendation {
34
31
  return {
35
32
  name: "harness-extras",
36
33
  recommended: true,
37
34
  because:
38
- "its compaction-handoff hooks (which carry work across a context " +
39
- "compaction) and read-only Bash guard are harness-level, not tied " +
40
- "to any particular project kind; its " +
41
- "statusLine is the only surface that exposes live context-window " +
42
- "pressure -- no hook event receives token data -- and reads only the " +
43
- "stdin payload plus local git and memory state. It does occupy five " +
44
- "terminal rows (session, model, context, quota, work).",
35
+ "its compaction-handoff hooks (which carry a work summary across a " +
36
+ "compaction) and its read-only Bash guard for review spokes are " +
37
+ "harness-level, not tied to any particular project kind.",
45
38
  };
46
39
  }
47
40
 
48
41
  /**
49
- * `github`'s workflow assumes only GitHub, which this baseline's whole
50
- * toolchain (CI, Dependency Review, rulesets) already does -- nothing about
51
- * any project kind. Beyond the mention-mode Action (`claude.yml`) it ships a
52
- * second workflow, `claude-pr-review.yml`, which posts an automated Claude
53
- * review comment on every PR, plus three GitHub-operations skills:
42
+ * `statusline` is the five-row `statusLine` script (session, model,
43
+ * context, quota, work) plus a per-subagent row renderer, carved out of
44
+ * `harness-extras`. Its scripts read only the stdin payload, `.git/HEAD`
45
+ * (via `node:fs`, never a `git` subprocess) and
46
+ * `os.freemem()`/`os.totalmem()`, and `statusLine` is the only documented
47
+ * surface carrying live `context_window.used_percentage`: no hook event
48
+ * receives token or context data, so "when to compact" can live nowhere
49
+ * else. That is harness-level, so it is recommended for every project
50
+ * kind. In adopt mode a project that already defines `statusLine` or
51
+ * `subagentStatusLine` keeps its own value -- it is never overwritten, so
52
+ * the owner decides which one to run.
53
+ */
54
+ function recommendStatusline(): PackRecommendation {
55
+ return {
56
+ name: "statusline",
57
+ recommended: true,
58
+ because:
59
+ "its five-row statusLine (session, model, context, quota, work) plus " +
60
+ "a per-subagent row renderer is the only surface that exposes live " +
61
+ "context-window pressure -- no hook event receives token data -- and " +
62
+ "reads only the stdin payload plus local git and memory state. It " +
63
+ "does occupy five terminal rows. A project that already defines " +
64
+ "statusLine or subagentStatusLine keeps its own value (it is never " +
65
+ "overwritten) and must decide which one to run.",
66
+ };
67
+ }
68
+
69
+ /**
70
+ * `github` is three GitHub-operations skills driven by the `gh` CLI:
54
71
  * `reviewing-dependabot-prs` (classifies and batch-merges open Dependabot
55
72
  * PRs), `triaging-scan-alerts` (triages open code-scanning alerts to
56
- * file:line) and `watching-pr-checks`. It is not zero-setup: it adds two
57
- * GitHub Actions workflows and needs an auth secret the pack cannot create
58
- * itself.
73
+ * file:line) and `watching-pr-checks`. It assumes only GitHub, which this
74
+ * baseline's whole toolchain (CI, Dependency Review, rulesets) already does
75
+ * -- nothing about any project kind -- and needs only `gh` CLI auth, so it
76
+ * is recommended for every kind.
59
77
  */
60
78
  function recommendGithub(): PackRecommendation {
61
79
  return {
@@ -63,22 +81,43 @@ function recommendGithub(): PackRecommendation {
63
81
  recommended: true,
64
82
  because:
65
83
  "the baseline's toolchain already assumes GitHub (CI, Dependency " +
66
- "Review, rulesets), so a Claude Code Action integration applies to " +
67
- "any project kind. Alongside the mention-mode Action it adds a " +
68
- "second workflow (claude-pr-review.yml) that posts an automated " +
69
- "Claude review comment on every PR, plus skills for classifying and " +
70
- "batch-merging open Dependabot PRs (reviewing-dependabot-prs), " +
71
- "triaging open code-scanning alerts to file:line " +
72
- "(triaging-scan-alerts) and watching a PR's checks " +
73
- "(watching-pr-checks). It does add two GitHub Actions workflows and " +
74
- "needs an auth secret configured by hand -- the pack cannot create it.",
84
+ "Review, rulesets), so its gh-CLI skills apply to any project kind: " +
85
+ "classifying and batch-merging open Dependabot PRs " +
86
+ "(reviewing-dependabot-prs), triaging open code-scanning alerts to " +
87
+ "file:line (triaging-scan-alerts) and watching a PR's checks " +
88
+ "(watching-pr-checks). It needs only gh CLI auth.",
75
89
  };
76
90
  }
77
91
 
78
92
  /**
79
- * `publishing` is the one kind-scoped pack: a release pipeline (a changesets
93
+ * `claude-github` is Anthropic's Claude Code GitHub Action as two
94
+ * workflows: `claude.yml` (mention-mode, answering `@claude` in issues and
95
+ * PRs) and `claude-pr-review.yml` (an automated Claude review comment on
96
+ * every PR). It needs an auth secret (`ANTHROPIC_API_KEY` or a Claude
97
+ * subscription OAuth token) configured by hand, since the pack cannot
98
+ * create it, and the review workflow spends API credits on every PR. That
99
+ * is a cost and setup decision no interview answer can infer, so it is
100
+ * opt-in for every project kind -- but it stays on offer.
101
+ */
102
+ function recommendClaudeGithub(): PackRecommendation {
103
+ return {
104
+ name: "claude-github",
105
+ recommended: false,
106
+ because:
107
+ "it adds Anthropic's Claude Code GitHub Action as two workflows: " +
108
+ "@claude mention-mode (claude.yml) and an automated Claude review " +
109
+ "comment on every PR (claude-pr-review.yml). It needs an auth secret " +
110
+ "(ANTHROPIC_API_KEY or a Claude subscription OAuth token) configured " +
111
+ "by hand -- the pack cannot create it -- and the review workflow " +
112
+ "spends API credits on every PR, so it is opt-in.",
113
+ };
114
+ }
115
+
116
+ /**
117
+ * `publishing` is a kind-scoped pack: a release pipeline (a changesets
80
118
  * version PR, then a staged, provenance-attested npm publish via trusted
81
- * publishing) plus SPDX/REUSE license headers. Secret scanning and OpenSSF
119
+ * publishing) plus a gate that the published type declarations' dependencies
120
+ * are installable by consumers (dts-deps). Secret scanning and OpenSSF
82
121
  * Scorecard are not part of it -- they are the separate `supply-chain` pack,
83
122
  * since they apply to any repo, published or not. A `library` or `cli`
84
123
  * typically publishes an npm package; a
@@ -95,12 +134,13 @@ function recommendPublishing(answers: InterviewAnswers): PackRecommendation {
95
134
  because: recommended
96
135
  ? "a library or CLI typically ships an npm package, so this pack's " +
97
136
  "release pipeline applies: a changesets version PR, then a staged, " +
98
- "provenance-attested npm publish via trusted publishing -- plus " +
99
- "SPDX/REUSE license headers. The repository-hygiene scans that " +
100
- "apply to any project, published or not, are the separate " +
101
- "supply-chain pack. It is fresh-mode only and needs one-time npm and GitHub setup (the " +
102
- "trusted publisher, the release credentials) the pack cannot do " +
103
- "itself."
137
+ "provenance-attested npm publish via trusted publishing, with a " +
138
+ "dts-deps gate that the published type declarations' dependencies " +
139
+ "resolve for consumers. The repository-hygiene scans that apply to " +
140
+ "any project, published or not, are the separate supply-chain " +
141
+ "pack. It is fresh-mode only and needs one-time npm and GitHub " +
142
+ "setup (the trusted publisher, the release credentials) the pack " +
143
+ "cannot do itself."
104
144
  : "a frontend or service is typically deployed, and a Claude Code " +
105
145
  "plugin ships through a marketplace manifest, rather than published " +
106
146
  "to a package registry, so a changesets/npm release pipeline is not " +
@@ -109,6 +149,38 @@ function recommendPublishing(answers: InterviewAnswers): PackRecommendation {
109
149
  };
110
150
  }
111
151
 
152
+ /**
153
+ * `licensing` is the half carved out of `publishing`: an SPDX/REUSE
154
+ * license-header gate (`check-license-headers`) plus a `REUSE.toml`
155
+ * template. Licensing metadata matters most for code that is distributed,
156
+ * so it is pre-selected for a `library` or `cli`, the same kinds
157
+ * `publishing` targets -- but it is independent of `publishing` and stays
158
+ * on offer for every kind. It is fresh-mode only: an established project
159
+ * fails `pnpm verify` until the one-time backfill (`git add -A`, then
160
+ * `node bin/check-license-headers.mjs --fix`) has touched every file.
161
+ */
162
+ function recommendLicensing(answers: InterviewAnswers): PackRecommendation {
163
+ const recommended = answers.kind === "library" || answers.kind === "cli";
164
+ return {
165
+ name: "licensing",
166
+ recommended,
167
+ because: recommended
168
+ ? "a library or CLI is distributed, which is where licensing metadata " +
169
+ "matters most, so this pack's SPDX/REUSE license-header gate and " +
170
+ "REUSE.toml template apply. It is independent of the publishing " +
171
+ "pack. It is fresh-mode only: the one-time backfill (git add -A, " +
172
+ "then node bin/check-license-headers.mjs --fix) has to touch every " +
173
+ "file before pnpm verify passes, which an established project " +
174
+ "would fail until then."
175
+ : "a frontend, service or Claude Code plugin is less often " +
176
+ "redistributed as source, so an SPDX/REUSE license-header gate is " +
177
+ "not recommended by default -- it is still available, independent " +
178
+ "of the publishing pack. It is fresh-mode only: the one-time " +
179
+ "backfill (git add -A, then node bin/check-license-headers.mjs " +
180
+ "--fix) has to touch every file before pnpm verify passes.",
181
+ };
182
+ }
183
+
112
184
  /**
113
185
  * `worktrees` is opt-in for every project kind: rather than adding a
114
186
  * nicety on top of the existing workflow, it changes the workflow itself --
@@ -170,18 +242,27 @@ function recommendQuality(): PackRecommendation {
170
242
  }
171
243
 
172
244
  /**
173
- * Every pack's recommendation for the given interview answers. Only
174
- * `publishing` varies by `answers.kind` today; `harness-extras`, `github`,
175
- * `supply-chain` and `quality` are recommended for every kind, and
176
- * `worktrees` is opt-in for every kind.
245
+ * Every pack's recommendation for the given interview answers. Two packs
246
+ * vary by `answers.kind` today, `publishing` and `licensing`;
247
+ * `harness-extras`, `statusline`, `github`, `supply-chain` and `quality`
248
+ * are recommended for every kind, and `claude-github` and `worktrees` are
249
+ * opt-in for every kind.
250
+ *
251
+ * @example
252
+ * ```ts
253
+ * const picks = recommendPacks(answers).filter((r) => r.recommended);
254
+ * ```
177
255
  */
178
256
  export function recommendPacks(
179
257
  answers: InterviewAnswers,
180
258
  ): PackRecommendation[] {
181
259
  return [
182
260
  recommendHarnessExtras(),
261
+ recommendStatusline(),
183
262
  recommendGithub(),
263
+ recommendClaudeGithub(),
184
264
  recommendPublishing(answers),
265
+ recommendLicensing(answers),
185
266
  recommendWorktrees(),
186
267
  recommendSupplyChain(),
187
268
  recommendQuality(),
@@ -20,7 +20,7 @@
20
20
  * again:
21
21
  *
22
22
  * - `code-review` -- duplicates the built-in `/code-review` and the optional
23
- * `github` pack's PR-review Action.
23
+ * `claude-github` pack's PR-review Action.
24
24
  * - `code-simplifier` -- duplicates the built-in `/simplify`; its
25
25
  * unrestricted-tools agent is blocked by the baseline's hub-and-spoke
26
26
  * write guard on `src/`/`tests/` anyway.