@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.
- package/README.md +20 -5
- package/dist/customize-paths.d.ts +51 -15
- package/dist/customize-paths.js +32 -13
- package/dist/fs-guard.d.ts +2 -2
- package/dist/harness/rules.d.ts +2 -1
- package/dist/harness/rules.js +3 -1
- package/dist/inventory.d.ts +1 -1
- package/dist/inventory.js +5 -2
- package/dist/plugin.d.ts +12 -12
- package/dist/plugin.js +34 -26
- 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 +73 -408
- package/plugin/skills/customize/step-0-reconcile.md +265 -0
- package/plugin/skills/customize/step-3-round-1.md +171 -0
- 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 +154 -11
- package/templates/core/.claude/agents/Explore.md +1 -1
- package/templates/core/.claude/hooks/guard-hub-src-writes.mjs +7 -12
- package/templates/core/.claude/hooks/guard-no-commonjs.mjs +3 -2
- package/templates/core/.claude/hooks/inject-decision-gate.mjs +7 -7
- 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/skills/triaging-ci/SKILL.md +2 -2
- package/templates/core/.claude/skills/writing-commits/SKILL.md +4 -4
- package/templates/core/.prettierignore +1 -0
- package/templates/core/CLAUDE.md +28 -15
- package/templates/core/README.md +15 -3
- package/templates/core/_gitignore +1 -0
- package/templates/core/bin/check-exports.mjs +5 -3
- package/templates/core/bin/lib/harness-rules.mjs +3 -1
- package/templates/core/bin/lib/toolchain-rules.mjs +17 -9
- package/templates/core/bin/lint-commit.mjs +215 -10
- package/templates/core/tsconfig.base.json +10 -6
- package/templates/packs/README.md +25 -13
- package/templates/packs/github/files/.github/workflows/claude-pr-review.yml +3 -4
- package/templates/packs/github/files/.github/workflows/claude.yml +5 -8
- 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/files/.claude/hooks/subagent-statusline.mjs +29 -14
- 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/publishing/pack.json +1 -1
- package/templates/packs/quality/files/.claude/agents/type-design-analyzer.md +1 -1
- package/templates/packs/quality/pack.json +1 -1
- 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
package/plugin/src/plugin-map.ts
CHANGED
|
@@ -9,6 +9,32 @@
|
|
|
9
9
|
* `pack-map.ts` applies to `templates/packs/` bundles. A stored, unit-tested
|
|
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
|
+
*
|
|
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
|
+
*
|
|
19
|
+
* Evaluated and deliberately not offered, recorded so they are not proposed
|
|
20
|
+
* again:
|
|
21
|
+
*
|
|
22
|
+
* - `code-review` -- duplicates the built-in `/code-review` and the optional
|
|
23
|
+
* `github` pack's PR-review Action.
|
|
24
|
+
* - `code-simplifier` -- duplicates the built-in `/simplify`; its
|
|
25
|
+
* unrestricted-tools agent is blocked by the baseline's hub-and-spoke
|
|
26
|
+
* write guard on `src/`/`tests/` anyway.
|
|
27
|
+
* - `feature-dev` -- duplicates plan mode, `starting-work` and the TDD loop;
|
|
28
|
+
* its `code-reviewer` competes with the baseline's.
|
|
29
|
+
* - `pr-review-toolkit` -- overlaps the baseline's `code-reviewer` and
|
|
30
|
+
* `silent-failure-hunter` and the optional `quality` pack's
|
|
31
|
+
* `type-design-analyzer`.
|
|
32
|
+
* - `hookify` -- runs `python3` on every tool call, and keeps its rules in
|
|
33
|
+
* gitignored `.local.md` files that bypass the graded, committed hooks and
|
|
34
|
+
* the hook cap.
|
|
35
|
+
* - `remember` -- third-party under a source-available license that forbids
|
|
36
|
+
* modification and redistribution; it sends transcripts to `claude -p`,
|
|
37
|
+
* writes `.remember/`, and can push memory to a remote.
|
|
12
38
|
*/
|
|
13
39
|
import type { InterviewAnswers } from "./kind-facet-map.js";
|
|
14
40
|
|
|
@@ -29,12 +55,18 @@ export interface PluginRecommendation {
|
|
|
29
55
|
|
|
30
56
|
/**
|
|
31
57
|
* What `/customize` knows beyond the interview answers by the time it
|
|
32
|
-
* recommends plugins: which packs the user chose,
|
|
33
|
-
* authors its own skills
|
|
58
|
+
* recommends plugins: which packs the user chose, whether the project
|
|
59
|
+
* authors its own skills, and which packages it depends on. All are
|
|
60
|
+
* optional; an absent field reads as "no" (or "none").
|
|
34
61
|
*/
|
|
35
62
|
export interface PluginRecommendationContext {
|
|
36
63
|
readonly chosenPacks?: readonly string[];
|
|
37
64
|
readonly hasCustomSkills?: boolean;
|
|
65
|
+
/**
|
|
66
|
+
* Package names from the project's `package.json` `dependencies` and
|
|
67
|
+
* `devDependencies` combined. Absent reads as none.
|
|
68
|
+
*/
|
|
69
|
+
readonly dependencies?: readonly string[];
|
|
38
70
|
}
|
|
39
71
|
|
|
40
72
|
function pluginId(name: string): string {
|
|
@@ -163,10 +195,80 @@ function recommendSecurityGuidance(
|
|
|
163
195
|
};
|
|
164
196
|
}
|
|
165
197
|
|
|
198
|
+
/**
|
|
199
|
+
* `claude-security` is the on-demand counterpart to `security-guidance`: it
|
|
200
|
+
* runs only when invoked, so unlike that plugin's per-turn Stop-hook LLM
|
|
201
|
+
* review it costs nothing while idle, and is pre-selected for every project.
|
|
202
|
+
*/
|
|
203
|
+
function recommendClaudeSecurity(): PluginRecommendation {
|
|
204
|
+
return {
|
|
205
|
+
id: pluginId("claude-security"),
|
|
206
|
+
recommended: true,
|
|
207
|
+
because:
|
|
208
|
+
"it runs on demand -- only when invoked -- so it costs nothing while " +
|
|
209
|
+
"idle, unlike security-guidance's Stop-hook LLM review on every " +
|
|
210
|
+
"turn. When run it scans the repo or a diff, challenges each finding " +
|
|
211
|
+
"before reporting it, and can draft patches. Its post-push scan tip " +
|
|
212
|
+
"can be turned off with CLAUDE_SECURITY_SCAN_TIP=off.",
|
|
213
|
+
prerequisites: ["Python 3.9+ on PATH"],
|
|
214
|
+
};
|
|
215
|
+
}
|
|
216
|
+
|
|
217
|
+
function dependsOn(
|
|
218
|
+
context: PluginRecommendationContext | undefined,
|
|
219
|
+
packageName: string,
|
|
220
|
+
): boolean {
|
|
221
|
+
return context?.dependencies?.includes(packageName) ?? false;
|
|
222
|
+
}
|
|
223
|
+
|
|
224
|
+
/**
|
|
225
|
+
* `agent-sdk-dev` scaffolds and verifies Claude Agent SDK applications, so it
|
|
226
|
+
* is pre-selected only when the project depends on
|
|
227
|
+
* `@anthropic-ai/claude-agent-sdk`.
|
|
228
|
+
*/
|
|
229
|
+
function recommendAgentSdkDev(
|
|
230
|
+
context: PluginRecommendationContext | undefined,
|
|
231
|
+
): PluginRecommendation {
|
|
232
|
+
const recommended = dependsOn(context, "@anthropic-ai/claude-agent-sdk");
|
|
233
|
+
return {
|
|
234
|
+
id: pluginId("agent-sdk-dev"),
|
|
235
|
+
recommended,
|
|
236
|
+
because: recommended
|
|
237
|
+
? "the project depends on @anthropic-ai/claude-agent-sdk, and this " +
|
|
238
|
+
"plugin scaffolds new SDK apps (/new-sdk-app) and verifies existing " +
|
|
239
|
+
"ones against the SDK's current guidance."
|
|
240
|
+
: "only useful to a project that builds on the Claude Agent SDK; " +
|
|
241
|
+
"@anthropic-ai/claude-agent-sdk is not among this project's " +
|
|
242
|
+
"dependencies.",
|
|
243
|
+
};
|
|
244
|
+
}
|
|
245
|
+
|
|
246
|
+
/**
|
|
247
|
+
* `mcp-server-dev` carries skills for building MCP servers and MCP apps and
|
|
248
|
+
* for MCPB packaging, so it is pre-selected only when the project depends on
|
|
249
|
+
* `@modelcontextprotocol/sdk`.
|
|
250
|
+
*/
|
|
251
|
+
function recommendMcpServerDev(
|
|
252
|
+
context: PluginRecommendationContext | undefined,
|
|
253
|
+
): PluginRecommendation {
|
|
254
|
+
const recommended = dependsOn(context, "@modelcontextprotocol/sdk");
|
|
255
|
+
return {
|
|
256
|
+
id: pluginId("mcp-server-dev"),
|
|
257
|
+
recommended,
|
|
258
|
+
because: recommended
|
|
259
|
+
? "the project depends on @modelcontextprotocol/sdk, and this plugin " +
|
|
260
|
+
"brings skills for building MCP servers and MCP apps and for " +
|
|
261
|
+
"packaging them as MCPB bundles."
|
|
262
|
+
: "only useful to a project that builds on the MCP SDK; " +
|
|
263
|
+
"@modelcontextprotocol/sdk is not among this project's " +
|
|
264
|
+
"dependencies.",
|
|
265
|
+
};
|
|
266
|
+
}
|
|
267
|
+
|
|
166
268
|
/**
|
|
167
269
|
* `skill-creator` scaffolds, evaluates and iterates on skills. The baseline's
|
|
168
|
-
* own skills are maintained by
|
|
169
|
-
* pays for itself in a project that writes skills of its own.
|
|
270
|
+
* own skills are maintained upstream by m3l-groundwork, not by the project,
|
|
271
|
+
* so it only pays for itself in a project that writes skills of its own.
|
|
170
272
|
*/
|
|
171
273
|
function recommendSkillCreator(
|
|
172
274
|
context: PluginRecommendationContext | undefined,
|
|
@@ -211,26 +313,67 @@ function recommendClaudeCodeSetup(): PluginRecommendation {
|
|
|
211
313
|
};
|
|
212
314
|
}
|
|
213
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
|
+
|
|
214
333
|
/**
|
|
215
334
|
* Every built-in marketplace plugin's recommendation for the given interview
|
|
216
|
-
* answers and context
|
|
217
|
-
* `
|
|
218
|
-
*
|
|
219
|
-
* `
|
|
220
|
-
* `
|
|
221
|
-
*
|
|
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
|
|
339
|
+
* chosen; `security-guidance` for a `service` or a `thorough` CI depth;
|
|
340
|
+
* `skill-creator` when the project has its own skills; `agent-sdk-dev` and
|
|
341
|
+
* `mcp-server-dev` when the project depends on the Claude Agent SDK or the
|
|
342
|
+
* MCP SDK respectively. Never: `claude-code-setup`. A pure function --
|
|
343
|
+
* identical inputs always produce an equal result.
|
|
344
|
+
*
|
|
345
|
+
* @example
|
|
346
|
+
* ```ts
|
|
347
|
+
* import { recommendPlugins } from "./plugin-map.js";
|
|
348
|
+
*
|
|
349
|
+
* const recommendations = recommendPlugins(
|
|
350
|
+
* {
|
|
351
|
+
* kind: "service",
|
|
352
|
+
* runtime: "node",
|
|
353
|
+
* testsMandatory: true,
|
|
354
|
+
* ciDepth: "standard",
|
|
355
|
+
* keepAgents: ["code-reviewer"],
|
|
356
|
+
* },
|
|
357
|
+
* { chosenPacks: ["github"], dependencies: ["@modelcontextprotocol/sdk"] },
|
|
358
|
+
* );
|
|
359
|
+
* const preselected = recommendations.filter((r) => r.recommended);
|
|
360
|
+
* ```
|
|
222
361
|
*/
|
|
223
362
|
export function recommendPlugins(
|
|
224
363
|
answers: InterviewAnswers,
|
|
225
364
|
context?: PluginRecommendationContext,
|
|
226
365
|
): PluginRecommendation[] {
|
|
227
|
-
|
|
366
|
+
const fixed = [
|
|
228
367
|
recommendContext7(),
|
|
229
368
|
recommendTypescriptLsp(),
|
|
230
369
|
recommendClaudeMdManagement(),
|
|
231
370
|
recommendGithub(context),
|
|
232
371
|
recommendSecurityGuidance(answers),
|
|
372
|
+
recommendClaudeSecurity(),
|
|
233
373
|
recommendSkillCreator(context),
|
|
234
374
|
recommendClaudeCodeSetup(),
|
|
375
|
+
recommendAgentSdkDev(context),
|
|
376
|
+
recommendMcpServerDev(context),
|
|
235
377
|
];
|
|
378
|
+
return answers.kind === "plugin" ? [...fixed, recommendPluginDev()] : fixed;
|
|
236
379
|
}
|
|
@@ -3,7 +3,7 @@ name: Explore
|
|
|
3
3
|
description: Fast read-only search agent for locating and understanding code. Use it to find files by pattern (e.g. "src/components/**/*.tsx"), grep for symbols or keywords (e.g. "API endpoints"), answer "where is X defined / which files reference Y," or read a bounded set of files in full when the caller says so. Do NOT use it for code review, design-doc auditing, or open-ended cross-file consistency judgment across the whole repo — those need a specialized reviewer. When calling, specify search breadth ("quick" for a single targeted lookup, "medium" for moderate exploration, "very thorough" to search across multiple locations and naming conventions) and say explicitly if the task requires reading matched files in full rather than excerpting them.
|
|
4
4
|
tools: Read, Grep, Glob, Bash, WebSearch, WebFetch
|
|
5
5
|
disallowedTools: Agent
|
|
6
|
-
model: claude-haiku-
|
|
6
|
+
model: claude-haiku-5-5
|
|
7
7
|
maxTurns: 40
|
|
8
8
|
color: cyan
|
|
9
9
|
---
|
|
@@ -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
|
|
@@ -97,8 +97,9 @@ if (isEntryPoint()) {
|
|
|
97
97
|
process.stderr.write(
|
|
98
98
|
`Blocked: CommonJS construct(s) found (this project is ESM only):\n` +
|
|
99
99
|
hits.map((h) => ` - ${h}`).join("\n") +
|
|
100
|
-
`\nUse ESM equivalents: import/export, import.meta.
|
|
101
|
-
`
|
|
100
|
+
`\nUse ESM equivalents: import/export, import.meta.dirname and ` +
|
|
101
|
+
`import.meta.filename (stable on Node 24+) in place of __dirname and ` +
|
|
102
|
+
`__filename, or fileURLToPath(import.meta.url).\n`,
|
|
102
103
|
);
|
|
103
104
|
process.exit(2);
|
|
104
105
|
}
|
|
@@ -73,13 +73,13 @@ export function buildContext(branch) {
|
|
|
73
73
|
: `on \`${branch}\``;
|
|
74
74
|
return [
|
|
75
75
|
"Decision gate (before editing code/tests) -- currently " +
|
|
76
|
-
`${branchLine}.
|
|
77
|
-
" • Branch -- `feat/<slug>` or `fix/<slug>` off `main
|
|
78
|
-
(onMain ? "
|
|
79
|
-
"
|
|
80
|
-
" • PR -- any `src/`/`tests/` change lands via PR,
|
|
81
|
-
" • Push -- `origin <branch>`, not `origin main`.",
|
|
82
|
-
"guard-branch-isolation.mjs
|
|
76
|
+
`${branchLine}. These decisions come first, ideally via the \`starting-work\` skill:`,
|
|
77
|
+
" • Branch -- a `feat/<slug>` or `fix/<slug>` branch off `main`, not `main` itself" +
|
|
78
|
+
(onMain ? "; HEAD may be on/at `main` now" : "") +
|
|
79
|
+
".",
|
|
80
|
+
" • PR -- any `src/`/`tests/` change lands via a PR, not a direct commit to `main`.",
|
|
81
|
+
" • Push -- the target is `origin <branch>`, not `origin main`.",
|
|
82
|
+
"guard-branch-isolation.mjs blocks src/test writes while HEAD is on `main`.",
|
|
83
83
|
].join("\n");
|
|
84
84
|
}
|
|
85
85
|
|
|
@@ -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
|
|
|
@@ -4,8 +4,8 @@ description: >-
|
|
|
4
4
|
Diagnose a CI failure via gh CLI: resolve the failing run, fetch logs, map the
|
|
5
5
|
failure to its pipeline step, report root cause plus the exact local repro
|
|
6
6
|
command, and present 3-5 fix options. Use for /triaging-ci, "why did CI fail",
|
|
7
|
-
"CI is failing", "
|
|
8
|
-
gh CLI.
|
|
7
|
+
"CI is failing", "the build is red", "find the root cause of a failing
|
|
8
|
+
build", "debug the CI run", or a specific run ID/URL. GitHub stance: gh CLI.
|
|
9
9
|
---
|
|
10
10
|
|
|
11
11
|
Diagnose why a GitHub Actions CI run failed by fetching its logs via `gh` and
|
|
@@ -104,7 +104,7 @@ Co-Authored-By: <exact model name from your environment> <noreply@anthropic.com>
|
|
|
104
104
|
|
|
105
105
|
**Co-Authored-By footer**: include whenever Claude authored or substantially
|
|
106
106
|
assisted the commit. Use the exact model name from the environment (e.g.,
|
|
107
|
-
`Claude Sonnet 5`, `Claude Opus 5`) — never copy a model name from an example
|
|
107
|
+
`Claude Sonnet 5.5`, `Claude Opus 5.5`) — never copy a model name from an example
|
|
108
108
|
or template. The trailer is a provenance marker, not a legal authorship
|
|
109
109
|
claim.
|
|
110
110
|
|
|
@@ -163,7 +163,7 @@ EventEmitter<TEventMap> to the public entry point.
|
|
|
163
163
|
|
|
164
164
|
Three new named exports; no existing export changed.
|
|
165
165
|
|
|
166
|
-
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
|
|
166
|
+
Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
|
|
167
167
|
```
|
|
168
168
|
|
|
169
169
|
---
|
|
@@ -215,7 +215,7 @@ the durable fixes so later modules don't re-hit them.
|
|
|
215
215
|
|
|
216
216
|
No src/, test, or exports-map changes; zero semver impact.
|
|
217
217
|
|
|
218
|
-
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
|
|
218
|
+
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
|
|
219
219
|
```
|
|
220
220
|
|
|
221
221
|
---
|
|
@@ -244,5 +244,5 @@ output/ holds run archives, not raw output; the old name was misleading.
|
|
|
244
244
|
|
|
245
245
|
BREAKING CHANGE: Paths.outputDir removed; use archiveDir instead.
|
|
246
246
|
|
|
247
|
-
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
|
|
247
|
+
Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
|
|
248
248
|
```
|
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
|
|
@@ -79,9 +79,11 @@ try {
|
|
|
79
79
|
// This project is ESM-only by design (no CommonJS -- see
|
|
80
80
|
// guard-no-commonjs.mjs); attw's default node16-from-CJS check
|
|
81
81
|
// flags exactly the interop this package intentionally doesn't
|
|
82
|
-
// support. Ignoring this one rule is
|
|
83
|
-
//
|
|
84
|
-
//
|
|
82
|
+
// support. Ignoring this one rule (`--ignore-rules`) is a narrow
|
|
83
|
+
// suppression of that known interop gap, not of a real problem. attw's
|
|
84
|
+
// documented ESM-only mechanism is the broader `--profile esm-only`,
|
|
85
|
+
// which ignores every CJS-mode resolution failure; this keeps the
|
|
86
|
+
// narrower rule on purpose so other CJS-side problems still surface.
|
|
85
87
|
"--ignore-rules",
|
|
86
88
|
"cjs-resolves-to-esm",
|
|
87
89
|
],
|
|
@@ -19,7 +19,8 @@ import { fieldList, fieldText, parseFrontmatter } from "./frontmatter.mjs";
|
|
|
19
19
|
* Model ids and aliases the rubric accepts: the current ids and aliases, plus
|
|
20
20
|
* ids that were once listed here, kept until Anthropic deprecates them. The
|
|
21
21
|
* ids follow Anthropic's models overview and model-deprecations pages
|
|
22
|
-
* (retrieved 2026-10-
|
|
22
|
+
* (retrieved 2026-10-08): Haiku 5.5 (released 2026-10-07) is current, and
|
|
23
|
+
* Haiku 4.5 is legacy but still active. A legacy id that was never listed here is
|
|
23
24
|
* deliberately not added, so the rule keeps nudging pins toward current
|
|
24
25
|
* models. Bump alongside a harness-guidance refresh sweep.
|
|
25
26
|
* @public Not imported anywhere else in this project -- exported only for
|
|
@@ -36,6 +37,7 @@ export const CURRENT_MODELS = [
|
|
|
36
37
|
"claude-sonnet-5",
|
|
37
38
|
"claude-sonnet-5-5",
|
|
38
39
|
"claude-fable-5-1",
|
|
40
|
+
"claude-haiku-5-5",
|
|
39
41
|
"claude-haiku-4-5",
|
|
40
42
|
"claude-haiku-4-5-20251001",
|
|
41
43
|
];
|
|
@@ -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`,
|