@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
@@ -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,20 +242,81 @@ 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
+ * `frontend` is a kind-scoped pack: a read-only `ui-reviewer` agent (a
246
+ * static accessibility review against WCAG 2.2) plus a `new-component`
247
+ * skill that scaffolds a component by mirroring a sibling's conventions.
248
+ * Both only have something to work on in a project that builds UI, so it
249
+ * is pre-selected for the `frontend` kind alone -- but it stays on offer
250
+ * for every other kind.
251
+ */
252
+ function recommendFrontend(answers: InterviewAnswers): PackRecommendation {
253
+ const recommended = answers.kind === "frontend";
254
+ return {
255
+ name: "frontend",
256
+ recommended,
257
+ because: recommended
258
+ ? "a frontend project builds UI, so the pack's read-only ui-reviewer " +
259
+ "agent (a static accessibility review against WCAG 2.2) and its " +
260
+ "new-component skill (mirrors a sibling component's conventions) " +
261
+ "have something to work on."
262
+ : "not preselected because it adds a UI accessibility reviewer and a " +
263
+ "component skill that only help a project that builds UI; it is " +
264
+ "preselected for the frontend kind.",
265
+ };
266
+ }
267
+
268
+ /**
269
+ * `service` is a kind-scoped pack: a read-only `performance-analyzer` agent
270
+ * (a static review for blocking calls and unbounded work) plus an `api-doc`
271
+ * skill that writes an OpenAPI description from the routes the code
272
+ * defines. Both only have something to work on in a project that serves an
273
+ * API, so it is pre-selected for the `service` kind alone -- but it stays
274
+ * on offer for every other kind.
275
+ */
276
+ function recommendService(answers: InterviewAnswers): PackRecommendation {
277
+ const recommended = answers.kind === "service";
278
+ return {
279
+ name: "service",
280
+ recommended,
281
+ because: recommended
282
+ ? "a service project serves an API, so the pack's read-only " +
283
+ "performance-analyzer agent (a static review for blocking calls and " +
284
+ "unbounded work) and its api-doc skill (an OpenAPI description from " +
285
+ "the routes the code defines) have something to work on."
286
+ : "not preselected because it adds a performance reviewer and an " +
287
+ "API-documentation skill that only help a project that serves an " +
288
+ "API; it is preselected for the service kind.",
289
+ };
290
+ }
291
+
292
+ /**
293
+ * Every pack's recommendation for the given interview answers, eleven in
294
+ * all. Four packs vary by `answers.kind` today: `publishing` and
295
+ * `licensing` (pre-selected for a library or CLI), `frontend` (pre-selected
296
+ * for the frontend kind) and `service` (pre-selected for the service kind).
297
+ * `harness-extras`, `statusline`, `github`, `supply-chain`
298
+ * and `quality` are recommended for every kind, and `claude-github` and
299
+ * `worktrees` are opt-in for every kind.
300
+ *
301
+ * @example
302
+ * ```ts
303
+ * const picks = recommendPacks(answers).filter((r) => r.recommended);
304
+ * ```
177
305
  */
178
306
  export function recommendPacks(
179
307
  answers: InterviewAnswers,
180
308
  ): PackRecommendation[] {
181
309
  return [
182
310
  recommendHarnessExtras(),
311
+ recommendStatusline(),
183
312
  recommendGithub(),
313
+ recommendClaudeGithub(),
184
314
  recommendPublishing(answers),
315
+ recommendLicensing(answers),
185
316
  recommendWorktrees(),
186
317
  recommendSupplyChain(),
187
318
  recommendQuality(),
319
+ recommendFrontend(answers),
320
+ recommendService(answers),
188
321
  ];
189
322
  }
@@ -4,23 +4,27 @@
4
4
  /**
5
5
  * The plugin recommendation table `/customize` reads in Step 3 to pre-select
6
6
  * which built-in `claude-plugins-official` marketplace plugin(s) to offer,
7
- * with the evidence shown alongside each recommendation -- the same
7
+ * and, separately, which service-integration plugins to offer (never
8
+ * pre-selected) for the SDKs the project depends on, with the evidence
9
+ * shown alongside each recommendation -- the same
8
10
  * "inference happens once, visibly, with its reasoning attached" principle
9
11
  * `pack-map.ts` applies to `templates/packs/` bundles. A stored, unit-tested
10
12
  * module rather than a judgment made afresh each run, so the same interview
11
13
  * answers and context always produce the same recommendation.
12
14
  *
13
- * `plugin-dev` is offered only for the `plugin` kind (a repo that authors a
14
- * Claude Code plugin) and is then appended last; for every other kind it is
15
- * absent rather than listed as not recommended, so the ten-entry list
16
- * `/customize` offers in fixed batches keeps its order. m3l-groundwork itself
17
- * enables it, since it authors the `/customize` plugin.
15
+ * Two plugins are offered for one kind only and are then appended last as an
16
+ * eleventh entry: `plugin-dev` for the `plugin` kind (a repo that authors a
17
+ * Claude Code plugin), and `frontend-design` for the `frontend` kind. For
18
+ * every other kind each is absent rather than listed as not recommended, so
19
+ * the first ten entries `/customize` offers in fixed batches keep their
20
+ * order. m3l-groundwork itself enables `plugin-dev`, since it authors the
21
+ * `/customize` plugin.
18
22
  *
19
23
  * Evaluated and deliberately not offered, recorded so they are not proposed
20
24
  * again:
21
25
  *
22
26
  * - `code-review` -- duplicates the built-in `/code-review` and the optional
23
- * `github` pack's PR-review Action.
27
+ * `claude-github` pack's PR-review Action.
24
28
  * - `code-simplifier` -- duplicates the built-in `/simplify`; its
25
29
  * unrestricted-tools agent is blocked by the baseline's hub-and-spoke
26
30
  * write guard on `src/`/`tests/` anyway.
@@ -35,6 +39,20 @@
35
39
  * - `remember` -- third-party under a source-available license that forbids
36
40
  * modification and redistribution; it sends transcripts to `claude -p`,
37
41
  * writes `.remember/`, and can push memory to a remote.
42
+ * - `commit-commands` -- its `/commit` asks for neither Conventional Commits
43
+ * nor a Co-Authored-By trailer, `/commit-push-pr` commits, pushes and opens
44
+ * the PR in one turn, and `/clean_gone` force-deletes local branches whose
45
+ * remote is gone, and their worktrees, so it bypasses and competes with the
46
+ * baseline's `writing-commits`, `creating-prs` and `finishing-work`.
47
+ * - `vercel` -- ships SessionStart and Skill hooks and, by default, sends
48
+ * telemetry that includes an install id.
49
+ * - `stripe` -- its node hooks run on every prompt and every tool batch,
50
+ * spawn the `stripe` CLI and inject feedback prompts.
51
+ * - `convex` -- a PreToolUse lint hook, a Stop hook that can run for up to
52
+ * 180 seconds, polling shell monitors, default-on telemetry and an
53
+ * unpinned `npx convex@latest`.
54
+ * - `linear` -- its SDK package name was not confirmed from vendor docs, so
55
+ * there is no verified dependency signal to offer it from.
38
56
  */
39
57
  import type { InterviewAnswers } from "./kind-facet-map.js";
40
58
 
@@ -67,6 +85,14 @@ export interface PluginRecommendationContext {
67
85
  * `devDependencies` combined. Absent reads as none.
68
86
  */
69
87
  readonly dependencies?: readonly string[];
88
+ /**
89
+ * True when the project already carries its own design system: a
90
+ * design-token file, a CSS file with a Tailwind `@theme` block, or an
91
+ * in-house design-system package in its dependencies. A bare Tailwind
92
+ * config does not count, and a fresh bootstrap is false. Absent reads as
93
+ * false.
94
+ */
95
+ readonly hasDesignSystem?: boolean;
70
96
  }
71
97
 
72
98
  function pluginId(name: string): string {
@@ -288,28 +314,41 @@ function recommendSkillCreator(
288
314
  }
289
315
 
290
316
  /**
291
- * `claude-code-setup` recommends automations (hooks, skills, MCP servers,
292
- * subagents) for a codebase -- which is exactly the job `/customize` is
293
- * already doing, against a baseline designed for it. Running both would
294
- * produce two competing sets of suggestions, so it is never pre-selected;
295
- * it is listed with that reason rather than silently omitted, so the user
296
- * can see why. TypeScript-toolchain gaps are a distinct question from Claude
297
- * Code automation and are answered instead by the baseline
298
- * `typescript-guidance` skill's `gaps` mode.
317
+ * `claude-code-setup`'s `claude-automation-recommender` skill is read-only:
318
+ * it recommends hooks, subagents, skills, plugins and MCP servers for any
319
+ * codebase but edits nothing. The overlap with `/customize` is partial.
320
+ * Hooks, subagents, plugins and the skills those plugins supply are where the
321
+ * two compete -- `/customize` already tailors hooks, subagents and plugins
322
+ * against the baseline and edits the files, and its `harness-guidance` skill
323
+ * has authority over skills, so the plugin's picks would duplicate or
324
+ * contradict it (its skills table suggests skills from plugins this table
325
+ * deliberately rejects, such as `commit`, `writing-rules` and `feature-dev`,
326
+ * and it suggests a `code-reviewer` subagent the baseline already ships).
327
+ * What it alone would add -- MCP server suggestions drawn mostly from the
328
+ * project's dependencies and tooling signals, which `/customize` does not
329
+ * make, plus project-domain skill ideas such as API docs, migrations or
330
+ * component scaffolds -- is not enough to outweigh that conflict, so it is
331
+ * never pre-selected; it is listed with that reason rather than silently
332
+ * omitted, so the user can see why. TypeScript-toolchain gaps are a distinct
333
+ * question from Claude Code automation and are answered instead by the
334
+ * baseline `typescript-guidance` skill's `gaps` mode.
299
335
  */
300
336
  function recommendClaudeCodeSetup(): PluginRecommendation {
301
337
  return {
302
338
  id: pluginId("claude-code-setup"),
303
339
  recommended: false,
304
340
  because:
305
- "its automation recommender overlaps what /customize is already " +
306
- "doing -- tailoring hooks, skills and agents to this project against " +
307
- "the baseline -- so enabling it would produce a second, competing " +
308
- "set of suggestions. TypeScript-toolchain gaps are a separate " +
309
- "question from Claude Code automation, and are answered instead by " +
310
- "the baseline typescript-guidance skill's gaps mode with " +
311
- "live-researched, cited recommendations. " +
312
- "Listed so the choice is visible, not silently left out.",
341
+ "its claude-automation-recommender skill is read-only: it suggests " +
342
+ "hooks, subagents, skills, plugins and MCP servers but edits nothing. " +
343
+ "It competes with /customize on hooks, subagents, plugins and the " +
344
+ "skills those plugins supply, which /customize already tailors " +
345
+ "against the baseline, so its picks would duplicate or contradict " +
346
+ "them. What it alone would add is MCP server suggestions drawn mostly " +
347
+ "from the project's dependencies, which /customize does not make, " +
348
+ "plus project-domain skill ideas such as API docs or migrations. " +
349
+ "TypeScript-toolchain gaps are answered instead by the baseline " +
350
+ "typescript-guidance skill's gaps mode. Listed so the choice is " +
351
+ "visible, not silently left out.",
313
352
  };
314
353
  }
315
354
 
@@ -330,17 +369,51 @@ function recommendPluginDev(): PluginRecommendation {
330
369
  };
331
370
  }
332
371
 
372
+ /**
373
+ * `frontend-design` is a single skill of visual design guidance -- palette,
374
+ * type, layout, a list of "generated look" traits to avoid, and a
375
+ * plan-then-build process -- with no hooks, commands or agents. It follows a
376
+ * brief that pins down a visual direction, but by default its first pass
377
+ * proposes its own palette and token system, which competes with a design
378
+ * system the project already has. So it is pre-selected for the `frontend`
379
+ * kind only when no existing design system was found.
380
+ */
381
+ function recommendFrontendDesign(
382
+ context: PluginRecommendationContext | undefined,
383
+ ): PluginRecommendation {
384
+ const recommended = !(context?.hasDesignSystem ?? false);
385
+ return {
386
+ id: pluginId("frontend-design"),
387
+ recommended,
388
+ because: recommended
389
+ ? "it is one design-guidance skill -- palette, type, layout, " +
390
+ "generated-look traits to avoid and a plan-then-build process -- " +
391
+ "with no hooks or agents, and a frontend project has UI work to " +
392
+ "apply it to. Pre-selected because no existing design system was " +
393
+ "found in the project."
394
+ : "not pre-selected because the project already has a design " +
395
+ "system: by default this skill proposes its own palette and token " +
396
+ "system, which competes with the project's existing one (it still " +
397
+ "follows a brief that pins down a visual direction). It stays on " +
398
+ "offer if that design system is only partial.",
399
+ };
400
+ }
401
+
333
402
  /**
334
403
  * Every built-in marketplace plugin's recommendation for the given interview
335
404
  * answers and context: always the same ten in the same order, plus an
336
- * eleventh, `plugin-dev`, appended last for the `plugin` kind only.
405
+ * eleventh appended last for two kinds only -- `plugin-dev` for the `plugin`
406
+ * kind, `frontend-design` for the `frontend` kind.
337
407
  * Pre-selected unconditionally: `context7`, `typescript-lsp`,
338
- * `claude-md-management` and `claude-security`. Conditionally: `github` when the `github` pack was
408
+ * `claude-md-management` and `claude-security`, plus `plugin-dev` whenever it
409
+ * is present. Conditionally: `github` when the `github` pack was
339
410
  * chosen; `security-guidance` for a `service` or a `thorough` CI depth;
340
411
  * `skill-creator` when the project has its own skills; `agent-sdk-dev` and
341
412
  * `mcp-server-dev` when the project depends on the Claude Agent SDK or the
342
- * MCP SDK respectively. Never: `claude-code-setup`. A pure function --
343
- * identical inputs always produce an equal result.
413
+ * MCP SDK respectively; `frontend-design`, when present, unless the project
414
+ * already has a design system (`hasDesignSystem`). Never:
415
+ * `claude-code-setup`. A pure function -- identical inputs always produce an
416
+ * equal result.
344
417
  *
345
418
  * @example
346
419
  * ```ts
@@ -375,5 +448,181 @@ export function recommendPlugins(
375
448
  recommendAgentSdkDev(context),
376
449
  recommendMcpServerDev(context),
377
450
  ];
378
- return answers.kind === "plugin" ? [...fixed, recommendPluginDev()] : fixed;
451
+ if (answers.kind === "plugin") return [...fixed, recommendPluginDev()];
452
+ if (answers.kind === "frontend") {
453
+ return [...fixed, recommendFrontendDesign(context)];
454
+ }
455
+ return fixed;
456
+ }
457
+
458
+ /**
459
+ * One service-integration plugin: the exact package names and whole npm
460
+ * scopes (written with their trailing `/`) that signal it, whether the
461
+ * plugin ships skills beside its MCP server, an optional phrase saying how
462
+ * the server serves the dependency, the caveat that closes its reasoning,
463
+ * and its prerequisites.
464
+ */
465
+ interface IntegrationSpec {
466
+ readonly name: string;
467
+ readonly exact: readonly string[];
468
+ readonly scopes: readonly string[];
469
+ readonly hasSkills: boolean;
470
+ readonly serves?: string;
471
+ readonly caveat: string;
472
+ readonly prerequisites: readonly string[];
473
+ }
474
+
475
+ const LIVE_ACCOUNT =
476
+ "Not pre-selected because the plugin connects Claude to a live account.";
477
+
478
+ const INTEGRATIONS: readonly IntegrationSpec[] = [
479
+ {
480
+ name: "playwright",
481
+ exact: ["@playwright/test", "@playwright/mcp"],
482
+ scopes: [],
483
+ hasSkills: false,
484
+ serves: " by driving a real browser",
485
+ caveat:
486
+ "Not pre-selected because its server downloads and runs unpinned " +
487
+ "npm code at every launch.",
488
+ prerequisites: [
489
+ "Node.js 18 or newer",
490
+ "the plugin's MCP server launches through " +
491
+ "`npx @playwright/mcp@latest`, which is unpinned: it downloads and " +
492
+ "runs npm code at every launch",
493
+ "no account or sign-in is needed",
494
+ ],
495
+ },
496
+ {
497
+ name: "firebase",
498
+ exact: ["firebase", "firebase-admin", "firebase-tools"],
499
+ scopes: [],
500
+ hasSkills: false,
501
+ caveat: LIVE_ACCOUNT,
502
+ prerequisites: [
503
+ "Node.js and npm",
504
+ "a Firebase (Google) account and a Firebase project",
505
+ "`firebase login` (the server also has a login tool)",
506
+ "the server launches through `npx -y firebase-tools@latest mcp`, " +
507
+ "which is unpinned",
508
+ ],
509
+ },
510
+ {
511
+ name: "supabase",
512
+ exact: [],
513
+ scopes: ["@supabase/"],
514
+ hasSkills: true,
515
+ caveat:
516
+ LIVE_ACCOUNT +
517
+ " Note: the catalog entry's repository is under the " +
518
+ "supabase-community org, although its manifest names Supabase as " +
519
+ "author.",
520
+ prerequisites: [
521
+ "a Supabase account",
522
+ "the MCP server signs in with OAuth 2.1 (a scoped personal access " +
523
+ "token in a Bearer header is the CI alternative)",
524
+ ],
525
+ },
526
+ {
527
+ name: "neon",
528
+ exact: ["@neon/ai-sdk-provider"],
529
+ scopes: ["@neondatabase/"],
530
+ hasSkills: true,
531
+ caveat: LIVE_ACCOUNT,
532
+ prerequisites: [
533
+ "a Neon account",
534
+ "OAuth sign-in on first use of the MCP tools",
535
+ ],
536
+ },
537
+ {
538
+ name: "prisma",
539
+ exact: ["prisma", "@prisma/client"],
540
+ scopes: [],
541
+ hasSkills: false,
542
+ caveat: LIVE_ACCOUNT,
543
+ prerequisites: [
544
+ "a Prisma account and workspace (sign-in for the remote server)",
545
+ "the plugin also ships a local server that launches through " +
546
+ "`npx -y prisma mcp`, which is unpinned",
547
+ ],
548
+ },
549
+ {
550
+ name: "sentry",
551
+ exact: [],
552
+ scopes: ["@sentry/"],
553
+ hasSkills: true,
554
+ caveat: LIVE_ACCOUNT,
555
+ prerequisites: ["a Sentry account"],
556
+ },
557
+ {
558
+ name: "cloudflare",
559
+ exact: ["wrangler", "@cloudflare/ai-chat", "@cloudflare/sandbox"],
560
+ scopes: [],
561
+ hasSkills: true,
562
+ caveat: LIVE_ACCOUNT,
563
+ prerequisites: ["a Cloudflare account"],
564
+ },
565
+ ];
566
+
567
+ function integrationBecause(spec: IntegrationSpec, dependency: string): string {
568
+ const surface = spec.hasSkills ? "MCP server and skills" : "MCP server";
569
+ return (
570
+ `${dependency} is among the project's dependencies, so this ` +
571
+ `plugin's ${surface} would serve it${spec.serves ?? ""}. ${spec.caveat}`
572
+ );
573
+ }
574
+
575
+ function matchesSpec(spec: IntegrationSpec, dependency: unknown): boolean {
576
+ if (typeof dependency !== "string") return false;
577
+ return (
578
+ spec.exact.some((name) => name === dependency) ||
579
+ spec.scopes.some((scope) => dependency.startsWith(scope))
580
+ );
581
+ }
582
+
583
+ /**
584
+ * The service-integration plugins worth offering for the project's
585
+ * dependencies: `playwright`, `firebase`, `supabase`, `neon`, `prisma`,
586
+ * `sentry` and `cloudflare`, each returned only when one of its verified
587
+ * dependency signals is present, at most once, in that fixed order. None is
588
+ * ever pre-selected (`recommended` is always false): each connects Claude to
589
+ * a live account or runs unpinned code, which is the user's call to make.
590
+ * Each `because` names the first matching dependency in the order the
591
+ * context lists them, and `prerequisites` is always non-empty.
592
+ *
593
+ * An integration is offered only if its plugin ships an MCP server (and
594
+ * sometimes skills) but no hooks and no default-on telemetry, and only on a
595
+ * verified dependency signal: an exact package name or a whole npm scope,
596
+ * never a bare prefix. Kept apart from {@link recommendPlugins}, whose ids
597
+ * it never repeats. A pure function -- identical inputs always produce an
598
+ * equal result, and the context is never mutated.
599
+ *
600
+ * @example
601
+ * ```ts
602
+ * import { recommendIntegrations } from "./plugin-map.js";
603
+ *
604
+ * const offers = recommendIntegrations({
605
+ * dependencies: ["@sentry/node", "prisma"],
606
+ * });
607
+ * const ids = offers.map((offer) => offer.id);
608
+ * ```
609
+ */
610
+ export function recommendIntegrations(
611
+ context?: PluginRecommendationContext,
612
+ ): PluginRecommendation[] {
613
+ const dependencies: readonly unknown[] = context?.dependencies ?? [];
614
+ const offers: PluginRecommendation[] = [];
615
+ for (const spec of INTEGRATIONS) {
616
+ const matched = dependencies.find((dependency) =>
617
+ matchesSpec(spec, dependency),
618
+ );
619
+ if (typeof matched !== "string") continue;
620
+ offers.push({
621
+ id: pluginId(spec.name),
622
+ recommended: false,
623
+ because: integrationBecause(spec, matched),
624
+ prerequisites: [...spec.prerequisites],
625
+ });
626
+ }
627
+ return offers;
379
628
  }