@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/README.md
CHANGED
|
@@ -44,14 +44,53 @@ Read this project's rendered docs site at
|
|
|
44
44
|
|
|
45
45
|
## Quickstart
|
|
46
46
|
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
|
|
54
|
-
|
|
47
|
+
Install [Node 24+](https://nodejs.org/), [pnpm](https://pnpm.io/installation)
|
|
48
|
+
and [Claude Code](https://docs.claude.com/en/docs/claude-code/overview) first
|
|
49
|
+
(see ["Requirements"](#requirements) below for exact versions). Nothing is
|
|
50
|
+
installed globally: `npx` and `pnpm dlx` fetch the CLI, run it once and leave
|
|
51
|
+
only a download cache behind.
|
|
52
|
+
|
|
53
|
+
**A new project.** Point the CLI at an empty or missing directory:
|
|
54
|
+
|
|
55
|
+
```bash
|
|
56
|
+
# with npx
|
|
57
|
+
npx @monte3l/groundwork my-app
|
|
58
|
+
|
|
59
|
+
# or with pnpm
|
|
60
|
+
pnpm dlx @monte3l/groundwork my-app
|
|
61
|
+
```
|
|
62
|
+
|
|
63
|
+
It writes the baseline, runs `git init` and `pnpm install`, and installs the
|
|
64
|
+
`/customize` skill. Add `--pack <name>` to install an optional
|
|
65
|
+
[pack](#packs) at the same time (`--list-packs` shows them).
|
|
66
|
+
|
|
67
|
+
**An existing project.** Run the CLI from the project's root, or pass its path.
|
|
68
|
+
It detects that the directory already looks like a project and switches to
|
|
69
|
+
adopt mode, which surveys it read-only and never overwrites a project file:
|
|
70
|
+
|
|
71
|
+
```bash
|
|
72
|
+
cd path/to/your-project
|
|
73
|
+
|
|
74
|
+
# with npx
|
|
75
|
+
npx @monte3l/groundwork .
|
|
76
|
+
|
|
77
|
+
# or with pnpm
|
|
78
|
+
pnpm dlx @monte3l/groundwork .
|
|
79
|
+
```
|
|
80
|
+
|
|
81
|
+
It writes a report and staged copies of what it would add under
|
|
82
|
+
`.groundwork/`, plus one guarded copy of the `/customize` skill.
|
|
83
|
+
|
|
84
|
+
**Then, in either case:**
|
|
85
|
+
|
|
86
|
+
```bash
|
|
87
|
+
cd my-app # or stay in your existing project
|
|
88
|
+
claude # open the project in Claude Code
|
|
89
|
+
```
|
|
90
|
+
|
|
91
|
+
Run `/customize` inside Claude Code. For a new project it interviews you and
|
|
92
|
+
tailors the baseline. For an existing one it first reconciles the survey
|
|
93
|
+
against your repo and confirms each change with you before editing anything.
|
|
55
94
|
|
|
56
95
|
> [!NOTE]
|
|
57
96
|
> Earlier releases shipped on other [dist-tags](https://github.com/monte3l/m3l-groundwork/blob/main/docs/glossary.md#dist-tag).
|
|
@@ -106,10 +145,15 @@ the wiring contract.
|
|
|
106
145
|
|
|
107
146
|
| Pack | Contents |
|
|
108
147
|
| ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
109
|
-
| `harness-extras` | The compaction-handoff hook pair
|
|
148
|
+
| `harness-extras` | The compaction-handoff hook pair and a read-only Bash guard. |
|
|
149
|
+
| `statusline` | A five-row Claude Code status line plus a per-subagent row renderer, width-fit to the terminal. Sets the `statusLine` and `subagentStatusLine` keys. |
|
|
110
150
|
| `quality` | A per-file size ratchet gate over `src/` and `tests/`, and a read-only `type-design-analyzer` review agent. Adopt-capable, recommended for every project kind. |
|
|
111
|
-
| `
|
|
112
|
-
| `
|
|
151
|
+
| `frontend` | A read-only `ui-reviewer` accessibility agent (static WCAG 2.2 review) and a `new-component` skill that mirrors a sibling component. Recommended for the `frontend` kind only. |
|
|
152
|
+
| `service` | A read-only `performance-analyzer` agent (static review for blocking calls and unbounded work; profiling is reported as `NOT CHECKED`) and an `api-doc` skill that writes an OpenAPI description from the routes the code defines. Recommended for the `service` kind only. |
|
|
153
|
+
| `claude-github` | Anthropic's official Claude Code GitHub Action as two workflows: `@claude` mention-mode and an automated PR-review comment on every pull request -- no hooks, no gate. Needs an auth secret the pack cannot create, and the review spends API credits per PR. |
|
|
154
|
+
| `github` | Three `gh`-CLI skills (Dependabot PR triage, scan-alert triage, PR-check watching) -- no hooks, no gate, no workflows. |
|
|
155
|
+
| `publishing` | A release pipeline (changesets version-PR / staged, provenance-attested npm publish via trusted publishing). Fresh mode only. |
|
|
156
|
+
| `licensing` | An SPDX/REUSE license-header gate (`check-license-headers.mjs`, a `lint`-group verify step) and a `REUSE.toml` template. Fresh mode only, because the one-time backfill fails an established project's `pnpm verify`. |
|
|
113
157
|
| `supply-chain` | Secret scanning (`gitleaks.yml`) and an OpenSSF Scorecard run (`scorecard.yml`) for any GitHub project, published or not. Two workflows (read-only apart from the Scorecard job's `security-events` and `id-token` write), adopt-capable, recommended for every project kind. |
|
|
114
158
|
| `worktrees` | Enforces that all src/tests development happens inside an isolated git worktree, on any branch, for any caller: a `working-in-worktrees` skill (start/status/sync/finish/fan-out), a dependency-install backstop hook, a guard stricter than the baseline's own branch/hub guards, and a `.worktreeinclude` copying `.env`/`.env.local`/`.env.*.local` into every worktree Claude Code creates. Changes the day-to-day workflow -- opt-in, not recommended by default. |
|
|
115
159
|
|
|
@@ -164,7 +208,7 @@ The `/customize` skill is also available as a Claude Code plugin, for use in
|
|
|
164
208
|
a project that was not bootstrapped by this CLI:
|
|
165
209
|
|
|
166
210
|
```
|
|
167
|
-
/plugin marketplace add monte3l/m3l-
|
|
211
|
+
/plugin marketplace add monte3l/m3l-plugins
|
|
168
212
|
/plugin install m3l-groundwork-customize@monte3l
|
|
169
213
|
```
|
|
170
214
|
|
|
@@ -247,6 +291,11 @@ See [`CONTRIBUTING.md`](https://github.com/monte3l/m3l-groundwork/blob/main/CONT
|
|
|
247
291
|
`@monte3l/groundwork` is released, published, and verified, and
|
|
248
292
|
[`CLAUDE.md`](https://github.com/monte3l/m3l-groundwork/blob/main/CLAUDE.md#releases) for the full design.
|
|
249
293
|
|
|
294
|
+
The `/customize` plugin has no release of its own. The central
|
|
295
|
+
`monte3l/m3l-plugins` marketplace lists it pinned to a CLI release tag
|
|
296
|
+
(`@monte3l/groundwork@X.Y.Z`), so a plugin change reaches marketplace users
|
|
297
|
+
only after the next CLI release **and** a pin-bump PR in `monte3l/m3l-plugins`.
|
|
298
|
+
|
|
250
299
|
[`CLAUDE.md`](https://github.com/monte3l/m3l-groundwork/blob/main/CLAUDE.md) is the full reference: architecture, the command
|
|
251
300
|
table, conventions, and known gaps.
|
|
252
301
|
|
|
@@ -276,7 +325,7 @@ everything else that goes wrong at run time.
|
|
|
276
325
|
| Unrecognized flag, missing flag value, repeated `--name`, missing or extra target argument | 2 | Prints the error and the usage text. |
|
|
277
326
|
| `--adopt` with `--fresh` | 2 | The two are mutually exclusive. |
|
|
278
327
|
| `--name` is not a valid npm package name, or a `--pack` value is not a valid pack name | 2 | Prints the rule it broke and the usage text. |
|
|
279
|
-
| Unknown `--pack` | 2 | Lists the available packs.
|
|
328
|
+
| Unknown `--pack` | 2 | Lists the available packs. |
|
|
280
329
|
| `--pack` for a pack without fresh mode | 2 | Says the pack does not support fresh mode and lists its modes. |
|
|
281
330
|
| Adopt mode with `--adopt` and a missing target directory, `--force` or `--pack` | 2 | Adopt never writes project files and surveys every pack itself; run `/customize` to install a pack. |
|
|
282
331
|
| Windows, fresh mode | 1 | Refuses before writing anything: Linux and macOS only. Adopt mode, `--help`, `--version` and `--list-packs` still run. |
|
package/dist/harness/rules.js
CHANGED
|
@@ -473,7 +473,7 @@ const descriptionSubstance = {
|
|
|
473
473
|
else if (description.length > DESCRIPTION_MAX) {
|
|
474
474
|
failures.push({
|
|
475
475
|
subject,
|
|
476
|
-
message: `description is ${description.length} chars; over ${DESCRIPTION_MAX}
|
|
476
|
+
message: `description is ${description.length} chars; over the ${DESCRIPTION_MAX}-char Agent Skills maximum (Claude Code also truncates description + when_to_use at 1,536 in its skill listing)`,
|
|
477
477
|
});
|
|
478
478
|
}
|
|
479
479
|
};
|
package/dist/main.js
CHANGED
|
@@ -389,28 +389,18 @@ function describeInstallFailure(error) {
|
|
|
389
389
|
return `\`pnpm install\` failed (${code})`;
|
|
390
390
|
return "`pnpm install` failed";
|
|
391
391
|
}
|
|
392
|
-
// A pack that was renamed or folded into another, mapped to its successor so
|
|
393
|
-
// an old `--pack` name gets a pointed hint rather than a bare "unknown pack".
|
|
394
|
-
const RENAMED_PACKS = new Map([
|
|
395
|
-
["statusline", "harness-extras"],
|
|
396
|
-
]);
|
|
397
392
|
/**
|
|
398
393
|
* Loads one `--pack` for fresh mode -- called for every pack before any file
|
|
399
|
-
* is written. An unknown name (
|
|
400
|
-
*
|
|
401
|
-
*
|
|
402
|
-
*
|
|
403
|
-
* not a bad invocation.
|
|
394
|
+
* is written. An unknown name (the message lists the available packs) or a
|
|
395
|
+
* fresh-incompatible pack is a usage error (exit 2); a pack that exists but
|
|
396
|
+
* whose manifest fails to load propagates `loadPack`'s own error unchanged
|
|
397
|
+
* (exit 1), since that is a broken install, not a bad invocation.
|
|
404
398
|
*/
|
|
405
399
|
function resolveFreshPack(name) {
|
|
406
400
|
const available = listPackNames();
|
|
407
401
|
if (!available.includes(name)) {
|
|
408
|
-
const successor = RENAMED_PACKS.get(name);
|
|
409
|
-
const hint = successor === undefined
|
|
410
|
-
? ""
|
|
411
|
-
: ` -- it was renamed to "${successor}"; use --pack ${successor}`;
|
|
412
402
|
const list = available.length > 0 ? available.join(", ") : "none";
|
|
413
|
-
throw new CliUsageError(`unknown pack "${name}"
|
|
403
|
+
throw new CliUsageError(`unknown pack "${name}" (available: ${list})\n\n${USAGE}`);
|
|
414
404
|
}
|
|
415
405
|
const pack = loadPack(name);
|
|
416
406
|
if (!pack.manifest.modes.includes("fresh")) {
|
package/dist/merge-json.d.ts
CHANGED
|
@@ -46,6 +46,8 @@ interface SettingsHookCommand {
|
|
|
46
46
|
command: string;
|
|
47
47
|
if?: string;
|
|
48
48
|
timeout?: number;
|
|
49
|
+
/** Hook failure policy (Claude Code 2.1.295+); defaults to `"continue"`. */
|
|
50
|
+
onFailure?: "continue" | "block";
|
|
49
51
|
}
|
|
50
52
|
interface SettingsHookEntry {
|
|
51
53
|
matcher?: string;
|
|
@@ -58,7 +60,7 @@ export type SettingsHooksFragment = Record<string, SettingsHookEntry[]>;
|
|
|
58
60
|
* counts as a match -- e.g. `PreCompact`, which has none); within a matched
|
|
59
61
|
* entry, only `hooks` commands not already present (compared by exact
|
|
60
62
|
* `command` string) are appended. A command that matches on `command` but
|
|
61
|
-
* differs in its other fields (`if`, `timeout`) is a hard collision, never
|
|
63
|
+
* differs in its other fields (`if`, `timeout`, `onFailure`) is a hard collision, never
|
|
62
64
|
* a silent overwrite. An event name of `__proto__`, `constructor` or
|
|
63
65
|
* `prototype` throws: the check runs per key inside the loop, before that
|
|
64
66
|
* key is read or written, and nothing escapes the failed merge -- `existing`
|
package/dist/merge-json.js
CHANGED
|
@@ -110,7 +110,7 @@ function assertSafeKey(key, context) {
|
|
|
110
110
|
* counts as a match -- e.g. `PreCompact`, which has none); within a matched
|
|
111
111
|
* entry, only `hooks` commands not already present (compared by exact
|
|
112
112
|
* `command` string) are appended. A command that matches on `command` but
|
|
113
|
-
* differs in its other fields (`if`, `timeout`) is a hard collision, never
|
|
113
|
+
* differs in its other fields (`if`, `timeout`, `onFailure`) is a hard collision, never
|
|
114
114
|
* a silent overwrite. An event name of `__proto__`, `constructor` or
|
|
115
115
|
* `prototype` throws: the check runs per key inside the loop, before that
|
|
116
116
|
* key is read or written, and nothing escapes the failed merge -- `existing`
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@monte3l/groundwork",
|
|
3
|
-
"version": "1.0
|
|
3
|
+
"version": "1.1.0",
|
|
4
4
|
"description": "CLI that bootstraps a TypeScript project with a strict toolchain and Claude Code setup, or read-only surveys an existing one, plus a /customize plugin that tailors it to current guidance.",
|
|
5
5
|
"keywords": [
|
|
6
6
|
"bootstrap",
|
|
@@ -259,6 +259,23 @@ declined, plus any prerequisite named against an enabled plugin
|
|
|
259
259
|
plugin's `prerequisites` names) as a follow-up the
|
|
260
260
|
user still has to satisfy.
|
|
261
261
|
|
|
262
|
+
Close with two follow-ups the project's own files cannot carry, because both
|
|
263
|
+
are per-user. **Notifications:** Claude Code sends a desktop notification by
|
|
264
|
+
itself only in Ghostty, Kitty and iTerm2; in another terminal, set
|
|
265
|
+
`"preferredNotifChannel": "terminal_bell"` in `~/.claude/settings.json` (or
|
|
266
|
+
add a `Notification` hook) to be alerted when Claude needs a permission or is
|
|
267
|
+
waiting for input. **Fewer permission prompts:** after a few sessions, run
|
|
268
|
+
`/fewer-permission-prompts`, which scans the transcripts for common read-only
|
|
269
|
+
Bash and MCP calls and proposes an allowlist for the project's
|
|
270
|
+
`.claude/settings.json`; the baseline ships none because it cannot know the
|
|
271
|
+
project's commands in advance.
|
|
272
|
+
|
|
273
|
+
**Dependabot grouping:** at CI depth thorough in a fresh bootstrap, `.github/dependabot.yml`
|
|
274
|
+
gets an `npm` entry with `groups` (see Step 3 Round 1). Report whether it was
|
|
275
|
+
added, and that Dependabot support for the project's pnpm version is
|
|
276
|
+
**unconfirmed**: tell the owner to check the first Dependabot PR, and to expect failed or partial updates if the project uses pnpm `catalogs` or workspace `overrides`. At any other
|
|
277
|
+
depth, mention it as an option only.
|
|
278
|
+
|
|
262
279
|
**Write the report to a file as well (adopt mode only).** Save the same report
|
|
263
280
|
to `.groundwork/customization-report.md`, so a reviewer can read it without
|
|
264
281
|
asking for the chat. Include which conflicts were resolved and which packs
|
|
@@ -24,6 +24,50 @@
|
|
|
24
24
|
**CI depth = thorough**: note this for Round 2 — `harness-guidance` may
|
|
25
25
|
recommend additional current-best-practice lanes (e.g. a scheduled
|
|
26
26
|
dependency audit) beyond what the baseline ships.
|
|
27
|
+
- **CI depth = thorough also adds npm grouping to Dependabot.** Append this
|
|
28
|
+
block to `updates:` in `.github/dependabot.yml`, which the baseline ships
|
|
29
|
+
with only the `github-actions` ecosystem, at the same two-space item
|
|
30
|
+
indentation as that entry:
|
|
31
|
+
|
|
32
|
+
```yaml
|
|
33
|
+
- package-ecosystem: "npm"
|
|
34
|
+
directory: "/"
|
|
35
|
+
schedule:
|
|
36
|
+
interval: "weekly"
|
|
37
|
+
cooldown:
|
|
38
|
+
default-days: 7
|
|
39
|
+
commit-message:
|
|
40
|
+
prefix: "chore"
|
|
41
|
+
labels:
|
|
42
|
+
- "dependencies"
|
|
43
|
+
groups:
|
|
44
|
+
dev-dependencies:
|
|
45
|
+
dependency-type: "development"
|
|
46
|
+
update-types: ["minor", "patch"]
|
|
47
|
+
prod-dependencies:
|
|
48
|
+
dependency-type: "production"
|
|
49
|
+
update-types: ["minor", "patch"]
|
|
50
|
+
```
|
|
51
|
+
|
|
52
|
+
The baseline's comment above the `github-actions` entry says npm updates are
|
|
53
|
+
deliberately not enabled here: rewrite or drop that sentence when you add the
|
|
54
|
+
block, so the file does not contradict itself. Major bumps stay one PR each.
|
|
55
|
+
Dependabot's `npm` ecosystem also covers pnpm, but GitHub's
|
|
56
|
+
supported-ecosystems page lists pnpm only up to v10 and the baseline pins a
|
|
57
|
+
newer pnpm, so when the project uses pnpm, support for its pnpm version is
|
|
58
|
+
**unconfirmed**: say so in Step 7 and tell the owner to check the first
|
|
59
|
+
Dependabot PR. Upstream, `dependabot-core` is adding pnpm 12 support in stages and
|
|
60
|
+
GitHub's docs lag behind it: Part 1 (#16513) and Part 2 (#16517) merged on
|
|
61
|
+
2026-10-09, Part 3 (#16521) is still open, and #15904 (a pnpm 12 environment
|
|
62
|
+
lockfile read as an empty dependency graph) is still open. A
|
|
63
|
+
`minimumReleaseAge` failure on pnpm 12.3 or newer was fixed (#16375), but
|
|
64
|
+
projects that use `catalogs` or workspace `overrides` still hit open issues
|
|
65
|
+
(grouped updates leave overrides stale). If the project uses `catalog:`
|
|
66
|
+
entries or workspace `overrides`, tell the owner to expect failed
|
|
67
|
+
or partial updates until those issues close. **At any other CI depth in a fresh bootstrap** this is not
|
|
68
|
+
offered as a question (the plugin offer's question counts are fixed); it is
|
|
69
|
+
only a Step 7 follow-up.
|
|
70
|
+
|
|
27
71
|
- **Agents not kept**: delete their `.claude/agents/<name>.md` file. Never
|
|
28
72
|
delete `Explore`, `test-author`, or `code-implementer` even if unselected
|
|
29
73
|
— they're load-bearing for the hub-and-spoke loop `CLAUDE.md` documents.
|
|
@@ -39,6 +83,12 @@
|
|
|
39
83
|
the project actually has, instead of a named baseline path — "tests must not
|
|
40
84
|
hard-fail `pre-push`" is applied to _the gate the inventory found_ (jest in
|
|
41
85
|
CI, husky locally, whatever it is), not to `lefthook.yml`/`ci.yml` by name.
|
|
86
|
+
In adopt mode the Dependabot block above is never applied, because Step 0.4
|
|
87
|
+
did not confirm it. When `.github/dependabot.yml` already exists and has no
|
|
88
|
+
`npm` entry for directory "/", name the block in Step 7 as a follow-up the
|
|
89
|
+
owner can paste in; never create the file, and never touch an existing `npm`
|
|
90
|
+
entry (the project's own cadence and groups win).
|
|
91
|
+
|
|
42
92
|
Concretely, adopt-mode Round 1 applies exactly three things, all already
|
|
43
93
|
confirmed in Step 0.4:
|
|
44
94
|
|
|
@@ -61,18 +111,21 @@ confirmed in Step 0.4:
|
|
|
61
111
|
`recommendPacks(answers)` from `pack-map.ts` (alongside this file, same
|
|
62
112
|
copy mechanism as `kind-facet-map.ts`) with the now-confirmed
|
|
63
113
|
`InterviewAnswers` and compare its verdict against Step 0.4's decision.
|
|
64
|
-
`harness-extras`, `github`, `
|
|
65
|
-
never disagree (none of the
|
|
66
|
-
answer -- `worktrees` is always
|
|
67
|
-
day-to-day workflow rather than
|
|
68
|
-
|
|
69
|
-
|
|
114
|
+
`harness-extras`, `statusline`, `github`, `claude-github`, `supply-chain`,
|
|
115
|
+
`quality`, and `worktrees` never disagree (none of the seven's
|
|
116
|
+
recommendation varies by kind or answer -- `worktrees` is always
|
|
117
|
+
`recommended: false`, since it changes the day-to-day workflow rather than
|
|
118
|
+
adding a nicety, and `claude-github` is always `recommended: false`, since
|
|
119
|
+
its workflows need an auth secret and the review spends API credits on
|
|
120
|
+
every PR; the other five are always `recommended: true`), but `publishing`'s, `licensing`'s, `frontend`'s and `service`'s do (`publishing` and
|
|
121
|
+
`licensing` are each recommended for `library`/`cli`, `frontend` only for the `frontend` kind, `service` only for the `service` kind) — if the comparison surfaces a real
|
|
70
122
|
conflict there or for any future kind-scoped pack, raise it rather than
|
|
71
123
|
silently overriding the user's Step 0.4 answer, mirroring Step 4's "the
|
|
72
124
|
one exception" rule for guidance findings. Before installing, check the
|
|
73
125
|
pack's own `modes`: a pack whose `modes` doesn't include `"adopt"` (today,
|
|
74
126
|
`publishing` — its release flow encodes decisions too project-specific to
|
|
75
|
-
apply blind
|
|
127
|
+
apply blind — and `licensing`, whose one-time SPDX header backfill fails an
|
|
128
|
+
established project's `pnpm verify`) is never auto-installed here even if staged and approved;
|
|
76
129
|
instead, state in Step 7 that it needs a manual install (point at `.groundwork/packs/<name>/` and the pack's own `adoptNotes`, and say to strip the `.staged` suffix from every name when copying by hand and to replace every `__KEY__` token with the project's real value) and stop
|
|
77
130
|
there for that pack. Before merging any staged `pack.json.staged` wiring, repeat
|
|
78
131
|
the prototype-key check from Step 0.4(c): if a key of `wiring.settings`,
|
|
@@ -90,20 +143,23 @@ confirmed in Step 0.4:
|
|
|
90
143
|
from `pack.json.staged` (the bytes Step 0.1 read) for a schema 5 or later inventory and
|
|
91
144
|
from the unsuffixed `pack.json` for schema 1-4,
|
|
92
145
|
against what Step 0.2's deep read already found — a `.claude/settings.json`
|
|
93
|
-
hook fragment merges the same way the baseline's own hook entries would;
|
|
146
|
+
hook fragment merges the same way the baseline's own hook entries would, and when the project already registers the same hook `command` (a pack installed before it gained a key such as `onFailure`), add only the keys the fragment has and the existing registration lacks, keep every field the project already sets, and ask before changing a key both define with a different value (the CLI's `mergeSettingsHooks` never overwrites one);
|
|
94
147
|
`wiring.settingsTopLevel` is a set of top-level keys (e.g. `statusLine`)
|
|
95
148
|
planted whole, and only when the project doesn't already define that key —
|
|
96
149
|
when it does, show the existing value and ask, since the CLI's own
|
|
97
150
|
`mergeSettingsTopLevel` treats a differing value as a hard error and this
|
|
98
151
|
hand-applied path must not be laxer than the automated one (also check
|
|
99
152
|
`.claude/settings.local.json` and the user's `~/.claude/settings.json`,
|
|
100
|
-
either of which can shadow a project `statusLine`). For `
|
|
153
|
+
either of which can shadow a project `statusLine`). For `statusline`
|
|
101
154
|
specifically, a `statusLine`/`subagentStatusLine` collision is never a
|
|
102
|
-
reason to fail the whole pack install: skip just
|
|
103
|
-
|
|
104
|
-
`subagent-statusline.mjs`
|
|
105
|
-
|
|
106
|
-
|
|
155
|
+
reason to fail the whole pack install: skip just the colliding key and the
|
|
156
|
+
script that renders it (`statusline.mjs` for `statusLine`,
|
|
157
|
+
`subagent-statusline.mjs` for `subagentStatusLine`; `statusline-layout.mjs`
|
|
158
|
+
stays while either remains), install the other key normally, and skip the
|
|
159
|
+
whole pack only when both keys are already set, stating the skip plainly in
|
|
160
|
+
Step 7. The pack is separate from `harness-extras` for exactly this reason,
|
|
161
|
+
so a skipped status line never costs the compaction-handoff hooks or
|
|
162
|
+
`guard-readonly-bash`. For `harness-extras`, `guard-readonly-bash.mjs` imports
|
|
107
163
|
`bin/lib/agent-roster.mjs`: when the project keeps no agents and that file is
|
|
108
164
|
not being installed, skip that one hook too (the pack's `adoptNotes` allow
|
|
109
165
|
it), record it in `round1.dropped` and say in Step 7 that it was skipped and
|
|
@@ -142,9 +198,11 @@ any reason goes into `round1.dropped` with that reason.
|
|
|
142
198
|
`PluginRecommendationContext`: `chosenPacks` is whatever the packs decision
|
|
143
199
|
just above actually landed on (fresh: what `--pack` installed at bootstrap
|
|
144
200
|
time, detectable from the installed files -- e.g. `.changeset/config.json`
|
|
145
|
-
means `publishing`, `.
|
|
146
|
-
(the only marker `plugin-map.ts` actually reads; `
|
|
147
|
-
|
|
201
|
+
means `publishing`, `.claude/skills/watching-pr-checks/SKILL.md` means `github`
|
|
202
|
+
(the only marker `plugin-map.ts` actually reads; the `claude-github` pack's
|
|
203
|
+
`.github/workflows/claude-pr-review.yml` needs no marker, since no plugin
|
|
204
|
+
varies by its presence; `harness-extras` and `statusline` have
|
|
205
|
+
no plugin that varies by their presence, so they need no marker here); adopt: the
|
|
148
206
|
packs Step 0.4(c) confirmed, revised by this step's own `recommendPacks`
|
|
149
207
|
comparison if it changed anything); `hasCustomSkills` is `false` for a fresh
|
|
150
208
|
bootstrap (nothing has authored a skill yet) and, for adopt mode, whatever
|
|
@@ -154,18 +212,45 @@ already-installed pack's skills (e.g. the `github` pack's three);
|
|
|
154
212
|
in the project's root `package.json` (the same read in both modes; a fresh
|
|
155
213
|
bootstrap carries only the baseline's own devDependencies, so no SDK plugin
|
|
156
214
|
is pre-selected there, and a monorepo whose SDK dependency sits only in a
|
|
157
|
-
workspace package is not pre-selected either -- the user can still pick it
|
|
215
|
+
workspace package is not pre-selected either -- the user can still pick it,
|
|
216
|
+
except for an integration, where `recommendIntegrations` does not return it);
|
|
217
|
+
`hasDesignSystem` is `true` when the project already carries its own design
|
|
218
|
+
system: a design-token file (`tokens.css` or `tokens.json`, at the project
|
|
219
|
+
root or under `design/` or `src/`), a CSS file with a Tailwind `@theme` block,
|
|
220
|
+
or an in-house design-system package among its `dependencies`. A bare Tailwind
|
|
221
|
+
config does not count, and a fresh bootstrap is `false`. It only decides
|
|
222
|
+
whether `frontend-design` is pre-selected, since that plugin's skill defaults
|
|
223
|
+
to proposing its own palette and token system. Call
|
|
158
224
|
`recommendPlugins(answers, context)` from `plugin-map.ts`
|
|
159
225
|
(alongside this file, same copy mechanism as `pack-map.ts`) with the
|
|
160
226
|
now-confirmed `InterviewAnswers`, and offer every entry it returns (ten, or
|
|
161
|
-
eleven for the `plugin` kind, whose `plugin-dev` entry comes last
|
|
227
|
+
eleven for the `plugin` kind, whose `plugin-dev` entry comes last, or the
|
|
228
|
+
`frontend` kind, whose `frontend-design` entry comes last) in **one**
|
|
162
229
|
`AskUserQuestion` call holding three multi-select questions (a question
|
|
163
230
|
takes at most four options, so split the list in its fixed order: entries
|
|
164
231
|
1-4, 5-7, and 8 to the last entry, so 8-10 or 8-11), each option pre-selected per its entry's `recommended`
|
|
165
232
|
boolean with its `because` shown as the evidence -- same
|
|
166
233
|
"visible reasoning" principle as every other inference in this skill.
|
|
167
234
|
|
|
168
|
-
|
|
235
|
+
**Integrations (both modes), right after that offer.** Call
|
|
236
|
+
`recommendIntegrations(context)` from the same `plugin-map.ts` with the same
|
|
237
|
+
context. It returns a plugin only when the project's `dependencies` name that
|
|
238
|
+
service's SDK or CLI (for example `@sentry/node`, `@supabase/supabase-js`,
|
|
239
|
+
`prisma`, `wrangler`), so it is usually empty: when it is, say nothing and move
|
|
240
|
+
on. Otherwise offer its entries in one more `AskUserQuestion` call, in the
|
|
241
|
+
table's order, with none pre-selected -- every `recommended` is `false`,
|
|
242
|
+
because these plugins connect Claude to a live account or run unpinned code
|
|
243
|
+
and the user opts in -- and each `because` shown as the evidence, with its
|
|
244
|
+
`prerequisites` beside it (for three of the plugins they include a note that
|
|
245
|
+
the server starts through an unpinned `npx` launch). The tool takes two to four
|
|
246
|
+
options per question, so use as few multi-select questions as fit four options
|
|
247
|
+
each and split evenly across them, never leaving a question with fewer than two
|
|
248
|
+
options (five entries are 3+2, seven are 4+3). A single entry is asked as one
|
|
249
|
+
`Enable / Skip` question instead. Write every entry the user selected into
|
|
250
|
+
`enabledPlugins` and print their install commands and `prerequisites` as
|
|
251
|
+
described below.
|
|
252
|
+
|
|
253
|
+
Write every entry the user selected into `.claude/settings.json`'s
|
|
169
254
|
`enabledPlugins` (`{"<id>": true}` per entry, e.g.
|
|
170
255
|
`"context7@claude-plugins-official": true`) -- additive and entry-by-entry,
|
|
171
256
|
same discipline as the CLI's own `mergeSettingsHooks` (which owns the
|
package/plugin/src/domain-map.ts
CHANGED
|
@@ -88,7 +88,7 @@ export const TYPESCRIPT_DOMAIN_GLOBS = [
|
|
|
88
88
|
* `bin/lib/*.mjs` are typescript-domain globs, so without this list the
|
|
89
89
|
* grader's own rules would be swept by `typescript-guidance` -- wrong,
|
|
90
90
|
* because they encode Claude Code harness guidance. The Claude Code Action
|
|
91
|
-
* workflows (`claude.yml`, and the `github` pack's automated-review
|
|
91
|
+
* workflows (`claude.yml`, and the `claude-github` pack's automated-review
|
|
92
92
|
* `claude-pr-review.yml`) are here for the same reason against
|
|
93
93
|
* `.github/workflows/*.yml`: their trigger, action pin and model choice are
|
|
94
94
|
* Anthropic guidance, not toolchain. Consulted before the typescript list in
|