@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.
- package/README.md +8 -1
- package/package.json +1 -1
- package/plugin/skills/customize/SKILL.md +17 -0
- package/plugin/skills/customize/step-3-round-1.md +82 -5
- package/plugin/src/pack-map.ts +57 -5
- package/plugin/src/plugin-map.ts +276 -27
- package/templates/core/.claude/settings.json +11 -1
- package/templates/core/.claude/skills/creating-prs/SKILL.md +1 -0
- package/templates/core/.claude/skills/finishing-work/SKILL.md +1 -0
- package/templates/core/.claude/skills/harness-guidance/SKILL.md +1 -0
- package/templates/core/.claude/skills/starting-work/SKILL.md +20 -0
- package/templates/core/.claude/skills/triaging-ci/SKILL.md +1 -0
- package/templates/core/.claude/skills/typescript-guidance/SKILL.md +1 -0
- package/templates/core/.claude/skills/writing-commits/SKILL.md +1 -0
- package/templates/core/CLAUDE.md +6 -3
- package/templates/packs/README.md +2 -0
- package/templates/packs/claude-github/files/.github/workflows/claude-pr-review.yml +1 -1
- package/templates/packs/claude-github/files/.github/workflows/claude.yml +1 -1
- package/templates/packs/frontend/files/.claude/agents/ui-reviewer.md +132 -0
- package/templates/packs/frontend/files/.claude/skills/new-component/SKILL.md +72 -0
- package/templates/packs/frontend/pack.json +19 -0
- package/templates/packs/github/files/.claude/skills/reviewing-dependabot-prs/SKILL.md +4 -0
- package/templates/packs/github/files/.claude/skills/triaging-scan-alerts/SKILL.md +3 -0
- package/templates/packs/github/files/.claude/skills/watching-pr-checks/SKILL.md +4 -0
- package/templates/packs/harness-extras/files/.claude/hooks/guard-readonly-bash.mjs +1117 -122
- package/templates/packs/harness-extras/pack.json +1 -1
- package/templates/packs/quality/files/.claude/agents/type-design-analyzer.md +1 -1
- package/templates/packs/service/files/.claude/agents/performance-analyzer.md +96 -0
- package/templates/packs/service/files/.claude/skills/api-doc/SKILL.md +67 -0
- package/templates/packs/service/files/.claude/skills/api-doc/openapi-template.yaml +48 -0
- package/templates/packs/service/pack.json +19 -0
- 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-
|
|
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
|
|
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 `
|
|
71
|
-
recommended for `library`/`cli`,
|
|
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
|
|
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
|
|
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
|
-
|
|
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
|
package/plugin/src/pack-map.ts
CHANGED
|
@@ -242,11 +242,61 @@ function recommendQuality(): PackRecommendation {
|
|
|
242
242
|
}
|
|
243
243
|
|
|
244
244
|
/**
|
|
245
|
-
*
|
|
246
|
-
*
|
|
247
|
-
*
|
|
248
|
-
*
|
|
249
|
-
*
|
|
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
|
}
|
package/plugin/src/plugin-map.ts
CHANGED
|
@@ -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
|
-
*
|
|
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
|
-
*
|
|
14
|
-
*
|
|
15
|
-
*
|
|
16
|
-
*
|
|
17
|
-
*
|
|
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`
|
|
292
|
-
*
|
|
293
|
-
*
|
|
294
|
-
*
|
|
295
|
-
*
|
|
296
|
-
*
|
|
297
|
-
*
|
|
298
|
-
*
|
|
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
|
|
306
|
-
"
|
|
307
|
-
"
|
|
308
|
-
"
|
|
309
|
-
"
|
|
310
|
-
"
|
|
311
|
-
"
|
|
312
|
-
"
|
|
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
|
|
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
|
|
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
|
|
343
|
-
*
|
|
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
|
-
|
|
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": [
|
|
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": [
|