@monte3l/groundwork 1.0.0 → 1.0.2
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 +373 -39
- package/dist/main.d.ts +1 -1
- package/dist/main.js +40 -18
- package/dist/packs.js +89 -1
- package/dist/report.js +18 -10
- package/package.json +9 -7
- package/plugin/skills/customize/SKILL.md +49 -6
- package/plugin/skills/customize/step-0-reconcile.md +109 -9
- package/plugin/skills/customize/step-3-round-1.md +28 -1
- package/templates/core/.claude/agents/code-implementer.md +6 -3
- package/templates/core/.claude/rules/agent-dispatch.md +10 -0
- package/templates/core/.claude/settings.json +8 -0
- package/templates/core/.claude/skills/harness-guidance/SKILL.md +9 -3
- package/templates/core/.claude/skills/typescript-guidance/SKILL.md +11 -1
- package/templates/core/.claude/skills/typescript-guidance/references/tooling-sources.md +10 -0
- package/templates/core/CLAUDE.md +24 -0
package/README.md
CHANGED
|
@@ -1,45 +1,379 @@
|
|
|
1
|
-
|
|
2
|
-
|
|
3
|
-
|
|
4
|
-
|
|
5
|
-
|
|
6
|
-
|
|
7
|
-
|
|
8
|
-
|
|
9
|
-
|
|
10
|
-
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
|
|
1
|
+
<!--
|
|
2
|
+
GENERATED from the root README.md -- do not hand-edit.
|
|
3
|
+
Run `node bin/build-npm-readme.mjs` to regenerate; `--check` (the
|
|
4
|
+
`npm-readme` verify step) fails on drift.
|
|
5
|
+
-->
|
|
6
|
+
|
|
7
|
+
# m3l-groundwork
|
|
8
|
+
|
|
9
|
+
[](https://github.com/monte3l/m3l-groundwork/actions/workflows/ci.yml)
|
|
10
|
+
[](https://securityscorecards.dev/viewer/?uri=github.com/monte3l/m3l-groundwork)
|
|
11
|
+
[](https://www.bestpractices.dev/projects/14937)
|
|
12
|
+
[](https://socket.dev/npm/package/@monte3l/groundwork/overview)
|
|
13
|
+
[](https://api.reuse.software/info/github.com/monte3l/m3l-groundwork)
|
|
14
|
+
|
|
15
|
+
m3l-groundwork is a command-line tool that sets up (or reports on) a
|
|
16
|
+
TypeScript project's toolchain and [Claude Code](https://docs.claude.com/en/docs/claude-code/overview)
|
|
17
|
+
setup, then keeps that setup current with live upstream guidance.
|
|
18
|
+
|
|
19
|
+
Read this project's rendered docs site at
|
|
20
|
+
[groundwork.monte3l.com](https://groundwork.monte3l.com).
|
|
21
|
+
|
|
22
|
+
## Who is this for
|
|
23
|
+
|
|
24
|
+
- Someone starting a **new TypeScript project** who wants a strict
|
|
25
|
+
toolchain and a working Claude Code setup from the first commit, instead
|
|
26
|
+
of assembling both by hand.
|
|
27
|
+
- A team with an **existing TypeScript project** who wants an honest,
|
|
28
|
+
read-only report on how it compares to that same baseline, with no risk
|
|
29
|
+
of an automated tool rewriting their repo.
|
|
30
|
+
- Anyone who wants their project's Claude Code configuration and
|
|
31
|
+
TypeScript toolchain to stay aligned with current official guidance,
|
|
32
|
+
rather than frozen at whatever was true the day it was set up.
|
|
33
|
+
|
|
34
|
+
## New to Claude Code or TypeScript?
|
|
35
|
+
|
|
36
|
+
- [Claude Code documentation](https://docs.claude.com/en/docs/claude-code/overview)
|
|
37
|
+
-- what it is and how to install it.
|
|
38
|
+
- [`docs/glossary.md`](https://github.com/monte3l/m3l-groundwork/blob/main/docs/glossary.md) -- plain-English definitions of the
|
|
39
|
+
terms used throughout this repo's docs (harness, skill, pack, gate, and
|
|
40
|
+
so on).
|
|
41
|
+
- [TypeScript Handbook](https://www.typescriptlang.org/docs/handbook/intro.html)
|
|
42
|
+
-- if TypeScript itself is new to you.
|
|
43
|
+
|
|
44
|
+
## Quickstart
|
|
45
|
+
|
|
46
|
+
1. Install [Node 24+](https://nodejs.org/) and [pnpm](https://pnpm.io/installation)
|
|
47
|
+
(see ["Requirements"](#requirements) below for exact versions).
|
|
48
|
+
2. Run `npx @monte3l/groundwork my-app` to bootstrap a new project
|
|
49
|
+
named `my-app`.
|
|
50
|
+
3. `cd my-app`.
|
|
51
|
+
4. Open the `my-app` folder in Claude Code.
|
|
52
|
+
5. Run `/customize` -- it interviews you and tailors the baseline to your
|
|
53
|
+
project.
|
|
54
|
+
|
|
55
|
+
> [!NOTE]
|
|
56
|
+
> Earlier releases shipped on other [dist-tags](https://github.com/monte3l/m3l-groundwork/blob/main/docs/glossary.md#dist-tag).
|
|
57
|
+
> If you installed a `0.x` release from `next` or a `1.0.0-rc` release from
|
|
58
|
+
> `rc`, switch to the default `latest` tag: a prerelease version range never
|
|
59
|
+
> crosses to `1.0.0` on its own. See
|
|
60
|
+
> ["Versioning policy"](#versioning-policy) below for what counts as the
|
|
61
|
+
> CLI's public API, frozen since 1.0.
|
|
62
|
+
|
|
63
|
+
## What it is
|
|
64
|
+
|
|
65
|
+
A two-phase bootstrapper. Point it at a directory and it leaves you with a
|
|
66
|
+
strict TypeScript toolchain, a Claude Code [harness](https://github.com/monte3l/m3l-groundwork/blob/main/docs/glossary.md#harness),
|
|
67
|
+
and CI wired to the same gates you run locally.
|
|
68
|
+
|
|
69
|
+
**Phase A** (`packages/cli`) is deterministic: an offline Node CLI with no
|
|
70
|
+
runtime dependencies that writes the baseline. It makes no network call
|
|
71
|
+
beyond the final package install, and the same input always produces the
|
|
72
|
+
same output.
|
|
73
|
+
|
|
74
|
+
**Phase B** (`packages/plugin`) is adaptive: the [`/customize`](https://github.com/monte3l/m3l-groundwork/blob/main/docs/glossary.md#customize)
|
|
75
|
+
skill, which interviews you (or, for an existing project, reconciles the
|
|
76
|
+
CLI's survey against the real repo) and then sweeps current official
|
|
77
|
+
TypeScript and Anthropic sources, so the result reflects upstream guidance
|
|
78
|
+
today rather than whenever this repo last shipped.
|
|
79
|
+
|
|
80
|
+
They stay two separate phases on purpose, rather than one -- see
|
|
81
|
+
[`docs/architecture.md`](https://github.com/monte3l/m3l-groundwork/blob/main/docs/architecture.md#the-two-phase-split) for why.
|
|
82
|
+
|
|
83
|
+
## Two modes
|
|
84
|
+
|
|
85
|
+
The mode is auto-detected from the target directory; `--fresh` and `--adopt`
|
|
86
|
+
override it.
|
|
87
|
+
|
|
88
|
+
| Mode | When | What it does |
|
|
89
|
+
| --------- | --------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
90
|
+
| **Fresh** | The target is empty or missing | Writes the full baseline, installs any `--pack`, installs the `/customize` skill, runs `git init`, then `pnpm install`. |
|
|
91
|
+
| **Adopt** | The target already looks like a project | Surveys it read-only and writes `.groundwork/`: an inventory, a report, inert `.staged` copies of the baseline files it would add (`.groundwork/baseline/`) and of the packs (`.groundwork/packs/`). It writes only under `.groundwork/`, plus one guarded copy of the `/customize` skill, and never overwrites a project file. |
|
|
92
|
+
|
|
93
|
+
That copy lands at `.claude/skills/customize/`, or at `.groundwork/customize/`
|
|
94
|
+
when something already there blocks it. It is where the real work happens: it reads the survey, confirms
|
|
95
|
+
each change with you, and only then edits your project.
|
|
96
|
+
|
|
97
|
+
## Packs
|
|
98
|
+
|
|
99
|
+
A [pack](https://github.com/monte3l/m3l-groundwork/blob/main/docs/glossary.md#pack) is an optional bundle of extra files -- an
|
|
100
|
+
agent, a hook, a gate -- installed on top of the baseline for projects that
|
|
101
|
+
want more than the capped default. A pack never edits YAML or JavaScript;
|
|
102
|
+
it only adds files and extends three JSON files the baseline already
|
|
103
|
+
reads. See [`templates/packs/README.md`](https://github.com/monte3l/m3l-groundwork/blob/main/templates/packs/README.md) for
|
|
104
|
+
the wiring contract.
|
|
105
|
+
|
|
106
|
+
| Pack | Contents |
|
|
107
|
+
| ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
108
|
+
| `harness-extras` | The compaction-handoff hook pair, a read-only Bash guard, and a five-row Claude Code status line plus a per-subagent row renderer, width-fit to the terminal. |
|
|
109
|
+
| `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. |
|
|
110
|
+
| `github` | Anthropic's official Claude Code GitHub Action (`@claude` mention-mode) plus an automated PR-review Action and three `gh`-CLI skills (Dependabot PR triage, scan-alert triage, PR-check watching) -- no hooks, no gate. Needs an auth secret the pack cannot create. |
|
|
111
|
+
| `publishing` | A release pipeline (changesets version-PR / staged, provenance-attested npm publish via trusted publishing) plus SPDX license headers. Fresh mode only. |
|
|
112
|
+
| `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. |
|
|
113
|
+
| `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. |
|
|
114
|
+
|
|
115
|
+
In fresh mode `--pack` installs a pack directly. In adopt mode the CLI only
|
|
116
|
+
surveys which packs apply and stages them under `.groundwork/packs/` (and
|
|
117
|
+
the baseline files it would add under `.groundwork/baseline/`);
|
|
118
|
+
`/customize` installs from there after you confirm.
|
|
119
|
+
|
|
120
|
+
## Flags
|
|
121
|
+
|
|
122
|
+
| Flag | Effect |
|
|
123
|
+
| ----------------------- | ----------------------------------------------------------------------------- |
|
|
124
|
+
| `--name <project-name>` | Override the project name (default: the target directory's basename). |
|
|
125
|
+
| `--skip-install` | Skip the final `pnpm install` (fresh mode only). |
|
|
126
|
+
| `--force` | Overwrite a non-empty target directory (fresh mode only). |
|
|
127
|
+
| `--adopt` | Force adopt mode, even if the target looks empty. |
|
|
128
|
+
| `--fresh` | Force fresh mode, even if the target looks like an existing project. |
|
|
129
|
+
| `--pack <name>` | Install an opt-in pack from `templates/packs/` (fresh mode only; repeatable). |
|
|
130
|
+
| `--list-packs` | Print every available pack and exit. |
|
|
131
|
+
| `--help`, `--version` | Print usage, or the CLI's version. |
|
|
132
|
+
|
|
133
|
+
An unexpected failure (anything that is not a bad invocation) prints its
|
|
134
|
+
error name before the message, for example `TypeError: ...`. Set `M3L_DEBUG`
|
|
135
|
+
to any non-empty value to also print its stack trace.
|
|
136
|
+
|
|
137
|
+
## Requirements
|
|
138
|
+
|
|
139
|
+
- **Node 24+**. `.node-version` is the authority.
|
|
140
|
+
- **pnpm**. Fresh mode ends with a `pnpm install` in the new project (skip it
|
|
141
|
+
with `--skip-install`), and this repo pins 12.8.1 through `packageManager`.
|
|
142
|
+
- **git**.
|
|
143
|
+
- **Claude Code**, for Phase B only. The CLI itself does not need it.
|
|
144
|
+
|
|
145
|
+
## Install and run
|
|
146
|
+
|
|
147
|
+
The Quickstart above covers the common case. Here are two other ways to
|
|
148
|
+
run this project.
|
|
149
|
+
|
|
150
|
+
To run it from a checkout instead (or to work on it), build it and call the
|
|
151
|
+
built entry point directly:
|
|
26
152
|
|
|
27
153
|
```bash
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
|
|
154
|
+
git clone https://github.com/monte3l/m3l-groundwork.git
|
|
155
|
+
cd m3l-groundwork
|
|
156
|
+
pnpm install
|
|
157
|
+
pnpm build
|
|
158
|
+
|
|
159
|
+
node packages/cli/bin/m3l-groundwork.mjs ../my-new-project
|
|
160
|
+
```
|
|
161
|
+
|
|
162
|
+
The `/customize` skill is also available as a Claude Code plugin, for use in
|
|
163
|
+
a project that was not bootstrapped by this CLI:
|
|
164
|
+
|
|
31
165
|
```
|
|
166
|
+
/plugin marketplace add monte3l/m3l-groundwork
|
|
167
|
+
/plugin install m3l-groundwork-customize@monte3l
|
|
168
|
+
```
|
|
169
|
+
|
|
170
|
+
`npx` leaves nothing installed globally -- it only populates its own
|
|
171
|
+
download cache (`npm cache clean` clears it, if you want that back too).
|
|
172
|
+
|
|
173
|
+
## What a fresh bootstrap gives you
|
|
174
|
+
|
|
175
|
+
```
|
|
176
|
+
my-new-project/
|
|
177
|
+
├── src/, tests/ # placeholder entry point and test
|
|
178
|
+
├── tsconfig*.json # strict flags, split into base / tooling / build
|
|
179
|
+
├── eslint.config.js # typescript-eslint, flat config
|
|
180
|
+
├── vitest.config.ts # v8 coverage with a per-file gate
|
|
181
|
+
├── lefthook.yml # pre-commit, commit-msg and pre-push hooks
|
|
182
|
+
├── bin/verify.mjs # runs the same five gate groups CI runs
|
|
183
|
+
├── .github/workflows/ # ci, dependency-review, security-audit
|
|
184
|
+
├── .claude/ # agents, skills, hooks, rules, settings.json
|
|
185
|
+
├── CLAUDE.md # the agent-facing project guide
|
|
186
|
+
└── docs/research/ # living trackers for the guidance sweeps
|
|
187
|
+
```
|
|
188
|
+
|
|
189
|
+
`pnpm verify` runs the same five [groups](https://github.com/monte3l/m3l-groundwork/blob/main/docs/glossary.md#verify-group)
|
|
190
|
+
(`format`, `lint`, `typecheck`, `build`, `test`) that the pre-push hook and
|
|
191
|
+
CI run, all read from one list in `bin/lib/verify-steps.mjs`. The baseline
|
|
192
|
+
is also graded by two offline checks, one for the harness and one for the
|
|
193
|
+
toolchain, that run as part of `pnpm verify`.
|
|
194
|
+
|
|
195
|
+
The baseline is deliberately [capped](https://github.com/monte3l/m3l-groundwork/blob/main/docs/glossary.md#cap): at most 5
|
|
196
|
+
agents, 8 skills, 10 hooks, 3 CI workflows and 12 root scripts. Anything
|
|
197
|
+
useful beyond that ships as a pack instead.
|
|
198
|
+
|
|
199
|
+
## Then run /customize
|
|
200
|
+
|
|
201
|
+
The skill lands at `.claude/skills/customize/` in the target project. Open it
|
|
202
|
+
in Claude Code and run `/customize`.
|
|
203
|
+
|
|
204
|
+
In adopt mode the CLI never removes or overwrites anything the project owns
|
|
205
|
+
there. A `.claude/skills/customize/` that holds only files with none of the
|
|
206
|
+
skill's names is used as is, and the skill is added beside them. If the
|
|
207
|
+
project already owns an entry under one of the skill's names, the CLI writes
|
|
208
|
+
the skill to `.groundwork/customize/` instead and says so; Claude Code does
|
|
209
|
+
not load that copy, so run the plugin's `/customize` or replace the project's
|
|
210
|
+
copy yourself. If `.claude`, `.claude/skills` or `.claude/skills/customize` is
|
|
211
|
+
a symlink or not a directory, no project copy exists: fix that path, copy the
|
|
212
|
+
staged skill into place, or run the plugin's `/customize`. Fresh mode with
|
|
213
|
+
`--force` does replace an existing skill copy. Fresh mode also checks, before
|
|
214
|
+
it writes anything, that no directory component of a destination below the target directory and no existing
|
|
215
|
+
file the baseline or a `--pack` would write is a symlink (or a non-directory
|
|
216
|
+
where a directory is needed); the same check covers the `/customize` skill copy's destination. If one fails, it refuses and writes nothing. The
|
|
217
|
+
target directory itself and its ancestors are not checked, and neither are
|
|
218
|
+
the `.git` directory `git init` creates and the `node_modules` the install step
|
|
219
|
+
fills: a symlink there is followed.
|
|
220
|
+
|
|
221
|
+
- **Fresh project:** a short interview (project kind, runtime target, test
|
|
222
|
+
strictness, CI depth) tailors the baseline, then a guidance sweep checks the
|
|
223
|
+
result against current upstream sources.
|
|
224
|
+
- **Adopted project:** Step 0 reconciles the survey against the real repo and
|
|
225
|
+
confirms each change before anything is written, then the same guidance
|
|
226
|
+
sweep runs.
|
|
227
|
+
|
|
228
|
+
## Working on this repo
|
|
229
|
+
|
|
230
|
+
`pnpm verify` runs every gate. The pre-push hook and CI run the same five
|
|
231
|
+
groups by name, so anything `pnpm verify` catches, CI catches too. CI adds
|
|
232
|
+
one job on top, `pnpm test:e2e`, which is the real acceptance test: it
|
|
233
|
+
bootstraps throwaway projects with the built CLI and runs their own
|
|
234
|
+
`pnpm verify`. It is slow and touches the network, so it is not part of
|
|
235
|
+
`pnpm verify`; run it yourself after any change to `packages/cli/src/`,
|
|
236
|
+
`templates/core/` or the `/customize` skill. `pnpm eval` makes paid model
|
|
237
|
+
calls and never runs in CI.
|
|
238
|
+
|
|
239
|
+
See [`CONTRIBUTING.md`](https://github.com/monte3l/m3l-groundwork/blob/main/CONTRIBUTING.md) for the full setup and PR workflow.
|
|
240
|
+
|
|
241
|
+
### Releasing
|
|
242
|
+
|
|
243
|
+
See [`CONTRIBUTING.md`](https://github.com/monte3l/m3l-groundwork/blob/main/CONTRIBUTING.md#releasing) for how
|
|
244
|
+
`@monte3l/groundwork` is released, published, and verified, and
|
|
245
|
+
[`CLAUDE.md`](https://github.com/monte3l/m3l-groundwork/blob/main/CLAUDE.md#releases) for the full design.
|
|
246
|
+
|
|
247
|
+
[`CLAUDE.md`](https://github.com/monte3l/m3l-groundwork/blob/main/CLAUDE.md) is the full reference: architecture, the command
|
|
248
|
+
table, conventions, and known gaps.
|
|
249
|
+
|
|
250
|
+
### Project docs
|
|
251
|
+
|
|
252
|
+
- [`CONTRIBUTING.md`](https://github.com/monte3l/m3l-groundwork/blob/main/CONTRIBUTING.md) -- how to contribute.
|
|
253
|
+
- [`GOVERNANCE.md`](https://github.com/monte3l/m3l-groundwork/blob/main/GOVERNANCE.md) -- decision-making, roles, and access
|
|
254
|
+
continuity.
|
|
255
|
+
- [`ROADMAP.md`](https://github.com/monte3l/m3l-groundwork/blob/main/ROADMAP.md) -- what's planned, and what isn't.
|
|
256
|
+
- [`SECURITY.md`](https://github.com/monte3l/m3l-groundwork/blob/main/SECURITY.md) -- reporting a vulnerability, and how to
|
|
257
|
+
verify a release.
|
|
258
|
+
- [`docs/architecture.md`](https://github.com/monte3l/m3l-groundwork/blob/main/docs/architecture.md) -- a high-level map of the
|
|
259
|
+
two phases.
|
|
260
|
+
- [`docs/assurance-case.md`](https://github.com/monte3l/m3l-groundwork/blob/main/docs/assurance-case.md) -- the threat model and
|
|
261
|
+
security design argument.
|
|
262
|
+
- [`docs/glossary.md`](https://github.com/monte3l/m3l-groundwork/blob/main/docs/glossary.md) -- plain-English definitions of
|
|
263
|
+
this repo's jargon.
|
|
264
|
+
- [`CODE_OF_CONDUCT.md`](https://github.com/monte3l/m3l-groundwork/blob/main/CODE_OF_CONDUCT.md).
|
|
265
|
+
|
|
266
|
+
### Exit codes and failure behaviour
|
|
267
|
+
|
|
268
|
+
Exit `2` is a bad invocation, raised before anything is written. Exit `1` is
|
|
269
|
+
everything else that goes wrong at run time.
|
|
270
|
+
|
|
271
|
+
| Situation | Exit | What happens / what to do |
|
|
272
|
+
| ------------------------------------------------------------------------------------------ | ---- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
273
|
+
| Unrecognized flag, missing flag value, repeated `--name`, missing or extra target argument | 2 | Prints the error and the usage text. |
|
|
274
|
+
| `--adopt` with `--fresh` | 2 | The two are mutually exclusive. |
|
|
275
|
+
| `--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. |
|
|
276
|
+
| Unknown `--pack` | 2 | Lists the available packs. A retired name gets a hint: `statusline` was renamed to `harness-extras`. |
|
|
277
|
+
| `--pack` for a pack without fresh mode | 2 | Says the pack does not support fresh mode and lists its modes. |
|
|
278
|
+
| 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. |
|
|
279
|
+
| Windows, fresh mode | 1 | Refuses before writing anything: Linux and macOS only. Adopt mode, `--help`, `--version` and `--list-packs` still run. |
|
|
280
|
+
| Fresh target is not empty and `--force` is absent | 1 | Refuses; pass `--force` to overwrite, or `--adopt` to survey it. |
|
|
281
|
+
| Fresh mode, `/customize` skill install fails | 1 | The project is already written and `git init` and `pnpm install` did not run. Re-run with `--fresh --force` plus your original `--name`, `--pack` and `--skip-install`; a plain re-run adopts it. |
|
|
282
|
+
| Fresh mode, `git init` fails | 1 | The project is left written. Run `git init` (and `pnpm install` unless `--skip-install`) yourself. |
|
|
283
|
+
| Fresh mode, `pnpm install` fails | 1 | The project is left written without dependencies. Run `pnpm install` there yourself. |
|
|
284
|
+
| Adopt mode fails after it starts deleting the previous run's files | 1 | The message names which of `inventory.json`, `adoption-report.md` and `adoption-decisions.json` were removed; fix the cause and re-run. A removed `adoption-decisions.json` is not recreated. |
|
|
285
|
+
| A pack's manifest fails to load | 1 | A broken install, not a bad invocation. |
|
|
286
|
+
|
|
287
|
+
A flag value that starts with `-` counts as missing, and `--pack` is the only value
|
|
288
|
+
flag you can repeat. `--help`, `--version` and `--list-packs` exit `0`, but an
|
|
289
|
+
unrecognized or malformed flag anywhere on the command line still exits `2` first.
|
|
290
|
+
|
|
291
|
+
### Mode signals
|
|
292
|
+
|
|
293
|
+
In adopt mode the signal that chose the mode is printed as
|
|
294
|
+
`adopt mode: <signal>` and recorded in the report's `**Mode:**` line. The
|
|
295
|
+
fresh-mode signals only explain the detection: nothing prints them.
|
|
296
|
+
|
|
297
|
+
| Signal | Mode | When |
|
|
298
|
+
| ------------------------------------------------------ | ----- | ----------------------------------------------------- |
|
|
299
|
+
| `<dir> does not exist yet` | Fresh | The target is missing. |
|
|
300
|
+
| `<dir> is empty` | Fresh | The target is an empty directory. |
|
|
301
|
+
| `<dir> exists but has no recognizable project markers` | Fresh | None of the adopt signals below match. |
|
|
302
|
+
| `found package.json` | Adopt | A `package.json` is in the target. |
|
|
303
|
+
| `found a .git directory` | Adopt | A `.git` directory is in the target. |
|
|
304
|
+
| `found a .git file (a worktree or submodule)` | Adopt | `.git` is a file. |
|
|
305
|
+
| `found <name>` | Adopt | A loose `.ts`, `.tsx` or `.js` file is in the target. |
|
|
306
|
+
| `--adopt forced` | Adopt | `--adopt` was passed. |
|
|
307
|
+
| `--fresh forced` | Fresh | `--fresh` was passed. |
|
|
308
|
+
|
|
309
|
+
### Report headings
|
|
310
|
+
|
|
311
|
+
`.groundwork/adoption-report.md` is written in this order. Headings are
|
|
312
|
+
exact strings.
|
|
313
|
+
|
|
314
|
+
| Heading | Present |
|
|
315
|
+
| ---------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
316
|
+
| `# Adoption report` | Always, followed by a `Generated ...` line and the `**Mode:**` line |
|
|
317
|
+
| `## Codebase shape` | Always |
|
|
318
|
+
| `## Toolchain enforcement in effect` | Always |
|
|
319
|
+
| `## Toolchain grade` | Always; says there is nothing to grade when no toolchain files exist. Has `### Toolchain wiring findings` and `### Toolchain quality findings (advisory)` when there is something to grade |
|
|
320
|
+
| `## Existing Claude Code harness` | Always; short when there is no `.claude/` directory |
|
|
321
|
+
| `## Harness grade` | Always; says there is nothing to grade when neither `.claude/` nor `CLAUDE.md` exists. Has `### Wiring findings`, `### Quality findings (advisory)` and `### Baseline harness files this project has changed` when applicable |
|
|
322
|
+
| `## Human-facing docs & guidelines` | Always |
|
|
323
|
+
| `## Baseline caps after a merge (approximate)` | Always |
|
|
324
|
+
| `## Available packs` | Always, with one `### <pack name>` per pack when any packs exist |
|
|
325
|
+
| `## What groundwork would change` | Always |
|
|
326
|
+
| `## Could not be determined` | Always |
|
|
327
|
+
| `## Next step` | Always, followed by a staged-files note (when anything was staged) and a note that `.groundwork/` was not added to `.gitignore` |
|
|
328
|
+
|
|
329
|
+
The CLI never edits your `.gitignore`: the closing note says so and leaves
|
|
330
|
+
the choice to you.
|
|
331
|
+
|
|
332
|
+
## Versioning policy
|
|
333
|
+
|
|
334
|
+
`@monte3l/groundwork` follows [Semantic Versioning](https://semver.org/).
|
|
335
|
+
Until 1.0.0, breaking changes ship in a `minor` release, as SemVer allows
|
|
336
|
+
for major version zero -- see the changesets in this repo's history for
|
|
337
|
+
examples. From 1.0.0, the public API is:
|
|
338
|
+
|
|
339
|
+
1. **CLI flags, modes, and exit codes** -- `--help` lists every flag; exit
|
|
340
|
+
`0` is success, `1` is a runtime failure, `2` is a bad invocation (see
|
|
341
|
+
[Exit codes and failure behaviour](#exit-codes-and-failure-behaviour)).
|
|
342
|
+
The mode is announced on stdout as `adopt mode: <signal>` (adopt only)
|
|
343
|
+
and in the report as `**Mode:** adopt -- <signal>`; the signals are
|
|
344
|
+
listed under [Mode signals](#mode-signals).
|
|
345
|
+
2. **`.groundwork/inventory.json`** -- a `schemaVersion` bump that
|
|
346
|
+
`/customize` can't read is a breaking change.
|
|
347
|
+
3. **`.groundwork/adoption-report.md`'s section headings**, listed under
|
|
348
|
+
[Report headings](#report-headings).
|
|
349
|
+
4. **`.groundwork/packs/` and `.groundwork/baseline/` staging layouts**, and
|
|
350
|
+
pack names. Baseline files are staged as inert copies with a `.staged`
|
|
351
|
+
suffix appended to each name (so no project tool discovers them), listed
|
|
352
|
+
with their original path and a `sha256` in `inventory.json`'s
|
|
353
|
+
`stagedBaseline`. Packs follow the same convention:
|
|
354
|
+
`.groundwork/packs/<name>/pack.json.staged` and
|
|
355
|
+
`.groundwork/packs/<name>/files/<path>.staged`, listed with their original
|
|
356
|
+
path and a `sha256` in `inventory.json`'s `stagedPacks`. All packs are
|
|
357
|
+
staged together: written to a temp sibling directory and swapped in by
|
|
358
|
+
rename, never half-written.
|
|
359
|
+
5. **The `engines.node` floor** -- narrowing it is breaking; widening it
|
|
360
|
+
isn't.
|
|
361
|
+
6. **`/customize`'s invocation name**, and the promise that it reads every
|
|
362
|
+
inventory `schemaVersion` the CLI has ever emitted since 1.0.
|
|
363
|
+
|
|
364
|
+
**Not covered by this policy:** the **contents** of the baseline the CLI
|
|
365
|
+
emits (`templates/core/`, `templates/packs/`). What a fresh bootstrap
|
|
366
|
+
writes into your project follows current upstream TypeScript and Anthropic
|
|
367
|
+
guidance and can change in a minor release -- that's the whole point of
|
|
368
|
+
`/customize`'s live guidance sweep. Also not covered: internal modules
|
|
369
|
+
(anything under `packages/*/src/` not listed above) and the exact prose of
|
|
370
|
+
`adoption-report.md`'s body.
|
|
32
371
|
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
every flag, or `--list-packs` for the optional packs. Exit `0` is success, `1`
|
|
36
|
-
is a runtime failure, and `2` is a bad invocation.
|
|
372
|
+
**Deprecation:** anything on this list gets at least one minor release with
|
|
373
|
+
a visible warning before it's removed in a major release.
|
|
37
374
|
|
|
38
|
-
|
|
39
|
-
the [repository README](https://github.com/monte3l/m3l-groundwork/blob/main/README.md),
|
|
40
|
-
whose [versioning policy](https://github.com/monte3l/m3l-groundwork/blob/main/README.md#versioning-policy)
|
|
41
|
-
also lists the stable surfaces, including the adoption report's section headings.
|
|
42
|
-
Unfamiliar terms (harness, adopt mode, pack, and the rest) are defined in the
|
|
43
|
-
[glossary](https://github.com/monte3l/m3l-groundwork/blob/main/docs/glossary.md).
|
|
375
|
+
## License
|
|
44
376
|
|
|
45
|
-
MIT
|
|
377
|
+
[MIT](https://github.com/monte3l/m3l-groundwork/blob/main/LICENSE). The license covers the bootstrapper itself, not what it
|
|
378
|
+
writes: the code the CLI emits into your project is yours to use and
|
|
379
|
+
relicense as you see fit.
|
package/dist/main.d.ts
CHANGED
|
@@ -18,7 +18,7 @@ export interface CliOptions {
|
|
|
18
18
|
*
|
|
19
19
|
* @example
|
|
20
20
|
* ```sh
|
|
21
|
-
* npx @monte3l/groundwork
|
|
21
|
+
* npx @monte3l/groundwork ./my-app --bogus
|
|
22
22
|
* # stderr: unrecognized option: --bogus (followed by the usage text)
|
|
23
23
|
* echo $? # 2 -- a runtime failure exits 1 instead
|
|
24
24
|
* ```
|
package/dist/main.js
CHANGED
|
@@ -92,7 +92,7 @@ const BOOLEAN_FLAGS = new Set([
|
|
|
92
92
|
*
|
|
93
93
|
* @example
|
|
94
94
|
* ```sh
|
|
95
|
-
* npx @monte3l/groundwork
|
|
95
|
+
* npx @monte3l/groundwork ./my-app --bogus
|
|
96
96
|
* # stderr: unrecognized option: --bogus (followed by the usage text)
|
|
97
97
|
* echo $? # 2 -- a runtime failure exits 1 instead
|
|
98
98
|
* ```
|
|
@@ -474,25 +474,44 @@ const STALE_FILE_NAMES = [
|
|
|
474
474
|
"inventory.json",
|
|
475
475
|
"adoption-report.md",
|
|
476
476
|
"adoption-decisions.json",
|
|
477
|
+
"customization-report.md",
|
|
477
478
|
];
|
|
479
|
+
const DECISIONS_CAVEAT = "adoption-decisions.json held the decisions /customize recorded";
|
|
480
|
+
const CUSTOMIZATION_CAVEAT = "customization-report.md held the report /customize wrote";
|
|
481
|
+
/**
|
|
482
|
+
* The "a re-run does not recreate it" caveat for whichever of the two
|
|
483
|
+
* `/customize`-written files were removed: empty when neither was, one
|
|
484
|
+
* clause when one was, and a single combined clause when both were.
|
|
485
|
+
*/
|
|
486
|
+
function notRecreatedCaveat(removed) {
|
|
487
|
+
const decisions = removed.includes("adoption-decisions.json");
|
|
488
|
+
const customization = removed.includes("customization-report.md");
|
|
489
|
+
if (decisions && customization) {
|
|
490
|
+
return ` -- ${DECISIONS_CAVEAT}, and ${CUSTOMIZATION_CAVEAT}; a re-run recreates neither`;
|
|
491
|
+
}
|
|
492
|
+
if (decisions) {
|
|
493
|
+
return ` -- ${DECISIONS_CAVEAT}, which a re-run does not recreate`;
|
|
494
|
+
}
|
|
495
|
+
if (customization) {
|
|
496
|
+
return ` -- ${CUSTOMIZATION_CAVEAT}, which a re-run does not recreate`;
|
|
497
|
+
}
|
|
498
|
+
return "";
|
|
499
|
+
}
|
|
478
500
|
/**
|
|
479
501
|
* Which previous `.groundwork/` files a failed run actually removed, worded
|
|
480
502
|
* for a message: only those in `removed` are named, and the decisions file
|
|
481
|
-
*
|
|
482
|
-
* them.
|
|
503
|
+
* and the customization report each carry their "a re-run does not recreate
|
|
504
|
+
* it" caveat only when they are among them.
|
|
483
505
|
*/
|
|
484
506
|
function describeRemoved(removed) {
|
|
485
507
|
if (removed.length === 0) {
|
|
486
|
-
return "no previous .groundwork/ inventory, report
|
|
508
|
+
return "no previous .groundwork/ inventory, adoption report, decisions file or customization report was removed";
|
|
487
509
|
}
|
|
488
510
|
const names = removed.length === 1
|
|
489
511
|
? removed.join("")
|
|
490
512
|
: `${removed.slice(0, -1).join(", ")} and ${removed.slice(-1).join("")}`;
|
|
491
513
|
const verb = removed.length === 1 ? "was" : "were";
|
|
492
|
-
|
|
493
|
-
? " -- adoption-decisions.json held the decisions /customize recorded, which a re-run does not recreate"
|
|
494
|
-
: "";
|
|
495
|
-
return `the previous .groundwork/${names} ${verb} removed${decisionsCaveat}`;
|
|
514
|
+
return `the previous .groundwork/${names} ${verb} removed${notRecreatedCaveat(removed)}`;
|
|
496
515
|
}
|
|
497
516
|
/**
|
|
498
517
|
* A failure after `runAdopt`'s point of no return. The message embeds the
|
|
@@ -583,7 +602,7 @@ function groundworkReportNextStep(result) {
|
|
|
583
602
|
* already deleted, so nothing reads the gap as a completed run.
|
|
584
603
|
*
|
|
585
604
|
* Checked before anything under `.groundwork/` is deleted or written, in
|
|
586
|
-
* this order: the
|
|
605
|
+
* this order: the four stale-file paths are scope-checked against
|
|
587
606
|
* {@link assertAdoptWriteScope}; every pack is loaded and validated by
|
|
588
607
|
* `loadPack` and surveyed (`planConflicts`, `observeWiring`); the pack
|
|
589
608
|
* staging plan (`planPackStaging`) and the baseline staging plan
|
|
@@ -598,8 +617,9 @@ function groundworkReportNextStep(result) {
|
|
|
598
617
|
* directory throws with the previous `.groundwork/` untouched.
|
|
599
618
|
*
|
|
600
619
|
* **The point of no return** is the first deletion of a stale
|
|
601
|
-
* `inventory.json`/`adoption-report.md`/`adoption-decisions.json
|
|
602
|
-
* order), which follows those checks;
|
|
620
|
+
* `inventory.json`/`adoption-report.md`/`adoption-decisions.json`/
|
|
621
|
+
* `customization-report.md` (in that order), which follows those checks;
|
|
622
|
+
* which of the four existed is
|
|
603
623
|
* recorded just before. After the deletions, packs and the baseline are
|
|
604
624
|
* staged from the plans already computed (their trees are not walked
|
|
605
625
|
* again), the harness and toolchain are graded, the `/customize` skill is
|
|
@@ -610,8 +630,9 @@ function groundworkReportNextStep(result) {
|
|
|
610
630
|
* rename). A failure in any of those steps -- a failed deletion included --
|
|
611
631
|
* is rethrown as an `Error` with the failure as `cause` and its message
|
|
612
632
|
* embedded, naming only the previous files that existed and were actually
|
|
613
|
-
* removed (and, when `adoption-decisions.json`
|
|
614
|
-
*
|
|
633
|
+
* removed (and, when `adoption-decisions.json` or `customization-report.md`
|
|
634
|
+
* is among them, that it held the decisions or the report `/customize`
|
|
635
|
+
* wrote, which a re-run does not recreate),
|
|
615
636
|
* and saying to fix the cause and re-run the CLI -- once, even when the
|
|
616
637
|
* cause's own message already says so. An `AssertionError` (a broken
|
|
617
638
|
* write-scope or containment invariant, a bug a re-run cannot fix) keeps
|
|
@@ -686,11 +707,12 @@ function runAdopt(options, detection) {
|
|
|
686
707
|
let nextStep;
|
|
687
708
|
try {
|
|
688
709
|
// The point of no return: the first deletion. A previous run's
|
|
689
|
-
// inventory/report -- and the decisions
|
|
690
|
-
// them -- must not survive a run that fails
|
|
691
|
-
// read them as describing the new staging.
|
|
692
|
-
// is staged; inventory/report are rewritten
|
|
693
|
-
//
|
|
710
|
+
// inventory/report -- and the decisions and customization report
|
|
711
|
+
// /customize wrote against them -- must not survive a run that fails
|
|
712
|
+
// part-way: /customize would read them as describing the new staging.
|
|
713
|
+
// All four go before anything is staged; inventory/report are rewritten
|
|
714
|
+
// only at the end, and the decisions file and customization report only
|
|
715
|
+
// by /customize. Inside the wrapping, so a failed
|
|
694
716
|
// deletion reports which files are already gone. Every path is removed,
|
|
695
717
|
// not just the pre-existing ones: existsSync follows symlinks, so a
|
|
696
718
|
// dangling one must still go before the report's "wx" write below.
|
package/dist/packs.js
CHANGED
|
@@ -228,6 +228,94 @@ function writeVerifyStepsPacksJson(path, steps) {
|
|
|
228
228
|
lines.push("]");
|
|
229
229
|
writeFileSync(path, lines.join("\n") + "\n");
|
|
230
230
|
}
|
|
231
|
+
const SETTINGS_PRINT_WIDTH = 80;
|
|
232
|
+
const SETTINGS_MAX_DEPTH = 64;
|
|
233
|
+
function isJsonScalar(value) {
|
|
234
|
+
return (value === null ||
|
|
235
|
+
typeof value === "string" ||
|
|
236
|
+
typeof value === "number" ||
|
|
237
|
+
typeof value === "boolean");
|
|
238
|
+
}
|
|
239
|
+
function stringifyScalar(value) {
|
|
240
|
+
const text = JSON.stringify(value);
|
|
241
|
+
if (typeof text !== "string") {
|
|
242
|
+
throw new Error(`settings.json value ${String(value)} is not serializable`);
|
|
243
|
+
}
|
|
244
|
+
return text;
|
|
245
|
+
}
|
|
246
|
+
/**
|
|
247
|
+
* Prints `value` at `indent` (in spaces). `prefix` is what precedes the value
|
|
248
|
+
* on its first line (indent plus any `"key": `) and `suffix` what follows its
|
|
249
|
+
* last (a trailing comma or nothing) -- both count toward the one-line fit
|
|
250
|
+
* check for an all-scalar array. Width is measured in UTF-16 code units
|
|
251
|
+
* (`.length`), not Prettier's display width, so a line holding CJK or other
|
|
252
|
+
* wide characters can stay collapsed where Prettier would expand it. See
|
|
253
|
+
* {@link writeSettingsJson} for the shapes this reproduces and the known
|
|
254
|
+
* divergences.
|
|
255
|
+
*/
|
|
256
|
+
function printSettingsValue(value, indent, prefix, suffix, depth) {
|
|
257
|
+
if (depth > SETTINGS_MAX_DEPTH) {
|
|
258
|
+
throw new Error(`settings.json nests deeper than ${String(SETTINGS_MAX_DEPTH)} levels`);
|
|
259
|
+
}
|
|
260
|
+
if (isJsonScalar(value))
|
|
261
|
+
return stringifyScalar(value);
|
|
262
|
+
const pad = " ".repeat(indent + 2);
|
|
263
|
+
const close = " ".repeat(indent);
|
|
264
|
+
if (Array.isArray(value)) {
|
|
265
|
+
const items = value;
|
|
266
|
+
if (items.length === 0)
|
|
267
|
+
return "[]";
|
|
268
|
+
if (items.every(isJsonScalar)) {
|
|
269
|
+
const flat = `[${items.map(stringifyScalar).join(", ")}]`;
|
|
270
|
+
if ((prefix + flat + suffix).length <= SETTINGS_PRINT_WIDTH)
|
|
271
|
+
return flat;
|
|
272
|
+
}
|
|
273
|
+
const lines = items.map((item, index) => {
|
|
274
|
+
const comma = index < items.length - 1 ? "," : "";
|
|
275
|
+
return `${pad}${printSettingsValue(item, indent + 2, pad, comma, depth + 1)}${comma}`;
|
|
276
|
+
});
|
|
277
|
+
return `[\n${lines.join("\n")}\n${close}]`;
|
|
278
|
+
}
|
|
279
|
+
if (typeof value === "object") {
|
|
280
|
+
// Match JSON.stringify: an own key whose value is undefined is omitted.
|
|
281
|
+
const entries = Object.entries(value).filter(([, v]) => v !== undefined);
|
|
282
|
+
if (entries.length === 0)
|
|
283
|
+
return "{}";
|
|
284
|
+
const lines = entries.map(([key, v], index) => {
|
|
285
|
+
const comma = index < entries.length - 1 ? "," : "";
|
|
286
|
+
const head = `${pad}${stringifyScalar(key)}: `;
|
|
287
|
+
return `${head}${printSettingsValue(v, indent + 2, head, comma, depth + 1)}${comma}`;
|
|
288
|
+
});
|
|
289
|
+
return `{\n${lines.join("\n")}\n${close}}`;
|
|
290
|
+
}
|
|
291
|
+
throw new Error(`settings.json holds a non-JSON ${typeof value} value`);
|
|
292
|
+
}
|
|
293
|
+
/**
|
|
294
|
+
* Serializes `.claude/settings.json` so it matches Prettier's JSON output
|
|
295
|
+
* for the shapes a Claude Code settings file holds -- objects, arrays of
|
|
296
|
+
* objects, and arrays of strings: 2-space indent, objects one key per line
|
|
297
|
+
* (`{}` when empty), an array of objects expanded one element per line
|
|
298
|
+
* (`[]` when empty), and an array of only scalars kept on one line --
|
|
299
|
+
* `["a", "b"]` -- when that whole line, indent and key and any trailing
|
|
300
|
+
* comma included, fits in 80 columns, else expanded one per line.
|
|
301
|
+
* `JSON.stringify(value, null, 2)` always expands arrays, so a short
|
|
302
|
+
* `permissions.deny` list written through `writeJson` fails
|
|
303
|
+
* `prettier --check` after every pack install. Key order is preserved.
|
|
304
|
+
*
|
|
305
|
+
* This is not a general JSON formatter. It throws on a non-JSON value or
|
|
306
|
+
* nesting past a fixed depth, and it diverges from Prettier in ways no
|
|
307
|
+
* settings file reaches today: an array containing arrays or empty objects
|
|
308
|
+
* is always expanded (Prettier collapses it when it fits); a wide numeric
|
|
309
|
+
* array prints one number per line (Prettier fills several per line); width
|
|
310
|
+
* is measured with `.length` code units rather than Prettier's display
|
|
311
|
+
* width, so CJK or other wide characters can collapse a line Prettier would
|
|
312
|
+
* expand; and numbers use `JSON.stringify`'s form (`1e+21`, where Prettier
|
|
313
|
+
* keeps `1e21`).
|
|
314
|
+
*/
|
|
315
|
+
function writeSettingsJson(path, value) {
|
|
316
|
+
mkdirSync(dirname(path), { recursive: true });
|
|
317
|
+
writeFileSync(path, `${printSettingsValue(value, 0, "", "", 0)}\n`);
|
|
318
|
+
}
|
|
231
319
|
/**
|
|
232
320
|
* Installs one pack into a target directory that already has the baseline
|
|
233
321
|
* emitted (fresh mode only). Copies `files/` via the existing `emitTemplate`
|
|
@@ -254,7 +342,7 @@ export function installPack(pack, targetDir, tokens) {
|
|
|
254
342
|
settings = mergeSettingsHooks(settings, manifest.wiring.settings);
|
|
255
343
|
}
|
|
256
344
|
settings = mergeSettingsTopLevel(settings, manifest.wiring.settingsTopLevel ?? {});
|
|
257
|
-
|
|
345
|
+
writeSettingsJson(settingsPath, settings);
|
|
258
346
|
if (Object.keys(manifest.wiring.packageScripts).length > 0) {
|
|
259
347
|
const pkgPath = join(targetDir, "package.json");
|
|
260
348
|
const pkg = readJsonOrThrow(pkgPath);
|
package/dist/report.js
CHANGED
|
@@ -363,21 +363,17 @@ function renderUndeterminedSection(inventory) {
|
|
|
363
363
|
*/
|
|
364
364
|
function renderStagedFilesNote(stagedBaseline, stagedPacks) {
|
|
365
365
|
const parts = [];
|
|
366
|
-
const dirs = [];
|
|
367
366
|
if (stagedBaseline.files.length > 0) {
|
|
368
367
|
parts.push(`the baseline files staged under \`${stagedBaseline.dir}/\``);
|
|
369
|
-
dirs.push(stagedBaseline.dir);
|
|
370
368
|
}
|
|
371
369
|
if (stagedPacks.length > 0) {
|
|
372
370
|
parts.push(`the ${stagedPacks.length} pack(s) staged under \`${STAGED_PACKS_DIR}/\` ` +
|
|
373
371
|
`(each pack's \`${STAGED_PACK_MANIFEST}\` included)`);
|
|
374
|
-
dirs.push(STAGED_PACKS_DIR);
|
|
375
372
|
}
|
|
376
373
|
const subject = parts.join(" and ");
|
|
377
374
|
if (subject === "") {
|
|
378
375
|
return [];
|
|
379
376
|
}
|
|
380
|
-
const ignoreLines = dirs.map((dir) => `\`${dir}/\``).join(" and a ");
|
|
381
377
|
return [
|
|
382
378
|
`${subject.charAt(0).toUpperCase()}${subject.slice(1)} are inert copies, never ` +
|
|
383
379
|
`installed: each carries a \`${STAGED_SUFFIX}\` suffix so no tool in this ` +
|
|
@@ -385,8 +381,8 @@ function renderStagedFilesNote(stagedBaseline, stagedPacks) {
|
|
|
385
381
|
`confirm it. Decide whether to commit or ignore those \`${STAGED_SUFFIX}\` ` +
|
|
386
382
|
"files before your next commit: they are verbatim template copies, so " +
|
|
387
383
|
"a strict license-header check, or any gate that runs over every " +
|
|
388
|
-
|
|
389
|
-
|
|
384
|
+
"tracked file, may flag them. The `.groundwork/*` line in the " +
|
|
385
|
+
"`.gitignore` recommendation below keeps them out of git.",
|
|
390
386
|
"",
|
|
391
387
|
];
|
|
392
388
|
}
|
|
@@ -464,10 +460,22 @@ export function renderReport(inventory, nextStep) {
|
|
|
464
460
|
"is the point where it's caught.",
|
|
465
461
|
"",
|
|
466
462
|
...renderStagedFilesNote(inventory.stagedBaseline, inventory.stagedPacks),
|
|
467
|
-
"`.groundwork/` itself was not added to this project's `.gitignore
|
|
468
|
-
"
|
|
469
|
-
"
|
|
470
|
-
"
|
|
463
|
+
"`.groundwork/` itself was not added to this project's `.gitignore`. " +
|
|
464
|
+
"We recommend tracking this report (and `customization-report.md`, " +
|
|
465
|
+
"once `/customize` has written it) as a record of the adoption, and " +
|
|
466
|
+
"ignoring the rest, which is disposable -- regenerate it any time by " +
|
|
467
|
+
"re-running the CLI:",
|
|
468
|
+
"",
|
|
469
|
+
"```gitignore",
|
|
470
|
+
".groundwork/*",
|
|
471
|
+
"!.groundwork/adoption-report.md",
|
|
472
|
+
"!.groundwork/customization-report.md",
|
|
473
|
+
"```",
|
|
474
|
+
"",
|
|
475
|
+
"`/customize` asks about this at the end of its run. With this rule a " +
|
|
476
|
+
"clone of the project holds the two reports but no " +
|
|
477
|
+
"`.groundwork/inventory.json`, so on such a clone re-run the CLI " +
|
|
478
|
+
"(`npx @monte3l/groundwork .`) and then run `/customize`.",
|
|
471
479
|
"",
|
|
472
480
|
];
|
|
473
481
|
return sections.join("\n");
|
package/package.json
CHANGED
|
@@ -1,15 +1,17 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@monte3l/groundwork",
|
|
3
|
-
"version": "1.0.
|
|
4
|
-
"description": "CLI that
|
|
3
|
+
"version": "1.0.2",
|
|
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
|
-
"typescript",
|
|
7
|
-
"claude-code",
|
|
8
6
|
"bootstrap",
|
|
9
|
-
"
|
|
10
|
-
"
|
|
7
|
+
"claude-code",
|
|
8
|
+
"claude-code-plugin",
|
|
9
|
+
"cli",
|
|
10
|
+
"developer-tools",
|
|
11
|
+
"scaffolding",
|
|
12
|
+
"typescript"
|
|
11
13
|
],
|
|
12
|
-
"homepage": "https://
|
|
14
|
+
"homepage": "https://groundwork.monte3l.com",
|
|
13
15
|
"bugs": {
|
|
14
16
|
"url": "https://github.com/monte3l/m3l-groundwork/issues"
|
|
15
17
|
},
|
|
@@ -59,20 +59,26 @@ procedure, and a compacted session keeps only the start of this file.
|
|
|
59
59
|
|
|
60
60
|
In outline:
|
|
61
61
|
|
|
62
|
-
1. Look for `.groundwork/inventory.json`. No `.groundwork/` at all
|
|
63
|
-
fresh bootstrap: skip to Step 1
|
|
64
|
-
|
|
62
|
+
1. Look for `.groundwork/inventory.json`. No `.groundwork/` at all usually
|
|
63
|
+
means a fresh bootstrap: skip to Step 1, unless `git rev-list -n1 HEAD`
|
|
64
|
+
shows the repository has commits (the folder may be gitignored), in which
|
|
65
|
+
case ask first. A `.groundwork/` holding only tracked report files is a
|
|
66
|
+
clone of an adopted project: re-run the CLI. Any other `.groundwork/` with
|
|
67
|
+
no inventory means an interrupted CLI run, and an unreadable inventory is invalid: in both cases
|
|
65
68
|
stop and change nothing, and never treat the project as a fresh bootstrap.
|
|
66
69
|
2. **The deep read.** The CLI's survey is an index, not an interpretation:
|
|
67
70
|
read the real files it flagged `needsReading`, and reconcile its facts
|
|
68
71
|
against the repository.
|
|
69
|
-
3. **Write the findings back** into `.groundwork/adoption-report.md
|
|
72
|
+
3. **Write the findings back** into `.groundwork/adoption-report.md`,
|
|
73
|
+
replacing the CLI's sections by heading (the table in step 0.3 says which
|
|
74
|
+
are replaced and which are kept), and refresh it after Rounds 1 and 2.
|
|
70
75
|
4. **Confirm** the additions, the conflict resolutions and which packs to
|
|
71
76
|
install, in one `AskUserQuestion` round. Nothing is written to a project
|
|
72
77
|
file before this.
|
|
73
78
|
5. **Record the confirmed decisions** to `.groundwork/adoption-decisions.json`
|
|
74
|
-
so a compacted or resumed session does not re-ask them.
|
|
75
|
-
|
|
79
|
+
so a compacted or resumed session does not re-ask them. Update it after
|
|
80
|
+
every later step, record a dismissed question as dismissed, and after a
|
|
81
|
+
compaction read that file first and never re-ask a recorded decision.
|
|
76
82
|
|
|
77
83
|
## Step 1 — Interview
|
|
78
84
|
|
|
@@ -109,6 +115,10 @@ never names a `ProjectKind` itself (the type lives in this plugin's
|
|
|
109
115
|
happens once, here, visibly, with its reasoning attached — not buried in an
|
|
110
116
|
offline heuristic no one reviews.
|
|
111
117
|
|
|
118
|
+
A question the user dismisses is not an answer. Apply its default, record the
|
|
119
|
+
entry (adopt mode) as `"dismissed"` with that default as the fallback, and report it in
|
|
120
|
+
Step 7 under "Assumed, not answered".
|
|
121
|
+
|
|
112
122
|
Packs are **not** re-asked here — Step 0.4 already collected that decision
|
|
113
123
|
(adopt mode) or the CLI already installed at bootstrap time via `--pack`
|
|
114
124
|
(fresh mode, nothing left to ask). Step 3 below is where a confirmed kind can
|
|
@@ -183,6 +193,12 @@ final summary every place the findings disagreed with what Round 0/1
|
|
|
183
193
|
shipped — that disagreement list is the feature: it's the evidence the
|
|
184
194
|
baseline had gone stale.
|
|
185
195
|
|
|
196
|
+
**A finding that changes hook behaviour** (a guard failing closed, a new
|
|
197
|
+
deny rule, a widened matcher) is not applied silently in either direction. In
|
|
198
|
+
adopt mode, collect those into one `AskUserQuestion` (apply or defer),
|
|
199
|
+
record each answer under `round2` in the decisions file, and put a deferred
|
|
200
|
+
one in the tracker's pending remediation.
|
|
201
|
+
|
|
186
202
|
**The one exception.** Where a finding would undo an **explicit interview
|
|
187
203
|
answer** from Step 1 — the user said tests must not gate `pre-push`,
|
|
188
204
|
guidance says they should — surface the conflict and leave the user's
|
|
@@ -242,3 +258,30 @@ declined, plus any prerequisite named against an enabled plugin
|
|
|
242
258
|
(e.g. `typescript-language-server` on `PATH`, or the Python version a
|
|
243
259
|
plugin's `prerequisites` names) as a follow-up the
|
|
244
260
|
user still has to satisfy.
|
|
261
|
+
|
|
262
|
+
**Write the report to a file as well (adopt mode only).** Save the same report
|
|
263
|
+
to `.groundwork/customization-report.md`, so a reviewer can read it without
|
|
264
|
+
asking for the chat. Include which conflicts were resolved and which packs
|
|
265
|
+
were installed, anything in `round1.dropped` with its reason, a **Needs a
|
|
266
|
+
human read** list (every file in `round1.mechanicallyRetargeted`, plus any
|
|
267
|
+
retargeted gate reported as not exercised), an **Assumed, not answered** list
|
|
268
|
+
(each `"dismissed"` interview entry and the fallback used), and a skipped
|
|
269
|
+
`guard-readonly-bash` with its reason. Rewrite the adoption report's
|
|
270
|
+
`## Next step` to point at this file. Never write it in fresh mode: a
|
|
271
|
+
`.groundwork/` directory with no inventory reads as an interrupted adopt run.
|
|
272
|
+
|
|
273
|
+
**Adopt mode only: ask once about `.gitignore`.** The CLI never edits the
|
|
274
|
+
project's `.gitignore`. Recommend tracking the two reports and ignoring the
|
|
275
|
+
rest of `.groundwork/` (the inventory holds absolute machine paths, the
|
|
276
|
+
staged copies are bulky, and the decisions file is only valid beside its own
|
|
277
|
+
inventory):
|
|
278
|
+
|
|
279
|
+
```gitignore
|
|
280
|
+
.groundwork/*
|
|
281
|
+
!.groundwork/adoption-report.md
|
|
282
|
+
!.groundwork/customization-report.md
|
|
283
|
+
```
|
|
284
|
+
|
|
285
|
+
Add it only if the user agrees. Say that a teammate's clone then holds the
|
|
286
|
+
two reports but no `.groundwork/inventory.json`, which Step 0.1 recognizes as a
|
|
287
|
+
clone and answers with the re-run advice.
|
|
@@ -13,9 +13,29 @@ Contents:
|
|
|
13
13
|
## Step 0 — Reconcile (adopt mode only)
|
|
14
14
|
|
|
15
15
|
1. Look for `.groundwork/inventory.json`.
|
|
16
|
-
- **Absent, and no `.groundwork/` directory either →
|
|
16
|
+
- **Absent, and no `.groundwork/` directory either → usually a fresh
|
|
17
17
|
bootstrap; skip straight to Step 1.** Everything below this step applies
|
|
18
|
-
only when an inventory exists.
|
|
18
|
+
only when an inventory exists. **One guard first:** an adopted project
|
|
19
|
+
may gitignore `.groundwork/`, so a clone can lack the directory. Run
|
|
20
|
+
`git rev-list -n1 HEAD` in the project. Empty output, or a non-zero exit
|
|
21
|
+
(no commits, or not a git repository at all, which is what the CLI's fresh
|
|
22
|
+
mode leaves behind), keeps the fresh path. A commit means the project
|
|
23
|
+
already has history, so ask once with `AskUserQuestion`: "fresh
|
|
24
|
+
bootstrap" or "an adopted project whose `.groundwork/` is missing". The
|
|
25
|
+
second answer stops with the re-run advice below and changes nothing.
|
|
26
|
+
Never apply fresh-mode tailoring to an established codebase on the
|
|
27
|
+
strength of a missing directory alone.
|
|
28
|
+
- **Absent, but `.groundwork/` holds only tracked report files → a clone
|
|
29
|
+
of an adopted project.** The recommended `.gitignore` (Step 7) tracks
|
|
30
|
+
`adoption-report.md` and `customization-report.md` and ignores the
|
|
31
|
+
rest, so a clone has a `.groundwork/` with those reports and no
|
|
32
|
+
inventory, no `baseline/` and no `packs/`. Confirm with
|
|
33
|
+
`git ls-files .groundwork` (it lists the files present). This is not an
|
|
34
|
+
interrupted run. Stop, change nothing, and tell the user: "This clone has
|
|
35
|
+
the adoption reports but not the inventory, which is deliberately not
|
|
36
|
+
committed. Re-run `npx @monte3l/groundwork .` and then run `/customize`
|
|
37
|
+
again. The re-run deletes the tracked `.groundwork/customization-report.md`
|
|
38
|
+
from your working tree; `git restore` brings it back if you want it."
|
|
19
39
|
- **Absent, but `.groundwork/` exists → a previous CLI adopt run did not
|
|
20
40
|
complete** (the CLI deletes the old inventory before it stages anything
|
|
21
41
|
and writes the new one last, so no inventory beside a `.groundwork/`
|
|
@@ -25,12 +45,12 @@ Contents:
|
|
|
25
45
|
previous adopt run did not finish, or `inventory.json` was removed.
|
|
26
46
|
If this project was never adopted (it was bootstrapped fresh), delete
|
|
27
47
|
`.groundwork/` and run `/customize` again. Otherwise re-run
|
|
28
|
-
`npx @monte3l/groundwork
|
|
48
|
+
`npx @monte3l/groundwork .` and then run `/customize` again."
|
|
29
49
|
Change nothing.
|
|
30
50
|
- **Present, but not valid JSON, or its `schemaVersion` is not an integer
|
|
31
51
|
of at least 1 → stop and change nothing.** Tell the user: "`.groundwork/inventory.json`
|
|
32
52
|
is not valid JSON or has no usable `schemaVersion`. Re-run
|
|
33
|
-
`npx @monte3l/groundwork
|
|
53
|
+
`npx @monte3l/groundwork .` and then run `/customize` again."
|
|
34
54
|
|
|
35
55
|
**Check `inventory.schemaVersion` before reading anything else.** This
|
|
36
56
|
skill understands schema versions **1 through 6** (the highest it knows is
|
|
@@ -46,7 +66,7 @@ Contents:
|
|
|
46
66
|
project owns there, nor writes through a symlinked `.claude`), it writes a
|
|
47
67
|
fresh one to `.groundwork/customize/`, which Claude Code does not load. So delete
|
|
48
68
|
that directory first (this discards any local edits the project made to
|
|
49
|
-
its copy) and then re-run `npx @monte3l/groundwork
|
|
69
|
+
its copy) and then re-run `npx @monte3l/groundwork .`. A
|
|
50
70
|
copy in `.groundwork/customize/` is refreshed by re-running the CLI. What
|
|
51
71
|
each version added:
|
|
52
72
|
|
|
@@ -172,7 +192,7 @@ Contents:
|
|
|
172
192
|
`stagedBaseline.files`, a pack's `files` or a pack's manifest
|
|
173
193
|
means stop -- all of Round 1, including conflicts and packs -- and
|
|
174
194
|
change nothing.** This is the single stop list for the staged baseline and the staged packs.
|
|
175
|
-
Tell the user: "The staged baseline in `.groundwork/baseline/` or a staged pack in `.groundwork/packs/` is incomplete or does not match `.groundwork/inventory.json` (<the first entry that failed and why>). Re-run `npx @monte3l/groundwork
|
|
195
|
+
Tell the user: "The staged baseline in `.groundwork/baseline/` or a staged pack in `.groundwork/packs/` is incomplete or does not match `.groundwork/inventory.json` (<the first entry that failed and why>). Re-run `npx @monte3l/groundwork .` and then run `/customize` again." **Never fall back to `inventory.templateRoot` for a schema 5 or later inventory, packs included:** that fallback exists for a schema 1-4 inventory only, and only for the baseline additions (a schema 1-4 inventory's packs are read from their unsuffixed copy, see Step 0.4(c) and Round 1).
|
|
176
196
|
- What a passing check proves: the staging is complete and matches the
|
|
177
197
|
inventory. It does **not** prove the files are untampered -- anyone who
|
|
178
198
|
can edit the staged files can edit the inventory's hashes too.
|
|
@@ -222,9 +242,31 @@ Contents:
|
|
|
222
242
|
3. **Write the findings back** into `.groundwork/adoption-report.md`,
|
|
223
243
|
replacing the CLI's index-level sections ("a `lefthook.yml` exists")
|
|
224
244
|
with semantic ones ("pre-push runs lint and typecheck; tests do not
|
|
225
|
-
gate").
|
|
226
|
-
|
|
227
|
-
|
|
245
|
+
gate"). Do it by heading, never by prepending a new section above the
|
|
246
|
+
old ones: a report that keeps both contradicts itself once Round 1 runs.
|
|
247
|
+
Every `##` heading the CLI emits has exactly one fate:
|
|
248
|
+
|
|
249
|
+
| Heading | Fate |
|
|
250
|
+
| ---------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
|
|
251
|
+
| `## Codebase shape` | Replace now with what the deep read established (what is unresolved stays listed, what it explained goes) |
|
|
252
|
+
| `## Toolchain enforcement in effect` | Replace now ("pre-push runs lint and typecheck; tests do not gate") |
|
|
253
|
+
| `## Existing Claude Code harness` | Replace now with the real wiring, then rewrite again after Round 1 so it states the installed harness |
|
|
254
|
+
| `## Human-facing docs & guidelines` | Replace now with what the docs actually say |
|
|
255
|
+
| `## Could not be determined` | Replace now: drop each item the deep read resolved, keep the rest |
|
|
256
|
+
| `## Toolchain grade` | Keep verbatim: deterministic CLI facts |
|
|
257
|
+
| `## Harness grade` | Keep verbatim: deterministic CLI facts |
|
|
258
|
+
| `## Available packs` | Keep verbatim: deterministic CLI facts |
|
|
259
|
+
| `## Baseline caps after a merge (approximate)` | Rewrite after Round 1 with the real post-install counts |
|
|
260
|
+
| `## What groundwork would change` | Rewrite after Round 1 as "What groundwork changed": resolutions applied, files added, packs installed, planned installs dropped and why |
|
|
261
|
+
| `## Next step` | Rewrite in Step 7 to point at `.groundwork/customization-report.md` |
|
|
262
|
+
|
|
263
|
+
Refresh the report again at the end of Round 1 and Round 2, so no section
|
|
264
|
+
survives that says "none", "would be added" or "run `/customize`" about
|
|
265
|
+
something that already happened. If the no-shell bullet in step 1
|
|
266
|
+
applied, carry its skip note into the rewritten report: this step
|
|
267
|
+
replaces the report's sections, so a note written earlier would be
|
|
268
|
+
dropped.
|
|
269
|
+
|
|
228
270
|
4. **Confirm.** Give a short summary in chat, then ask **one**
|
|
229
271
|
`AskUserQuestion` covering: (a) _did this miss anything about your
|
|
230
272
|
project?_ — the free-text option is the point of this question, not a
|
|
@@ -263,3 +305,61 @@ Contents:
|
|
|
263
305
|
A CLI re-run deletes this file along with the old inventory, because its
|
|
264
306
|
decisions were made against the previous staging; a decisions file found
|
|
265
307
|
beside a fresh inventory therefore belongs to this inventory.
|
|
308
|
+
|
|
309
|
+
Write the file as soon as Step 0.4 is answered, then update it after each
|
|
310
|
+
later step, never only at the end. Its full shape:
|
|
311
|
+
|
|
312
|
+
```json
|
|
313
|
+
{
|
|
314
|
+
"schemaVersion": 1,
|
|
315
|
+
"decidedAt": "2026-01-01T00:00:00Z",
|
|
316
|
+
"progress": { "lastCompletedStep": "step-0.4" },
|
|
317
|
+
"step0": {
|
|
318
|
+
"additions": ["<path>"],
|
|
319
|
+
"conflicts": [{ "path": "<path>", "resolution": "keep|take|merge" }],
|
|
320
|
+
"packs": ["<name>"],
|
|
321
|
+
"missedNotes": "<the user's free text, or empty>"
|
|
322
|
+
},
|
|
323
|
+
"interview": {
|
|
324
|
+
"kind": { "value": "library", "status": "confirmed", "fallback": null }
|
|
325
|
+
},
|
|
326
|
+
"agentsKept": ["Explore"],
|
|
327
|
+
"plugins": { "enabled": ["<id>"], "declined": ["<id>"] },
|
|
328
|
+
"round1": {
|
|
329
|
+
"installed": ["<path>"],
|
|
330
|
+
"dropped": [{ "path": "<path>", "reason": "<why>" }],
|
|
331
|
+
"mechanicallyRetargeted": ["<path>"]
|
|
332
|
+
},
|
|
333
|
+
"round2": {
|
|
334
|
+
"applied": ["<finding>"],
|
|
335
|
+
"deferred": [{ "finding": "<finding>", "reason": "<why>" }]
|
|
336
|
+
}
|
|
337
|
+
}
|
|
338
|
+
```
|
|
339
|
+
|
|
340
|
+
- `progress.lastCompletedStep` is `step-0.4`, `step-1`, `step-3`,
|
|
341
|
+
`step-3-plugins`, `step-4` or `step-6`, set after that step finishes.
|
|
342
|
+
- `interview` holds one entry per Step 1 question. `status` is
|
|
343
|
+
`"confirmed"`, `"corrected"` or `"dismissed"`. A question the user
|
|
344
|
+
dismissed without answering is recorded as `"dismissed"` with the
|
|
345
|
+
default actually used in `fallback`, never as an answer. Step 7 lists it
|
|
346
|
+
under "Assumed, not answered".
|
|
347
|
+
- `agentsKept` and `plugins` are written when Step 1 and Round 1's plugin
|
|
348
|
+
question are answered.
|
|
349
|
+
- `round1.dropped` records every planned install Round 1 did not carry out
|
|
350
|
+
(a guard whose subject does not exist in this project, for instance) with
|
|
351
|
+
the reason. `round1.mechanicallyRetargeted` is Step 3's "needs a human
|
|
352
|
+
read" list.
|
|
353
|
+
- `round2` records each finding applied and each deferred. A finding that
|
|
354
|
+
changes how a hook behaves (making a guard fail closed, a new deny rule, a
|
|
355
|
+
widened matcher) is collected into one `AskUserQuestion` (apply or
|
|
356
|
+
defer), and the answer is recorded here. A deferred one also goes into
|
|
357
|
+
the tracker's pending remediation, so a later sweep does not re-decide it
|
|
358
|
+
silently.
|
|
359
|
+
|
|
360
|
+
**After a compaction or resume, read this file first and never re-ask a
|
|
361
|
+
decision whose entry is already recorded.** Resume at the step after
|
|
362
|
+
`progress.lastCompletedStep`, but always re-run Step 0.1's validity and
|
|
363
|
+
integrity checks first (they are cheap and idempotent), because the project
|
|
364
|
+
can change between sessions. Only a `"dismissed"` entry may be asked
|
|
365
|
+
again.
|
|
@@ -103,7 +103,11 @@ confirmed in Step 0.4:
|
|
|
103
103
|
and the three statusline scripts (`statusline.mjs`, `statusline-layout.mjs`,
|
|
104
104
|
`subagent-statusline.mjs`) and install the pack's other artifacts (the
|
|
105
105
|
compaction-handoff hooks and `guard-readonly-bash`) normally, stating the
|
|
106
|
-
skip plainly in Step 7
|
|
106
|
+
skip plainly in Step 7. `guard-readonly-bash.mjs` imports
|
|
107
|
+
`bin/lib/agent-roster.mjs`: when the project keeps no agents and that file is
|
|
108
|
+
not being installed, skip that one hook too (the pack's `adoptNotes` allow
|
|
109
|
+
it), record it in `round1.dropped` and say in Step 7 that it was skipped and
|
|
110
|
+
why;
|
|
107
111
|
`wiring.verifySteps` becomes a step in whatever this project's real gate
|
|
108
112
|
runner is (a `package.json` script plus a line in its `lefthook.yml`/
|
|
109
113
|
`.husky/pre-push`/CI workflow, written by hand to match its actual shape)
|
|
@@ -111,6 +115,29 @@ confirmed in Step 0.4:
|
|
|
111
115
|
other artifacts and state plainly in Step 7 that the gate was not wired,
|
|
112
116
|
rather than inventing a runner the project never asked for.
|
|
113
117
|
|
|
118
|
+
**Retarget what you installed (adopt mode).** A staged skill, agent, rule or
|
|
119
|
+
hook still speaks the baseline's tooling. For every one you install, rewrite
|
|
120
|
+
each package-manager command to the project's own (`survey.shape.packageManager`;
|
|
121
|
+
a `package.json` script of the same purpose wins over a guessed command) and
|
|
122
|
+
each path to the project's real source and test directories. A project with
|
|
123
|
+
no package manager and no `package.json` gets its real gate in place of the
|
|
124
|
+
command, or the command is removed and Step 7 says the project has none.
|
|
125
|
+
Class every file you touched as one of two:
|
|
126
|
+
|
|
127
|
+
- **Tailored**: you rewrote the prose to fit the project.
|
|
128
|
+
- **Mechanically retargeted**: only the commands and paths were swapped, so
|
|
129
|
+
the surrounding prose may still read oddly.
|
|
130
|
+
|
|
131
|
+
Record the mechanically retargeted files in `round1.mechanicallyRetargeted` and print it in
|
|
132
|
+
Step 7 under **Needs a human read**. Files under a guidance skill's
|
|
133
|
+
`references/` document upstream tools, so they keep their `pnpm` text: name
|
|
134
|
+
that exception in the report instead of editing them. Finally run each
|
|
135
|
+
retargeted gate command (`post-edit-verify`'s formatter, linter and type
|
|
136
|
+
check, for instance) once against the project's real files. When one cannot
|
|
137
|
+
run, because dependencies are not installed for example, report it as **not
|
|
138
|
+
exercised** with the reason, never as working. A planned install you drop for
|
|
139
|
+
any reason goes into `round1.dropped` with that reason.
|
|
140
|
+
|
|
114
141
|
**Plugins (both modes), after packs are settled above.** Build a
|
|
115
142
|
`PluginRecommendationContext`: `chosenPacks` is whatever the packs decision
|
|
116
143
|
just above actually landed on (fresh: what `--pack` installed at bootstrap
|
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: code-implementer
|
|
3
3
|
description: Writer spoke for the TDD build pipeline. Given a contract and a set of failing tests, writes the minimal src/** implementation to make those tests pass, then refactors while green. Use during the GREEN phase of TDD. It writes implementation only — it never writes tests and never reviews code.
|
|
4
|
-
tools: Read, Write, Edit, Grep, Glob, Bash, mcp__context7__resolve-library-id, mcp__context7__query-docs
|
|
4
|
+
tools: Read, Write, Edit, Grep, Glob, Bash, mcp__context7__resolve-library-id, mcp__context7__query-docs, mcp__plugin_context7_context7__resolve-library-id, mcp__plugin_context7_context7__query-docs
|
|
5
5
|
disallowedTools: Agent
|
|
6
6
|
mcpServers: [context7]
|
|
7
7
|
model: claude-opus-5-5
|
|
@@ -102,8 +102,11 @@ that to the hub rather than absorbing it silently.
|
|
|
102
102
|
|
|
103
103
|
## Consulting context7 for library behavioral semantics
|
|
104
104
|
|
|
105
|
-
You hold a scoped grant to `
|
|
106
|
-
|
|
105
|
+
You hold a scoped grant to `resolve-library-id` and `query-docs` under both
|
|
106
|
+
names Claude Code can give the server: `mcp__context7__*` when context7 is a
|
|
107
|
+
project or user MCP server, and `mcp__plugin_context7_context7__*` when it
|
|
108
|
+
comes from the `context7` plugin (a plugin's server is namespaced
|
|
109
|
+
`plugin:<plugin>:<server>`). Use them when you need a third-party
|
|
107
110
|
dependency's _behavioral_ semantics that a `.d.ts` file cannot express:
|
|
108
111
|
retry/backoff behavior, terminal-state classification, pagination contracts,
|
|
109
112
|
or which error a call throws under a specific condition. Resolve the library
|
|
@@ -26,6 +26,16 @@ contract (a documented behavior, an interface to satisfy):
|
|
|
26
26
|
parallel over the diff. Must-fix findings route back to
|
|
27
27
|
`code-implementer` and the loop repeats until clean.
|
|
28
28
|
|
|
29
|
+
**Spokes do not nest, and their `permissionMode` is not a safety property.**
|
|
30
|
+
Claude Code lets a subagent spawn its own, three layers deep by default
|
|
31
|
+
(`CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH`); every spoke here sets
|
|
32
|
+
`disallowedTools: Agent`, which is what keeps the roster flat. A session in
|
|
33
|
+
auto, `acceptEdits` or `bypassPermissions` mode overrides a spoke's
|
|
34
|
+
`permissionMode` (the field applies only under `default`, `dontAsk` or
|
|
35
|
+
`plan`), so `acceptEdits` on the writer spokes is often inert. The PreToolUse
|
|
36
|
+
guards bound a spoke, not `permissionMode`. Source:
|
|
37
|
+
[sub-agents](https://code.claude.com/docs/en/sub-agents).
|
|
38
|
+
|
|
29
39
|
## Dispatch sizing
|
|
30
40
|
|
|
31
41
|
- **Decompose before you dispatch.** Scale the dispatch to task complexity —
|
|
@@ -1,5 +1,8 @@
|
|
|
1
1
|
{
|
|
2
2
|
"$schema": "https://json.schemastore.org/claude-code-settings.json",
|
|
3
|
+
"permissions": {
|
|
4
|
+
"deny": ["Read(./.env)", "Read(./.env.*)", "Read(./secrets/**)"]
|
|
5
|
+
},
|
|
3
6
|
"hooks": {
|
|
4
7
|
"UserPromptSubmit": [
|
|
5
8
|
{
|
|
@@ -29,6 +32,7 @@
|
|
|
29
32
|
{
|
|
30
33
|
"type": "command",
|
|
31
34
|
"command": "node \"$CLAUDE_PROJECT_DIR/.claude/hooks/guard-hub-src-writes.mjs\"",
|
|
35
|
+
"onFailure": "block",
|
|
32
36
|
"timeout": 30
|
|
33
37
|
}
|
|
34
38
|
]
|
|
@@ -49,21 +53,25 @@
|
|
|
49
53
|
{
|
|
50
54
|
"type": "command",
|
|
51
55
|
"command": "node \"$CLAUDE_PROJECT_DIR/.claude/hooks/guard-protected-paths.mjs\"",
|
|
56
|
+
"onFailure": "block",
|
|
52
57
|
"timeout": 30
|
|
53
58
|
},
|
|
54
59
|
{
|
|
55
60
|
"type": "command",
|
|
56
61
|
"command": "node \"$CLAUDE_PROJECT_DIR/.claude/hooks/guard-branch-isolation.mjs\"",
|
|
62
|
+
"onFailure": "block",
|
|
57
63
|
"timeout": 30
|
|
58
64
|
},
|
|
59
65
|
{
|
|
60
66
|
"type": "command",
|
|
61
67
|
"command": "node \"$CLAUDE_PROJECT_DIR/.claude/hooks/guard-hub-src-writes.mjs\"",
|
|
68
|
+
"onFailure": "block",
|
|
62
69
|
"timeout": 30
|
|
63
70
|
},
|
|
64
71
|
{
|
|
65
72
|
"type": "command",
|
|
66
73
|
"command": "node \"$CLAUDE_PROJECT_DIR/.claude/hooks/guard-secret-writes.mjs\"",
|
|
74
|
+
"onFailure": "block",
|
|
67
75
|
"timeout": 30
|
|
68
76
|
}
|
|
69
77
|
]
|
|
@@ -28,8 +28,10 @@ faster — and say in the answer that a full `refresh` sweep is available if
|
|
|
28
28
|
the question turns out to implicate more than the one facet asked about.
|
|
29
29
|
|
|
30
30
|
**Must only run in the main (hub) agent, never inside a subagent** — it ends
|
|
31
|
-
in `EnterPlanMode` (refresh) or dispatches other agents (either mode), which
|
|
32
|
-
|
|
31
|
+
in `EnterPlanMode` (refresh) or dispatches other agents (either mode), which a
|
|
32
|
+
spoke cannot do: every spoke sets `disallowedTools: Agent`, and Claude Code otherwise
|
|
33
|
+
lets a subagent spawn its own, three layers deep by default
|
|
34
|
+
(`CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH`).
|
|
33
35
|
|
|
34
36
|
**No files are written by this skill itself** in research mode by default;
|
|
35
37
|
refresh mode writes to exactly one file, the tracker, in Step 5.
|
|
@@ -96,7 +98,11 @@ concern) — every other facet below is identical regardless of project kind.
|
|
|
96
98
|
`<scratchpad>/harness-refresh-<date>/`.
|
|
97
99
|
2. **Build the delta.** `WebFetch` the Claude Code CHANGELOG, extract
|
|
98
100
|
entries newer than the recorded version. An unreachable source is a
|
|
99
|
-
coverage gap, not a blocker.
|
|
101
|
+
coverage gap, not a blocker. With an `unset` tracker there is no recorded
|
|
102
|
+
version to start from, so the delta has no lower bound: read as far back as
|
|
103
|
+
the fetch returns, and write the oldest version you actually read into the
|
|
104
|
+
tracker as a coverage note (`changelog read back to <version>`), never
|
|
105
|
+
implying full coverage of anything older. Pass this delta into all five briefs below
|
|
100
106
|
— it is not a sixth facet.
|
|
101
107
|
3. **Fan out five fixed facets in one message** — fixed, not derived per
|
|
102
108
|
run, so sweeps stay comparable and the tracker stays diffable:
|
|
@@ -40,7 +40,8 @@ than the one facet asked about.
|
|
|
40
40
|
**Must only run in the main (hub) agent, never inside a subagent** — it ends
|
|
41
41
|
in `EnterPlanMode` (refresh) or an `AskUserQuestion` (research or refresh,
|
|
42
42
|
occasionally), and every mode launches parallel `Explore` research agents,
|
|
43
|
-
none of which a
|
|
43
|
+
none of which a spoke can do (`disallowedTools: Agent` on every spoke; Claude Code
|
|
44
|
+
otherwise allows nesting three layers deep, `CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH`).
|
|
44
45
|
|
|
45
46
|
**No files are written by this skill itself** in research mode by default;
|
|
46
47
|
refresh mode writes to exactly one file, the tracker, in Step 5; `gaps` mode
|
|
@@ -120,6 +121,15 @@ conflict-resolution machinery for an existing value.
|
|
|
120
121
|
check against, not restate. Missing tracker/facet → first run, `NEW`
|
|
121
122
|
only. Then read the allowlist file; state today's date; derive a run
|
|
122
123
|
directory `<scratchpad>/ts-refresh-<date>/`.
|
|
124
|
+
|
|
125
|
+
**A project with no TypeScript toolchain gets no sweep.** When the project
|
|
126
|
+
has no `typescript` entry in `dependencies` or `devDependencies` and no
|
|
127
|
+
`tsconfig*.json`, say so, write nothing else, and set the tracker header to
|
|
128
|
+
`last-verified=n/a typescript-version=n/a reason=no-typescript-toolchain`.
|
|
129
|
+
`unset` means "not run yet" and invites a first sweep; `n/a` says there is
|
|
130
|
+
nothing to sweep. A later run re-checks the condition before honouring `n/a`:
|
|
131
|
+
once a TypeScript toolchain appears, treat the tracker as a first run.
|
|
132
|
+
|
|
123
133
|
2. **Build the delta.** `WebFetch` the devblog index and
|
|
124
134
|
`github.com/microsoft/TypeScript/releases`; extract entries newer than
|
|
125
135
|
the recorded version. An unreachable source is a coverage gap, not a
|
|
@@ -29,6 +29,16 @@ Plus **the official docs of a tool the project's interview actually
|
|
|
29
29
|
selected** for bundling, if one was chosen and isn't already covered above
|
|
30
30
|
(a specific bundler's own docs).
|
|
31
31
|
|
|
32
|
+
Plus **the official docs of any test runner, linter, formatter or type-test
|
|
33
|
+
tool the project itself lists under `devDependencies`** that isn't covered
|
|
34
|
+
above (`ava`, `xo`, Playwright and `expect-type` are the cases that prompted
|
|
35
|
+
this). That tool's own documentation is owner-normative **for that tool
|
|
36
|
+
only**: take its domain from the `homepage` field of its installed
|
|
37
|
+
`package.json` (no network needed), never from a search result, pass it as one
|
|
38
|
+
extra `allowed_domains` entry for that area, and record it in the tracker's
|
|
39
|
+
Sources. A tool with no installed `homepage`, or one hosted on a general
|
|
40
|
+
code-hosting or blogging domain, stays a coverage gap rather than a source.
|
|
41
|
+
|
|
32
42
|
One of the fixed domains is **path-scoped within a domain
|
|
33
43
|
`typescript-guidance` also uses, for a different path**:
|
|
34
44
|
|
package/templates/core/CLAUDE.md
CHANGED
|
@@ -131,6 +131,30 @@ one. Check `/plugin` for installed mods alongside `/status`.
|
|
|
131
131
|
writer spoke only with both present, so a call carrying `agent_type` but no
|
|
132
132
|
`agent_id` is treated as the hub and is blocked.
|
|
133
133
|
|
|
134
|
+
**Four guards block when they crash, and a secrets deny rule ships in
|
|
135
|
+
`settings.json`.** `guard-secret-writes`, `guard-hub-src-writes`,
|
|
136
|
+
`guard-branch-isolation` and `guard-protected-paths` carry
|
|
137
|
+
`"onFailure": "block"` (Claude Code 2.1.295 or later). By default a hook that
|
|
138
|
+
crashes or times out lets the call through; with this key it is blocked. It
|
|
139
|
+
applies only to a failure the hook does not handle itself: each guard still
|
|
140
|
+
catches bad input and exits 0 on purpose, so the key covers a load error, a
|
|
141
|
+
missing `node` or the 30-second timeout. Because `guard-hub-src-writes` is also
|
|
142
|
+
registered on `Bash`, a missing `node` or a timed-out scan blocks every `Bash`
|
|
143
|
+
call until it is fixed (run the command yourself with the `!` prefix to get
|
|
144
|
+
past it). The style guards and `guard-git-push-signed` stay fail-open on
|
|
145
|
+
purpose: the push guard has its own command parser and the remote's
|
|
146
|
+
signed-commit rule is the authoritative layer. `permissions.deny` blocks
|
|
147
|
+
`Read(./.env)`, `Read(./.env.*)` and `Read(./secrets/**)`, which also covers
|
|
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.
|
|
150
|
+
|
|
151
|
+
**A spoke's `permissionMode` can be overridden.** A session in auto,
|
|
152
|
+
`acceptEdits` or `bypassPermissions` mode overrides a spoke's `permissionMode`
|
|
153
|
+
(the field applies only when the session is in `default`, `dontAsk` or
|
|
154
|
+
`plan`), so treat the hooks, not `permissionMode`, as what bounds a spoke.
|
|
155
|
+
Claude Code also lets a subagent spawn subagents three layers deep by default;
|
|
156
|
+
`disallowedTools: Agent` on every spoke is what keeps this roster flat.
|
|
157
|
+
|
|
134
158
|
Full dispatch-sizing and recovery guidance: `.claude/rules/agent-dispatch.md`
|
|
135
159
|
(auto-loads when editing `.claude/skills/**` or `.claude/agents/**`).
|
|
136
160
|
|