@monte3l/groundwork 1.0.3 → 1.0.5
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 +54 -12
- package/dist/assets.d.ts +22 -2
- package/dist/assets.js +40 -15
- package/dist/emit.js +3 -2
- package/dist/harness/rules.js +1 -1
- package/dist/main.js +5 -15
- package/dist/merge-json.d.ts +3 -1
- package/dist/merge-json.js +1 -1
- package/package.json +1 -1
- package/plugin/skills/customize/step-3-round-1.md +25 -17
- package/plugin/src/domain-map.ts +1 -1
- package/plugin/src/pack-map.ts +125 -44
- package/plugin/src/plugin-map.ts +1 -1
- package/templates/core/.claude/hooks/inject-decision-gate.mjs +4 -0
- package/templates/core/.claude/rules/agent-dispatch.md +46 -0
- package/templates/core/CLAUDE.md +41 -60
- package/templates/core/bin/check-exports.mjs +3 -1
- package/templates/core/bin/lib/harness-rules.mjs +1 -1
- package/templates/core/eslint.config.js +2 -0
- package/templates/core/vitest.config.ts +4 -3
- package/templates/packs/README.md +6 -3
- package/templates/packs/{github → claude-github}/files/.github/workflows/claude-pr-review.yml +1 -1
- package/templates/packs/{github → claude-github}/files/.github/workflows/claude.yml +1 -1
- package/templates/packs/claude-github/pack.json +19 -0
- package/templates/packs/github/pack.json +3 -3
- package/templates/packs/harness-extras/pack.json +3 -15
- package/templates/packs/licensing/pack.json +31 -0
- package/templates/packs/publishing/files/tools/release/_package-lock.json +914 -0
- package/templates/packs/publishing/pack.json +3 -14
- package/templates/packs/statusline/pack.json +31 -0
- package/templates/packs/supply-chain/pack.json +1 -1
- package/templates/packs/worktrees/pack.json +2 -1
- /package/templates/packs/{publishing → licensing}/files/REUSE.toml +0 -0
- /package/templates/packs/{publishing → licensing}/files/bin/check-license-headers.mjs +0 -0
- /package/templates/packs/{harness-extras → statusline}/files/.claude/hooks/statusline-layout.mjs +0 -0
- /package/templates/packs/{harness-extras → statusline}/files/.claude/hooks/statusline.mjs +0 -0
- /package/templates/packs/{harness-extras → statusline}/files/.claude/hooks/subagent-statusline.mjs +0 -0
package/README.md
CHANGED
|
@@ -44,14 +44,53 @@ Read this project's rendered docs site at
|
|
|
44
44
|
|
|
45
45
|
## Quickstart
|
|
46
46
|
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
|
|
54
|
-
|
|
47
|
+
Install [Node 24+](https://nodejs.org/), [pnpm](https://pnpm.io/installation)
|
|
48
|
+
and [Claude Code](https://docs.claude.com/en/docs/claude-code/overview) first
|
|
49
|
+
(see ["Requirements"](#requirements) below for exact versions). Nothing is
|
|
50
|
+
installed globally: `npx` and `pnpm dlx` fetch the CLI, run it once and leave
|
|
51
|
+
only a download cache behind.
|
|
52
|
+
|
|
53
|
+
**A new project.** Point the CLI at an empty or missing directory:
|
|
54
|
+
|
|
55
|
+
```bash
|
|
56
|
+
# with npx
|
|
57
|
+
npx @monte3l/groundwork my-app
|
|
58
|
+
|
|
59
|
+
# or with pnpm
|
|
60
|
+
pnpm dlx @monte3l/groundwork my-app
|
|
61
|
+
```
|
|
62
|
+
|
|
63
|
+
It writes the baseline, runs `git init` and `pnpm install`, and installs the
|
|
64
|
+
`/customize` skill. Add `--pack <name>` to install an optional
|
|
65
|
+
[pack](#packs) at the same time (`--list-packs` shows them).
|
|
66
|
+
|
|
67
|
+
**An existing project.** Run the CLI from the project's root, or pass its path.
|
|
68
|
+
It detects that the directory already looks like a project and switches to
|
|
69
|
+
adopt mode, which surveys it read-only and never overwrites a project file:
|
|
70
|
+
|
|
71
|
+
```bash
|
|
72
|
+
cd path/to/your-project
|
|
73
|
+
|
|
74
|
+
# with npx
|
|
75
|
+
npx @monte3l/groundwork .
|
|
76
|
+
|
|
77
|
+
# or with pnpm
|
|
78
|
+
pnpm dlx @monte3l/groundwork .
|
|
79
|
+
```
|
|
80
|
+
|
|
81
|
+
It writes a report and staged copies of what it would add under
|
|
82
|
+
`.groundwork/`, plus one guarded copy of the `/customize` skill.
|
|
83
|
+
|
|
84
|
+
**Then, in either case:**
|
|
85
|
+
|
|
86
|
+
```bash
|
|
87
|
+
cd my-app # or stay in your existing project
|
|
88
|
+
claude # open the project in Claude Code
|
|
89
|
+
```
|
|
90
|
+
|
|
91
|
+
Run `/customize` inside Claude Code. For a new project it interviews you and
|
|
92
|
+
tailors the baseline. For an existing one it first reconciles the survey
|
|
93
|
+
against your repo and confirms each change with you before editing anything.
|
|
55
94
|
|
|
56
95
|
> [!NOTE]
|
|
57
96
|
> Earlier releases shipped on other [dist-tags](https://github.com/monte3l/m3l-groundwork/blob/main/docs/glossary.md#dist-tag).
|
|
@@ -106,10 +145,13 @@ the wiring contract.
|
|
|
106
145
|
|
|
107
146
|
| Pack | Contents |
|
|
108
147
|
| ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
109
|
-
| `harness-extras` | The compaction-handoff hook pair
|
|
148
|
+
| `harness-extras` | The compaction-handoff hook pair and a read-only Bash guard. |
|
|
149
|
+
| `statusline` | A five-row Claude Code status line plus a per-subagent row renderer, width-fit to the terminal. Sets the `statusLine` and `subagentStatusLine` keys. |
|
|
110
150
|
| `quality` | A per-file size ratchet gate over `src/` and `tests/`, and a read-only `type-design-analyzer` review agent. Adopt-capable, recommended for every project kind. |
|
|
111
|
-
| `github`
|
|
112
|
-
| `
|
|
151
|
+
| `claude-github` | Anthropic's official Claude Code GitHub Action as two workflows: `@claude` mention-mode and an automated PR-review comment on every pull request -- no hooks, no gate. Needs an auth secret the pack cannot create, and the review spends API credits per PR. |
|
|
152
|
+
| `github` | Three `gh`-CLI skills (Dependabot PR triage, scan-alert triage, PR-check watching) -- no hooks, no gate, no workflows. |
|
|
153
|
+
| `publishing` | A release pipeline (changesets version-PR / staged, provenance-attested npm publish via trusted publishing). Fresh mode only. |
|
|
154
|
+
| `licensing` | An SPDX/REUSE license-header gate (`check-license-headers.mjs`, a `lint`-group verify step) and a `REUSE.toml` template. Fresh mode only, because the one-time backfill fails an established project's `pnpm verify`. |
|
|
113
155
|
| `supply-chain` | Secret scanning (`gitleaks.yml`) and an OpenSSF Scorecard run (`scorecard.yml`) for any GitHub project, published or not. Two workflows (read-only apart from the Scorecard job's `security-events` and `id-token` write), adopt-capable, recommended for every project kind. |
|
|
114
156
|
| `worktrees` | Enforces that all src/tests development happens inside an isolated git worktree, on any branch, for any caller: a `working-in-worktrees` skill (start/status/sync/finish/fan-out), a dependency-install backstop hook, a guard stricter than the baseline's own branch/hub guards, and a `.worktreeinclude` copying `.env`/`.env.local`/`.env.*.local` into every worktree Claude Code creates. Changes the day-to-day workflow -- opt-in, not recommended by default. |
|
|
115
157
|
|
|
@@ -276,7 +318,7 @@ everything else that goes wrong at run time.
|
|
|
276
318
|
| Unrecognized flag, missing flag value, repeated `--name`, missing or extra target argument | 2 | Prints the error and the usage text. |
|
|
277
319
|
| `--adopt` with `--fresh` | 2 | The two are mutually exclusive. |
|
|
278
320
|
| `--name` is not a valid npm package name, or a `--pack` value is not a valid pack name | 2 | Prints the rule it broke and the usage text. |
|
|
279
|
-
| Unknown `--pack` | 2 | Lists the available packs.
|
|
321
|
+
| Unknown `--pack` | 2 | Lists the available packs. |
|
|
280
322
|
| `--pack` for a pack without fresh mode | 2 | Says the pack does not support fresh mode and lists its modes. |
|
|
281
323
|
| Adopt mode with `--adopt` and a missing target directory, `--force` or `--pack` | 2 | Adopt never writes project files and surveys every pack itself; run `/customize` to install a pack. |
|
|
282
324
|
| Windows, fresh mode | 1 | Refuses before writing anything: Linux and macOS only. Adopt mode, `--help`, `--version` and `--list-packs` still run. |
|
package/dist/assets.d.ts
CHANGED
|
@@ -5,9 +5,29 @@ export interface AssetPaths {
|
|
|
5
5
|
/** Path from the package root, in a published tarball. */
|
|
6
6
|
local: string;
|
|
7
7
|
}
|
|
8
|
-
/**
|
|
8
|
+
/**
|
|
9
|
+
* The vendored spelling of a name npm strips: `.gitignore` becomes
|
|
10
|
+
* `_gitignore` and `package-lock.json` becomes `_package-lock.json`; every
|
|
11
|
+
* other name is unchanged.
|
|
12
|
+
*
|
|
13
|
+
* @example
|
|
14
|
+
* ```ts
|
|
15
|
+
* escapeDotfileName(".npmrc"); // "_npmrc"
|
|
16
|
+
* escapeDotfileName("package.json"); // "package.json"
|
|
17
|
+
* ```
|
|
18
|
+
*/
|
|
9
19
|
export declare function escapeDotfileName(name: string): string;
|
|
10
|
-
/**
|
|
20
|
+
/**
|
|
21
|
+
* Inverse of `escapeDotfileName`: `_gitignore` becomes `.gitignore` and
|
|
22
|
+
* `_package-lock.json` becomes `package-lock.json`; every other name is
|
|
23
|
+
* unchanged.
|
|
24
|
+
*
|
|
25
|
+
* @example
|
|
26
|
+
* ```ts
|
|
27
|
+
* restoreDotfileName("_package-lock.json"); // "package-lock.json"
|
|
28
|
+
* restoreDotfileName("_package.json"); // "_package.json"
|
|
29
|
+
* ```
|
|
30
|
+
*/
|
|
11
31
|
export declare function restoreDotfileName(name: string): string;
|
|
12
32
|
/** `restoreDotfileName` applied to the final segment of a `/`- or `\`-separated relative path. */
|
|
13
33
|
export declare function restoreDotfilePath(relPath: string): string;
|
package/dist/assets.js
CHANGED
|
@@ -20,25 +20,50 @@ import { existsSync, readFileSync } from "node:fs";
|
|
|
20
20
|
import { dirname, join } from "node:path";
|
|
21
21
|
import { fileURLToPath } from "node:url";
|
|
22
22
|
/**
|
|
23
|
-
*
|
|
24
|
-
* (`pnpm pack` keeps `.gitignore`, `npm pack` drops it; both
|
|
25
|
-
*
|
|
26
|
-
*
|
|
23
|
+
* File names npm-family tooling strips from a tarball, at any depth, no matter
|
|
24
|
+
* what `files` says (`pnpm pack` keeps `.gitignore`, `npm pack` drops it; both
|
|
25
|
+
* drop `.npmrc` and `package-lock.json`), each paired with the escaped name
|
|
26
|
+
* the vendored copy stores it under. A dotfile's escape replaces its leading
|
|
27
|
+
* dot with `_`; `package-lock.json` has no dot to replace, so it gains a `_`
|
|
28
|
+
* prefix. The walkers (`emit.ts`, `conflicts.ts`, `staging.ts`) restore the
|
|
29
|
+
* real name on the way out. `templates/core/package.json` is not escaped:
|
|
30
|
+
* npm never strips a `package.json`.
|
|
31
|
+
*/
|
|
32
|
+
const ESCAPED_NAMES = new Map([
|
|
33
|
+
[".gitignore", "_gitignore"],
|
|
34
|
+
[".npmrc", "_npmrc"],
|
|
35
|
+
[".npmignore", "_npmignore"],
|
|
36
|
+
["package-lock.json", "_package-lock.json"],
|
|
37
|
+
]);
|
|
38
|
+
/** Escaped name to real name: the inverse of {@link ESCAPED_NAMES}. */
|
|
39
|
+
const RESTORED_NAMES = new Map([...ESCAPED_NAMES].map(([real, escaped]) => [escaped, real]));
|
|
40
|
+
/**
|
|
41
|
+
* The vendored spelling of a name npm strips: `.gitignore` becomes
|
|
42
|
+
* `_gitignore` and `package-lock.json` becomes `_package-lock.json`; every
|
|
43
|
+
* other name is unchanged.
|
|
44
|
+
*
|
|
45
|
+
* @example
|
|
46
|
+
* ```ts
|
|
47
|
+
* escapeDotfileName(".npmrc"); // "_npmrc"
|
|
48
|
+
* escapeDotfileName("package.json"); // "package.json"
|
|
49
|
+
* ```
|
|
27
50
|
*/
|
|
28
|
-
const ESCAPED_DOTFILES = [".gitignore", ".npmrc", ".npmignore"];
|
|
29
|
-
/** The vendored spelling of a stripped dotfile: `.gitignore` becomes `_gitignore`. */
|
|
30
51
|
export function escapeDotfileName(name) {
|
|
31
|
-
return
|
|
32
|
-
? `_${name.slice(1)}`
|
|
33
|
-
: name;
|
|
52
|
+
return ESCAPED_NAMES.get(name) ?? name;
|
|
34
53
|
}
|
|
35
|
-
/**
|
|
54
|
+
/**
|
|
55
|
+
* Inverse of `escapeDotfileName`: `_gitignore` becomes `.gitignore` and
|
|
56
|
+
* `_package-lock.json` becomes `package-lock.json`; every other name is
|
|
57
|
+
* unchanged.
|
|
58
|
+
*
|
|
59
|
+
* @example
|
|
60
|
+
* ```ts
|
|
61
|
+
* restoreDotfileName("_package-lock.json"); // "package-lock.json"
|
|
62
|
+
* restoreDotfileName("_package.json"); // "_package.json"
|
|
63
|
+
* ```
|
|
64
|
+
*/
|
|
36
65
|
export function restoreDotfileName(name) {
|
|
37
|
-
|
|
38
|
-
return name.startsWith("_") &&
|
|
39
|
-
ESCAPED_DOTFILES.includes(restored)
|
|
40
|
-
? restored
|
|
41
|
-
: name;
|
|
66
|
+
return RESTORED_NAMES.get(name) ?? name;
|
|
42
67
|
}
|
|
43
68
|
/** `restoreDotfileName` applied to the final segment of a `/`- or `\`-separated relative path. */
|
|
44
69
|
export function restoreDotfilePath(relPath) {
|
package/dist/emit.js
CHANGED
|
@@ -4,8 +4,9 @@
|
|
|
4
4
|
* Copies `templates/core` into a target directory, applying token
|
|
5
5
|
* substitution to both file contents and path segments (so a token in a
|
|
6
6
|
* directory or file NAME, not just its content, is honored). A published
|
|
7
|
-
* tarball stores `.gitignore`/`.npmrc` as
|
|
8
|
-
* the real names);
|
|
7
|
+
* tarball stores `.gitignore`/`.npmrc`/`package-lock.json` as
|
|
8
|
+
* `_gitignore`/`_npmrc`/`_package-lock.json` (npm strips the real names);
|
|
9
|
+
* they are restored here -- see `assets.ts`.
|
|
9
10
|
*
|
|
10
11
|
* Every destination path is planned and `lstat`-checked before the first
|
|
11
12
|
* write ({@link assertSafeEmitDestinations}), so a symlink or a misplaced
|
package/dist/harness/rules.js
CHANGED
|
@@ -473,7 +473,7 @@ const descriptionSubstance = {
|
|
|
473
473
|
else if (description.length > DESCRIPTION_MAX) {
|
|
474
474
|
failures.push({
|
|
475
475
|
subject,
|
|
476
|
-
message: `description is ${description.length} chars; over ${DESCRIPTION_MAX}
|
|
476
|
+
message: `description is ${description.length} chars; over the ${DESCRIPTION_MAX}-char Agent Skills maximum (Claude Code also truncates description + when_to_use at 1,536 in its skill listing)`,
|
|
477
477
|
});
|
|
478
478
|
}
|
|
479
479
|
};
|
package/dist/main.js
CHANGED
|
@@ -389,28 +389,18 @@ function describeInstallFailure(error) {
|
|
|
389
389
|
return `\`pnpm install\` failed (${code})`;
|
|
390
390
|
return "`pnpm install` failed";
|
|
391
391
|
}
|
|
392
|
-
// A pack that was renamed or folded into another, mapped to its successor so
|
|
393
|
-
// an old `--pack` name gets a pointed hint rather than a bare "unknown pack".
|
|
394
|
-
const RENAMED_PACKS = new Map([
|
|
395
|
-
["statusline", "harness-extras"],
|
|
396
|
-
]);
|
|
397
392
|
/**
|
|
398
393
|
* Loads one `--pack` for fresh mode -- called for every pack before any file
|
|
399
|
-
* is written. An unknown name (
|
|
400
|
-
*
|
|
401
|
-
*
|
|
402
|
-
*
|
|
403
|
-
* not a bad invocation.
|
|
394
|
+
* is written. An unknown name (the message lists the available packs) or a
|
|
395
|
+
* fresh-incompatible pack is a usage error (exit 2); a pack that exists but
|
|
396
|
+
* whose manifest fails to load propagates `loadPack`'s own error unchanged
|
|
397
|
+
* (exit 1), since that is a broken install, not a bad invocation.
|
|
404
398
|
*/
|
|
405
399
|
function resolveFreshPack(name) {
|
|
406
400
|
const available = listPackNames();
|
|
407
401
|
if (!available.includes(name)) {
|
|
408
|
-
const successor = RENAMED_PACKS.get(name);
|
|
409
|
-
const hint = successor === undefined
|
|
410
|
-
? ""
|
|
411
|
-
: ` -- it was renamed to "${successor}"; use --pack ${successor}`;
|
|
412
402
|
const list = available.length > 0 ? available.join(", ") : "none";
|
|
413
|
-
throw new CliUsageError(`unknown pack "${name}"
|
|
403
|
+
throw new CliUsageError(`unknown pack "${name}" (available: ${list})\n\n${USAGE}`);
|
|
414
404
|
}
|
|
415
405
|
const pack = loadPack(name);
|
|
416
406
|
if (!pack.manifest.modes.includes("fresh")) {
|
package/dist/merge-json.d.ts
CHANGED
|
@@ -46,6 +46,8 @@ interface SettingsHookCommand {
|
|
|
46
46
|
command: string;
|
|
47
47
|
if?: string;
|
|
48
48
|
timeout?: number;
|
|
49
|
+
/** Hook failure policy (Claude Code 2.1.295+); defaults to `"continue"`. */
|
|
50
|
+
onFailure?: "continue" | "block";
|
|
49
51
|
}
|
|
50
52
|
interface SettingsHookEntry {
|
|
51
53
|
matcher?: string;
|
|
@@ -58,7 +60,7 @@ export type SettingsHooksFragment = Record<string, SettingsHookEntry[]>;
|
|
|
58
60
|
* counts as a match -- e.g. `PreCompact`, which has none); within a matched
|
|
59
61
|
* entry, only `hooks` commands not already present (compared by exact
|
|
60
62
|
* `command` string) are appended. A command that matches on `command` but
|
|
61
|
-
* differs in its other fields (`if`, `timeout`) is a hard collision, never
|
|
63
|
+
* differs in its other fields (`if`, `timeout`, `onFailure`) is a hard collision, never
|
|
62
64
|
* a silent overwrite. An event name of `__proto__`, `constructor` or
|
|
63
65
|
* `prototype` throws: the check runs per key inside the loop, before that
|
|
64
66
|
* key is read or written, and nothing escapes the failed merge -- `existing`
|
package/dist/merge-json.js
CHANGED
|
@@ -110,7 +110,7 @@ function assertSafeKey(key, context) {
|
|
|
110
110
|
* counts as a match -- e.g. `PreCompact`, which has none); within a matched
|
|
111
111
|
* entry, only `hooks` commands not already present (compared by exact
|
|
112
112
|
* `command` string) are appended. A command that matches on `command` but
|
|
113
|
-
* differs in its other fields (`if`, `timeout`) is a hard collision, never
|
|
113
|
+
* differs in its other fields (`if`, `timeout`, `onFailure`) is a hard collision, never
|
|
114
114
|
* a silent overwrite. An event name of `__proto__`, `constructor` or
|
|
115
115
|
* `prototype` throws: the check runs per key inside the loop, before that
|
|
116
116
|
* key is read or written, and nothing escapes the failed merge -- `existing`
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@monte3l/groundwork",
|
|
3
|
-
"version": "1.0.
|
|
3
|
+
"version": "1.0.5",
|
|
4
4
|
"description": "CLI that bootstraps a TypeScript project with a strict toolchain and Claude Code setup, or read-only surveys an existing one, plus a /customize plugin that tailors it to current guidance.",
|
|
5
5
|
"keywords": [
|
|
6
6
|
"bootstrap",
|
|
@@ -61,18 +61,21 @@ confirmed in Step 0.4:
|
|
|
61
61
|
`recommendPacks(answers)` from `pack-map.ts` (alongside this file, same
|
|
62
62
|
copy mechanism as `kind-facet-map.ts`) with the now-confirmed
|
|
63
63
|
`InterviewAnswers` and compare its verdict against Step 0.4's decision.
|
|
64
|
-
`harness-extras`, `github`, `
|
|
65
|
-
never disagree (none of the
|
|
66
|
-
answer -- `worktrees` is always
|
|
67
|
-
day-to-day workflow rather than
|
|
68
|
-
|
|
69
|
-
|
|
64
|
+
`harness-extras`, `statusline`, `github`, `claude-github`, `supply-chain`,
|
|
65
|
+
`quality`, and `worktrees` never disagree (none of the seven's
|
|
66
|
+
recommendation varies by kind or answer -- `worktrees` is always
|
|
67
|
+
`recommended: false`, since it changes the day-to-day workflow rather than
|
|
68
|
+
adding a nicety, and `claude-github` is always `recommended: false`, since
|
|
69
|
+
its workflows need an auth secret and the review spends API credits on
|
|
70
|
+
every PR; the other five are always `recommended: true`), but `publishing`'s and `licensing`'s do (each
|
|
71
|
+
recommended for `library`/`cli`, not for `frontend`/`service`) — if the comparison surfaces a real
|
|
70
72
|
conflict there or for any future kind-scoped pack, raise it rather than
|
|
71
73
|
silently overriding the user's Step 0.4 answer, mirroring Step 4's "the
|
|
72
74
|
one exception" rule for guidance findings. Before installing, check the
|
|
73
75
|
pack's own `modes`: a pack whose `modes` doesn't include `"adopt"` (today,
|
|
74
76
|
`publishing` — its release flow encodes decisions too project-specific to
|
|
75
|
-
apply blind
|
|
77
|
+
apply blind — and `licensing`, whose one-time SPDX header backfill fails an
|
|
78
|
+
established project's `pnpm verify`) is never auto-installed here even if staged and approved;
|
|
76
79
|
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
80
|
there for that pack. Before merging any staged `pack.json.staged` wiring, repeat
|
|
78
81
|
the prototype-key check from Step 0.4(c): if a key of `wiring.settings`,
|
|
@@ -90,20 +93,23 @@ confirmed in Step 0.4:
|
|
|
90
93
|
from `pack.json.staged` (the bytes Step 0.1 read) for a schema 5 or later inventory and
|
|
91
94
|
from the unsuffixed `pack.json` for schema 1-4,
|
|
92
95
|
against what Step 0.2's deep read already found — a `.claude/settings.json`
|
|
93
|
-
hook fragment merges the same way the baseline's own hook entries would;
|
|
96
|
+
hook fragment merges the same way the baseline's own hook entries would, and when the project already registers the same hook `command` (a pack installed before it gained a key such as `onFailure`), add only the keys the fragment has and the existing registration lacks, keep every field the project already sets, and ask before changing a key both define with a different value (the CLI's `mergeSettingsHooks` never overwrites one);
|
|
94
97
|
`wiring.settingsTopLevel` is a set of top-level keys (e.g. `statusLine`)
|
|
95
98
|
planted whole, and only when the project doesn't already define that key —
|
|
96
99
|
when it does, show the existing value and ask, since the CLI's own
|
|
97
100
|
`mergeSettingsTopLevel` treats a differing value as a hard error and this
|
|
98
101
|
hand-applied path must not be laxer than the automated one (also check
|
|
99
102
|
`.claude/settings.local.json` and the user's `~/.claude/settings.json`,
|
|
100
|
-
either of which can shadow a project `statusLine`). For `
|
|
103
|
+
either of which can shadow a project `statusLine`). For `statusline`
|
|
101
104
|
specifically, a `statusLine`/`subagentStatusLine` collision is never a
|
|
102
|
-
reason to fail the whole pack install: skip just
|
|
103
|
-
|
|
104
|
-
`subagent-statusline.mjs`
|
|
105
|
-
|
|
106
|
-
|
|
105
|
+
reason to fail the whole pack install: skip just the colliding key and the
|
|
106
|
+
script that renders it (`statusline.mjs` for `statusLine`,
|
|
107
|
+
`subagent-statusline.mjs` for `subagentStatusLine`; `statusline-layout.mjs`
|
|
108
|
+
stays while either remains), install the other key normally, and skip the
|
|
109
|
+
whole pack only when both keys are already set, stating the skip plainly in
|
|
110
|
+
Step 7. The pack is separate from `harness-extras` for exactly this reason,
|
|
111
|
+
so a skipped status line never costs the compaction-handoff hooks or
|
|
112
|
+
`guard-readonly-bash`. For `harness-extras`, `guard-readonly-bash.mjs` imports
|
|
107
113
|
`bin/lib/agent-roster.mjs`: when the project keeps no agents and that file is
|
|
108
114
|
not being installed, skip that one hook too (the pack's `adoptNotes` allow
|
|
109
115
|
it), record it in `round1.dropped` and say in Step 7 that it was skipped and
|
|
@@ -142,9 +148,11 @@ any reason goes into `round1.dropped` with that reason.
|
|
|
142
148
|
`PluginRecommendationContext`: `chosenPacks` is whatever the packs decision
|
|
143
149
|
just above actually landed on (fresh: what `--pack` installed at bootstrap
|
|
144
150
|
time, detectable from the installed files -- e.g. `.changeset/config.json`
|
|
145
|
-
means `publishing`, `.
|
|
146
|
-
(the only marker `plugin-map.ts` actually reads; `
|
|
147
|
-
|
|
151
|
+
means `publishing`, `.claude/skills/watching-pr-checks/SKILL.md` means `github`
|
|
152
|
+
(the only marker `plugin-map.ts` actually reads; the `claude-github` pack's
|
|
153
|
+
`.github/workflows/claude-pr-review.yml` needs no marker, since no plugin
|
|
154
|
+
varies by its presence; `harness-extras` and `statusline` have
|
|
155
|
+
no plugin that varies by their presence, so they need no marker here); adopt: the
|
|
148
156
|
packs Step 0.4(c) confirmed, revised by this step's own `recommendPacks`
|
|
149
157
|
comparison if it changed anything); `hasCustomSkills` is `false` for a fresh
|
|
150
158
|
bootstrap (nothing has authored a skill yet) and, for adopt mode, whatever
|
package/plugin/src/domain-map.ts
CHANGED
|
@@ -88,7 +88,7 @@ export const TYPESCRIPT_DOMAIN_GLOBS = [
|
|
|
88
88
|
* `bin/lib/*.mjs` are typescript-domain globs, so without this list the
|
|
89
89
|
* grader's own rules would be swept by `typescript-guidance` -- wrong,
|
|
90
90
|
* because they encode Claude Code harness guidance. The Claude Code Action
|
|
91
|
-
* workflows (`claude.yml`, and the `github` pack's automated-review
|
|
91
|
+
* workflows (`claude.yml`, and the `claude-github` pack's automated-review
|
|
92
92
|
* `claude-pr-review.yml`) are here for the same reason against
|
|
93
93
|
* `.github/workflows/*.yml`: their trigger, action pin and model choice are
|
|
94
94
|
* Anthropic guidance, not toolchain. Consulted before the typescript list in
|
package/plugin/src/pack-map.ts
CHANGED
|
@@ -19,43 +19,61 @@ export interface PackRecommendation {
|
|
|
19
19
|
}
|
|
20
20
|
|
|
21
21
|
/**
|
|
22
|
-
* `harness-extras`'s remaining artifacts (the compaction-handoff hook pair
|
|
23
|
-
*
|
|
22
|
+
* `harness-extras`'s remaining artifacts (the compaction-handoff hook pair,
|
|
23
|
+
* which carries a work summary across a compaction, and a read-only Bash
|
|
24
|
+
* guard for review spokes) are harness-level, not domain-level -- they
|
|
24
25
|
* apply to any TypeScript project regardless of what it's building. The
|
|
25
26
|
* type-design-analyzer agent and the file-budget gate it once also carried
|
|
26
|
-
* now live in the separate `quality` pack
|
|
27
|
-
*
|
|
28
|
-
* `node:fs`, never a `git` subprocess) and `os.freemem()`/`os.totalmem()`,
|
|
29
|
-
* and `statusLine` is the only documented surface carrying live
|
|
30
|
-
* `context_window.used_percentage`: no hook event receives token or context
|
|
31
|
-
* data, so "when to compact" can live nowhere else.
|
|
27
|
+
* now live in the separate `quality` pack, and its status-line scripts in
|
|
28
|
+
* the separate `statusline` pack.
|
|
32
29
|
*/
|
|
33
30
|
function recommendHarnessExtras(): PackRecommendation {
|
|
34
31
|
return {
|
|
35
32
|
name: "harness-extras",
|
|
36
33
|
recommended: true,
|
|
37
34
|
because:
|
|
38
|
-
"its compaction-handoff hooks (which carry work across a
|
|
39
|
-
"compaction) and read-only Bash guard
|
|
40
|
-
"to any particular project kind
|
|
41
|
-
"statusLine is the only surface that exposes live context-window " +
|
|
42
|
-
"pressure -- no hook event receives token data -- and reads only the " +
|
|
43
|
-
"stdin payload plus local git and memory state. It does occupy five " +
|
|
44
|
-
"terminal rows (session, model, context, quota, work).",
|
|
35
|
+
"its compaction-handoff hooks (which carry a work summary across a " +
|
|
36
|
+
"compaction) and its read-only Bash guard for review spokes are " +
|
|
37
|
+
"harness-level, not tied to any particular project kind.",
|
|
45
38
|
};
|
|
46
39
|
}
|
|
47
40
|
|
|
48
41
|
/**
|
|
49
|
-
* `
|
|
50
|
-
*
|
|
51
|
-
*
|
|
52
|
-
*
|
|
53
|
-
*
|
|
42
|
+
* `statusline` is the five-row `statusLine` script (session, model,
|
|
43
|
+
* context, quota, work) plus a per-subagent row renderer, carved out of
|
|
44
|
+
* `harness-extras`. Its scripts read only the stdin payload, `.git/HEAD`
|
|
45
|
+
* (via `node:fs`, never a `git` subprocess) and
|
|
46
|
+
* `os.freemem()`/`os.totalmem()`, and `statusLine` is the only documented
|
|
47
|
+
* surface carrying live `context_window.used_percentage`: no hook event
|
|
48
|
+
* receives token or context data, so "when to compact" can live nowhere
|
|
49
|
+
* else. That is harness-level, so it is recommended for every project
|
|
50
|
+
* kind. In adopt mode a project that already defines `statusLine` or
|
|
51
|
+
* `subagentStatusLine` keeps its own value -- it is never overwritten, so
|
|
52
|
+
* the owner decides which one to run.
|
|
53
|
+
*/
|
|
54
|
+
function recommendStatusline(): PackRecommendation {
|
|
55
|
+
return {
|
|
56
|
+
name: "statusline",
|
|
57
|
+
recommended: true,
|
|
58
|
+
because:
|
|
59
|
+
"its five-row statusLine (session, model, context, quota, work) plus " +
|
|
60
|
+
"a per-subagent row renderer is the only surface that exposes live " +
|
|
61
|
+
"context-window pressure -- no hook event receives token data -- and " +
|
|
62
|
+
"reads only the stdin payload plus local git and memory state. It " +
|
|
63
|
+
"does occupy five terminal rows. A project that already defines " +
|
|
64
|
+
"statusLine or subagentStatusLine keeps its own value (it is never " +
|
|
65
|
+
"overwritten) and must decide which one to run.",
|
|
66
|
+
};
|
|
67
|
+
}
|
|
68
|
+
|
|
69
|
+
/**
|
|
70
|
+
* `github` is three GitHub-operations skills driven by the `gh` CLI:
|
|
54
71
|
* `reviewing-dependabot-prs` (classifies and batch-merges open Dependabot
|
|
55
72
|
* PRs), `triaging-scan-alerts` (triages open code-scanning alerts to
|
|
56
|
-
* file:line) and `watching-pr-checks`. It
|
|
57
|
-
*
|
|
58
|
-
*
|
|
73
|
+
* file:line) and `watching-pr-checks`. It assumes only GitHub, which this
|
|
74
|
+
* baseline's whole toolchain (CI, Dependency Review, rulesets) already does
|
|
75
|
+
* -- nothing about any project kind -- and needs only `gh` CLI auth, so it
|
|
76
|
+
* is recommended for every kind.
|
|
59
77
|
*/
|
|
60
78
|
function recommendGithub(): PackRecommendation {
|
|
61
79
|
return {
|
|
@@ -63,22 +81,43 @@ function recommendGithub(): PackRecommendation {
|
|
|
63
81
|
recommended: true,
|
|
64
82
|
because:
|
|
65
83
|
"the baseline's toolchain already assumes GitHub (CI, Dependency " +
|
|
66
|
-
"Review, rulesets), so
|
|
67
|
-
"
|
|
68
|
-
"
|
|
69
|
-
"
|
|
70
|
-
"
|
|
71
|
-
"triaging open code-scanning alerts to file:line " +
|
|
72
|
-
"(triaging-scan-alerts) and watching a PR's checks " +
|
|
73
|
-
"(watching-pr-checks). It does add two GitHub Actions workflows and " +
|
|
74
|
-
"needs an auth secret configured by hand -- the pack cannot create it.",
|
|
84
|
+
"Review, rulesets), so its gh-CLI skills apply to any project kind: " +
|
|
85
|
+
"classifying and batch-merging open Dependabot PRs " +
|
|
86
|
+
"(reviewing-dependabot-prs), triaging open code-scanning alerts to " +
|
|
87
|
+
"file:line (triaging-scan-alerts) and watching a PR's checks " +
|
|
88
|
+
"(watching-pr-checks). It needs only gh CLI auth.",
|
|
75
89
|
};
|
|
76
90
|
}
|
|
77
91
|
|
|
78
92
|
/**
|
|
79
|
-
* `
|
|
93
|
+
* `claude-github` is Anthropic's Claude Code GitHub Action as two
|
|
94
|
+
* workflows: `claude.yml` (mention-mode, answering `@claude` in issues and
|
|
95
|
+
* PRs) and `claude-pr-review.yml` (an automated Claude review comment on
|
|
96
|
+
* every PR). It needs an auth secret (`ANTHROPIC_API_KEY` or a Claude
|
|
97
|
+
* subscription OAuth token) configured by hand, since the pack cannot
|
|
98
|
+
* create it, and the review workflow spends API credits on every PR. That
|
|
99
|
+
* is a cost and setup decision no interview answer can infer, so it is
|
|
100
|
+
* opt-in for every project kind -- but it stays on offer.
|
|
101
|
+
*/
|
|
102
|
+
function recommendClaudeGithub(): PackRecommendation {
|
|
103
|
+
return {
|
|
104
|
+
name: "claude-github",
|
|
105
|
+
recommended: false,
|
|
106
|
+
because:
|
|
107
|
+
"it adds Anthropic's Claude Code GitHub Action as two workflows: " +
|
|
108
|
+
"@claude mention-mode (claude.yml) and an automated Claude review " +
|
|
109
|
+
"comment on every PR (claude-pr-review.yml). It needs an auth secret " +
|
|
110
|
+
"(ANTHROPIC_API_KEY or a Claude subscription OAuth token) configured " +
|
|
111
|
+
"by hand -- the pack cannot create it -- and the review workflow " +
|
|
112
|
+
"spends API credits on every PR, so it is opt-in.",
|
|
113
|
+
};
|
|
114
|
+
}
|
|
115
|
+
|
|
116
|
+
/**
|
|
117
|
+
* `publishing` is a kind-scoped pack: a release pipeline (a changesets
|
|
80
118
|
* version PR, then a staged, provenance-attested npm publish via trusted
|
|
81
|
-
* publishing) plus
|
|
119
|
+
* publishing) plus a gate that the published type declarations' dependencies
|
|
120
|
+
* are installable by consumers (dts-deps). Secret scanning and OpenSSF
|
|
82
121
|
* Scorecard are not part of it -- they are the separate `supply-chain` pack,
|
|
83
122
|
* since they apply to any repo, published or not. A `library` or `cli`
|
|
84
123
|
* typically publishes an npm package; a
|
|
@@ -95,12 +134,13 @@ function recommendPublishing(answers: InterviewAnswers): PackRecommendation {
|
|
|
95
134
|
because: recommended
|
|
96
135
|
? "a library or CLI typically ships an npm package, so this pack's " +
|
|
97
136
|
"release pipeline applies: a changesets version PR, then a staged, " +
|
|
98
|
-
"provenance-attested npm publish via trusted publishing
|
|
99
|
-
"
|
|
100
|
-
"
|
|
101
|
-
"
|
|
102
|
-
"
|
|
103
|
-
"
|
|
137
|
+
"provenance-attested npm publish via trusted publishing, with a " +
|
|
138
|
+
"dts-deps gate that the published type declarations' dependencies " +
|
|
139
|
+
"resolve for consumers. The repository-hygiene scans that apply to " +
|
|
140
|
+
"any project, published or not, are the separate supply-chain " +
|
|
141
|
+
"pack. It is fresh-mode only and needs one-time npm and GitHub " +
|
|
142
|
+
"setup (the trusted publisher, the release credentials) the pack " +
|
|
143
|
+
"cannot do itself."
|
|
104
144
|
: "a frontend or service is typically deployed, and a Claude Code " +
|
|
105
145
|
"plugin ships through a marketplace manifest, rather than published " +
|
|
106
146
|
"to a package registry, so a changesets/npm release pipeline is not " +
|
|
@@ -109,6 +149,38 @@ function recommendPublishing(answers: InterviewAnswers): PackRecommendation {
|
|
|
109
149
|
};
|
|
110
150
|
}
|
|
111
151
|
|
|
152
|
+
/**
|
|
153
|
+
* `licensing` is the half carved out of `publishing`: an SPDX/REUSE
|
|
154
|
+
* license-header gate (`check-license-headers`) plus a `REUSE.toml`
|
|
155
|
+
* template. Licensing metadata matters most for code that is distributed,
|
|
156
|
+
* so it is pre-selected for a `library` or `cli`, the same kinds
|
|
157
|
+
* `publishing` targets -- but it is independent of `publishing` and stays
|
|
158
|
+
* on offer for every kind. It is fresh-mode only: an established project
|
|
159
|
+
* fails `pnpm verify` until the one-time backfill (`git add -A`, then
|
|
160
|
+
* `node bin/check-license-headers.mjs --fix`) has touched every file.
|
|
161
|
+
*/
|
|
162
|
+
function recommendLicensing(answers: InterviewAnswers): PackRecommendation {
|
|
163
|
+
const recommended = answers.kind === "library" || answers.kind === "cli";
|
|
164
|
+
return {
|
|
165
|
+
name: "licensing",
|
|
166
|
+
recommended,
|
|
167
|
+
because: recommended
|
|
168
|
+
? "a library or CLI is distributed, which is where licensing metadata " +
|
|
169
|
+
"matters most, so this pack's SPDX/REUSE license-header gate and " +
|
|
170
|
+
"REUSE.toml template apply. It is independent of the publishing " +
|
|
171
|
+
"pack. It is fresh-mode only: the one-time backfill (git add -A, " +
|
|
172
|
+
"then node bin/check-license-headers.mjs --fix) has to touch every " +
|
|
173
|
+
"file before pnpm verify passes, which an established project " +
|
|
174
|
+
"would fail until then."
|
|
175
|
+
: "a frontend, service or Claude Code plugin is less often " +
|
|
176
|
+
"redistributed as source, so an SPDX/REUSE license-header gate is " +
|
|
177
|
+
"not recommended by default -- it is still available, independent " +
|
|
178
|
+
"of the publishing pack. It is fresh-mode only: the one-time " +
|
|
179
|
+
"backfill (git add -A, then node bin/check-license-headers.mjs " +
|
|
180
|
+
"--fix) has to touch every file before pnpm verify passes.",
|
|
181
|
+
};
|
|
182
|
+
}
|
|
183
|
+
|
|
112
184
|
/**
|
|
113
185
|
* `worktrees` is opt-in for every project kind: rather than adding a
|
|
114
186
|
* nicety on top of the existing workflow, it changes the workflow itself --
|
|
@@ -170,18 +242,27 @@ function recommendQuality(): PackRecommendation {
|
|
|
170
242
|
}
|
|
171
243
|
|
|
172
244
|
/**
|
|
173
|
-
* Every pack's recommendation for the given interview answers.
|
|
174
|
-
*
|
|
175
|
-
* `supply-chain` and `quality`
|
|
176
|
-
*
|
|
245
|
+
* Every pack's recommendation for the given interview answers. Two packs
|
|
246
|
+
* vary by `answers.kind` today, `publishing` and `licensing`;
|
|
247
|
+
* `harness-extras`, `statusline`, `github`, `supply-chain` and `quality`
|
|
248
|
+
* are recommended for every kind, and `claude-github` and `worktrees` are
|
|
249
|
+
* opt-in for every kind.
|
|
250
|
+
*
|
|
251
|
+
* @example
|
|
252
|
+
* ```ts
|
|
253
|
+
* const picks = recommendPacks(answers).filter((r) => r.recommended);
|
|
254
|
+
* ```
|
|
177
255
|
*/
|
|
178
256
|
export function recommendPacks(
|
|
179
257
|
answers: InterviewAnswers,
|
|
180
258
|
): PackRecommendation[] {
|
|
181
259
|
return [
|
|
182
260
|
recommendHarnessExtras(),
|
|
261
|
+
recommendStatusline(),
|
|
183
262
|
recommendGithub(),
|
|
263
|
+
recommendClaudeGithub(),
|
|
184
264
|
recommendPublishing(answers),
|
|
265
|
+
recommendLicensing(answers),
|
|
185
266
|
recommendWorktrees(),
|
|
186
267
|
recommendSupplyChain(),
|
|
187
268
|
recommendQuality(),
|
package/plugin/src/plugin-map.ts
CHANGED
|
@@ -20,7 +20,7 @@
|
|
|
20
20
|
* again:
|
|
21
21
|
*
|
|
22
22
|
* - `code-review` -- duplicates the built-in `/code-review` and the optional
|
|
23
|
-
* `github` pack's PR-review Action.
|
|
23
|
+
* `claude-github` pack's PR-review Action.
|
|
24
24
|
* - `code-simplifier` -- duplicates the built-in `/simplify`; its
|
|
25
25
|
* unrestricted-tools agent is blocked by the baseline's hub-and-spoke
|
|
26
26
|
* write guard on `src/`/`tests/` anyway.
|