@monte3l/groundwork 1.0.5 → 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 (32) hide show
  1. package/README.md +8 -1
  2. package/package.json +1 -1
  3. package/plugin/skills/customize/SKILL.md +17 -0
  4. package/plugin/skills/customize/step-3-round-1.md +82 -5
  5. package/plugin/src/pack-map.ts +57 -5
  6. package/plugin/src/plugin-map.ts +276 -27
  7. package/templates/core/.claude/settings.json +11 -1
  8. package/templates/core/.claude/skills/creating-prs/SKILL.md +1 -0
  9. package/templates/core/.claude/skills/finishing-work/SKILL.md +1 -0
  10. package/templates/core/.claude/skills/harness-guidance/SKILL.md +1 -0
  11. package/templates/core/.claude/skills/starting-work/SKILL.md +20 -0
  12. package/templates/core/.claude/skills/triaging-ci/SKILL.md +1 -0
  13. package/templates/core/.claude/skills/typescript-guidance/SKILL.md +1 -0
  14. package/templates/core/.claude/skills/writing-commits/SKILL.md +1 -0
  15. package/templates/core/CLAUDE.md +6 -3
  16. package/templates/packs/README.md +2 -0
  17. package/templates/packs/claude-github/files/.github/workflows/claude-pr-review.yml +1 -1
  18. package/templates/packs/claude-github/files/.github/workflows/claude.yml +1 -1
  19. package/templates/packs/frontend/files/.claude/agents/ui-reviewer.md +132 -0
  20. package/templates/packs/frontend/files/.claude/skills/new-component/SKILL.md +72 -0
  21. package/templates/packs/frontend/pack.json +19 -0
  22. package/templates/packs/github/files/.claude/skills/reviewing-dependabot-prs/SKILL.md +4 -0
  23. package/templates/packs/github/files/.claude/skills/triaging-scan-alerts/SKILL.md +3 -0
  24. package/templates/packs/github/files/.claude/skills/watching-pr-checks/SKILL.md +4 -0
  25. package/templates/packs/harness-extras/files/.claude/hooks/guard-readonly-bash.mjs +1117 -122
  26. package/templates/packs/harness-extras/pack.json +1 -1
  27. package/templates/packs/quality/files/.claude/agents/type-design-analyzer.md +1 -1
  28. package/templates/packs/service/files/.claude/agents/performance-analyzer.md +96 -0
  29. package/templates/packs/service/files/.claude/skills/api-doc/SKILL.md +67 -0
  30. package/templates/packs/service/files/.claude/skills/api-doc/openapi-template.yaml +48 -0
  31. package/templates/packs/service/pack.json +19 -0
  32. package/templates/packs/worktrees/files/.claude/skills/working-in-worktrees/SKILL.md +20 -5
package/README.md CHANGED
@@ -148,6 +148,8 @@ the wiring contract.
148
148
  | `harness-extras` | The compaction-handoff hook pair and a read-only Bash guard. |
149
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. |
150
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. |
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. |
151
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. |
152
154
  | `github` | Three `gh`-CLI skills (Dependabot PR triage, scan-alert triage, PR-check watching) -- no hooks, no gate, no workflows. |
153
155
  | `publishing` | A release pipeline (changesets version-PR / staged, provenance-attested npm publish via trusted publishing). Fresh mode only. |
@@ -206,7 +208,7 @@ The `/customize` skill is also available as a Claude Code plugin, for use in
206
208
  a project that was not bootstrapped by this CLI:
207
209
 
208
210
  ```
209
- /plugin marketplace add monte3l/m3l-groundwork
211
+ /plugin marketplace add monte3l/m3l-plugins
210
212
  /plugin install m3l-groundwork-customize@monte3l
211
213
  ```
212
214
 
@@ -289,6 +291,11 @@ See [`CONTRIBUTING.md`](https://github.com/monte3l/m3l-groundwork/blob/main/CONT
289
291
  `@monte3l/groundwork` is released, published, and verified, and
290
292
  [`CLAUDE.md`](https://github.com/monte3l/m3l-groundwork/blob/main/CLAUDE.md#releases) for the full design.
291
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
+
292
299
  [`CLAUDE.md`](https://github.com/monte3l/m3l-groundwork/blob/main/CLAUDE.md) is the full reference: architecture, the command
293
300
  table, conventions, and known gaps.
294
301
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@monte3l/groundwork",
3
- "version": "1.0.5",
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
 
@@ -67,8 +117,8 @@ confirmed in Step 0.4:
67
117
  `recommended: false`, since it changes the day-to-day workflow rather than
68
118
  adding a nicety, and `claude-github` is always `recommended: false`, since
69
119
  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
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
72
122
  conflict there or for any future kind-scoped pack, raise it rather than
73
123
  silently overriding the user's Step 0.4 answer, mirroring Step 4's "the
74
124
  one exception" rule for guidance findings. Before installing, check the
@@ -162,18 +212,45 @@ already-installed pack's skills (e.g. the `github` pack's three);
162
212
  in the project's root `package.json` (the same read in both modes; a fresh
163
213
  bootstrap carries only the baseline's own devDependencies, so no SDK plugin
164
214
  is pre-selected there, and a monorepo whose SDK dependency sits only in a
165
- 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
166
224
  `recommendPlugins(answers, context)` from `plugin-map.ts`
167
225
  (alongside this file, same copy mechanism as `pack-map.ts`) with the
168
226
  now-confirmed `InterviewAnswers`, and offer every entry it returns (ten, or
169
- 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**
170
229
  `AskUserQuestion` call holding three multi-select questions (a question
171
230
  takes at most four options, so split the list in its fixed order: entries
172
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`
173
232
  boolean with its `because` shown as the evidence -- same
174
233
  "visible reasoning" principle as every other inference in this skill.
175
234
 
176
- 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
177
254
  `enabledPlugins` (`{"<id>": true}` per entry, e.g.
178
255
  `"context7@claude-plugins-official": true`) -- additive and entry-by-entry,
179
256
  same discipline as the CLI's own `mergeSettingsHooks` (which owns the
@@ -242,11 +242,61 @@ function recommendQuality(): PackRecommendation {
242
242
  }
243
243
 
244
244
  /**
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.
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.
250
300
  *
251
301
  * @example
252
302
  * ```ts
@@ -266,5 +316,7 @@ export function recommendPacks(
266
316
  recommendWorktrees(),
267
317
  recommendSupplyChain(),
268
318
  recommendQuality(),
319
+ recommendFrontend(answers),
320
+ recommendService(answers),
269
321
  ];
270
322
  }
@@ -4,17 +4,21 @@
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:
@@ -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
  }
@@ -1,7 +1,17 @@
1
1
  {
2
2
  "$schema": "https://json.schemastore.org/claude-code-settings.json",
3
3
  "permissions": {
4
- "deny": ["Read(./.env)", "Read(./.env.*)", "Read(./secrets/**)"]
4
+ "deny": [
5
+ "Read(./.env)",
6
+ "Read(./.env.*)",
7
+ "Read(./secrets/**)",
8
+ "Read(**/credentials.json)",
9
+ "Read(**/secrets.yaml)",
10
+ "Edit(**/pnpm-lock.yaml)",
11
+ "Edit(**/package-lock.json)",
12
+ "Edit(**/yarn.lock)",
13
+ "Edit(**/.git/**)"
14
+ ]
5
15
  },
6
16
  "hooks": {
7
17
  "UserPromptSubmit": [