@monte3l/groundwork 1.0.0-rc.5 → 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 (40) hide show
  1. package/README.md +20 -5
  2. package/dist/inventory.d.ts +1 -1
  3. package/dist/inventory.js +5 -2
  4. package/dist/report.js +74 -10
  5. package/dist/survey/survey-harness.d.ts +10 -2
  6. package/dist/survey/survey-harness.js +90 -4
  7. package/dist/survey/survey-shape.js +6 -3
  8. package/dist/survey/survey-toolchain.js +7 -9
  9. package/dist/survey/types.d.ts +33 -0
  10. package/dist/toolchain/grade.js +6 -7
  11. package/dist/toolchain/rules.d.ts +5 -3
  12. package/dist/toolchain/rules.js +6 -4
  13. package/package.json +1 -1
  14. package/plugin/skills/customize/SKILL.md +40 -5
  15. package/plugin/skills/customize/step-0-reconcile.md +10 -6
  16. package/plugin/skills/customize/step-3-round-1.md +12 -11
  17. package/plugin/src/domain-map.ts +2 -2
  18. package/plugin/src/kind-facet-map.ts +39 -9
  19. package/plugin/src/pack-map.ts +5 -3
  20. package/plugin/src/plugin-map.ts +29 -7
  21. package/templates/core/.claude/hooks/guard-hub-src-writes.mjs +7 -12
  22. package/templates/core/.claude/rules/agent-dispatch.md +12 -7
  23. package/templates/core/.claude/rules/src.md +7 -4
  24. package/templates/core/.claude/rules/tests.md +2 -2
  25. package/templates/core/.claude/skills/finishing-work/SKILL.md +4 -3
  26. package/templates/core/CLAUDE.md +28 -15
  27. package/templates/core/README.md +15 -3
  28. package/templates/core/bin/lib/toolchain-rules.mjs +17 -9
  29. package/templates/core/bin/lint-commit.mjs +215 -10
  30. package/templates/packs/README.md +19 -13
  31. package/templates/packs/github/files/.github/workflows/claude-pr-review.yml +2 -3
  32. package/templates/packs/github/files/.github/workflows/claude.yml +4 -7
  33. package/templates/packs/github/pack.json +1 -1
  34. package/templates/packs/harness-extras/files/.claude/hooks/guard-readonly-bash.mjs +3 -5
  35. package/templates/packs/harness-extras/pack.json +1 -1
  36. package/templates/packs/publishing/files/.github/workflows/release.yml +4 -7
  37. package/templates/packs/publishing/files/bin/pnpm-publish-shim.mjs +4 -14
  38. package/templates/packs/supply-chain/files/.github/workflows/scorecard.yml +4 -2
  39. package/templates/packs/supply-chain/pack.json +2 -2
  40. package/templates/packs/worktrees/pack.json +1 -1
@@ -33,8 +33,8 @@ Contents:
33
33
  `npx @monte3l/groundwork@rc .` and then run `/customize` again."
34
34
 
35
35
  **Check `inventory.schemaVersion` before reading anything else.** This
36
- skill understands schema versions **1 through 5** (the highest it knows is
37
- 5). If `schemaVersion` is **higher than 5**, the CLI that wrote it is newer
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
38
  than this plugin: **stop and change nothing**, do not interpret the
39
39
  inventory (a newer schema may have renamed or repurposed fields, and a
40
40
  confident misreading is worse than none), and tell the user to update the
@@ -57,8 +57,9 @@ Contents:
57
57
  | 3 | `harnessGrade`, `harnessConformance` | skip the harness-grade starting point |
58
58
  | 4 | `toolchainGrade`, `toolchainConformance` | skip the toolchain-grade starting point |
59
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 |
60
61
 
61
- **For a schema 5 inventory only: verify the staged baseline now, before
62
+ **For a schema 5 or later inventory: verify the staged baseline now, before
62
63
  anything is offered to the user.** A schema 1-4 inventory has no
63
64
  `stagedBaseline`: skip this whole block (every bullet below, including
64
65
  its stop list) and use the `inventory.templateRoot` fallback in Round 1.
@@ -159,7 +160,7 @@ Contents:
159
160
  - An empty `files` list is legitimate (nothing was missing from the
160
161
  project) and creates no `.groundwork/baseline/` directory; that alone is
161
162
  not a failure.
162
- - **For a schema 5 inventory, a `stagedBaseline` that is missing, not an
163
+ - **For a schema 5 or later inventory, a `stagedBaseline` that is missing, not an
163
164
  object, or whose `files` is not an array also stops the run** (a
164
165
  `files: {}` is not an empty list); so does a `stagedPacks` that is
165
166
  missing or not an array, or a pack entry that is not an object or whose
@@ -171,7 +172,7 @@ Contents:
171
172
  `stagedBaseline.files`, a pack's `files` or a pack's manifest
172
173
  means stop -- all of Round 1, including conflicts and packs -- and
173
174
  change nothing.** This is the single stop list for the staged baseline and the staged packs.
174
- 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 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).
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).
175
176
  - What a passing check proves: the staging is complete and matches the
176
177
  inventory. It does **not** prove the files are untampered -- anyone who
177
178
  can edit the staged files can edit the inventory's hashes too.
@@ -188,7 +189,10 @@ Contents:
188
189
  docs/ADR files the survey indexed. Dispatch this as parallel read-only
189
190
  `Explore` agents, one per discovery area (shape/toolchain, harness, docs),
190
191
  so you aggregate their findings rather than reading everything yourself.
191
- The harness agent also starts from `inventory.harnessGrade` (the report's
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
192
196
  `## Harness grade` section): a deterministic, offline check of the
193
197
  existing `.claude/` wiring. Its **wiring findings** (a hook registration
194
198
  naming a missing file, a skill or agent with unreadable frontmatter, a
@@ -7,11 +7,11 @@
7
7
  **Fresh bootstrap** applies directly, no research needed:
8
8
 
9
9
  - **Project kind ≠ library**: if `check:exports` (publint/attw) doesn't
10
- apply to the chosen kind (CLI, frontend, service), remove the
10
+ apply to the chosen kind (CLI, frontend, service, plugin), remove the
11
11
  `check:exports` step from `bin/lib/verify-steps.mjs` and the
12
12
  corresponding `.github/workflows/ci.yml` line, and drop the `exports`
13
13
  field from `package.json` in favor of a `bin` field (CLI) or leave `main`/
14
- no public export map at all (service).
14
+ no public export map at all (service, plugin).
15
15
  - **Runtime target = browser or both**: note that `tsconfig.base.json`'s
16
16
  `lib` and `moduleResolution` will very likely need to change — but leave
17
17
  the actual edit to Round 2's `typescript-guidance` sweep, which has full
@@ -43,7 +43,7 @@ Concretely, adopt-mode Round 1 applies exactly three things, all already
43
43
  confirmed in Step 0.4:
44
44
 
45
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 inventory, install them from the staged copy Step 0.1 already verified,
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
47
  using the bytes you read then (Step 0.1 also already checked that the
48
48
  staged files match the `absent` conflicts). Write them to the project at `path` (the
49
49
  `.staged` suffix stripped, never to the staged name), filling in the
@@ -73,7 +73,7 @@ confirmed in Step 0.4:
73
73
  pack's own `modes`: a pack whose `modes` doesn't include `"adopt"` (today,
74
74
  `publishing` — its release flow encodes decisions too project-specific to
75
75
  apply blind) is never auto-installed here even if staged and approved;
76
- instead, state in Step 6 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
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
77
  there for that pack. Before merging any staged `pack.json.staged` wiring, repeat
78
78
  the prototype-key check from Step 0.4(c): if a key of `wiring.settings`,
79
79
  `wiring.settingsTopLevel` or `wiring.packageScripts` is `__proto__`,
@@ -87,7 +87,7 @@ confirmed in Step 0.4:
87
87
  `.groundwork/packs/<name>/files/<path>` instead (no `.staged` suffix to strip,
88
88
  not hash-verified; token substitution still applies).
89
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 inventory and
90
+ from `pack.json.staged` (the bytes Step 0.1 read) for a schema 5 or later inventory and
91
91
  from the unsuffixed `pack.json` for schema 1-4,
92
92
  against what Step 0.2's deep read already found — a `.claude/settings.json`
93
93
  hook fragment merges the same way the baseline's own hook entries would;
@@ -103,12 +103,12 @@ confirmed in Step 0.4:
103
103
  and the three statusline scripts (`statusline.mjs`, `statusline-layout.mjs`,
104
104
  `subagent-statusline.mjs`) and install the pack's other artifacts (the
105
105
  compaction-handoff hooks and `guard-readonly-bash`) normally, stating the
106
- skip plainly in Step 6;
106
+ skip plainly in Step 7;
107
107
  `wiring.verifySteps` becomes a step in whatever this project's real gate
108
108
  runner is (a `package.json` script plus a line in its `lefthook.yml`/
109
109
  `.husky/pre-push`/CI workflow, written by hand to match its actual shape)
110
110
  — or, if the project has no such gate runner at all, install the pack's
111
- other artifacts and state plainly in Step 6 that the gate was not wired,
111
+ other artifacts and state plainly in Step 7 that the gate was not wired,
112
112
  rather than inventing a runner the project never asked for.
113
113
 
114
114
  **Plugins (both modes), after packs are settled above.** Build a
@@ -130,10 +130,11 @@ is pre-selected there, and a monorepo whose SDK dependency sits only in a
130
130
  workspace package is not pre-selected either -- the user can still pick it). Call
131
131
  `recommendPlugins(answers, context)` from `plugin-map.ts`
132
132
  (alongside this file, same copy mechanism as `pack-map.ts`) with the
133
- now-confirmed `InterviewAnswers`, and offer all ten in **one**
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**
134
135
  `AskUserQuestion` call holding three multi-select questions (a question
135
136
  takes at most four options, so split the list in its fixed order: entries
136
- 1-4, 5-7, 8-10), each option pre-selected per its entry's `recommended`
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`
137
138
  boolean with its `because` shown as the evidence -- same
138
139
  "visible reasoning" principle as every other inference in this skill.
139
140
 
@@ -147,14 +148,14 @@ already sets explicitly (an existing `false` is a decision the user made,
147
148
  not an oversight to correct), and never touch `.claude/settings.local.json`
148
149
  or the user's own `~/.claude/settings.json` scope. `claude-plugins-official`
149
150
  is a built-in marketplace, so no `extraKnownMarketplaces` entry is needed
150
- for any of the ten.
151
+ for any entry.
151
152
 
152
153
  **Committing this entry does not install the plugin for anyone.** A
153
154
  project-scope `enabledPlugins: true` with no local install produces no
154
155
  folder-trust auto-prompt -- Claude Code's `/plugin` Errors tab instead shows
155
156
  "enabled in project settings but isn't installed here" until someone runs
156
157
  the install by hand. So for every newly-`true` entry, print the exact
157
- follow-up command in Step 6's report: `claude plugin install <id> --scope
158
+ follow-up command in Step 7's report: `claude plugin install <id> --scope
158
159
  project` (or `/plugin install <id>` inside a running session) -- the user,
159
160
  and every collaborator who pulls this change, still has to run it once. Do
160
161
  the same for each recommendation's `prerequisites` (the
@@ -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.",
@@ -10,12 +10,15 @@
10
10
  * module rather than a judgment made afresh each run, so the same interview
11
11
  * answers and context always produce the same recommendation.
12
12
  *
13
+ * `plugin-dev` is offered only for the `plugin` kind (a repo that authors a
14
+ * Claude Code plugin) and is then appended last; for every other kind it is
15
+ * absent rather than listed as not recommended, so the ten-entry list
16
+ * `/customize` offers in fixed batches keeps its order. m3l-groundwork itself
17
+ * enables it, since it authors the `/customize` plugin.
18
+ *
13
19
  * Evaluated and deliberately not offered, recorded so they are not proposed
14
20
  * again:
15
21
  *
16
- * - `plugin-dev` -- only for projects that author Claude Code plugins;
17
- * m3l-groundwork itself enables it, a bootstrapped TypeScript project has
18
- * no plugin to build, and `skill-creator` covers skill authoring.
19
22
  * - `code-review` -- duplicates the built-in `/code-review` and the optional
20
23
  * `github` pack's PR-review Action.
21
24
  * - `code-simplifier` -- duplicates the built-in `/simplify`; its
@@ -310,11 +313,29 @@ function recommendClaudeCodeSetup(): PluginRecommendation {
310
313
  };
311
314
  }
312
315
 
316
+ /**
317
+ * `plugin-dev` carries the skills and agents for building a Claude Code
318
+ * plugin itself -- manifests, hooks, commands, skills, MCP wiring -- so it is
319
+ * pre-selected for the `plugin` kind, the only kind that authors one.
320
+ */
321
+ function recommendPluginDev(): PluginRecommendation {
322
+ return {
323
+ id: pluginId("plugin-dev"),
324
+ recommended: true,
325
+ because:
326
+ "this project authors a Claude Code plugin, and plugin-dev brings " +
327
+ "guidance and validation for exactly that: the plugin manifest, " +
328
+ "hooks, commands, skills, agents and MCP server wiring, plus the " +
329
+ "marketplace entry it ships through.",
330
+ };
331
+ }
332
+
313
333
  /**
314
334
  * Every built-in marketplace plugin's recommendation for the given interview
315
- * answers and context, always the same ten in the same order. Pre-selected
316
- * unconditionally: `context7`, `typescript-lsp`, `claude-md-management` and
317
- * `claude-security`. Conditionally: `github` when the `github` pack was
335
+ * answers and context: always the same ten in the same order, plus an
336
+ * eleventh, `plugin-dev`, appended last for the `plugin` kind only.
337
+ * Pre-selected unconditionally: `context7`, `typescript-lsp`,
338
+ * `claude-md-management` and `claude-security`. Conditionally: `github` when the `github` pack was
318
339
  * chosen; `security-guidance` for a `service` or a `thorough` CI depth;
319
340
  * `skill-creator` when the project has its own skills; `agent-sdk-dev` and
320
341
  * `mcp-server-dev` when the project depends on the Claude Agent SDK or the
@@ -342,7 +363,7 @@ export function recommendPlugins(
342
363
  answers: InterviewAnswers,
343
364
  context?: PluginRecommendationContext,
344
365
  ): PluginRecommendation[] {
345
- return [
366
+ const fixed = [
346
367
  recommendContext7(),
347
368
  recommendTypescriptLsp(),
348
369
  recommendClaudeMdManagement(),
@@ -354,4 +375,5 @@ export function recommendPlugins(
354
375
  recommendAgentSdkDev(context),
355
376
  recommendMcpServerDev(context),
356
377
  ];
378
+ return answers.kind === "plugin" ? [...fixed, recommendPluginDev()] : fixed;
357
379
  }
@@ -12,13 +12,10 @@
12
12
  * guard alone is bypassed by a Bash command that writes the same file
13
13
  * (`cat > src/a.ts <<EOF`, `sed -i`, `cp`, a `python -c` one-liner).
14
14
  *
15
- * The seam: the PreToolUse payload carries a top-level `agent_type` field
16
- * both when the tool call fires inside a subagent AND in a main session
17
- * started with `claude --agent <name>`, while `agent_id` is sent ONLY when
18
- * the call fires inside a subagent. A spoke is therefore identified by both
19
- * fields together: a call naming a writer in `agent_type` but carrying no
20
- * non-blank string `agent_id` is the hub itself running as `--agent`, not a
21
- * dispatched spoke, and is treated as the hub.
15
+ * The seam: this guard requires both the top-level `agent_type` and
16
+ * `agent_id` payload fields to count a call as a writer spoke: a call naming
17
+ * a writer in `agent_type` but carrying no non-blank string `agent_id` is
18
+ * treated as the hub.
22
19
  *
23
20
  * The decision: block when BOTH conditions hold:
24
21
  * (a) the target path is a guarded source/test path, AND
@@ -1808,11 +1805,9 @@ function isEntryPoint() {
1808
1805
  }
1809
1806
 
1810
1807
  // The agent_type the pure decision functions should see: the payload's own
1811
- // only when a string `agent_id` that is non-empty after `.trim()` proves the
1812
- // call fires inside a subagent; otherwise (absent, non-string, empty or
1813
- // whitespace-only) undefined, i.e. the hub. `agent_type` alone is not
1814
- // enough -- a `claude --agent code-implementer` main session sends it too
1815
- // (see the header's "The seam").
1808
+ // only when a string `agent_id` that is non-empty after `.trim()` is present;
1809
+ // otherwise (absent, non-string, empty or whitespace-only) undefined, i.e. the
1810
+ // hub. A call counts as a spoke only with both fields.
1816
1811
  function spokeAgentType(input) {
1817
1812
  return typeof input.agent_id === "string" && input.agent_id.trim() !== ""
1818
1813
  ? input.agent_type
@@ -91,11 +91,16 @@ contract (a documented behavior, an interface to satisfy):
91
91
  - **Review spokes return a bounded digest**, not an open-ended report — the
92
92
  full report travels back inline in the response, capped at roughly 8,000
93
93
  characters (~2,000 tokens). No review spoke writes a scratchpad file.
94
- - **Plan mode propagates its read-only restriction to every subagent it
95
- dispatches** — not just the ones already read-only by design. A writer
96
- spoke dispatched while plan mode is active loses write access too. If a
97
- design depends on a subagent writing a file, verify with `git status`/`ls`
98
- after the dispatch rather than trusting the return value's success claim.
94
+ - **Do not assume plan mode makes a dispatched subagent read-only.** A
95
+ live probe on Claude Code 2.1.296 (2026-10-11) dispatched `test-author` and
96
+ a `general-purpose` agent from a session in plan mode, each told to write
97
+ one file outside the repo: both writes succeeded. Anthropic's
98
+ [subagent docs](https://code.claude.com/docs/en/sub-agents.md) say a
99
+ subagent that sets its own `permissionMode` keeps it, and our writer
100
+ spokes set `acceptEdits`. The main session itself may still decline to
101
+ dispatch a writer in plan mode. If a design depends on a subagent writing
102
+ or not writing a file, verify with `git status`/`ls` after the dispatch
103
+ rather than trusting the return value's success claim.
99
104
  - **A `SubagentStop`/`PreToolUse` hook flagging a dispatch is a prompt to
100
105
  verify, not a replacement for verifying.** Treat its stderr reminder as a
101
106
  signal to check state yourself.
@@ -104,8 +109,8 @@ contract (a documented behavior, an interface to satisfy):
104
109
  `guard-branch-isolation.mjs` let a top-level `src/`/`tests/` write through
105
110
  unblocked, check `/status`'s "Setting sources" line for a managed source
106
111
  before debugging the hook script itself -- a managed `allowManagedHooksOnly`
107
- policy (CLAUDE.md's "Agent Operating Model") disables project hooks
108
- outright, with no repo-visible signal that it's active.
112
+ policy (CLAUDE.md's "Agent Operating Model") means only managed hooks
113
+ run, with no repo-visible signal that it's active.
109
114
  - **A templated dispatch prompt needs a per-target assumption check, not
110
115
  just a per-target file-list check.** Verify the template's implicit
111
116
  assumptions against each target's own docs/tests before dispatch, not
@@ -6,10 +6,13 @@ paths:
6
6
  # Source rules (`src/**`)
7
7
 
8
8
  > This file is the terse checklist that auto-loads when you edit source.
9
- > Base standards — TypeScript strictness, ESM `.js` imports, named exports,
10
- > exporting a type next to its value, `readonly`/`const`, `interface` vs
11
- > `type`, exhaustive `switch`, TSDoc on every export — live in CLAUDE.md and
12
- > `eslint.config.js`; this file adds what those don't already say.
9
+ > Enforced by tooling: `strict` and ESM `.js` imports (`tsconfig.base.json`,
10
+ > `module: nodenext`), named exports only (`import-x/no-default-export`),
11
+ > exhaustive `switch` (`switch-exhaustiveness-check`), `const` over `let`/`var`
12
+ > (`prefer-const`, `no-var`), and TSDoc syntax (`tsdoc/syntax`, a warning).
13
+ > Conventions only, no rule checks them: exporting a type next to its value,
14
+ > `readonly`, `interface` vs `type`, and TSDoc on every export. This file
15
+ > adds what those don't already say.
13
16
 
14
17
  - **Don't pass `undefined` to an optional property.** Under
15
18
  `exactOptionalPropertyTypes`, an optional target field (`default?: number`)
@@ -116,8 +116,8 @@ throw "a string";
116
116
  list and cover any new ternary's non-`Error` arm in the same edit.
117
117
  - **A suite failing while a spoke fan-out is running may be contention, not
118
118
  a regression — re-run it alone first.**
119
- - Use `pnpm exec vitest`; a bare `npx vitest` can fail to resolve
120
- `@vitest/coverage-v8` under pnpm.
119
+ - Use `pnpm exec vitest`, not a bare `npx vitest`, so the project's own
120
+ pinned binary runs.
121
121
  - **Brace void-union handler bodies** — a handler typed `void |
122
122
  Promise<void>` whose arrow body returns a value fails typecheck (TS2322);
123
123
  the leniency applies only to a return type of _exactly_ `void`. Wrap the
@@ -142,9 +142,10 @@ the work is gone.
142
142
  **If a log is written here, commit and land it immediately** (its own small
143
143
  `docs:` commit via `writing-commits`) before moving on to any other task,
144
144
  rather than leaving it as an uncommitted file. **"Commit it" does not mean
145
- commit directly to `main`** — branch first (`git switch -c docs/<slug>-log`),
146
- commit there, push, and open a PR, even for a trivial docs-only change, if
147
- the project requires a PR for every change to `main`.
145
+ commit directly to `main`** when the project requires a PR for every change to
146
+ `main`: in that case branch first (`git switch -c docs/<slug>-log`), commit
147
+ there, push, and open a PR, even for a trivial docs-only change. Only if the
148
+ project allows direct pushes to `main` is the PR step skipped.
148
149
 
149
150
  ### 7 — Orphaned journal sweep
150
151
 
@@ -38,7 +38,8 @@ locally.
38
38
  ## Git Workflow
39
39
 
40
40
  **Conventional Commits (required)**, enforced by the `commit-msg` hook
41
- (`bin/lint-commit.mjs`). Add a `Co-Authored-By:` trailer when Claude
41
+ (`bin/lint-commit.mjs`, run after `bin/strip-claude-trailers.mjs` removes
42
+ harness-injected `Claude-*` trailers). Add a `Co-Authored-By:` trailer when Claude
42
43
  authored or substantially assisted a commit — see `.claude/skills/writing-commits/`.
43
44
 
44
45
  Branch off `main` as `feat/<slug>` / `fix/<slug>`, never work directly on
@@ -52,8 +53,9 @@ Never `git push --force` a shared branch.
52
53
  ## Architecture & Decisions
53
54
 
54
55
  `src/index.ts` is the current public entry point (see the `exports` map in
55
- `package.json`). Everything under `src/internal/`, if you create it, is
56
- private and must never be re-exported.
56
+ `package.json`). By convention, anything under `src/internal/` (if you create
57
+ it) is private and is not re-exported from the entry point; no lint rule
58
+ enforces this, so review for it.
57
59
 
58
60
  ## Agent Operating Model
59
61
 
@@ -71,6 +73,19 @@ contract:
71
73
  Must-fix findings route back to `code-implementer`, and the loop repeats
72
74
  until clean.
73
75
 
76
+ Also shipped: `.claude/agents/Explore.md`, a fast read-only search agent for
77
+ locating files and symbols.
78
+
79
+ Skills, each in `.claude/skills/<name>/`:
80
+
81
+ - `starting-work` — pre-work gate: picks the branch and whether a PR is needed.
82
+ - `writing-commits` — drafts a Conventional Commit from the staged diff.
83
+ - `creating-prs` — verifies gates, pushes, opens the PR and picks a merge path.
84
+ - `triaging-ci` — diagnoses a failed CI run and proposes fixes.
85
+ - `finishing-work` — post-merge cleanup: branches, refs, work log.
86
+ - `typescript-guidance` / `harness-guidance` — live research and refresh
87
+ sweeps (see Freshness).
88
+
74
89
  **The guard also screens `Bash`, but only conservatively.** The same hook
75
90
  runs on every `Bash` call and blocks a command that visibly writes into
76
91
  `src/` or `tests/` (redirects, `tee`, `sed -i`, `cp`/`mv` into them, a
@@ -90,9 +105,9 @@ silently disable it.** Managed settings (a `managed-settings.json` file, an
90
105
  MDM policy, or a claude.ai-console-managed remote policy) take precedence
91
106
  over every file this baseline installs, with no project-level override, and
92
107
  two managed-only keys -- `allowManagedHooksOnly` and
93
- `allowManagedPermissionRulesOnly` -- make Claude Code skip this project's
94
- own `.claude/settings.json` hooks and permission rules entirely rather than
95
- merge with them (see
108
+ `allowManagedPermissionRulesOnly` -- mean that only managed hooks run
109
+ (`allowManagedHooksOnly`) and only managed permission rules apply
110
+ (`allowManagedPermissionRulesOnly`) (see
96
111
  [Claude Code's managed-settings docs](https://code.claude.com/docs/en/managed-settings)).
97
112
  Nothing in this project can detect or gate against that from inside the
98
113
  repo -- the managed file lives outside any working tree, at an OS-level
@@ -112,11 +127,9 @@ only after the last mod calls `next` (see the
112
127
  Only managed-settings hooks outrank a mod, and nothing in the repo can detect
113
128
  one. Check `/plugin` for installed mods alongside `/status`.
114
129
 
115
- **The guard keys on `agent_id` as well as `agent_type`.** Claude Code sends
116
- `agent_type` both inside a subagent and in a main session started with
117
- `--agent <name>`; only a call inside a subagent also carries `agent_id`. A
118
- call counts as a writer spoke only with both present, so a hub launched as
119
- `claude --agent code-implementer` is still the hub and is blocked.
130
+ **The guard keys on `agent_id` as well as `agent_type`.** A call counts as a
131
+ writer spoke only with both present, so a call carrying `agent_type` but no
132
+ `agent_id` is treated as the hub and is blocked.
120
133
 
121
134
  Full dispatch-sizing and recovery guidance: `.claude/rules/agent-dispatch.md`
122
135
  (auto-loads when editing `.claude/skills/**` or `.claude/agents/**`).
@@ -144,10 +157,10 @@ the correct semver impact; new/changed exports have TSDoc and tests. If you
144
157
  touched the harness itself (hooks, agents, skills, rules, `settings.json`),
145
158
  `pnpm verify`'s `harness` step (`bin/check-harness.mjs`) must stay green: it
146
159
  fails on broken wiring and only warns on quality.
147
- If you touched the TypeScript toolchain (`tsconfig*.json`, `eslint.config.js`,
148
- `vitest.config.ts`, `bin/lib/verify-steps.mjs`, the toolchain pins in
149
- `package.json`), the `toolchain` step (`bin/check-toolchain.mjs`) must stay
150
- green the same way: it fails on wiring `tsc` and ESLint do not catch (a build
160
+ The `toolchain` step (`bin/check-toolchain.mjs`) runs on every
161
+ `pnpm verify`, and must stay green when you touch the TypeScript toolchain
162
+ (`tsconfig*.json`, `eslint.config.js`, `vitest.config.ts`,
163
+ `bin/lib/verify-steps.mjs`, the toolchain pins in `package.json`) the same way: it fails on wiring `tsc` and ESLint do not catch (a build
151
164
  project that emits nowhere, a verify step naming a script that does not exist)
152
165
  and only warns on quality (a missing strict flag, an option TypeScript has
153
166
  deprecated). Never silence it by deleting the check or lowering a threshold --
@@ -19,11 +19,23 @@ pnpm install
19
19
  pnpm verify
20
20
  ```
21
21
 
22
- `pnpm verify` runs the same checks CI runs — format, lint, typecheck, build,
23
- and test with coverage — in one command, so you can catch a failure locally
24
- before pushing. See `CLAUDE.md` for the full command reference and this
22
+ `pnpm verify` runs the same checks CI runs, in one command, so you can catch
23
+ a failure locally before pushing. In order: format check, lint, the Claude
24
+ Code harness grader, the TypeScript toolchain grader, knip (unused code and
25
+ dependencies), typecheck, build, tests with coverage, a package-exports check,
26
+ and a Node version pin check. See `CLAUDE.md` for the full command reference and this
25
27
  project's conventions.
26
28
 
29
+ ## Notable files
30
+
31
+ - `.github/dependabot.yml` — weekly Dependabot updates for the GitHub Actions
32
+ pinned in `.github/workflows/` (npm updates are left off by default).
33
+ - `pnpm-workspace.yaml` — pnpm's install-script approval list (`allowBuilds`),
34
+ which pnpm 10+ reads from here rather than from `package.json`.
35
+ - `bin/strip-claude-trailers.mjs` — run by the `commit-msg` hook in
36
+ `lefthook.yml` before commit linting; strips harness-injected `Claude-*`
37
+ trailers and leaves `Co-Authored-By:` alone.
38
+
27
39
  ## Tailor it to your project
28
40
 
29
41
  This baseline is frozen at the moment it was generated, and deliberately
@@ -26,8 +26,11 @@ import { readFileSync, readdirSync, statSync } from "node:fs";
26
26
  import { dirname, isAbsolute, join, relative, resolve } from "node:path";
27
27
 
28
28
  /**
29
- * Options TypeScript 6.0 deprecated. `removedIn` is the major that drops them
30
- * (`outFile` and `moduleResolution: classic` already went in 6.0).
29
+ * Options TypeScript 6.0 deprecated. `removedIn` is the major that drops them.
30
+ * `outFile` and `moduleResolution: classic` are `removedIn: 6` because the
31
+ * TypeScript 6.0 release notes call them removed; `tsc` 6.0.3 itself still
32
+ * accepts both behind `ignoreDeprecations: "6.0"` and warns that they stop
33
+ * functioning in 7.0.
31
34
  * https://www.typescriptlang.org/docs/handbook/release-notes/typescript-6-0.html
32
35
  * @public Not imported anywhere else in this project -- exported only for
33
36
  * m3l-groundwork's own upstream parity check (see the file header above).
@@ -649,12 +652,17 @@ function loadSnapshot(root) {
649
652
  packageRead.ok && isRecord(packageRead.value)
650
653
  ? packageRead.value
651
654
  : undefined;
652
- const scripts = {};
653
- if (pkg !== undefined && isRecord(pkg.scripts)) {
654
- for (const [name, cmd] of Object.entries(pkg.scripts)) {
655
- if (typeof cmd === "string") scripts[name] = cmd;
656
- }
657
- }
655
+ // Object.fromEntries, not `scripts[name] = cmd` on a `{}`: assignment to
656
+ // `__proto__` hits the prototype setter and silently drops a script of that
657
+ // name, while fromEntries defines every key as an own data property.
658
+ const scripts =
659
+ pkg !== undefined && isRecord(pkg.scripts)
660
+ ? Object.fromEntries(
661
+ Object.entries(pkg.scripts).filter(
662
+ ([, cmd]) => typeof cmd === "string",
663
+ ),
664
+ )
665
+ : {};
658
666
 
659
667
  const tsconfigFiles = new Map();
660
668
  const tsconfigLinks = [];
@@ -899,7 +907,7 @@ const gateWiring = {
899
907
  const script = first === "run" ? second : first;
900
908
  if (script !== undefined && !PNPM_BUILTINS.has(script)) {
901
909
  checked += 1;
902
- if (scripts[script] === undefined) {
910
+ if (!Object.hasOwn(scripts, script)) {
903
911
  failures.push({
904
912
  subject: `${stepsFile} step "${step.id}"`,
905
913
  message: `runs \`pnpm ${script}\`, but package.json has no "${script}" script`,