@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.
- package/README.md +62 -13
- package/dist/harness/rules.js +1 -1
- package/dist/main.js +5 -15
- package/dist/merge-json.d.ts +3 -1
- package/dist/merge-json.js +1 -1
- package/package.json +1 -1
- package/plugin/skills/customize/SKILL.md +17 -0
- package/plugin/skills/customize/step-3-round-1.md +105 -20
- package/plugin/src/domain-map.ts +1 -1
- package/plugin/src/pack-map.ts +177 -44
- package/plugin/src/plugin-map.ts +277 -28
- package/templates/core/.claude/hooks/inject-decision-gate.mjs +4 -0
- package/templates/core/.claude/rules/agent-dispatch.md +46 -0
- 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 +44 -60
- package/templates/core/bin/check-exports.mjs +3 -1
- package/templates/core/bin/lib/harness-rules.mjs +1 -1
- package/templates/core/eslint.config.js +2 -0
- package/templates/core/vitest.config.ts +4 -3
- package/templates/packs/README.md +8 -3
- package/templates/packs/{github → claude-github}/files/.github/workflows/claude-pr-review.yml +1 -1
- package/templates/packs/{github → claude-github}/files/.github/workflows/claude.yml +1 -1
- package/templates/packs/claude-github/pack.json +19 -0
- 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/github/pack.json +3 -3
- package/templates/packs/harness-extras/files/.claude/hooks/guard-readonly-bash.mjs +1117 -122
- package/templates/packs/harness-extras/pack.json +3 -15
- package/templates/packs/licensing/pack.json +31 -0
- package/templates/packs/publishing/pack.json +3 -14
- 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/statusline/pack.json +31 -0
- package/templates/packs/supply-chain/pack.json +1 -1
- package/templates/packs/worktrees/files/.claude/skills/working-in-worktrees/SKILL.md +20 -5
- package/templates/packs/worktrees/pack.json +2 -1
- /package/templates/packs/{publishing → licensing}/files/REUSE.toml +0 -0
- /package/templates/packs/{publishing → licensing}/files/bin/check-license-headers.mjs +0 -0
- /package/templates/packs/{harness-extras → statusline}/files/.claude/hooks/statusline-layout.mjs +0 -0
- /package/templates/packs/{harness-extras → statusline}/files/.claude/hooks/statusline.mjs +0 -0
- /package/templates/packs/{harness-extras → statusline}/files/.claude/hooks/subagent-statusline.mjs +0 -0
package/plugin/src/pack-map.ts
CHANGED
|
@@ -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
|
-
*
|
|
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
|
|
27
|
-
*
|
|
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
|
|
39
|
-
"compaction) and read-only Bash guard
|
|
40
|
-
"to any particular project kind
|
|
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
|
-
* `
|
|
50
|
-
*
|
|
51
|
-
*
|
|
52
|
-
*
|
|
53
|
-
*
|
|
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
|
|
57
|
-
*
|
|
58
|
-
*
|
|
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
|
|
67
|
-
"
|
|
68
|
-
"
|
|
69
|
-
"
|
|
70
|
-
"
|
|
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
|
-
* `
|
|
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
|
|
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
|
|
99
|
-
"
|
|
100
|
-
"
|
|
101
|
-
"
|
|
102
|
-
"
|
|
103
|
-
"
|
|
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
|
-
*
|
|
174
|
-
*
|
|
175
|
-
*
|
|
176
|
-
*
|
|
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
|
}
|
package/plugin/src/plugin-map.ts
CHANGED
|
@@ -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
|
-
*
|
|
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:
|
|
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`
|
|
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
|
}
|