@monte3l/groundwork 1.0.4 → 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/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/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/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.
|
|
@@ -11,6 +11,10 @@
|
|
|
11
11
|
* instead of being discovered when `guard-branch-isolation.mjs` blocks a
|
|
12
12
|
* src/test write on `main`.
|
|
13
13
|
*
|
|
14
|
+
* It sees the line as typed: Claude Code runs `UserPromptSubmit` hooks before
|
|
15
|
+
* a skill or slash command expands (2.1.299), so `/creating-prs fix the lint`
|
|
16
|
+
* is judged on those words, and a bare `/starting-work` carries no change verb.
|
|
17
|
+
*
|
|
14
18
|
* It is advisory: it emits `additionalContext` and exits 0. It never blocks.
|
|
15
19
|
* The heuristic is deliberately loose (inject on any change-intent verb,
|
|
16
20
|
* stay quiet on obvious reads) -- a spurious reminder is cheap; a missed one
|
|
@@ -36,6 +36,52 @@ auto, `acceptEdits` or `bypassPermissions` mode overrides a spoke's
|
|
|
36
36
|
guards bound a spoke, not `permissionMode`. Source:
|
|
37
37
|
[sub-agents](https://code.claude.com/docs/en/sub-agents).
|
|
38
38
|
|
|
39
|
+
## Guard limits and overrides (detail)
|
|
40
|
+
|
|
41
|
+
Sources: [hooks](https://code.claude.com/docs/en/hooks),
|
|
42
|
+
[hooks guide](https://code.claude.com/docs/en/hooks-guide),
|
|
43
|
+
[managed settings](https://code.claude.com/docs/en/managed-settings),
|
|
44
|
+
[mods events](https://code.claude.com/docs/en/plugins/mods/events),
|
|
45
|
+
[sub-agents](https://code.claude.com/docs/en/sub-agents) and
|
|
46
|
+
[agent teams](https://code.claude.com/docs/en/agent-teams).
|
|
47
|
+
|
|
48
|
+
- **The `Bash` screen is conservative.** `guard-hub-src-writes.mjs` blocks
|
|
49
|
+
redirects, `tee`, `sed -i`, `cp`/`mv` into a guarded path, an interpreter
|
|
50
|
+
snippet that writes there, and a copy, move or removal of a parent
|
|
51
|
+
(`rsync -a /tmp/x/ ./`, `rm -rf .`). It cannot see an interpreter running a
|
|
52
|
+
script from a project file, an `eval`, a computed path, a parent of the
|
|
53
|
+
project root (`rm -rf ..`), a workspace container below the project root, a
|
|
54
|
+
build step, a formatter or fixer (`prettier --write`, `eslint --fix`),
|
|
55
|
+
`git rm`/`git mv`, `find -exec`, `xargs` with a computed operand,
|
|
56
|
+
`tar`/`curl -o`, or a very long interpreter call (allowed with a stderr
|
|
57
|
+
note).
|
|
58
|
+
- **Managed settings outrank every project file.** A `managed-settings.json`
|
|
59
|
+
file, an MDM policy or a console-managed policy has no project-level
|
|
60
|
+
override, and `allowManagedHooksOnly` and `allowManagedPermissionRulesOnly`
|
|
61
|
+
mean only managed hooks run and only managed permission rules apply. The
|
|
62
|
+
file lives outside any working tree, so nothing here can detect it. On a
|
|
63
|
+
machine you don't control, run `/status` and read its "Setting sources"
|
|
64
|
+
line: if `guard-hub-src-writes.mjs` and `guard-branch-isolation.mjs` aren't
|
|
65
|
+
running, treat hub-and-spoke as an unenforced checklist.
|
|
66
|
+
- **An installed mod sits below managed settings and above project hooks.** A
|
|
67
|
+
mod that handles `tool.check` can approve a call a non-managed `PreToolUse`
|
|
68
|
+
hook blocked, and project `PreToolUse` hooks run only after the last mod
|
|
69
|
+
calls `next`. Only managed hooks outrank a mod. Check `/plugin` alongside
|
|
70
|
+
`/status`.
|
|
71
|
+
- **Who counts as a writer.** The guard needs a writer-spoke `agent_type` and a
|
|
72
|
+
non-empty `agent_id`. A fork subagent (on by default in every surface since
|
|
73
|
+
Claude Code 2.1.302) is not a writer spoke, so unless its payload reports a
|
|
74
|
+
writer `agent_type` it is treated as the hub (the docs don't say what a
|
|
75
|
+
fork's payload carries). A fork cannot spawn further agents. With agent teams on, an in-process
|
|
76
|
+
teammate has a documented `agent_id`; one built from a writer definition that
|
|
77
|
+
also reports that `agent_type` passes as a writer. A split-pane teammate does
|
|
78
|
+
not get `disallowedTools` (only an in-process one does), so every spoke's
|
|
79
|
+
`tools` list also omits `Agent`.
|
|
80
|
+
- **What `onFailure: "block"` covers.** A failure is a hook that cannot start,
|
|
81
|
+
times out, exits with any code other than 0 or 2, or prints invalid JSON. It
|
|
82
|
+
has no effect on `Stop`, `SubagentStop`, `TaskCompleted`, `TeammateIdle` or
|
|
83
|
+
async hooks.
|
|
84
|
+
|
|
39
85
|
## Dispatch sizing
|
|
40
86
|
|
|
41
87
|
- **Decompose before you dispatch.** Scale the dispatch to task complexity —
|
package/templates/core/CLAUDE.md
CHANGED
|
@@ -87,73 +87,54 @@ Skills, each in `.claude/skills/<name>/`:
|
|
|
87
87
|
sweeps (see Freshness).
|
|
88
88
|
|
|
89
89
|
**The guard also screens `Bash`, but only conservatively.** The same hook
|
|
90
|
-
|
|
91
|
-
`
|
|
92
|
-
|
|
93
|
-
|
|
94
|
-
|
|
95
|
-
|
|
96
|
-
|
|
97
|
-
|
|
98
|
-
|
|
99
|
-
|
|
100
|
-
|
|
101
|
-
|
|
102
|
-
|
|
103
|
-
|
|
104
|
-
|
|
105
|
-
|
|
106
|
-
|
|
107
|
-
|
|
108
|
-
|
|
109
|
-
(`allowManagedHooksOnly`) and only managed permission rules apply
|
|
110
|
-
(`allowManagedPermissionRulesOnly`) (see
|
|
111
|
-
[Claude Code's managed-settings docs](https://code.claude.com/docs/en/managed-settings)).
|
|
112
|
-
Nothing in this project can detect or gate against that from inside the
|
|
113
|
-
repo -- the managed file lives outside any working tree, at an OS-level
|
|
114
|
-
path. Run `/status` on a machine you don't control before trusting
|
|
115
|
-
`guard-hub-src-writes.mjs`/`guard-branch-isolation.mjs`: its "Setting
|
|
116
|
-
sources" line names every active source, and if these hooks aren't among
|
|
117
|
-
what's actually running, treat hub-and-spoke as an unenforced checklist
|
|
118
|
-
until confirmed otherwise.
|
|
119
|
-
|
|
120
|
-
**An installed Claude Code mod is a second silent override, below managed
|
|
121
|
-
settings.** Per the
|
|
122
|
-
[hooks guide](https://code.claude.com/docs/en/hooks-guide), a mod that
|
|
123
|
-
handles `tool.check` "can approve a call that your `PreToolUse` hook blocked,
|
|
124
|
-
unless the hook is in managed settings", and project `PreToolUse` hooks run
|
|
125
|
-
only after the last mod calls `next` (see the
|
|
126
|
-
[mods events reference](https://code.claude.com/docs/en/plugins/mods/events)).
|
|
127
|
-
Only managed-settings hooks outrank a mod, and nothing in the repo can detect
|
|
128
|
-
one. Check `/plugin` for installed mods alongside `/status`.
|
|
90
|
+
blocks a `Bash` command that visibly writes into `src/` or `tests/` (redirects,
|
|
91
|
+
`tee`, `sed -i`, `cp`/`mv` into them, an interpreter snippet that writes there,
|
|
92
|
+
a copy, move or removal of a parent of `src/` such as `rm -rf .`) unless the caller is
|
|
93
|
+
`test-author` or `code-implementer`. It cannot catch an indirect write (a
|
|
94
|
+
script from a project file, an `eval`, a computed path, a build step, a
|
|
95
|
+
formatter or fixer, `git rm`/`git mv`, `tar`/`curl -o`), so hub-and-spoke is a
|
|
96
|
+
convention backed by a guard that raises the bar, not a proof. To override it
|
|
97
|
+
deliberately, run the command yourself with the `!` prefix at the Claude Code
|
|
98
|
+
prompt, or edit the hook's registration in `.claude/settings.json`.
|
|
99
|
+
|
|
100
|
+
**Managed settings and mods can silently disable the guards.** A managed
|
|
101
|
+
deployment (`managed-settings.json`, MDM, a console policy) outranks every file
|
|
102
|
+
here, and `allowManagedHooksOnly` runs only managed hooks. An installed mod
|
|
103
|
+
that handles `tool.check` can approve a call a project `PreToolUse` hook
|
|
104
|
+
blocked, and only managed hooks outrank a mod. Nothing in the repo can detect
|
|
105
|
+
either: on a machine you don't control, check `/status` ("Setting sources") and
|
|
106
|
+
`/plugin` before trusting `guard-hub-src-writes.mjs` and
|
|
107
|
+
`guard-branch-isolation.mjs`. Detail and sources:
|
|
108
|
+
`.claude/rules/agent-dispatch.md`.
|
|
129
109
|
|
|
130
110
|
**The guard keys on `agent_id` as well as `agent_type`.** A call counts as a
|
|
131
|
-
writer spoke only with both present, so
|
|
132
|
-
|
|
133
|
-
|
|
134
|
-
|
|
111
|
+
writer spoke only with both present, so one carrying `agent_type` alone is
|
|
112
|
+
treated as the hub and blocked, as is a fork subagent unless its payload
|
|
113
|
+
reports a writer `agent_type` with an `agent_id` (details and versions in
|
|
114
|
+
`.claude/rules/agent-dispatch.md`). An in-process
|
|
115
|
+
agent-teams teammate has a documented `agent_id`, so one built from a writer
|
|
116
|
+
definition that reports that `agent_type` would pass.
|
|
117
|
+
|
|
118
|
+
**Four guards block when they fail, and a secrets deny rule ships in
|
|
135
119
|
`settings.json`.** `guard-secret-writes`, `guard-hub-src-writes`,
|
|
136
120
|
`guard-branch-isolation` and `guard-protected-paths` carry
|
|
137
|
-
`"onFailure": "block"` (Claude Code 2.1.295 or later)
|
|
138
|
-
|
|
139
|
-
|
|
140
|
-
|
|
141
|
-
missing `node`
|
|
142
|
-
|
|
143
|
-
|
|
144
|
-
|
|
145
|
-
|
|
146
|
-
|
|
147
|
-
`
|
|
148
|
-
`cat`, `head` and `tail` on those files in `Bash`. It does not cover `grep -r`
|
|
149
|
-
or a script that opens the file itself, and nothing else in this baseline does.
|
|
121
|
+
`"onFailure": "block"` (Claude Code 2.1.295 or later): a hook that cannot
|
|
122
|
+
start, times out, exits with any code other than 0 or 2, or prints invalid
|
|
123
|
+
JSON blocks the call instead of letting it through. Each guard still handles
|
|
124
|
+
bad input itself and exits 0 on purpose. Because `guard-hub-src-writes` is also
|
|
125
|
+
on `Bash`, a missing `node` blocks every `Bash` call until fixed (run the
|
|
126
|
+
command with the `!` prefix to get past it). The style guards and
|
|
127
|
+
`guard-git-push-signed` stay fail-open on purpose: the push guard has its own
|
|
128
|
+
parser and the remote's signed-commit rule is the authoritative layer.
|
|
129
|
+
`permissions.deny` blocks `Read(./.env)`, `Read(./.env.*)` and
|
|
130
|
+
`Read(./secrets/**)`, which also covers `cat`, `head` and `tail` on them in
|
|
131
|
+
`Bash`. It does not cover `grep -r` or a script that opens the file itself.
|
|
150
132
|
|
|
151
133
|
**A spoke's `permissionMode` can be overridden.** A session in auto,
|
|
152
134
|
`acceptEdits` or `bypassPermissions` mode overrides a spoke's `permissionMode`
|
|
153
|
-
(the field applies only
|
|
154
|
-
`
|
|
155
|
-
|
|
156
|
-
`disallowedTools: Agent` on every spoke is what keeps this roster flat.
|
|
135
|
+
(the field applies only in `default`, `dontAsk` or `plan`), so the hooks, not
|
|
136
|
+
`permissionMode`, bound a spoke. A subagent can spawn subagents three layers
|
|
137
|
+
deep by default; `disallowedTools: Agent` on every spoke keeps the roster flat.
|
|
157
138
|
|
|
158
139
|
Full dispatch-sizing and recovery guidance: `.claude/rules/agent-dispatch.md`
|
|
159
140
|
(auto-loads when editing `.claude/skills/**` or `.claude/agents/**`).
|
|
@@ -12,7 +12,9 @@
|
|
|
12
12
|
* types. Skips cleanly (exit 0, one warning) when the target has no
|
|
13
13
|
* `exports` field -- a project that isn't published doesn't need this gate,
|
|
14
14
|
* and `/customize` removes the step entirely for non-library project kinds
|
|
15
|
-
* rather than leaving a permanently-skipped one behind.
|
|
15
|
+
* rather than leaving a permanently-skipped one behind. attw resolves types
|
|
16
|
+
* with the TypeScript it bundles, not the project's own, so its verdict
|
|
17
|
+
* follows that resolver.
|
|
16
18
|
*/
|
|
17
19
|
import process from "node:process";
|
|
18
20
|
import { execFileSync } from "node:child_process";
|
|
@@ -691,7 +691,7 @@ const descriptionSubstance = {
|
|
|
691
691
|
} else if (description.length > DESCRIPTION_MAX) {
|
|
692
692
|
failures.push({
|
|
693
693
|
subject,
|
|
694
|
-
message: `description is ${description.length} chars; over ${DESCRIPTION_MAX}
|
|
694
|
+
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)`,
|
|
695
695
|
});
|
|
696
696
|
}
|
|
697
697
|
};
|
|
@@ -65,6 +65,8 @@ export default defineConfig(
|
|
|
65
65
|
"@typescript-eslint/no-non-null-assertion": "error",
|
|
66
66
|
"@typescript-eslint/no-floating-promises": "error",
|
|
67
67
|
"@typescript-eslint/switch-exhaustiveness-check": "error",
|
|
68
|
+
// Overlaps `verbatimModuleSyntax` (typescript-eslint warns the two can
|
|
69
|
+
// report the same import twice); kept for the rule's autofix.
|
|
68
70
|
"@typescript-eslint/consistent-type-imports": "error",
|
|
69
71
|
"@typescript-eslint/no-unused-vars": [
|
|
70
72
|
"error",
|
|
@@ -19,9 +19,10 @@ export default defineConfig({
|
|
|
19
19
|
// barrel pattern): a fresh scaffold's index.ts IS its real content,
|
|
20
20
|
// so excluding it would make this gate measure nothing at all.
|
|
21
21
|
exclude: ["**/*.d.ts"],
|
|
22
|
-
// json emits coverage-final.json: the
|
|
23
|
-
// are 100% on every metric
|
|
24
|
-
//
|
|
22
|
+
// json emits coverage-final.json: the text table can hide files that
|
|
23
|
+
// are 100% on every metric (Vitest sets `skipFull` when it detects an
|
|
24
|
+
// AI coding agent), so the JSON is the authoritative per-file record
|
|
25
|
+
// when investigating a suspected gap.
|
|
25
26
|
reporter: ["text", "html", "json"],
|
|
26
27
|
thresholds: {
|
|
27
28
|
// Scaffold-appropriate starting floor. Raise these to the project's
|
|
@@ -105,9 +105,12 @@ already enumerate groups rather than individual steps.
|
|
|
105
105
|
|
|
106
106
|
| Pack | Contents |
|
|
107
107
|
| ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
|
|
108
|
-
| `harness-extras` | Claude Code session
|
|
108
|
+
| `harness-extras` | Claude Code session hooks: the compaction-handoff hook pair (`PreCompact`, `SessionStart`) and a read-only Bash guard for review spokes. Registers hooks only; no top-level settings keys. |
|
|
109
|
+
| `statusline` | A five-row `statusLine` (session, model, context, quota, work) plus a per-subagent row renderer. The only pack that sets top-level settings keys (`statusLine`, `subagentStatusLine`); a project that already defines either must decide on it, see its `adoptNotes`. |
|
|
109
110
|
| `quality` | Two language-level review aids: a per-file size ratchet gate (`check-file-budget.mjs`, a `build`-group verify step) and a read-only `type-design-analyzer` agent. No hooks, no settings. Adopt-capable and recommended for every project kind. |
|
|
110
|
-
| `github`
|
|
111
|
-
| `
|
|
111
|
+
| `claude-github` | Anthropic's official Claude Code GitHub Action: one workflow wired for `@claude` mention-mode and a second that posts an automated Claude review comment on every PR. A pure file drop: no hooks, no gate. The workflows need an auth secret this pack cannot create and the review spends API credits per PR; see its `adoptNotes`. |
|
|
112
|
+
| `github` | GitHub-hosted collaboration through the `gh` CLI: three skills — `reviewing-dependabot-prs`, `triaging-scan-alerts`, `watching-pr-checks`. No hooks, no gate, no workflows. `triaging-scan-alerts` needs code scanning turned on; see its `adoptNotes`. |
|
|
113
|
+
| `publishing` | A release pipeline: `release.yml` (changesets version-PR / staged, provenance-attested npm publish via trusted publishing), `check-publish-version.mjs` and `check-dts-deps.mjs`. Fresh mode only; see "The wiring contract" above and its `adoptNotes`. |
|
|
114
|
+
| `licensing` | An SPDX/REUSE license-header gate: `check-license-headers.mjs` (a `lint`-group verify step) and a `REUSE.toml` template. Fresh mode only: the one-time backfill (`setupSteps`) fails an established project's `pnpm verify` until it has touched every file; see its `adoptNotes`. |
|
|
112
115
|
| `supply-chain` | Secret scanning (`gitleaks.yml` with a `.gitleaks.toml`) and an OpenSSF Scorecard run (`scorecard.yml`) for any project on GitHub, published or not. A pure file drop of two workflows (read-only apart from the Scorecard job's `security-events` and `id-token` write): no hooks, no settings, no scripts, no gate. Adopt-capable and recommended for every project kind. |
|
|
113
116
|
| `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 `SessionStart` hook that installs dependencies into a freshly created worktree, a `PreToolUse` guard stricter than the baseline's own `guard-branch-isolation.mjs`/`guard-hub-src-writes.mjs`, a `repair-core-bare.mjs` hook (`SessionStart`, and `PostToolUse` after `EnterWorktree`/`ExitWorktree`/`Agent`) that resets the `core.bare = true` Claude Code's worktree tools are reported to leave in a normal repo's shared config, and a `.worktreeinclude` copying `.env`/`.env.local`/`.env.*.local` into every worktree Claude Code creates. Changes the day-to-day workflow, not just a nicety — see its `adoptNotes`. |
|
package/templates/packs/{github → claude-github}/files/.github/workflows/claude-pr-review.yml
RENAMED
|
@@ -86,7 +86,7 @@ jobs:
|
|
|
86
86
|
fetch-depth: 0
|
|
87
87
|
|
|
88
88
|
- id: claude
|
|
89
|
-
uses: anthropics/claude-code-action@
|
|
89
|
+
uses: anthropics/claude-code-action@5eb090f3c3afd701a0672cd32981197ca27688f6 # v1.0.253
|
|
90
90
|
with:
|
|
91
91
|
anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
|
|
92
92
|
# Swap in CLAUDE_CODE_OAUTH_TOKEN or the Workload Identity
|
|
@@ -67,7 +67,7 @@ jobs:
|
|
|
67
67
|
fetch-depth: 1
|
|
68
68
|
|
|
69
69
|
- name: Run Claude Code
|
|
70
|
-
uses: anthropics/claude-code-action@
|
|
70
|
+
uses: anthropics/claude-code-action@5eb090f3c3afd701a0672cd32981197ca27688f6 # v1.0.253
|
|
71
71
|
with:
|
|
72
72
|
# Option 1 (active default): a stored API key. Install the Claude
|
|
73
73
|
# GitHub App (https://github.com/apps/claude) and add
|
|
@@ -0,0 +1,19 @@
|
|
|
1
|
+
{
|
|
2
|
+
"schemaVersion": 1,
|
|
3
|
+
"name": "claude-github",
|
|
4
|
+
"description": "Anthropic's official Claude Code GitHub Action (anthropics/claude-code-action) on top of the baseline, as two workflows: claude.yml, wired for @claude mention-mode, and claude-pr-review.yml, which posts an automated Claude review comment on every pull request. Pure file drop: no hooks, no settings, no scripts, no verify step. Both need an auth secret this pack cannot create, and the review workflow spends API credits on every PR, so it is a separate pack from `github` rather than a default.",
|
|
5
|
+
"modes": ["fresh", "adopt"],
|
|
6
|
+
"budget": {
|
|
7
|
+
"agents": 0,
|
|
8
|
+
"skills": 0,
|
|
9
|
+
"hooks": 0,
|
|
10
|
+
"workflows": 2,
|
|
11
|
+
"scripts": 0
|
|
12
|
+
},
|
|
13
|
+
"wiring": {
|
|
14
|
+
"settings": {},
|
|
15
|
+
"packageScripts": {},
|
|
16
|
+
"verifySteps": []
|
|
17
|
+
},
|
|
18
|
+
"adoptNotes": "claude.yml only reacts to @claude mentions from a repository owner, member or collaborator (author_association), so an outside commenter on a public repository cannot start a job that holds contents: write and your auth secret. It also commits through the GitHub API (use_commit_signing) so a signed-commits ruleset accepts its work. claude-pr-review.yml runs on every non-bot, non-fork pull request, so it spends API credits on each push -- delete it and keep claude.yml if you only want on-demand help. Both workflows need one thing this pack cannot verify or install: an ANTHROPIC_API_KEY repository secret (the active default), or a CLAUDE_CODE_OAUTH_TOKEN from a Claude subscription, or a Workload Identity Federation setup in the Anthropic Console -- see the comments in .github/workflows/claude.yml for all three. An adopted project that already has its own .github/workflows/claude.yml or claude-pr-review.yml surfaces as an ordinary file conflict -- keep the existing one if it's already configured for that project's own auth choice, since this pack's version would just overwrite a working setup with its own generic defaults. The two workflows ship without an SPDX header on purpose (a header would carry a project-name token that stays literal in an adopt-mode install); a project that also installs `licensing` gets the headers from that pack's `check-license-headers.mjs --fix` backfill. These workflows used to ship inside the `github` pack; a project that installed that pack before the split keeps its files untouched."
|
|
19
|
+
}
|
|
@@ -1,13 +1,13 @@
|
|
|
1
1
|
{
|
|
2
2
|
"schemaVersion": 1,
|
|
3
3
|
"name": "github",
|
|
4
|
-
"description": "GitHub-hosted collaboration on top of the baseline
|
|
4
|
+
"description": "GitHub-hosted collaboration skills on top of the baseline, all driven by the gh CLI: reviewing-dependabot-prs (classify and batch-merge open Dependabot PRs), triaging-scan-alerts (triage open code-scanning alerts to file:line, report only), and watching-pr-checks (check a PR's CI status and hand off to a project's own /triaging-ci on a real failure). No hooks, no gate, no workflows: the Claude Code GitHub Action workflows are the separate `claude-github` pack.",
|
|
5
5
|
"modes": ["fresh", "adopt"],
|
|
6
6
|
"budget": {
|
|
7
7
|
"agents": 0,
|
|
8
8
|
"skills": 3,
|
|
9
9
|
"hooks": 0,
|
|
10
|
-
"workflows":
|
|
10
|
+
"workflows": 0,
|
|
11
11
|
"scripts": 0
|
|
12
12
|
},
|
|
13
13
|
"wiring": {
|
|
@@ -15,5 +15,5 @@
|
|
|
15
15
|
"packageScripts": {},
|
|
16
16
|
"verifySteps": []
|
|
17
17
|
},
|
|
18
|
-
"adoptNotes": "
|
|
18
|
+
"adoptNotes": "The three skills need only `gh` CLI auth (already required by every other gh-CLI-based skill this baseline ships) and install anywhere a .claude/ directory exists. triaging-scan-alerts reads code-scanning alerts, and nothing in the baseline or this pack produces them: turn on GitHub's CodeQL default setup for the repository (Settings > Code security), or install the `supply-chain` pack, whose scorecard.yml uploads SARIF, otherwise the skill's first call returns \"code scanning is not enabled\" and reports nothing. watching-pr-checks' handoff to /triaging-ci degrades gracefully if the project doesn't have that skill installed -- it still reports the real failure, just without the handoff. The Claude Code GitHub Action workflows (claude.yml, claude-pr-review.yml) used to ship in this pack and are now the separate `claude-github` pack; a project that installed this pack before the split keeps those files untouched."
|
|
19
19
|
}
|
|
@@ -1,12 +1,12 @@
|
|
|
1
1
|
{
|
|
2
2
|
"schemaVersion": 1,
|
|
3
3
|
"name": "harness-extras",
|
|
4
|
-
"description": "Adds Claude Code session ergonomics on top of the baseline: a pair of hooks that carry a work summary across a context-window compaction, a hook that blocks non-read-only Bash commands from read-only review spokes
|
|
4
|
+
"description": "Adds Claude Code session ergonomics on top of the baseline: a pair of hooks that carry a work summary across a context-window compaction, and a hook that blocks non-read-only Bash commands from read-only review spokes. The status line is the separate `statusline` pack.",
|
|
5
5
|
"modes": ["fresh", "adopt"],
|
|
6
6
|
"budget": {
|
|
7
7
|
"agents": 0,
|
|
8
8
|
"skills": 0,
|
|
9
|
-
"hooks":
|
|
9
|
+
"hooks": 3,
|
|
10
10
|
"workflows": 0,
|
|
11
11
|
"scripts": 0
|
|
12
12
|
},
|
|
@@ -51,20 +51,8 @@
|
|
|
51
51
|
}
|
|
52
52
|
]
|
|
53
53
|
},
|
|
54
|
-
"settingsTopLevel": {
|
|
55
|
-
"statusLine": {
|
|
56
|
-
"type": "command",
|
|
57
|
-
"command": "node \"$CLAUDE_PROJECT_DIR/.claude/hooks/statusline.mjs\"",
|
|
58
|
-
"refreshInterval": 30,
|
|
59
|
-
"padding": 1
|
|
60
|
-
},
|
|
61
|
-
"subagentStatusLine": {
|
|
62
|
-
"type": "command",
|
|
63
|
-
"command": "node \"$CLAUDE_PROJECT_DIR/.claude/hooks/subagent-statusline.mjs\""
|
|
64
|
-
}
|
|
65
|
-
},
|
|
66
54
|
"packageScripts": {},
|
|
67
55
|
"verifySteps": []
|
|
68
56
|
},
|
|
69
|
-
"adoptNotes": "The
|
|
57
|
+
"adoptNotes": "The compaction hooks install anywhere a .claude/ directory exists, but guard-readonly-bash.mjs imports ../../bin/lib/agent-roster.mjs (the baseline's list of writer spokes) -- copy that file alongside it in an adopted project, or skip that one hook. The PreCompact hook writes tmp/compact-handoff-<session_id>.json under the git worktree the session runs in (from the hook payload's cwd, since CLAUDE_PROJECT_DIR does not follow a session into a linked worktree) -- fresh mode's baseline .gitignore already lists tmp/ unconditionally, but an adopted project's own .gitignore was never touched by adopt mode, so add tmp/ there too before this pack's hooks run, or the handoff artifact can end up committed. The size-ratchet gate and the type-design-analyzer agent that used to ship here are now the separate `quality` pack. The status line that used to ship here is now the separate `statusline` pack, so installing this one never touches a project's own `statusLine` setting."
|
|
70
58
|
}
|
|
@@ -0,0 +1,31 @@
|
|
|
1
|
+
{
|
|
2
|
+
"schemaVersion": 1,
|
|
3
|
+
"name": "licensing",
|
|
4
|
+
"description": "An SPDX/REUSE license-header gate for a new project: check-license-headers.mjs (a lint-group verify step that fails on any git-tracked file with neither an SPDX header nor a REUSE.toml annotation, and inserts missing headers with --fix) and a REUSE.toml template. Fresh mode only, because the one-time backfill fails an established project's pnpm verify until it has touched every file. Split from `publishing` so a project can take the header gate without the npm release pipeline, and the other way round.",
|
|
5
|
+
"modes": ["fresh"],
|
|
6
|
+
"budget": {
|
|
7
|
+
"agents": 0,
|
|
8
|
+
"skills": 0,
|
|
9
|
+
"hooks": 0,
|
|
10
|
+
"workflows": 0,
|
|
11
|
+
"scripts": 0
|
|
12
|
+
},
|
|
13
|
+
"wiring": {
|
|
14
|
+
"settings": {},
|
|
15
|
+
"packageScripts": {},
|
|
16
|
+
"verifySteps": [
|
|
17
|
+
{
|
|
18
|
+
"id": "license-headers",
|
|
19
|
+
"group": "lint",
|
|
20
|
+
"name": "Check SPDX license headers",
|
|
21
|
+
"cmd": ["node", "bin/check-license-headers.mjs"]
|
|
22
|
+
}
|
|
23
|
+
]
|
|
24
|
+
},
|
|
25
|
+
"setupSteps": [
|
|
26
|
+
"git add -A",
|
|
27
|
+
"node bin/check-license-headers.mjs --fix",
|
|
28
|
+
"git add -A"
|
|
29
|
+
],
|
|
30
|
+
"adoptNotes": "REQUIRED right after install, before the first pnpm verify: `git add -A`, then `node bin/check-license-headers.mjs --fix`, then `git add -A` again and commit the result (the gate only checks git-tracked files, so a fresh project with nothing staged passes it vacuously and fails on every file at its first push) -- templates/core has never had a license-header gate before this pack, so every one of its own files (hooks, bin/ scripts, CI workflows, the placeholder src/tests, and the workflows of any other installed pack such as `claude-github` or `supply-chain`) is missing the SPDX header this pack's gate now requires. The shipped REUSE.toml and gate header use NOASSERTION as the license identifier because the pack cannot know the project's license: edit REUSE.toml and the headerLines() function in bin/check-license-headers.mjs once it is decided (a LICENSE file, if one exists, is the source of truth). In a hand-copied install the CLI does not substitute tokens, so replace every literal `__PROJECT_NAME__` in the copied files (REUSE.toml, the SPDX headers) with the project's real name first. Fresh mode only: the backfill fails an established project's pnpm verify until it has touched every file, so it is staged like every other pack (at .groundwork/packs/licensing/) but never auto-installed in adopt mode -- if an adopted project wants it, copy .groundwork/packs/licensing/files/ by hand, dropping the `.staged` suffix from every name (or copy templates/packs/licensing/files/ from this repo directly) and run the backfill above. The license-headers verify step is a lint-group gate and installs anywhere a bin/verify.mjs-shaped gate runner exists; wire it into the project's real one if it differs. REUSE.toml also carries globs for `.gitleaks.toml` and `.worktreeinclude`, the files the `supply-chain` and `worktrees` packs add, so the gate's uncovered-file check passes whether or not those packs are installed. This gate used to ship in the `publishing` pack; a project that installed that pack before the split keeps its files untouched."
|
|
31
|
+
}
|
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
{
|
|
2
2
|
"schemaVersion": 1,
|
|
3
3
|
"name": "publishing",
|
|
4
|
-
"description": "A release pipeline for a project that ships an npm package. Release half: release.yml (changesets version-PR / staged, provenance-attested npm publish via trusted publishing OIDC, including a direct check-publish-version.mjs call right before packing), .changeset/config.json + README.md, the pnpm-to-staged-publish shim (libnpmpublish, not the npm CLI), and one build-group gate (check-dts-deps.mjs).
|
|
4
|
+
"description": "A release pipeline for a project that ships an npm package. Release half: release.yml (changesets version-PR / staged, provenance-attested npm publish via trusted publishing OIDC, including a direct check-publish-version.mjs call right before packing), .changeset/config.json + README.md, the pnpm-to-staged-publish shim (libnpmpublish, not the npm CLI), and one build-group gate (check-dts-deps.mjs). The SPDX license-header gate is the separate `licensing` pack, and secret scanning and Scorecard are the separate `supply-chain` pack. Not adopt-capable: the release flow assumes decisions (registry access, npm trusted-publisher setup, a GitHub App for the version PR) too project-specific to install blind -- see adoptNotes.",
|
|
5
5
|
"modes": ["fresh"],
|
|
6
6
|
"budget": {
|
|
7
7
|
"agents": 0,
|
|
@@ -22,20 +22,9 @@
|
|
|
22
22
|
"group": "build",
|
|
23
23
|
"name": "Check .d.ts dependency declarations",
|
|
24
24
|
"cmd": ["node", "bin/check-dts-deps.mjs"]
|
|
25
|
-
},
|
|
26
|
-
{
|
|
27
|
-
"id": "license-headers",
|
|
28
|
-
"group": "lint",
|
|
29
|
-
"name": "Check SPDX license headers",
|
|
30
|
-
"cmd": ["node", "bin/check-license-headers.mjs"]
|
|
31
25
|
}
|
|
32
26
|
]
|
|
33
27
|
},
|
|
34
|
-
"setupSteps": [
|
|
35
|
-
|
|
36
|
-
"git add -A",
|
|
37
|
-
"node bin/check-license-headers.mjs --fix",
|
|
38
|
-
"git add -A"
|
|
39
|
-
],
|
|
40
|
-
"adoptNotes": "REQUIRED right after install, before the first pnpm verify -- two one-time steps, or pnpm verify fails immediately, not from a real regression but from two setup gaps this pack cannot close itself: (1) `pnpm add -D @changesets/cli` -- the wiring contract only extends package.json's scripts, never its dependencies (see templates/packs/README.md), so the wired `changeset`/`version:packages` scripts reference a binary knip's own unlisted-binaries check correctly flags as missing until this is installed; (2) `git add -A`, then `node bin/check-license-headers.mjs --fix`, then `git add -A` again and commit the result (the gate only checks git-tracked files, so a fresh project with nothing staged passes it vacuously and fails on every file at its first push) -- templates/core has never had a license-header gate before this pack, so every one of its own files (hooks, bin/ scripts, CI workflows, the placeholder src/tests, and the workflows of any other installed pack such as `github` or `supply-chain`) is missing the SPDX header this pack's own license-headers gate now requires, the same one-time cost this repo itself paid when it adopted the same gate (see CLAUDE.md's Definition of Done). In a hand-copied install the CLI does not substitute tokens, so replace every literal `__PROJECT_NAME__` in the copied files (REUSE.toml, the SPDX headers in bin/, the workflows) with the project's real name first. Fresh mode only: a release pipeline encodes decisions (whether the package is actually public, which registry, whether a GitHub App backs the version PR) this pack cannot survey or guess at safely, so it is staged like every other pack (at .groundwork/packs/publishing/) but never auto-installed in adopt mode -- if an adopted project wants it, copy .groundwork/packs/publishing/files/ by hand, dropping the `.staged` suffix from every name (or copy templates/packs/publishing/files/ from this repo directly) and work through the one-time setup below. check-publish-version.mjs is deliberately NOT one of this pack's wired verify steps: with changesets, package.json's version on the release branch is always the one just published between releases, so a version-already-published check running on every ordinary push (via pnpm verify / pre-push) would fail every single time until the next version PR lands -- it is instead invoked directly as a step inside release.yml's pack job, the one place \"is this version about to collide with an already-published one\" is actually the right question to ask. The two remaining verify-group gates (dts-deps, license-headers) install anywhere a bin/verify.mjs-shaped gate runner exists; wire them into the project's real one if it differs. Both check-publish-version.mjs and check-dts-deps.mjs no-op (checked: 0, not a failure) on a package.json with `private: true` (the baseline's own default) or (check-dts-deps.mjs only) with no dist/**/*.d.ts yet -- flip `private` to `false` (and set a real `name`) once the package is actually meant to publish. The pack assumes a public package: `.changeset/config.json` ships `access: public`, npm refuses `restricted` for an unscoped name, and the publisher always requests provenance, which npm ties to a public source repository -- a private scoped package needs `access: restricted` and the `provenance: true` option removed from the libnpmpublish call in bin/npm-stage-publish.mjs. `@changesets/changelog-github` (and its `repo` option) is a drop-in swap for `.changeset/config.json`'s plain default changelog generator, once this project's GitHub repository is known, for changelog entries that link back to the originating PR/commit -- see `.changeset/README.md`. One-time setup before release.yml's first real run (distinct from the two pnpm-verify prerequisites above), distilled from this repo's own .claude/rules/releases.md: (1) npm cannot configure a trusted publisher for a package that doesn't exist yet -- publish once by hand with a temporary token first; (2) the trusted publisher is bound to the exact workflow filename `release.yml` -- renaming or moving it breaks publishing until reconfigured on npmjs.com; (3) set the trusted publisher's allowed actions to staged-only (staged publishing only, npm's own default and recommendation since 2026-09-03) -- a maintainer runs `npm stage approve <id>` (2FA, never automatable) before a version actually installs; (4) create an `npm-publish` GitHub environment (via `gh api`, not committed as JSON) with a required reviewer, restricted to the release branch, so the `publish` job itself pauses before the git tag/Release/stage-publish exist; (5) if branch protection requires status checks on every PR with no bypass actor, the version-PR job needs a GitHub App installation token (`APP_CLIENT_ID`/`APP_PRIVATE_KEY` repo secrets), not the default GITHUB_TOKEN, or those checks never trigger and the PR can never merge -- if this project has no such rule, `github-token: ${{ secrets.GITHUB_TOKEN }}` is enough and the app-token step can be dropped. release.yml pins `tools/release/` (the exact libnpmpublish and npm-registry-fetch versions the publish job installs; it stages through them, not the npm CLI, because the CLI's bundled dependencies cannot be patched by an override) but the baseline's dependabot.yml only covers the github-actions ecosystem, so that pin goes stale unless you add an `npm` entry with `directory: \"/tools/release\"` to the project's own .github/dependabot.yml. The staged id to approve is printed by the workflow's \"Show the staged ids to approve\" step (and annotated on the run), and the `npm stage approve <id>` command is also written to the job summary. The secret-scanning and Scorecard workflows that used to ship here are now the separate `supply-chain` pack."
|
|
28
|
+
"setupSteps": ["pnpm add -D @changesets/cli"],
|
|
29
|
+
"adoptNotes": "REQUIRED right after install, before the first pnpm verify -- one step, or pnpm verify fails immediately, not from a real regression but from a setup gap this pack cannot close itself: `pnpm add -D @changesets/cli` -- the wiring contract only extends package.json's scripts, never its dependencies (see templates/packs/README.md), so the wired `changeset`/`version:packages` scripts reference a binary knip's own unlisted-binaries check correctly flags as missing until this is installed. In a hand-copied install the CLI does not substitute tokens, so replace every literal `__PROJECT_NAME__` in the copied files (the SPDX headers in bin/, the workflows) with the project's real name first. Fresh mode only: a release pipeline encodes decisions (whether the package is actually public, which registry, whether a GitHub App backs the version PR) this pack cannot survey or guess at safely, so it is staged like every other pack (at .groundwork/packs/publishing/) but never auto-installed in adopt mode -- if an adopted project wants it, copy .groundwork/packs/publishing/files/ by hand, dropping the `.staged` suffix from every name (or copy templates/packs/publishing/files/ from this repo directly) and work through the one-time setup below. check-publish-version.mjs is deliberately NOT one of this pack's wired verify steps: with changesets, package.json's version on the release branch is always the one just published between releases, so a version-already-published check running on every ordinary push (via pnpm verify / pre-push) would fail every single time until the next version PR lands -- it is instead invoked directly as a step inside release.yml's pack job, the one place \"is this version about to collide with an already-published one\" is actually the right question to ask. The remaining verify-group gate (dts-deps) installs anywhere a bin/verify.mjs-shaped gate runner exists; wire it into the project's real one if it differs. Both check-publish-version.mjs and check-dts-deps.mjs no-op (checked: 0, not a failure) on a package.json with `private: true` (the baseline's own default) or (check-dts-deps.mjs only) with no dist/**/*.d.ts yet -- flip `private` to `false` (and set a real `name`) once the package is actually meant to publish. The pack assumes a public package: `.changeset/config.json` ships `access: public`, npm refuses `restricted` for an unscoped name, and the publisher always requests provenance, which npm ties to a public source repository -- a private scoped package needs `access: restricted` and the `provenance: true` option removed from the libnpmpublish call in bin/npm-stage-publish.mjs. `@changesets/changelog-github` (and its `repo` option) is a drop-in swap for `.changeset/config.json`'s plain default changelog generator, once this project's GitHub repository is known, for changelog entries that link back to the originating PR/commit -- see `.changeset/README.md`. One-time setup before release.yml's first real run (distinct from the pnpm-verify prerequisite above), distilled from this repo's own .claude/rules/releases.md: (1) npm cannot configure a trusted publisher for a package that doesn't exist yet -- publish once by hand with a temporary token first; (2) the trusted publisher is bound to the exact workflow filename `release.yml` -- renaming or moving it breaks publishing until reconfigured on npmjs.com; (3) set the trusted publisher's allowed actions to staged-only (staged publishing only, npm's own default and recommendation since 2026-09-03) -- a maintainer runs `npm stage approve <id>` (2FA, never automatable) before a version actually installs; (4) create an `npm-publish` GitHub environment (via `gh api`, not committed as JSON) with a required reviewer, restricted to the release branch, so the `publish` job itself pauses before the git tag/Release/stage-publish exist; (5) if branch protection requires status checks on every PR with no bypass actor, the version-PR job needs a GitHub App installation token (`APP_CLIENT_ID`/`APP_PRIVATE_KEY` repo secrets), not the default GITHUB_TOKEN, or those checks never trigger and the PR can never merge -- if this project has no such rule, `github-token: ${{ secrets.GITHUB_TOKEN }}` is enough and the app-token step can be dropped. release.yml pins `tools/release/` (the exact libnpmpublish and npm-registry-fetch versions the publish job installs; it stages through them, not the npm CLI, because the CLI's bundled dependencies cannot be patched by an override) but the baseline's dependabot.yml only covers the github-actions ecosystem, so that pin goes stale unless you add an `npm` entry with `directory: \"/tools/release\"` to the project's own .github/dependabot.yml. The staged id to approve is printed by the workflow's \"Show the staged ids to approve\" step (and annotated on the run), and the `npm stage approve <id>` command is also written to the job summary. The secret-scanning and Scorecard workflows that used to ship here are now the separate `supply-chain` pack. The SPDX/REUSE license-header gate that used to ship here is now the separate fresh-only `licensing` pack: this pack's own scripts and release.yml still carry SPDX headers with a NOASSERTION license identifier, which is harmless without that gate but is what it would check."
|
|
41
30
|
}
|
|
@@ -0,0 +1,31 @@
|
|
|
1
|
+
{
|
|
2
|
+
"schemaVersion": 1,
|
|
3
|
+
"name": "statusline",
|
|
4
|
+
"description": "A five-row Claude Code statusLine (session, model, context, quota, work) plus a per-subagent row renderer -- the only documented surface carrying live context-window pressure. Three scripts and two top-level settings keys (`statusLine`, `subagentStatusLine`): no hook registrations, no verify step. Split from `harness-extras` so a project that already has its own status line can take that pack's hooks without a collision.",
|
|
5
|
+
"modes": ["fresh", "adopt"],
|
|
6
|
+
"budget": {
|
|
7
|
+
"agents": 0,
|
|
8
|
+
"skills": 0,
|
|
9
|
+
"hooks": 3,
|
|
10
|
+
"workflows": 0,
|
|
11
|
+
"scripts": 0
|
|
12
|
+
},
|
|
13
|
+
"wiring": {
|
|
14
|
+
"settings": {},
|
|
15
|
+
"settingsTopLevel": {
|
|
16
|
+
"statusLine": {
|
|
17
|
+
"type": "command",
|
|
18
|
+
"command": "node \"$CLAUDE_PROJECT_DIR/.claude/hooks/statusline.mjs\"",
|
|
19
|
+
"refreshInterval": 30,
|
|
20
|
+
"padding": 1
|
|
21
|
+
},
|
|
22
|
+
"subagentStatusLine": {
|
|
23
|
+
"type": "command",
|
|
24
|
+
"command": "node \"$CLAUDE_PROJECT_DIR/.claude/hooks/subagent-statusline.mjs\""
|
|
25
|
+
}
|
|
26
|
+
},
|
|
27
|
+
"packageScripts": {},
|
|
28
|
+
"verifySteps": []
|
|
29
|
+
},
|
|
30
|
+
"adoptNotes": "The statusline scripts read only the stdin payload, .git/HEAD (via node:fs, never a git subprocess) and process.availableMemory()/os.totalmem(), so they install anywhere a .claude/ directory exists -- no dependency on the baseline's file layout. The one real adopt risk is the two top-level settings keys: a project that already defines statusLine or subagentStatusLine collides, and its existing value must be shown and decided on, never overwritten -- if either is already set, skip that key and the script that renders it rather than failing the whole install; if both are set there is nothing left to install, so skip the pack. A statusLine in .claude/settings.local.json (or one passed with --settings) also shadows the project one; the user's own ~/.claude/settings.json ranks lower and does not -- check those before concluding the pack is wired. rate_limits.spend_limit and prompt_cache need Claude Code v2.1.251+, and the per-subagent model/contextWindowSize/effort fields need v2.1.205+/v2.1.214+, and the agentType label a row falls back to when a subagent has no name needs v2.1.293+; each renders only when present, so an older Claude Code degrades to fewer segments rather than breaking. The scripts behave the same on macOS and Linux; the memory segment uses process.availableMemory() (Node 22+), and on macOS with an older Node it is hidden rather than shown from os.freemem(), which undercounts there. Below roughly 40 columns the layout drops segments by priority rather than wrapping. These scripts used to ship inside the `harness-extras` pack; a project that installed that pack before the split keeps its files untouched."
|
|
31
|
+
}
|
|
@@ -15,5 +15,5 @@
|
|
|
15
15
|
"packageScripts": {},
|
|
16
16
|
"verifySteps": []
|
|
17
17
|
},
|
|
18
|
-
"adoptNotes": "An adopted project that already has its own .github/workflows/gitleaks.yml or scorecard.yml surfaces as an ordinary file conflict -- keep the existing one if it already works, since this pack's version would just replace a configured setup with its generic defaults. gitleaks.yml needs a free GITLEAKS_LICENSE repo secret for an organization-owned repository (gitleaks-action's own requirement); scorecard.yml assumes a public repository (`publish_results: true` needs one) -- set it `false` for a private repo. gitleaks.yml is read-only and scorecard.yml holds security-events: write and id-token: write in its analysis job; neither is a required check by default, so add either to branch protection once it has a clean run. The SPDX/REUSE license-header gate is not part of this pack: it lives in the fresh-only `
|
|
18
|
+
"adoptNotes": "An adopted project that already has its own .github/workflows/gitleaks.yml or scorecard.yml surfaces as an ordinary file conflict -- keep the existing one if it already works, since this pack's version would just replace a configured setup with its generic defaults. gitleaks.yml needs a free GITLEAKS_LICENSE repo secret for an organization-owned repository (gitleaks-action's own requirement); scorecard.yml assumes a public repository (`publish_results: true` needs one) -- set it `false` for a private repo. gitleaks.yml is read-only and scorecard.yml holds security-events: write and id-token: write in its analysis job; neither is a required check by default, so add either to branch protection once it has a clean run. The SPDX/REUSE license-header gate is not part of this pack: it lives in the fresh-only `licensing` pack, because it fails an established project's `pnpm verify` until a one-time backfill touches every file. The two workflows ship without an SPDX header on purpose (a header would carry a project-name token that stays literal in an adopt-mode install); a project that also installs `licensing` gets the headers from that pack's `check-license-headers.mjs --fix` backfill."
|
|
19
19
|
}
|
|
@@ -39,6 +39,7 @@
|
|
|
39
39
|
{
|
|
40
40
|
"type": "command",
|
|
41
41
|
"command": "node \"$CLAUDE_PROJECT_DIR/.claude/hooks/guard-worktree-only.mjs\"",
|
|
42
|
+
"onFailure": "block",
|
|
42
43
|
"timeout": 30
|
|
43
44
|
}
|
|
44
45
|
]
|
|
@@ -60,5 +61,5 @@
|
|
|
60
61
|
"packageScripts": {},
|
|
61
62
|
"verifySteps": []
|
|
62
63
|
},
|
|
63
|
-
"adoptNotes": "ensure-worktree-deps.mjs runs `pnpm install --frozen-lockfile --prefer-offline` automatically the first time a session starts inside a freshly created worktree with no node_modules yet -- this runs every dependency's lifecycle scripts the same way any `pnpm install` does, limited only by whatever `allowBuilds`/`onlyBuiltDependencies` policy the project's own pnpm config already sets (see typescript-guidance's pnpm supply-chain coverage if none is set). If node_modules in the worktree is a symlink (the usual result of `worktree.symlinkDirectories: [\"node_modules\"]` in .claude/settings.json, which this hook never reads), the hook detects the symlink and skips -- installing there would mutate the main checkout's own node_modules through the symlink. guard-worktree-only.mjs blocks every src/tests write outside a linked worktree under .claude/worktrees/, on any branch, for any caller (hub or writer spoke) -- this is stricter than guard-branch-isolation.mjs (which only blocks on main) and guard-hub-src-writes.mjs (which blocks the hub and any non-writer subagent); confirm the team actually wants every change routed through a worktree before installing this pack, since it changes the day-to-day workflow, not just adds a nicety. `.claude/worktrees/` should already be gitignored (the baseline's own .gitignore covers this); if adopting into a project with a hand-rolled .gitignore that doesn't, add it before installing. repair-core-bare.mjs resets `core.bare = true` to `false` in a non-bare repo's shared .git/config at session start and after EnterWorktree/ExitWorktree/Agent calls: Claude Code's worktree tools have been reported to leave it set (anthropics/claude-code#58345, #69802: user bug reports, both since closed as not planned, so whether it still reproduces is unconfirmed), which breaks `git status` in the main checkout. It only acts on a provably non-bare repository (its common git dir is named .git and contains an index), never on a genuine bare repo -- including a bare clone stored in a directory called .git -- and reports a failed repair on stdout rather than silently."
|
|
64
|
+
"adoptNotes": "ensure-worktree-deps.mjs runs `pnpm install --frozen-lockfile --prefer-offline` automatically the first time a session starts inside a freshly created worktree with no node_modules yet -- this runs every dependency's lifecycle scripts the same way any `pnpm install` does, limited only by whatever `allowBuilds`/`onlyBuiltDependencies` policy the project's own pnpm config already sets (see typescript-guidance's pnpm supply-chain coverage if none is set). If node_modules in the worktree is a symlink (the usual result of `worktree.symlinkDirectories: [\"node_modules\"]` in .claude/settings.json, which this hook never reads), the hook detects the symlink and skips -- installing there would mutate the main checkout's own node_modules through the symlink. guard-worktree-only.mjs is registered with `\"onFailure\": \"block\"` (Claude Code 2.1.295 or later; an older version ignores the key), so a hook that cannot start, times out, exits with a code other than 0 or 2 or prints invalid JSON blocks the write instead of letting it through. A project that installed this pack before it carried that key has the same registration without it: /customize adds the missing key when it installs the pack again, and otherwise add `\"onFailure\": \"block\"` to that registration in .claude/settings.json by hand. It blocks every src/tests write outside a linked worktree under .claude/worktrees/, on any branch, for any caller (hub or writer spoke) -- this is stricter than guard-branch-isolation.mjs (which only blocks on main) and guard-hub-src-writes.mjs (which blocks the hub and any non-writer subagent); confirm the team actually wants every change routed through a worktree before installing this pack, since it changes the day-to-day workflow, not just adds a nicety. `.claude/worktrees/` should already be gitignored (the baseline's own .gitignore covers this); if adopting into a project with a hand-rolled .gitignore that doesn't, add it before installing. repair-core-bare.mjs resets `core.bare = true` to `false` in a non-bare repo's shared .git/config at session start and after EnterWorktree/ExitWorktree/Agent calls: Claude Code's worktree tools have been reported to leave it set (anthropics/claude-code#58345, #69802: user bug reports, both since closed as not planned, so whether it still reproduces is unconfirmed), which breaks `git status` in the main checkout. It only acts on a provably non-bare repository (its common git dir is named .git and contains an index), never on a genuine bare repo -- including a bare clone stored in a directory called .git -- and reports a failed repair on stdout rather than silently."
|
|
64
65
|
}
|
|
File without changes
|
|
File without changes
|
/package/templates/packs/{harness-extras → statusline}/files/.claude/hooks/statusline-layout.mjs
RENAMED
|
File without changes
|
|
File without changes
|
/package/templates/packs/{harness-extras → statusline}/files/.claude/hooks/subagent-statusline.mjs
RENAMED
|
File without changes
|