@monte3l/groundwork 1.0.4 → 1.1.0

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 (55) hide show
  1. package/README.md +62 -13
  2. package/dist/harness/rules.js +1 -1
  3. package/dist/main.js +5 -15
  4. package/dist/merge-json.d.ts +3 -1
  5. package/dist/merge-json.js +1 -1
  6. package/package.json +1 -1
  7. package/plugin/skills/customize/SKILL.md +17 -0
  8. package/plugin/skills/customize/step-3-round-1.md +105 -20
  9. package/plugin/src/domain-map.ts +1 -1
  10. package/plugin/src/pack-map.ts +177 -44
  11. package/plugin/src/plugin-map.ts +277 -28
  12. package/templates/core/.claude/hooks/inject-decision-gate.mjs +4 -0
  13. package/templates/core/.claude/rules/agent-dispatch.md +46 -0
  14. package/templates/core/.claude/settings.json +11 -1
  15. package/templates/core/.claude/skills/creating-prs/SKILL.md +1 -0
  16. package/templates/core/.claude/skills/finishing-work/SKILL.md +1 -0
  17. package/templates/core/.claude/skills/harness-guidance/SKILL.md +1 -0
  18. package/templates/core/.claude/skills/starting-work/SKILL.md +20 -0
  19. package/templates/core/.claude/skills/triaging-ci/SKILL.md +1 -0
  20. package/templates/core/.claude/skills/typescript-guidance/SKILL.md +1 -0
  21. package/templates/core/.claude/skills/writing-commits/SKILL.md +1 -0
  22. package/templates/core/CLAUDE.md +44 -60
  23. package/templates/core/bin/check-exports.mjs +3 -1
  24. package/templates/core/bin/lib/harness-rules.mjs +1 -1
  25. package/templates/core/eslint.config.js +2 -0
  26. package/templates/core/vitest.config.ts +4 -3
  27. package/templates/packs/README.md +8 -3
  28. package/templates/packs/{github → claude-github}/files/.github/workflows/claude-pr-review.yml +1 -1
  29. package/templates/packs/{github → claude-github}/files/.github/workflows/claude.yml +1 -1
  30. package/templates/packs/claude-github/pack.json +19 -0
  31. package/templates/packs/frontend/files/.claude/agents/ui-reviewer.md +132 -0
  32. package/templates/packs/frontend/files/.claude/skills/new-component/SKILL.md +72 -0
  33. package/templates/packs/frontend/pack.json +19 -0
  34. package/templates/packs/github/files/.claude/skills/reviewing-dependabot-prs/SKILL.md +4 -0
  35. package/templates/packs/github/files/.claude/skills/triaging-scan-alerts/SKILL.md +3 -0
  36. package/templates/packs/github/files/.claude/skills/watching-pr-checks/SKILL.md +4 -0
  37. package/templates/packs/github/pack.json +3 -3
  38. package/templates/packs/harness-extras/files/.claude/hooks/guard-readonly-bash.mjs +1117 -122
  39. package/templates/packs/harness-extras/pack.json +3 -15
  40. package/templates/packs/licensing/pack.json +31 -0
  41. package/templates/packs/publishing/pack.json +3 -14
  42. package/templates/packs/quality/files/.claude/agents/type-design-analyzer.md +1 -1
  43. package/templates/packs/service/files/.claude/agents/performance-analyzer.md +96 -0
  44. package/templates/packs/service/files/.claude/skills/api-doc/SKILL.md +67 -0
  45. package/templates/packs/service/files/.claude/skills/api-doc/openapi-template.yaml +48 -0
  46. package/templates/packs/service/pack.json +19 -0
  47. package/templates/packs/statusline/pack.json +31 -0
  48. package/templates/packs/supply-chain/pack.json +1 -1
  49. package/templates/packs/worktrees/files/.claude/skills/working-in-worktrees/SKILL.md +20 -5
  50. package/templates/packs/worktrees/pack.json +2 -1
  51. /package/templates/packs/{publishing → licensing}/files/REUSE.toml +0 -0
  52. /package/templates/packs/{publishing → licensing}/files/bin/check-license-headers.mjs +0 -0
  53. /package/templates/packs/{harness-extras → statusline}/files/.claude/hooks/statusline-layout.mjs +0 -0
  54. /package/templates/packs/{harness-extras → statusline}/files/.claude/hooks/statusline.mjs +0 -0
  55. /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,15 @@ 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
+ | `frontend` | A read-only `ui-reviewer` accessibility agent (static WCAG 2.2 review) and a `new-component` skill that mirrors a sibling component. Recommended for the `frontend` kind only. |
152
+ | `service` | A read-only `performance-analyzer` agent (static review for blocking calls and unbounded work; profiling is reported as `NOT CHECKED`) and an `api-doc` skill that writes an OpenAPI description from the routes the code defines. Recommended for the `service` kind only. |
153
+ | `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. |
154
+ | `github` | Three `gh`-CLI skills (Dependabot PR triage, scan-alert triage, PR-check watching) -- no hooks, no gate, no workflows. |
155
+ | `publishing` | A release pipeline (changesets version-PR / staged, provenance-attested npm publish via trusted publishing). Fresh mode only. |
156
+ | `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
157
  | `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
158
  | `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
159
 
@@ -164,7 +208,7 @@ The `/customize` skill is also available as a Claude Code plugin, for use in
164
208
  a project that was not bootstrapped by this CLI:
165
209
 
166
210
  ```
167
- /plugin marketplace add monte3l/m3l-groundwork
211
+ /plugin marketplace add monte3l/m3l-plugins
168
212
  /plugin install m3l-groundwork-customize@monte3l
169
213
  ```
170
214
 
@@ -247,6 +291,11 @@ See [`CONTRIBUTING.md`](https://github.com/monte3l/m3l-groundwork/blob/main/CONT
247
291
  `@monte3l/groundwork` is released, published, and verified, and
248
292
  [`CLAUDE.md`](https://github.com/monte3l/m3l-groundwork/blob/main/CLAUDE.md#releases) for the full design.
249
293
 
294
+ The `/customize` plugin has no release of its own. The central
295
+ `monte3l/m3l-plugins` marketplace lists it pinned to a CLI release tag
296
+ (`@monte3l/groundwork@X.Y.Z`), so a plugin change reaches marketplace users
297
+ only after the next CLI release **and** a pin-bump PR in `monte3l/m3l-plugins`.
298
+
250
299
  [`CLAUDE.md`](https://github.com/monte3l/m3l-groundwork/blob/main/CLAUDE.md) is the full reference: architecture, the command
251
300
  table, conventions, and known gaps.
252
301
 
@@ -276,7 +325,7 @@ everything else that goes wrong at run time.
276
325
  | Unrecognized flag, missing flag value, repeated `--name`, missing or extra target argument | 2 | Prints the error and the usage text. |
277
326
  | `--adopt` with `--fresh` | 2 | The two are mutually exclusive. |
278
327
  | `--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`. |
328
+ | Unknown `--pack` | 2 | Lists the available packs. |
280
329
  | `--pack` for a pack without fresh mode | 2 | Says the pack does not support fresh mode and lists its modes. |
281
330
  | 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
331
  | Windows, fresh mode | 1 | Refuses before writing anything: Linux and macOS only. Adopt mode, `--help`, `--version` and `--list-packs` still run. |
@@ -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.4",
3
+ "version": "1.1.0",
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",
@@ -259,6 +259,23 @@ declined, plus any prerequisite named against an enabled plugin
259
259
  plugin's `prerequisites` names) as a follow-up the
260
260
  user still has to satisfy.
261
261
 
262
+ Close with two follow-ups the project's own files cannot carry, because both
263
+ are per-user. **Notifications:** Claude Code sends a desktop notification by
264
+ itself only in Ghostty, Kitty and iTerm2; in another terminal, set
265
+ `"preferredNotifChannel": "terminal_bell"` in `~/.claude/settings.json` (or
266
+ add a `Notification` hook) to be alerted when Claude needs a permission or is
267
+ waiting for input. **Fewer permission prompts:** after a few sessions, run
268
+ `/fewer-permission-prompts`, which scans the transcripts for common read-only
269
+ Bash and MCP calls and proposes an allowlist for the project's
270
+ `.claude/settings.json`; the baseline ships none because it cannot know the
271
+ project's commands in advance.
272
+
273
+ **Dependabot grouping:** at CI depth thorough in a fresh bootstrap, `.github/dependabot.yml`
274
+ gets an `npm` entry with `groups` (see Step 3 Round 1). Report whether it was
275
+ added, and that Dependabot support for the project's pnpm version is
276
+ **unconfirmed**: tell the owner to check the first Dependabot PR, and to expect failed or partial updates if the project uses pnpm `catalogs` or workspace `overrides`. At any other
277
+ depth, mention it as an option only.
278
+
262
279
  **Write the report to a file as well (adopt mode only).** Save the same report
263
280
  to `.groundwork/customization-report.md`, so a reviewer can read it without
264
281
  asking for the chat. Include which conflicts were resolved and which packs
@@ -24,6 +24,50 @@
24
24
  **CI depth = thorough**: note this for Round 2 — `harness-guidance` may
25
25
  recommend additional current-best-practice lanes (e.g. a scheduled
26
26
  dependency audit) beyond what the baseline ships.
27
+ - **CI depth = thorough also adds npm grouping to Dependabot.** Append this
28
+ block to `updates:` in `.github/dependabot.yml`, which the baseline ships
29
+ with only the `github-actions` ecosystem, at the same two-space item
30
+ indentation as that entry:
31
+
32
+ ```yaml
33
+ - package-ecosystem: "npm"
34
+ directory: "/"
35
+ schedule:
36
+ interval: "weekly"
37
+ cooldown:
38
+ default-days: 7
39
+ commit-message:
40
+ prefix: "chore"
41
+ labels:
42
+ - "dependencies"
43
+ groups:
44
+ dev-dependencies:
45
+ dependency-type: "development"
46
+ update-types: ["minor", "patch"]
47
+ prod-dependencies:
48
+ dependency-type: "production"
49
+ update-types: ["minor", "patch"]
50
+ ```
51
+
52
+ The baseline's comment above the `github-actions` entry says npm updates are
53
+ deliberately not enabled here: rewrite or drop that sentence when you add the
54
+ block, so the file does not contradict itself. Major bumps stay one PR each.
55
+ Dependabot's `npm` ecosystem also covers pnpm, but GitHub's
56
+ supported-ecosystems page lists pnpm only up to v10 and the baseline pins a
57
+ newer pnpm, so when the project uses pnpm, support for its pnpm version is
58
+ **unconfirmed**: say so in Step 7 and tell the owner to check the first
59
+ Dependabot PR. Upstream, `dependabot-core` is adding pnpm 12 support in stages and
60
+ GitHub's docs lag behind it: Part 1 (#16513) and Part 2 (#16517) merged on
61
+ 2026-10-09, Part 3 (#16521) is still open, and #15904 (a pnpm 12 environment
62
+ lockfile read as an empty dependency graph) is still open. A
63
+ `minimumReleaseAge` failure on pnpm 12.3 or newer was fixed (#16375), but
64
+ projects that use `catalogs` or workspace `overrides` still hit open issues
65
+ (grouped updates leave overrides stale). If the project uses `catalog:`
66
+ entries or workspace `overrides`, tell the owner to expect failed
67
+ or partial updates until those issues close. **At any other CI depth in a fresh bootstrap** this is not
68
+ offered as a question (the plugin offer's question counts are fixed); it is
69
+ only a Step 7 follow-up.
70
+
27
71
  - **Agents not kept**: delete their `.claude/agents/<name>.md` file. Never
28
72
  delete `Explore`, `test-author`, or `code-implementer` even if unselected
29
73
  — they're load-bearing for the hub-and-spoke loop `CLAUDE.md` documents.
@@ -39,6 +83,12 @@
39
83
  the project actually has, instead of a named baseline path — "tests must not
40
84
  hard-fail `pre-push`" is applied to _the gate the inventory found_ (jest in
41
85
  CI, husky locally, whatever it is), not to `lefthook.yml`/`ci.yml` by name.
86
+ In adopt mode the Dependabot block above is never applied, because Step 0.4
87
+ did not confirm it. When `.github/dependabot.yml` already exists and has no
88
+ `npm` entry for directory "/", name the block in Step 7 as a follow-up the
89
+ owner can paste in; never create the file, and never touch an existing `npm`
90
+ entry (the project's own cadence and groups win).
91
+
42
92
  Concretely, adopt-mode Round 1 applies exactly three things, all already
43
93
  confirmed in Step 0.4:
44
94
 
@@ -61,18 +111,21 @@ confirmed in Step 0.4:
61
111
  `recommendPacks(answers)` from `pack-map.ts` (alongside this file, same
62
112
  copy mechanism as `kind-facet-map.ts`) with the now-confirmed
63
113
  `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
114
+ `harness-extras`, `statusline`, `github`, `claude-github`, `supply-chain`,
115
+ `quality`, and `worktrees` never disagree (none of the seven's
116
+ recommendation varies by kind or answer -- `worktrees` is always
117
+ `recommended: false`, since it changes the day-to-day workflow rather than
118
+ adding a nicety, and `claude-github` is always `recommended: false`, since
119
+ its workflows need an auth secret and the review spends API credits on
120
+ every PR; the other five are always `recommended: true`), but `publishing`'s, `licensing`'s, `frontend`'s and `service`'s do (`publishing` and
121
+ `licensing` are each recommended for `library`/`cli`, `frontend` only for the `frontend` kind, `service` only for the `service` kind) — if the comparison surfaces a real
70
122
  conflict there or for any future kind-scoped pack, raise it rather than
71
123
  silently overriding the user's Step 0.4 answer, mirroring Step 4's "the
72
124
  one exception" rule for guidance findings. Before installing, check the
73
125
  pack's own `modes`: a pack whose `modes` doesn't include `"adopt"` (today,
74
126
  `publishing` — its release flow encodes decisions too project-specific to
75
- apply blind) is never auto-installed here even if staged and approved;
127
+ apply blind — and `licensing`, whose one-time SPDX header backfill fails an
128
+ established project's `pnpm verify`) is never auto-installed here even if staged and approved;
76
129
  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
130
  there for that pack. Before merging any staged `pack.json.staged` wiring, repeat
78
131
  the prototype-key check from Step 0.4(c): if a key of `wiring.settings`,
@@ -90,20 +143,23 @@ confirmed in Step 0.4:
90
143
  from `pack.json.staged` (the bytes Step 0.1 read) for a schema 5 or later inventory and
91
144
  from the unsuffixed `pack.json` for schema 1-4,
92
145
  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;
146
+ 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
147
  `wiring.settingsTopLevel` is a set of top-level keys (e.g. `statusLine`)
95
148
  planted whole, and only when the project doesn't already define that key —
96
149
  when it does, show the existing value and ask, since the CLI's own
97
150
  `mergeSettingsTopLevel` treats a differing value as a hard error and this
98
151
  hand-applied path must not be laxer than the automated one (also check
99
152
  `.claude/settings.local.json` and the user's `~/.claude/settings.json`,
100
- either of which can shadow a project `statusLine`). For `harness-extras`
153
+ either of which can shadow a project `statusLine`). For `statusline`
101
154
  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
155
+ reason to fail the whole pack install: skip just the colliding key and the
156
+ script that renders it (`statusline.mjs` for `statusLine`,
157
+ `subagent-statusline.mjs` for `subagentStatusLine`; `statusline-layout.mjs`
158
+ stays while either remains), install the other key normally, and skip the
159
+ whole pack only when both keys are already set, stating the skip plainly in
160
+ Step 7. The pack is separate from `harness-extras` for exactly this reason,
161
+ so a skipped status line never costs the compaction-handoff hooks or
162
+ `guard-readonly-bash`. For `harness-extras`, `guard-readonly-bash.mjs` imports
107
163
  `bin/lib/agent-roster.mjs`: when the project keeps no agents and that file is
108
164
  not being installed, skip that one hook too (the pack's `adoptNotes` allow
109
165
  it), record it in `round1.dropped` and say in Step 7 that it was skipped and
@@ -142,9 +198,11 @@ any reason goes into `round1.dropped` with that reason.
142
198
  `PluginRecommendationContext`: `chosenPacks` is whatever the packs decision
143
199
  just above actually landed on (fresh: what `--pack` installed at bootstrap
144
200
  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
201
+ means `publishing`, `.claude/skills/watching-pr-checks/SKILL.md` means `github`
202
+ (the only marker `plugin-map.ts` actually reads; the `claude-github` pack's
203
+ `.github/workflows/claude-pr-review.yml` needs no marker, since no plugin
204
+ varies by its presence; `harness-extras` and `statusline` have
205
+ no plugin that varies by their presence, so they need no marker here); adopt: the
148
206
  packs Step 0.4(c) confirmed, revised by this step's own `recommendPacks`
149
207
  comparison if it changed anything); `hasCustomSkills` is `false` for a fresh
150
208
  bootstrap (nothing has authored a skill yet) and, for adopt mode, whatever
@@ -154,18 +212,45 @@ already-installed pack's skills (e.g. the `github` pack's three);
154
212
  in the project's root `package.json` (the same read in both modes; a fresh
155
213
  bootstrap carries only the baseline's own devDependencies, so no SDK plugin
156
214
  is pre-selected there, and a monorepo whose SDK dependency sits only in a
157
- workspace package is not pre-selected either -- the user can still pick it). Call
215
+ workspace package is not pre-selected either -- the user can still pick it,
216
+ except for an integration, where `recommendIntegrations` does not return it);
217
+ `hasDesignSystem` is `true` when the project already carries its own design
218
+ system: a design-token file (`tokens.css` or `tokens.json`, at the project
219
+ root or under `design/` or `src/`), a CSS file with a Tailwind `@theme` block,
220
+ or an in-house design-system package among its `dependencies`. A bare Tailwind
221
+ config does not count, and a fresh bootstrap is `false`. It only decides
222
+ whether `frontend-design` is pre-selected, since that plugin's skill defaults
223
+ to proposing its own palette and token system. Call
158
224
  `recommendPlugins(answers, context)` from `plugin-map.ts`
159
225
  (alongside this file, same copy mechanism as `pack-map.ts`) with the
160
226
  now-confirmed `InterviewAnswers`, and offer every entry it returns (ten, or
161
- eleven for the `plugin` kind, whose `plugin-dev` entry comes last) in **one**
227
+ eleven for the `plugin` kind, whose `plugin-dev` entry comes last, or the
228
+ `frontend` kind, whose `frontend-design` entry comes last) in **one**
162
229
  `AskUserQuestion` call holding three multi-select questions (a question
163
230
  takes at most four options, so split the list in its fixed order: entries
164
231
  1-4, 5-7, and 8 to the last entry, so 8-10 or 8-11), each option pre-selected per its entry's `recommended`
165
232
  boolean with its `because` shown as the evidence -- same
166
233
  "visible reasoning" principle as every other inference in this skill.
167
234
 
168
- Write every confirmed `true` entry into `.claude/settings.json`'s
235
+ **Integrations (both modes), right after that offer.** Call
236
+ `recommendIntegrations(context)` from the same `plugin-map.ts` with the same
237
+ context. It returns a plugin only when the project's `dependencies` name that
238
+ service's SDK or CLI (for example `@sentry/node`, `@supabase/supabase-js`,
239
+ `prisma`, `wrangler`), so it is usually empty: when it is, say nothing and move
240
+ on. Otherwise offer its entries in one more `AskUserQuestion` call, in the
241
+ table's order, with none pre-selected -- every `recommended` is `false`,
242
+ because these plugins connect Claude to a live account or run unpinned code
243
+ and the user opts in -- and each `because` shown as the evidence, with its
244
+ `prerequisites` beside it (for three of the plugins they include a note that
245
+ the server starts through an unpinned `npx` launch). The tool takes two to four
246
+ options per question, so use as few multi-select questions as fit four options
247
+ each and split evenly across them, never leaving a question with fewer than two
248
+ options (five entries are 3+2, seven are 4+3). A single entry is asked as one
249
+ `Enable / Skip` question instead. Write every entry the user selected into
250
+ `enabledPlugins` and print their install commands and `prerequisites` as
251
+ described below.
252
+
253
+ Write every entry the user selected into `.claude/settings.json`'s
169
254
  `enabledPlugins` (`{"<id>": true}` per entry, e.g.
170
255
  `"context7@claude-plugins-official": true`) -- additive and entry-by-entry,
171
256
  same discipline as the CLI's own `mergeSettingsHooks` (which owns the
@@ -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