@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.
- package/README.md +20 -5
- package/dist/inventory.d.ts +1 -1
- package/dist/inventory.js +5 -2
- package/dist/report.js +74 -10
- package/dist/survey/survey-harness.d.ts +10 -2
- package/dist/survey/survey-harness.js +90 -4
- package/dist/survey/survey-shape.js +6 -3
- package/dist/survey/survey-toolchain.js +7 -9
- package/dist/survey/types.d.ts +33 -0
- package/dist/toolchain/grade.js +6 -7
- package/dist/toolchain/rules.d.ts +5 -3
- package/dist/toolchain/rules.js +6 -4
- package/package.json +1 -1
- package/plugin/skills/customize/SKILL.md +40 -5
- package/plugin/skills/customize/step-0-reconcile.md +10 -6
- package/plugin/skills/customize/step-3-round-1.md +12 -11
- package/plugin/src/domain-map.ts +2 -2
- package/plugin/src/kind-facet-map.ts +39 -9
- package/plugin/src/pack-map.ts +5 -3
- package/plugin/src/plugin-map.ts +29 -7
- package/templates/core/.claude/hooks/guard-hub-src-writes.mjs +7 -12
- package/templates/core/.claude/rules/agent-dispatch.md +12 -7
- package/templates/core/.claude/rules/src.md +7 -4
- package/templates/core/.claude/rules/tests.md +2 -2
- package/templates/core/.claude/skills/finishing-work/SKILL.md +4 -3
- package/templates/core/CLAUDE.md +28 -15
- package/templates/core/README.md +15 -3
- package/templates/core/bin/lib/toolchain-rules.mjs +17 -9
- package/templates/core/bin/lint-commit.mjs +215 -10
- package/templates/packs/README.md +19 -13
- package/templates/packs/github/files/.github/workflows/claude-pr-review.yml +2 -3
- package/templates/packs/github/files/.github/workflows/claude.yml +4 -7
- package/templates/packs/github/pack.json +1 -1
- package/templates/packs/harness-extras/files/.claude/hooks/guard-readonly-bash.mjs +3 -5
- package/templates/packs/harness-extras/pack.json +1 -1
- package/templates/packs/publishing/files/.github/workflows/release.yml +4 -7
- package/templates/packs/publishing/files/bin/pnpm-publish-shim.mjs +4 -14
- package/templates/packs/supply-chain/files/.github/workflows/scorecard.yml +4 -2
- package/templates/packs/supply-chain/pack.json +2 -2
- 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
|
|
37
|
-
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
package/plugin/src/domain-map.ts
CHANGED
|
@@ -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
|
|
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
|
|
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
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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.
|
|
191
|
+
emphasis: kindEmphasis.packaging,
|
|
162
192
|
},
|
|
163
|
-
{ facetId: "lint-typing-rules", emphasis: kindEmphasis.
|
|
193
|
+
{ facetId: "lint-typing-rules", emphasis: kindEmphasis.lint },
|
|
164
194
|
{ facetId: "testing-language-features", emphasis: kindEmphasis.testing },
|
|
165
195
|
];
|
|
166
196
|
|
package/plugin/src/pack-map.ts
CHANGED
|
@@ -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,
|
|
86
|
-
*
|
|
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
|
|
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.",
|
package/plugin/src/plugin-map.ts
CHANGED
|
@@ -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
|
|
316
|
-
*
|
|
317
|
-
*
|
|
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
|
-
|
|
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:
|
|
16
|
-
*
|
|
17
|
-
*
|
|
18
|
-
*
|
|
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()`
|
|
1812
|
-
//
|
|
1813
|
-
//
|
|
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
|
-
- **
|
|
95
|
-
|
|
96
|
-
|
|
97
|
-
|
|
98
|
-
|
|
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")
|
|
108
|
-
|
|
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
|
-
>
|
|
10
|
-
>
|
|
11
|
-
>
|
|
12
|
-
> `
|
|
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
|
|
120
|
-
|
|
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`**
|
|
146
|
-
|
|
147
|
-
|
|
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
|
|
package/templates/core/CLAUDE.md
CHANGED
|
@@ -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
|
|
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`).
|
|
56
|
-
private and
|
|
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` --
|
|
94
|
-
|
|
95
|
-
|
|
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`.**
|
|
116
|
-
|
|
117
|
-
|
|
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
|
-
|
|
148
|
-
`
|
|
149
|
-
`
|
|
150
|
-
|
|
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 --
|
package/templates/core/README.md
CHANGED
|
@@ -19,11 +19,23 @@ pnpm install
|
|
|
19
19
|
pnpm verify
|
|
20
20
|
```
|
|
21
21
|
|
|
22
|
-
`pnpm verify` runs the same checks CI runs
|
|
23
|
-
|
|
24
|
-
|
|
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
|
-
*
|
|
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
|
-
|
|
653
|
-
|
|
654
|
-
|
|
655
|
-
|
|
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
|
|
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`,
|