@monte3l/groundwork 1.0.0-rc.4 → 1.0.0-rc.6

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (61) hide show
  1. package/README.md +20 -5
  2. package/dist/customize-paths.d.ts +51 -15
  3. package/dist/customize-paths.js +32 -13
  4. package/dist/fs-guard.d.ts +2 -2
  5. package/dist/harness/rules.d.ts +2 -1
  6. package/dist/harness/rules.js +3 -1
  7. package/dist/inventory.d.ts +1 -1
  8. package/dist/inventory.js +5 -2
  9. package/dist/plugin.d.ts +12 -12
  10. package/dist/plugin.js +34 -26
  11. package/dist/report.js +74 -10
  12. package/dist/survey/survey-harness.d.ts +10 -2
  13. package/dist/survey/survey-harness.js +90 -4
  14. package/dist/survey/survey-shape.js +6 -3
  15. package/dist/survey/survey-toolchain.js +7 -9
  16. package/dist/survey/types.d.ts +33 -0
  17. package/dist/toolchain/grade.js +6 -7
  18. package/dist/toolchain/rules.d.ts +5 -3
  19. package/dist/toolchain/rules.js +6 -4
  20. package/package.json +1 -1
  21. package/plugin/skills/customize/SKILL.md +73 -408
  22. package/plugin/skills/customize/step-0-reconcile.md +265 -0
  23. package/plugin/skills/customize/step-3-round-1.md +171 -0
  24. package/plugin/src/domain-map.ts +2 -2
  25. package/plugin/src/kind-facet-map.ts +39 -9
  26. package/plugin/src/pack-map.ts +5 -3
  27. package/plugin/src/plugin-map.ts +154 -11
  28. package/templates/core/.claude/agents/Explore.md +1 -1
  29. package/templates/core/.claude/hooks/guard-hub-src-writes.mjs +7 -12
  30. package/templates/core/.claude/hooks/guard-no-commonjs.mjs +3 -2
  31. package/templates/core/.claude/hooks/inject-decision-gate.mjs +7 -7
  32. package/templates/core/.claude/rules/agent-dispatch.md +12 -7
  33. package/templates/core/.claude/rules/src.md +7 -4
  34. package/templates/core/.claude/rules/tests.md +2 -2
  35. package/templates/core/.claude/skills/finishing-work/SKILL.md +4 -3
  36. package/templates/core/.claude/skills/triaging-ci/SKILL.md +2 -2
  37. package/templates/core/.claude/skills/writing-commits/SKILL.md +4 -4
  38. package/templates/core/.prettierignore +1 -0
  39. package/templates/core/CLAUDE.md +28 -15
  40. package/templates/core/README.md +15 -3
  41. package/templates/core/_gitignore +1 -0
  42. package/templates/core/bin/check-exports.mjs +5 -3
  43. package/templates/core/bin/lib/harness-rules.mjs +3 -1
  44. package/templates/core/bin/lib/toolchain-rules.mjs +17 -9
  45. package/templates/core/bin/lint-commit.mjs +215 -10
  46. package/templates/core/tsconfig.base.json +10 -6
  47. package/templates/packs/README.md +25 -13
  48. package/templates/packs/github/files/.github/workflows/claude-pr-review.yml +3 -4
  49. package/templates/packs/github/files/.github/workflows/claude.yml +5 -8
  50. package/templates/packs/github/pack.json +1 -1
  51. package/templates/packs/harness-extras/files/.claude/hooks/guard-readonly-bash.mjs +3 -5
  52. package/templates/packs/harness-extras/files/.claude/hooks/subagent-statusline.mjs +29 -14
  53. package/templates/packs/harness-extras/pack.json +1 -1
  54. package/templates/packs/publishing/files/.github/workflows/release.yml +4 -7
  55. package/templates/packs/publishing/files/bin/pnpm-publish-shim.mjs +4 -14
  56. package/templates/packs/publishing/pack.json +1 -1
  57. package/templates/packs/quality/files/.claude/agents/type-design-analyzer.md +1 -1
  58. package/templates/packs/quality/pack.json +1 -1
  59. package/templates/packs/supply-chain/files/.github/workflows/scorecard.yml +4 -2
  60. package/templates/packs/supply-chain/pack.json +2 -2
  61. package/templates/packs/worktrees/pack.json +1 -1
@@ -0,0 +1,265 @@
1
+ # Step 0 — Reconcile (adopt mode only): detail
2
+
3
+ > Full text of Step 0 from `SKILL.md`. Read this whole file before acting on Step 0, and re-read it after a compaction: a compacted session keeps only the start of `SKILL.md`.
4
+
5
+ Contents:
6
+
7
+ 1. Look for `.groundwork/inventory.json` (fresh vs. interrupted vs. adopt)
8
+ 2. The deep read (the survey is an index, not an interpretation)
9
+ 3. Write the findings back into `.groundwork/adoption-report.md`
10
+ 4. Confirm (one `AskUserQuestion` round: additions, conflicts, packs)
11
+ 5. Record the confirmed decisions to `.groundwork/adoption-decisions.json`
12
+
13
+ ## Step 0 — Reconcile (adopt mode only)
14
+
15
+ 1. Look for `.groundwork/inventory.json`.
16
+ - **Absent, and no `.groundwork/` directory either → this is a fresh
17
+ bootstrap; skip straight to Step 1.** Everything below this step applies
18
+ only when an inventory exists.
19
+ - **Absent, but `.groundwork/` exists → a previous CLI adopt run did not
20
+ complete** (the CLI deletes the old inventory before it stages anything
21
+ and writes the new one last, so no inventory beside a `.groundwork/`
22
+ directory means the run died part-way). **Stop. Never fall through to
23
+ the fresh flow** -- that would run fresh-mode tailoring on an
24
+ established project. Tell the user: "`.groundwork/` is incomplete: a
25
+ previous adopt run did not finish, or `inventory.json` was removed.
26
+ If this project was never adopted (it was bootstrapped fresh), delete
27
+ `.groundwork/` and run `/customize` again. Otherwise re-run
28
+ `npx @monte3l/groundwork@rc .` and then run `/customize` again."
29
+ Change nothing.
30
+ - **Present, but not valid JSON, or its `schemaVersion` is not an integer
31
+ of at least 1 → stop and change nothing.** Tell the user: "`.groundwork/inventory.json`
32
+ is not valid JSON or has no usable `schemaVersion`. Re-run
33
+ `npx @monte3l/groundwork@rc .` and then run `/customize` again."
34
+
35
+ **Check `inventory.schemaVersion` before reading anything else.** This
36
+ skill understands schema versions **1 through 6** (the highest it knows is
37
+ 6). If `schemaVersion` is **higher than 6**, the CLI that wrote it is newer
38
+ than this plugin: **stop and change nothing**, do not interpret the
39
+ inventory (a newer schema may have renamed or repurposed fields, and a
40
+ confident misreading is worse than none), and tell the user to update the
41
+ plugin and re-run `/customize`. Say which update applies to the copy
42
+ that is running. For the plugin install, run `/plugin update`. For a
43
+ project-local copy in `.claude/skills/customize/`, `/plugin update` does
44
+ not touch it, and re-running the CLI alone does not either: the CLI
45
+ never overwrites a copy that differs (nor removes any other entry the
46
+ project owns there, nor writes through a symlinked `.claude`), it writes a
47
+ fresh one to `.groundwork/customize/`, which Claude Code does not load. So delete
48
+ that directory first (this discards any local edits the project made to
49
+ its copy) and then re-run `npx @monte3l/groundwork@rc .`. A
50
+ copy in `.groundwork/customize/` is refreshed by re-running the CLI. What
51
+ each version added:
52
+
53
+ | `schemaVersion` | Adds | If absent |
54
+ | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
55
+ | 1 | the survey, `conflicts` | (the floor) |
56
+ | 2 | `packs` | no packs to offer; skip the pack question |
57
+ | 3 | `harnessGrade`, `harnessConformance` | skip the harness-grade starting point |
58
+ | 4 | `toolchainGrade`, `toolchainConformance` | skip the toolchain-grade starting point |
59
+ | 5 | `stagedBaseline` (`{ dir, suffix, files }`): the baseline additions staged at `.groundwork/baseline/`, each as `{ path, staged, sha256 }`; `stagedPacks` (per pack: `{ name, dir, suffix, manifest, files }`): every pack staged at `.groundwork/packs/<name>/`, its manifest and each file as `{ path, staged, sha256 }` | schema 1-4 only: read baseline additions from `inventory.templateRoot`; packs use the unsuffixed copy under `.groundwork/packs/` |
60
+ | 6 | `survey.harness.pluginLayout`: `null`, or `{ manifest, components }` when the project root holds `.claude-plugin/plugin.json` (`components` lists which of `hooks/hooks.json`, `skills/`, `agents/`, `commands/`, `.mcp.json` exist) | no plugin-layout evidence; ask the project kind cold rather than pre-selecting one |
61
+
62
+ **For a schema 5 or later inventory: verify the staged baseline now, before
63
+ anything is offered to the user.** A schema 1-4 inventory has no
64
+ `stagedBaseline`: skip this whole block (every bullet below, including
65
+ its stop list) and use the `inventory.templateRoot` fallback in Round 1.
66
+ The inventory lives in the project tree and is untrusted input, so check
67
+ it before trusting any entry:
68
+
69
+ - `stagedBaseline.dir` must equal `.groundwork/baseline` exactly, and
70
+ `stagedBaseline.suffix` must equal `.staged` exactly. Take both values
71
+ from this list, not from the inventory: a `dir` of `.` with an empty
72
+ `suffix` would make you "verify" live project files.
73
+ - For every entry of `inventory.stagedBaseline.files`, require
74
+ `staged === path + ".staged"`, and require `path` to be relative, free
75
+ of any `..` segment, and not absolute. Reject the entry if `path` is
76
+ `""` or `"."`. Reject it too if `path` contains a `\` or a `:` (a
77
+ Windows `..\..` or `C:foo` would slip past the other checks). Reject a
78
+ duplicate `path` or a duplicate `staged` among the entries. These fields
79
+ use `/` separators on every platform: `conflicts[].relPath`,
80
+ `packs[].fileConflicts[].relPath`, `stagedBaseline.dir`,
81
+ `stagedBaseline.files[].path` and its `.staged` name, `stagedPacks[].dir`,
82
+ `stagedPacks[].files[].path` and `stagedPacks[].files[].staged`. Other paths in
83
+ the inventory are not normalized: `templateRoot` and `targetDir` are
84
+ absolute native paths, as are the survey's tsconfig chain entries.
85
+ - The `absent` conflicts in `inventory.conflicts` and the paths in
86
+ `stagedBaseline.files` must name the same set of files. If they
87
+ disagree (an `absent` conflict with no staged entry, or a staged entry
88
+ that is not an `absent` conflict), that is a mismatch: stop, with the
89
+ same message as a hash mismatch, before anything is offered or approved.
90
+ - Read each staged file at `.groundwork/baseline/<staged>` **once**.
91
+ It must exist, and the SHA-256 of its **raw bytes** (no end-of-line
92
+ normalization, no decoding) must equal the entry's `sha256`. Compute it
93
+ with, for example, this one-liner (it targets a POSIX shell or Git Bash,
94
+ not `cmd.exe` or an old PowerShell), passing the file as a single quoted
95
+ argument in place of `<file>`:
96
+ `node -e 'process.stdout.write(require("crypto").createHash("sha256").update(require("fs").readFileSync(process.argv[1])).digest("hex"))' <file>`
97
+ Keep those same bytes for the install in Round 1 (substitute tokens into
98
+ them) rather than reading the file a second time.
99
+ - **Staged packs, in the same block.** For every entry of
100
+ `inventory.stagedPacks`:
101
+ - `dir` must equal `.groundwork/packs/<name>`, built from the entry's
102
+ own `name`, and `suffix` must equal `.staged`. Take both from this
103
+ list, not from the inventory.
104
+ - `name` must be a single path segment: not empty, not `.` or `..`, and
105
+ free of `/`, `\` and `:`. Reject a duplicate pack `name`.
106
+ - `manifest.path` must equal `pack.json` and `manifest.staged` must
107
+ equal `pack.json.staged`.
108
+ - For every entry of its `files`, require `staged === path + ".staged"`,
109
+ and apply the same path checks as the staged baseline's files above
110
+ (relative, no `..` segment, not absolute, not `""` or `"."`, no `\` or
111
+ `:`). Reject a duplicate `path` or a duplicate `staged` among one
112
+ pack's files.
113
+ - The pack names in `inventory.packs` and in `inventory.stagedPacks`
114
+ must be the same set, and for each pack its `fileConflicts[].relPath`
115
+ set must equal its `files[].path` set.
116
+ - Read the staged manifest at `<dir>/pack.json.staged` and each staged
117
+ file at `<dir>/files/<staged>` once, and apply the SHA-256 check above
118
+ to the raw bytes of each. Keep the bytes Step 0.1 read (hash-checked
119
+ when a command could run): Round 1's install and the prototype-key
120
+ check in Step 0.4(c) use them, with no second read.
121
+ - **No shell tool available.** If a Bash or other command-running tool is
122
+ available, compute the hash as above. If you cannot run a command, do
123
+ not work around it: write no scratch script; while verifying, make no
124
+ `Write` or `Edit` outside `.groundwork/` (Round 1's confirmed installs are
125
+ not part of verification), dispatch no subagent to look for a shell, and
126
+ search for a command tool at most once. Skip only the SHA-256
127
+ comparison. Run every other check in this block with the file tools
128
+ (`Read`, `Glob`, `Grep`): the files exist, `staged === path + ".staged"`,
129
+ the paths are relative with no `..`, `\` or `:`, no duplicates, `dir`
130
+ and `suffix` exact, the `absent` conflicts and `stagedBaseline.files`
131
+ name the same set, and no extra staged file exists: list the staged
132
+ files with the `Glob` pattern `.groundwork/baseline/**/*.staged` and
133
+ compare with `stagedBaseline.files`. A `Glob` can skip hidden paths
134
+ (most staged files are dot-paths), honour an ignore file or truncate a
135
+ long list, so a result shorter than `stagedBaseline.files.length`, or
136
+ that looks truncated, is undetermined: report it in the Step 0.4 summary
137
+ and continue, since every listed entry's existence is already checked
138
+ one by one; only an extra `*.staged` file, one whose path is not in
139
+ `stagedBaseline.files`, stops the run. Run the same structural checks
140
+ for `inventory.stagedPacks`: each pack's `<dir>/pack.json.staged` and
141
+ every `<dir>/files/<staged>` exists, `staged === path + ".staged"` with
142
+ paths that are relative and free of `..`, `\` and `:`, no duplicates,
143
+ `name`, `dir`, `suffix`, `manifest.path` and `manifest.staged` exact,
144
+ the pack names in `inventory.packs` and `inventory.stagedPacks` the
145
+ same set, and each pack's `fileConflicts[].relPath` and `files[].path`
146
+ the same set. List each pack's staged files with the `Glob` pattern
147
+ `.groundwork/packs/**/*.staged` (the same hidden-path and
148
+ truncation caveats apply) and compare with every listed manifest and
149
+ file: an extra `*.staged` file at any depth under `.groundwork/packs/` that is neither a listed manifest nor a listed file stops the run. This is a partial no-shell
150
+ substitute for what the hash proves, and it is not tamper-resistance.
151
+ Then spend no further turns on verification and go on to the deep
152
+ read. State this plainly at the top of your first message to the user (the Step 0.4 summary, not a
153
+ separate earlier stop), and ask whether to continue or stop in that
154
+ same confirmation: the SHA-256 check was skipped because no command
155
+ could be run; a passing check would only have proven that the staging
156
+ is complete and matches the inventory, not that the files are
157
+ untampered; and which structural checks you did verify instead. Also
158
+ record the skip in `.groundwork/adoption-report.md` when you write the
159
+ findings back in Step 0.3. A structural failure, including an extra staged file, still stops, exactly as the stop list below says.
160
+ - An empty `files` list is legitimate (nothing was missing from the
161
+ project) and creates no `.groundwork/baseline/` directory; that alone is
162
+ not a failure.
163
+ - **For a schema 5 or later inventory, a `stagedBaseline` that is missing, not an
164
+ object, or whose `files` is not an array also stops the run** (a
165
+ `files: {}` is not an empty list); so does a `stagedPacks` that is
166
+ missing or not an array, or a pack entry that is not an object or whose
167
+ `files` is not an array. **Any invalid entry, missing file or hash mismatch (including a
168
+ wrong `dir` or `suffix`), any duplicate `staged` or `path` or pack `name`, any
169
+ `absent` conflicts and `stagedBaseline.files` that do not name the same
170
+ set, any pack whose names or file paths disagree with `inventory.packs`, and
171
+ (no-shell path) an extra `*.staged` file not named in
172
+ `stagedBaseline.files`, a pack's `files` or a pack's manifest
173
+ means stop -- all of Round 1, including conflicts and packs -- and
174
+ change nothing.** This is the single stop list for the staged baseline and the staged packs.
175
+ Tell the user: "The staged baseline in `.groundwork/baseline/` or a staged pack in `.groundwork/packs/` is incomplete or does not match `.groundwork/inventory.json` (<the first entry that failed and why>). Re-run `npx @monte3l/groundwork@rc .` and then run `/customize` again." **Never fall back to `inventory.templateRoot` for a schema 5 or later inventory, packs included:** that fallback exists for a schema 1-4 inventory only, and only for the baseline additions (a schema 1-4 inventory's packs are read from their unsuffixed copy, see Step 0.4(c) and Round 1).
176
+ - What a passing check proves: the staging is complete and matches the
177
+ inventory. It does **not** prove the files are untampered -- anyone who
178
+ can edit the staged files can edit the inventory's hashes too.
179
+
180
+ An inventory with `schemaVersion` below 5 has no staged copy; its
181
+ approved additions are read from `inventory.templateRoot` (see Round 1).
182
+
183
+ 2. **The deep read.** The CLI's survey is an index, not an interpretation —
184
+ it flagged what it found but could not parse (`needsReading: true` on
185
+ git-hook config, workflow files; anything in `survey.undetermined`) and
186
+ what it could only index, not summarize (`docs`). Read all of it for
187
+ real: the eslint config, the git-hook manager's actual stage commands,
188
+ the CI workflow job steps, `CLAUDE.md`, `CONTRIBUTING.md`, and any
189
+ docs/ADR files the survey indexed. Dispatch this as parallel read-only
190
+ `Explore` agents, one per discovery area (shape/toolchain, harness, docs),
191
+ so you aggregate their findings rather than reading everything yourself.
192
+ The harness agent also reads `survey.harness.pluginLayout` (schema 6): a
193
+ project with a `.claude-plugin/plugin.json` ships hooks, skills and agents
194
+ at the repository root, which the harness grade below does not cover, so
195
+ read those too. It starts from `inventory.harnessGrade` (the report's
196
+ `## Harness grade` section): a deterministic, offline check of the
197
+ existing `.claude/` wiring. Its **wiring findings** (a hook registration
198
+ naming a missing file, a skill or agent with unreadable frontmatter, a
199
+ `CLAUDE.md` path that no longer exists) are facts to verify against the
200
+ real files, not verdicts to take on trust. Its **quality findings** are
201
+ advisory. `inventory.harnessConformance` counts how far the harness has
202
+ drifted from the baseline's — information only, since divergence from the
203
+ baseline is the point of adopting. An inventory with `schemaVersion` below
204
+ 3 carries neither field; skip this and continue.
205
+
206
+ The toolchain agent likewise starts from `inventory.toolchainGrade` (the
207
+ report's `## Toolchain grade` section): a deterministic, offline check of
208
+ the tsconfig chain, ESLint and vitest config, verify-step wiring, and
209
+ toolchain pins. It reads files and never runs them, and it reads
210
+ `eslint.config.js`/`vitest.config.ts` by pattern rather than by evaluating
211
+ them -- so a **wiring finding** (a build project that emits nowhere, a
212
+ verify step naming a script or file that does not exist, a `.node-version`
213
+ that contradicts `engines.node`) is a fact to verify against the real files,
214
+ and a **quality finding** (a missing strict flag, an option TypeScript has
215
+ deprecated, ESLint without type-aware linting, a coverage gate that is not
216
+ per-file) is advisory. Absence is never a finding: a project with no vitest
217
+ config simply has no coverage-gate line. `inventory.toolchainConformance`
218
+ counts drift from the baseline's toolchain files -- information only. An
219
+ inventory with `schemaVersion` below 4 carries neither field; skip this and
220
+ continue.
221
+
222
+ 3. **Write the findings back** into `.groundwork/adoption-report.md`,
223
+ replacing the CLI's index-level sections ("a `lefthook.yml` exists")
224
+ with semantic ones ("pre-push runs lint and typecheck; tests do not
225
+ gate"). If the no-shell bullet in step 1 applied, carry its skip note
226
+ into the rewritten report: this step replaces the report's sections, so
227
+ a note written earlier would be dropped.
228
+ 4. **Confirm.** Give a short summary in chat, then ask **one**
229
+ `AskUserQuestion` covering: (a) _did this miss anything about your
230
+ project?_ — the free-text option is the point of this question, not a
231
+ formality — (b) the conflict resolutions from the inventory's conflict
232
+ table, batched by facet (toolchain config, harness) rather than one
233
+ question per file (the harness facet's batch also carries any wiring
234
+ findings you confirmed in the deep read, offered as fixes to make, and the
235
+ toolchain facet's batch does the same for confirmed toolchain wiring findings) — and
236
+ (c) **which pack(s) to install**, from `inventory.packs`. For each pack, show its `budget`, its
237
+ `wiringObservations` (facts about how it would land — e.g. "no
238
+ `bin/lib/verify-steps.packs.json` found: no `bin/verify.mjs`-shaped gate
239
+ runner detected", or "`.claude/settings.json` already sets a top-level
240
+ `statusLine`"), and its `adoptNotes` verbatim; a pack whose gate
241
+ dependency the project doesn't have is still offered for its other
242
+ artifacts, with that limitation stated plainly rather than silently
243
+ dropped. This is index-level evidence from the CLI, not a kind-based
244
+ judgment — see Step 3's note on revisiting it once the interview confirms
245
+ the project's kind.
246
+
247
+ The same question also carries (d) if the no-shell bullet applied: say the
248
+ SHA-256 check was skipped, what a passing check would have proven,
249
+ which checks ran instead and any undetermined result, and
250
+ ask whether to continue or stop.
251
+
252
+ Before offering any pack, check each staged `.groundwork/packs/<name>/pack.json.staged` (the bytes Step 0.1 read, hash-checked when a command could run; not a fresh read):
253
+ if `__proto__`, `constructor` or `prototype` is a key of its `wiring.settings`
254
+ (hook event names), `wiring.settingsTopLevel` or `wiring.packageScripts`
255
+ (script names), stop. The project tree is untrusted, and the CLI refuses such a
256
+ pack before staging it, so a staged manifest carrying one was edited after
257
+ staging. Name the pack, the field and the key, tell the user to delete
258
+ `.groundwork/` and re-run the CLI, and offer nothing from this run. Change nothing.
259
+ For a schema 1-4 inventory (the layout of the CLI releases before the `.staged` convention) there is no `.staged` copy and no hash: read the unsuffixed `.groundwork/packs/<name>/pack.json` (not hash-verified) and run this same prototype-key check on it.
260
+
261
+ 5. **Record the confirmed decisions** to `.groundwork/adoption-decisions.json`
262
+ so a compacted or resumed session doesn't silently lose them and re-ask.
263
+ A CLI re-run deletes this file along with the old inventory, because its
264
+ decisions were made against the previous staging; a decisions file found
265
+ beside a fresh inventory therefore belongs to this inventory.
@@ -0,0 +1,171 @@
1
+ # Step 3 — Round 1: deterministic tailoring: detail
2
+
3
+ > Full text of Step 3 from `SKILL.md`. Read this whole file before applying Round 1's edits, and re-read it after a compaction: a compacted session keeps only the start of `SKILL.md`.
4
+
5
+ ## Step 3 — Round 1: deterministic tailoring
6
+
7
+ **Fresh bootstrap** applies directly, no research needed:
8
+
9
+ - **Project kind ≠ library**: if `check:exports` (publint/attw) doesn't
10
+ apply to the chosen kind (CLI, frontend, service, plugin), remove the
11
+ `check:exports` step from `bin/lib/verify-steps.mjs` and the
12
+ corresponding `.github/workflows/ci.yml` line, and drop the `exports`
13
+ field from `package.json` in favor of a `bin` field (CLI) or leave `main`/
14
+ no public export map at all (service, plugin).
15
+ - **Runtime target = browser or both**: note that `tsconfig.base.json`'s
16
+ `lib` and `moduleResolution` will very likely need to change — but leave
17
+ the actual edit to Round 2's `typescript-guidance` sweep, which has full
18
+ authority over that file and access to current bundler-resolution
19
+ guidance you don't have without a live source.
20
+ - **Tests mandatory = warn only**: change the `test` lane in `lefthook.yml`
21
+ and `ci.yml` from a hard failure to a non-blocking report.
22
+ - **CI depth = minimal**: drop the `test` lane's coverage gate from CI
23
+ (still run locally); minimal keeps only format/lint/typecheck/build.
24
+ **CI depth = thorough**: note this for Round 2 — `harness-guidance` may
25
+ recommend additional current-best-practice lanes (e.g. a scheduled
26
+ dependency audit) beyond what the baseline ships.
27
+ - **Agents not kept**: delete their `.claude/agents/<name>.md` file. Never
28
+ delete `Explore`, `test-author`, or `code-implementer` even if unselected
29
+ — they're load-bearing for the hub-and-spoke loop `CLAUDE.md` documents.
30
+ - **Packs**: nothing to do here. A fresh bootstrap's packs were installed
31
+ (or not) by the CLI at `m3l-groundwork <dir> --pack <name>` invocation
32
+ time, before this skill ever ran — there is no fresh-mode install path in
33
+ `/customize` itself. To add a pack after the fact, re-run the CLI against
34
+ this now-non-empty directory (it auto-detects adopt mode) and run
35
+ `/customize` again; its Step 0 will offer the pack through the adopt path
36
+ below.
37
+
38
+ **Adopt mode** re-expresses each of the same five outcomes against whatever
39
+ the project actually has, instead of a named baseline path — "tests must not
40
+ hard-fail `pre-push`" is applied to _the gate the inventory found_ (jest in
41
+ CI, husky locally, whatever it is), not to `lefthook.yml`/`ci.yml` by name.
42
+ Concretely, adopt-mode Round 1 applies exactly three things, all already
43
+ confirmed in Step 0.4:
44
+
45
+ - The **approved additions** — files `templates/core` would add that the
46
+ project doesn't have and the user approved adding. For a schema 5 or later inventory, install them from the staged copy Step 0.1 already verified,
47
+ using the bytes you read then (Step 0.1 also already checked that the
48
+ staged files match the `absent` conflicts). Write them to the project at `path` (the
49
+ `.staged` suffix stripped, never to the staged name), filling in the
50
+ `__KEY__` tokens with the project's real values as you copy, same as
51
+ staged packs. Only a **schema 1-4** inventory has no staged copy and reads
52
+ additions from `inventory.templateRoot`; if that path no longer exists (a
53
+ pruned `npx` cache, a deleted temp checkout), say so and ask for a CLI
54
+ re-run rather than guessing at the baseline's contents.
55
+ - The **approved conflict resolutions** — for each divergent file the user
56
+ decided on, apply that decision (keep theirs / take groundwork's / merge
57
+ the named keys).
58
+ - The **approved packs** — installed from `.groundwork/packs/<name>/` (the
59
+ CLI's staged, self-contained copy of inert `.staged` files — never
60
+ `inventory.templateRoot`, which may not exist by the time this runs). Before installing, call
61
+ `recommendPacks(answers)` from `pack-map.ts` (alongside this file, same
62
+ copy mechanism as `kind-facet-map.ts`) with the now-confirmed
63
+ `InterviewAnswers` and compare its verdict against Step 0.4's decision.
64
+ `harness-extras`, `github`, `supply-chain`, `quality`, and `worktrees`
65
+ never disagree (none of the five's recommendation varies by kind or
66
+ answer -- `worktrees` is always `recommended: false`, since it changes the
67
+ day-to-day workflow rather than adding a nicety, and the other four are
68
+ always `recommended: true`), but `publishing`'s does (recommended for
69
+ `library`/`cli`, not for `frontend`/`service`) — if the comparison surfaces a real
70
+ conflict there or for any future kind-scoped pack, raise it rather than
71
+ silently overriding the user's Step 0.4 answer, mirroring Step 4's "the
72
+ one exception" rule for guidance findings. Before installing, check the
73
+ pack's own `modes`: a pack whose `modes` doesn't include `"adopt"` (today,
74
+ `publishing` — its release flow encodes decisions too project-specific to
75
+ apply blind) is never auto-installed here even if staged and approved;
76
+ 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
+ there for that pack. Before merging any staged `pack.json.staged` wiring, repeat
78
+ the prototype-key check from Step 0.4(c): if a key of `wiring.settings`,
79
+ `wiring.settingsTopLevel` or `wiring.packageScripts` is `__proto__`,
80
+ `constructor` or `prototype`, stop the same way and change nothing. For an
81
+ adopt-capable pack, install each file from
82
+ `.groundwork/packs/<name>/files/<path>.staged`, using the bytes Step 0.1 read (hash-checked when a command could run), and write it to the project at `path` (the `.staged` suffix
83
+ stripped, never to the staged name), filling in the `__KEY__` tokens with
84
+ the project's real values as you copy (respecting any approved per-file
85
+ conflict decision the same way the baseline's own additions are applied).
86
+ For a schema 1-4 inventory, install each file from the unsuffixed
87
+ `.groundwork/packs/<name>/files/<path>` instead (no `.staged` suffix to strip,
88
+ not hash-verified; token substitution still applies).
89
+ Then, for either schema, translate `pack.json`'s `wiring` by hand, reading it
90
+ from `pack.json.staged` (the bytes Step 0.1 read) for a schema 5 or later inventory and
91
+ from the unsuffixed `pack.json` for schema 1-4,
92
+ 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;
94
+ `wiring.settingsTopLevel` is a set of top-level keys (e.g. `statusLine`)
95
+ planted whole, and only when the project doesn't already define that key —
96
+ when it does, show the existing value and ask, since the CLI's own
97
+ `mergeSettingsTopLevel` treats a differing value as a hard error and this
98
+ hand-applied path must not be laxer than the automated one (also check
99
+ `.claude/settings.local.json` and the user's `~/.claude/settings.json`,
100
+ either of which can shadow a project `statusLine`). For `harness-extras`
101
+ specifically, a `statusLine`/`subagentStatusLine` collision is never a
102
+ reason to fail the whole pack install: skip just those two settings keys
103
+ and the three statusline scripts (`statusline.mjs`, `statusline-layout.mjs`,
104
+ `subagent-statusline.mjs`) and install the pack's other artifacts (the
105
+ compaction-handoff hooks and `guard-readonly-bash`) normally, stating the
106
+ skip plainly in Step 7;
107
+ `wiring.verifySteps` becomes a step in whatever this project's real gate
108
+ runner is (a `package.json` script plus a line in its `lefthook.yml`/
109
+ `.husky/pre-push`/CI workflow, written by hand to match its actual shape)
110
+ — or, if the project has no such gate runner at all, install the pack's
111
+ other artifacts and state plainly in Step 7 that the gate was not wired,
112
+ rather than inventing a runner the project never asked for.
113
+
114
+ **Plugins (both modes), after packs are settled above.** Build a
115
+ `PluginRecommendationContext`: `chosenPacks` is whatever the packs decision
116
+ just above actually landed on (fresh: what `--pack` installed at bootstrap
117
+ time, detectable from the installed files -- e.g. `.changeset/config.json`
118
+ means `publishing`, `.github/workflows/claude-pr-review.yml` means `github`
119
+ (the only marker `plugin-map.ts` actually reads; `harness-extras` has no
120
+ plugin that varies by its presence, so it needs no marker here); adopt: the
121
+ packs Step 0.4(c) confirmed, revised by this step's own `recommendPacks`
122
+ comparison if it changed anything); `hasCustomSkills` is `false` for a fresh
123
+ bootstrap (nothing has authored a skill yet) and, for adopt mode, whatever
124
+ Step 0's survey found beyond the baseline's own known skill names and any
125
+ already-installed pack's skills (e.g. the `github` pack's three);
126
+ `dependencies` is the key names under `dependencies` and `devDependencies`
127
+ in the project's root `package.json` (the same read in both modes; a fresh
128
+ bootstrap carries only the baseline's own devDependencies, so no SDK plugin
129
+ is pre-selected there, and a monorepo whose SDK dependency sits only in a
130
+ workspace package is not pre-selected either -- the user can still pick it). Call
131
+ `recommendPlugins(answers, context)` from `plugin-map.ts`
132
+ (alongside this file, same copy mechanism as `pack-map.ts`) with the
133
+ now-confirmed `InterviewAnswers`, and offer every entry it returns (ten, or
134
+ eleven for the `plugin` kind, whose `plugin-dev` entry comes last) in **one**
135
+ `AskUserQuestion` call holding three multi-select questions (a question
136
+ takes at most four options, so split the list in its fixed order: entries
137
+ 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`
138
+ boolean with its `because` shown as the evidence -- same
139
+ "visible reasoning" principle as every other inference in this skill.
140
+
141
+ Write every confirmed `true` entry into `.claude/settings.json`'s
142
+ `enabledPlugins` (`{"<id>": true}` per entry, e.g.
143
+ `"context7@claude-plugins-official": true`) -- additive and entry-by-entry,
144
+ same discipline as the CLI's own `mergeSettingsHooks` (which owns the
145
+ `hooks` block entry-by-entry, as opposed to `mergeSettingsTopLevel`'s
146
+ whole-key-at-a-time semantics): never remove or flip an entry the project
147
+ already sets explicitly (an existing `false` is a decision the user made,
148
+ not an oversight to correct), and never touch `.claude/settings.local.json`
149
+ or the user's own `~/.claude/settings.json` scope. `claude-plugins-official`
150
+ is a built-in marketplace, so no `extraKnownMarketplaces` entry is needed
151
+ for any entry.
152
+
153
+ **Committing this entry does not install the plugin for anyone.** A
154
+ project-scope `enabledPlugins: true` with no local install produces no
155
+ folder-trust auto-prompt -- Claude Code's `/plugin` Errors tab instead shows
156
+ "enabled in project settings but isn't installed here" until someone runs
157
+ the install by hand. So for every newly-`true` entry, print the exact
158
+ follow-up command in Step 7's report: `claude plugin install <id> --scope
159
+ project` (or `/plugin install <id>` inside a running session) -- the user,
160
+ and every collaborator who pulls this change, still has to run it once. Do
161
+ the same for each recommendation's `prerequisites` (the
162
+ `typescript-language-server` binary, or the Python version a plugin names) --
163
+ print them as
164
+ follow-ups, never attempt to install them.
165
+
166
+ Nothing else is touched. A project file the user didn't approve a change to
167
+ stays exactly as it was.
168
+
169
+ Run `pnpm verify` (fresh) or the project's own equivalent (adopt) after
170
+ Round 1's edits to confirm the tailored result still passes before moving to
171
+ Round 2.
@@ -9,8 +9,8 @@
9
9
  * harness against official Anthropic sources. Each sweep covers a fixed set of
10
10
  * "facets" (research topics within its domain, such as `compiler-config-flags`
11
11
  * or `hooks-lifecycle`); the interview's project "kind" (a `ProjectKind`: the
12
- * archetype -- library, cli, frontend or service -- the project is classified
13
- * as) only changes which facets get the most emphasis, never which files a
12
+ * archetype -- library, cli, frontend, service or plugin -- the project is
13
+ * classified as) only changes which facets get the most emphasis, never which files a
14
14
  * sweep owns. This module answers the file-ownership question.
15
15
  *
16
16
  * Used two ways: against the emitted baseline, to confirm neither sweep has a
@@ -6,7 +6,9 @@
6
6
  * research priority. Three terms recur throughout this file:
7
7
  *
8
8
  * - A "kind" is a `ProjectKind`: the project archetype the interview
9
- * classifies the project as (library, cli, frontend or service).
9
+ * classifies the project as (library, cli, frontend, service or plugin --
10
+ * a Claude Code plugin repo shipped through a marketplace manifest, not
11
+ * npm).
10
12
  * - A "guidance sweep" is the live research pass `/customize` runs over
11
13
  * official TypeScript and Anthropic sources, once per domain (TypeScript
12
14
  * toolchain, Claude Code harness).
@@ -29,7 +31,7 @@
29
31
  * research agent digs into deepest.
30
32
  */
31
33
 
32
- export type ProjectKind = "library" | "cli" | "frontend" | "service";
34
+ export type ProjectKind = "library" | "cli" | "frontend" | "service" | "plugin";
33
35
  export type RuntimeTarget = "node" | "browser" | "both";
34
36
  export type CiDepth = "minimal" | "standard" | "thorough";
35
37
 
@@ -71,36 +73,64 @@ export interface FacetPlan {
71
73
  readonly harness: readonly FacetEmphasis<HarnessFacetId>[];
72
74
  }
73
75
 
76
+ /**
77
+ * One kind's TypeScript emphasis. `packaging` and `lint` are separate fields
78
+ * because a kind can de-emphasize one without the other: a `plugin` ships
79
+ * through a marketplace manifest, so its packaging facet has little to say,
80
+ * while its lint facet matters as much as any other kind's.
81
+ */
74
82
  interface KindEmphasis {
75
83
  readonly configModules: string;
76
- readonly packagingLint: string;
84
+ readonly packaging: string;
85
+ readonly lint: string;
77
86
  readonly testing: string;
78
87
  }
79
88
 
89
+ /**
90
+ * The four original kinds emphasize one shared packaging-and-lint text for
91
+ * both facets; only `plugin` splits them.
92
+ */
93
+ function packagingAndLint(
94
+ text: string,
95
+ ): Pick<KindEmphasis, "packaging" | "lint"> {
96
+ return { packaging: text, lint: text };
97
+ }
98
+
80
99
  const TYPESCRIPT_EMPHASIS_BY_KIND: Record<ProjectKind, KindEmphasis> = {
81
100
  library: {
82
101
  configModules: "nodenext resolution, declaration emit",
83
- packagingLint:
102
+ ...packagingAndLint(
84
103
  "isolatedDeclarations, exports-map correctness, ESM-only vs dual, typed-lint preset for a published API",
104
+ ),
85
105
  testing: "Node-process testing, type-level assertions",
86
106
  },
87
107
  cli: {
88
108
  configModules: "Node runtime target, bin field and shebang packaging",
89
- packagingLint: "packaging for an executable, typed-lint preset",
109
+ ...packagingAndLint("packaging for an executable, typed-lint preset"),
90
110
  testing: "process/stdio testing",
91
111
  },
92
112
  frontend: {
93
113
  configModules: "bundler resolution, lib/DOM types for a bundled target",
94
- packagingLint:
114
+ ...packagingAndLint(
95
115
  "bundler-driven vs tsc-driven emit, typed-lint preset for JSX/component code",
116
+ ),
96
117
  testing: "browser mode vs jsdom, component testing",
97
118
  },
98
119
  service: {
99
120
  configModules:
100
121
  "Node module resolution and runtime target, no declaration emit",
101
- packagingLint: "emit for a deployed server, typed-lint preset",
122
+ ...packagingAndLint("emit for a deployed server, typed-lint preset"),
102
123
  testing: "integration-test isolation",
103
124
  },
125
+ plugin: {
126
+ configModules:
127
+ "Node runtime target for hook and mod scripts run from source, no declaration emit",
128
+ packaging:
129
+ "marketplace manifest and plugin.json correctness; no npm publish, so packaging is de-emphasized",
130
+ lint: "typed-lint preset for hook, mod and script code",
131
+ testing:
132
+ "hook stdin/stdout contract testing, skill and manifest validation",
133
+ },
104
134
  };
105
135
 
106
136
  function runtimeEmphasis(runtime: RuntimeTarget): string {
@@ -158,9 +188,9 @@ export function planFacets(answers: InterviewAnswers): FacetPlan {
158
188
  },
159
189
  {
160
190
  facetId: "packaging-declaration-emit",
161
- emphasis: kindEmphasis.packagingLint,
191
+ emphasis: kindEmphasis.packaging,
162
192
  },
163
- { facetId: "lint-typing-rules", emphasis: kindEmphasis.packagingLint },
193
+ { facetId: "lint-typing-rules", emphasis: kindEmphasis.lint },
164
194
  { facetId: "testing-language-features", emphasis: kindEmphasis.testing },
165
195
  ];
166
196
 
@@ -82,8 +82,9 @@ function recommendGithub(): PackRecommendation {
82
82
  * Scorecard are not part of it -- they are the separate `supply-chain` pack,
83
83
  * since they apply to any repo, published or not. A `library` or `cli`
84
84
  * typically publishes an npm package; a
85
- * `frontend` or `service` is typically deployed instead, so it is not
86
- * pre-selected there -- but it stays on offer. It is fresh-mode only and
85
+ * `frontend` or `service` is typically deployed instead, and a `plugin`
86
+ * ships through a marketplace manifest, so it is not pre-selected for those
87
+ * three -- but it stays on offer. It is fresh-mode only and
87
88
  * needs one-time npm and GitHub setup the pack cannot perform itself.
88
89
  */
89
90
  function recommendPublishing(answers: InterviewAnswers): PackRecommendation {
@@ -100,7 +101,8 @@ function recommendPublishing(answers: InterviewAnswers): PackRecommendation {
100
101
  "supply-chain pack. It is fresh-mode only and needs one-time npm and GitHub setup (the " +
101
102
  "trusted publisher, the release credentials) the pack cannot do " +
102
103
  "itself."
103
- : "a frontend or service is typically deployed rather than published " +
104
+ : "a frontend or service is typically deployed, and a Claude Code " +
105
+ "plugin ships through a marketplace manifest, rather than published " +
104
106
  "to a package registry, so a changesets/npm release pipeline is not " +
105
107
  "recommended by default -- it is still available if this project " +
106
108
  "does publish an npm package.",