@monte3l/groundwork 1.0.1 → 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/package.json +9 -7
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/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
|
},
|