@monte3l/groundwork 1.1.0 → 1.2.0
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 +11 -2
- package/package.json +2 -2
- package/templates/core/.claude/rules/agent-dispatch.md +10 -7
- package/templates/core/.node-version +1 -1
- package/templates/core/CLAUDE.md +1 -1
- package/templates/core/package.json +3 -3
- package/templates/packs/README.md +3 -2
- package/templates/packs/claude-github/files/.github/workflows/claude-pr-review.yml +1 -1
- package/templates/packs/claude-github/files/.github/workflows/claude.yml +11 -5
- package/templates/packs/claude-github/pack.json +1 -1
package/README.md
CHANGED
|
@@ -11,7 +11,7 @@
|
|
|
11
11
|
[](https://www.bestpractices.dev/projects/14937)
|
|
12
12
|
[](https://www.bestpractices.dev/projects/14937)
|
|
13
13
|
[](https://socket.dev/npm/package/@monte3l/groundwork/overview)
|
|
14
|
-
[](https://github.com/monte3l/m3l-groundwork/actions/workflows/reuse.yml)
|
|
15
15
|
|
|
16
16
|
m3l-groundwork is a command-line tool that sets up (or reports on) a
|
|
17
17
|
TypeScript project's toolchain and [Claude Code](https://docs.claude.com/en/docs/claude-code/overview)
|
|
@@ -207,11 +207,20 @@ node packages/cli/bin/m3l-groundwork.mjs ../my-new-project
|
|
|
207
207
|
The `/customize` skill is also available as a Claude Code plugin, for use in
|
|
208
208
|
a project that was not bootstrapped by this CLI:
|
|
209
209
|
|
|
210
|
+
```bash
|
|
211
|
+
claude plugin marketplace add monte3l/m3l-plugins
|
|
212
|
+
claude plugin install m3l-groundwork-customize@monte3l
|
|
210
213
|
```
|
|
214
|
+
|
|
215
|
+
```text
|
|
211
216
|
/plugin marketplace add monte3l/m3l-plugins
|
|
212
217
|
/plugin install m3l-groundwork-customize@monte3l
|
|
213
218
|
```
|
|
214
219
|
|
|
220
|
+
The first pair runs in your shell, the second inside a Claude Code session.
|
|
221
|
+
Settings and management are in the
|
|
222
|
+
[plugin README](https://github.com/monte3l/m3l-groundwork/blob/main/packages/plugin/README.md).
|
|
223
|
+
|
|
215
224
|
`npx` leaves nothing installed globally -- it only populates its own
|
|
216
225
|
download cache (`npm cache clean` clears it, if you want that back too).
|
|
217
226
|
|
|
@@ -385,7 +394,7 @@ the choice to you.
|
|
|
385
394
|
|
|
386
395
|
`@monte3l/groundwork` follows [Semantic Versioning](https://semver.org/).
|
|
387
396
|
Until 1.0.0, breaking changes ship in a `minor` release, as SemVer allows
|
|
388
|
-
for major version zero -- see the
|
|
397
|
+
for major version zero -- see the changelog for
|
|
389
398
|
examples. From 1.0.0, the public API is:
|
|
390
399
|
|
|
391
400
|
1. **CLI flags, modes, and exit codes** -- `--help` lists every flag; exit
|
package/package.json
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@monte3l/groundwork",
|
|
3
|
-
"version": "1.
|
|
4
|
-
"description": "CLI that
|
|
3
|
+
"version": "1.2.0",
|
|
4
|
+
"description": "A CLI that sets up a TypeScript project with a strict toolchain and Claude Code, or surveys an existing one read-only, plus a /customize skill that tailors it to current guidance",
|
|
5
5
|
"keywords": [
|
|
6
6
|
"bootstrap",
|
|
7
7
|
"claude-code",
|
|
@@ -42,10 +42,12 @@ Sources: [hooks](https://code.claude.com/docs/en/hooks),
|
|
|
42
42
|
[hooks guide](https://code.claude.com/docs/en/hooks-guide),
|
|
43
43
|
[managed settings](https://code.claude.com/docs/en/managed-settings),
|
|
44
44
|
[mods events](https://code.claude.com/docs/en/plugins/mods/events),
|
|
45
|
+
[permissions](https://code.claude.com/docs/en/permissions#precedence-among-rules-hooks-and-mods),
|
|
45
46
|
[sub-agents](https://code.claude.com/docs/en/sub-agents) and
|
|
46
47
|
[agent teams](https://code.claude.com/docs/en/agent-teams).
|
|
47
48
|
|
|
48
|
-
- **The `Bash` screen is conservative.**
|
|
49
|
+
- **The `Bash` screen is conservative.** A Monitor command reaches the hook as
|
|
50
|
+
`Bash` (probed on Claude Code 2.1.318). `guard-hub-src-writes.mjs` blocks
|
|
49
51
|
redirects, `tee`, `sed -i`, `cp`/`mv` into a guarded path, an interpreter
|
|
50
52
|
snippet that writes there, and a copy, move or removal of a parent
|
|
51
53
|
(`rsync -a /tmp/x/ ./`, `rm -rf .`). It cannot see an interpreter running a
|
|
@@ -63,16 +65,17 @@ Sources: [hooks](https://code.claude.com/docs/en/hooks),
|
|
|
63
65
|
machine you don't control, run `/status` and read its "Setting sources"
|
|
64
66
|
line: if `guard-hub-src-writes.mjs` and `guard-branch-isolation.mjs` aren't
|
|
65
67
|
running, treat hub-and-spoke as an unenforced checklist.
|
|
66
|
-
- **An installed mod sits below managed settings and above project hooks.**
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
|
|
70
|
-
`/
|
|
68
|
+
- **An installed mod sits below managed settings and above project hooks.**
|
|
69
|
+
Project `PreToolUse` hooks run only after the last mod calls `next`, so a mod
|
|
70
|
+
that answers `tool.call` without it stops them running. A mod's `tool.check`
|
|
71
|
+
answers after the hooks: with managed settings or a Team or Enterprise
|
|
72
|
+
`/login` a call a `PreToolUse` hook blocked stays blocked, and with neither
|
|
73
|
+
the mod can approve it. Check `/plugin` alongside `/status`.
|
|
71
74
|
- **Who counts as a writer.** The guard needs a writer-spoke `agent_type` and a
|
|
72
75
|
non-empty `agent_id`. A fork subagent (on by default in every surface since
|
|
73
76
|
Claude Code 2.1.302) is not a writer spoke, so unless its payload reports a
|
|
74
77
|
writer `agent_type` it is treated as the hub (the docs don't say what a
|
|
75
|
-
fork's payload carries).
|
|
78
|
+
fork's payload carries). At the depth limit a fork's `Agent` tool returns an error. With agent teams on, an in-process
|
|
76
79
|
teammate has a documented `agent_id`; one built from a writer definition that
|
|
77
80
|
also reports that `agent_type` passes as a writer. A split-pane teammate does
|
|
78
81
|
not get `disallowedTools` (only an in-process one does), so every spoke's
|
|
@@ -1 +1 @@
|
|
|
1
|
-
|
|
1
|
+
26
|
package/templates/core/CLAUDE.md
CHANGED
|
@@ -101,7 +101,7 @@ prompt, or edit the hook's registration in `.claude/settings.json`.
|
|
|
101
101
|
deployment (`managed-settings.json`, MDM, a console policy) outranks every file
|
|
102
102
|
here, and `allowManagedHooksOnly` runs only managed hooks. An installed mod
|
|
103
103
|
that handles `tool.check` can approve a call a project `PreToolUse` hook
|
|
104
|
-
blocked,
|
|
104
|
+
blocked, unless managed settings or a Team or Enterprise `/login` is in use. Nothing in the repo can detect
|
|
105
105
|
either: on a machine you don't control, check `/status` ("Setting sources") and
|
|
106
106
|
`/plugin` before trusting `guard-hub-src-writes.mjs` and
|
|
107
107
|
`guard-branch-isolation.mjs`. Detail and sources:
|
|
@@ -40,8 +40,8 @@
|
|
|
40
40
|
"@commitlint/load": "^21.2.2",
|
|
41
41
|
"@commitlint/types": "^21.2.0",
|
|
42
42
|
"@eslint/js": "^10.0.1",
|
|
43
|
-
"@types/node": "^
|
|
44
|
-
"@vitest/coverage-v8": "^5.0.
|
|
43
|
+
"@types/node": "^26.6.6",
|
|
44
|
+
"@vitest/coverage-v8": "^5.0.5",
|
|
45
45
|
"eslint": "^10.11.0",
|
|
46
46
|
"eslint-import-resolver-typescript": "^4.4.5",
|
|
47
47
|
"eslint-plugin-import-x": "^4.17.1",
|
|
@@ -53,6 +53,6 @@
|
|
|
53
53
|
"publint": "^0.3.24",
|
|
54
54
|
"typescript": "^6.0.3",
|
|
55
55
|
"typescript-eslint": "^8.71.0",
|
|
56
|
-
"vitest": "^5.0.
|
|
56
|
+
"vitest": "^5.0.5"
|
|
57
57
|
}
|
|
58
58
|
}
|
|
@@ -17,8 +17,9 @@ templates/packs/<name>/
|
|
|
17
17
|
```
|
|
18
18
|
|
|
19
19
|
A pack has no release of its own: it ships inside the CLI tarball, so a change
|
|
20
|
-
to one that is user-visible
|
|
21
|
-
`
|
|
20
|
+
to one that is user-visible is released by its Conventional Commit type
|
|
21
|
+
(`fix(packs): ...` for a fix or a change to existing behaviour,
|
|
22
|
+
`feat(packs): ...` for new public surface; there is no changeset). The checklist for working on a pack lives in the source
|
|
22
23
|
repository's own `.claude/rules/pack-<name>.md` (m3l-groundwork, not shipped),
|
|
23
24
|
not in the pack, since a pack cannot ship a rule (see below).
|
|
24
25
|
|
|
@@ -86,7 +86,7 @@ jobs:
|
|
|
86
86
|
fetch-depth: 0
|
|
87
87
|
|
|
88
88
|
- id: claude
|
|
89
|
-
uses: anthropics/claude-code-action@
|
|
89
|
+
uses: anthropics/claude-code-action@c0949c50a78c1ec8ce2647db36629b870e715d0c # v1.0.268
|
|
90
90
|
with:
|
|
91
91
|
anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
|
|
92
92
|
# Swap in CLAUDE_CODE_OAUTH_TOKEN or the Workload Identity
|
|
@@ -3,7 +3,9 @@ name: Claude Code
|
|
|
3
3
|
# Anthropic's official Claude Code GitHub Action (anthropics/claude-code-action),
|
|
4
4
|
# in interactive mode: responds to @claude mentions on issues, PR reviews,
|
|
5
5
|
# and review comments. Claude commits to a branch and links back to a
|
|
6
|
-
# PR-creation page -- it never opens a PR itself.
|
|
6
|
+
# PR-creation page -- it never opens a PR itself. Since v1.0.268 a run checks
|
|
7
|
+
# out the PR head as it was at the mention; if the branch moved after that,
|
|
8
|
+
# the run is skipped and you mention @claude again.
|
|
7
9
|
#
|
|
8
10
|
# Want automated review on every PR too? That's a separate workflow, not a
|
|
9
11
|
# block to uncomment here (a second `on:`/`jobs:` in one file would collide
|
|
@@ -67,7 +69,7 @@ jobs:
|
|
|
67
69
|
fetch-depth: 1
|
|
68
70
|
|
|
69
71
|
- name: Run Claude Code
|
|
70
|
-
uses: anthropics/claude-code-action@
|
|
72
|
+
uses: anthropics/claude-code-action@c0949c50a78c1ec8ce2647db36629b870e715d0c # v1.0.268
|
|
71
73
|
with:
|
|
72
74
|
# Option 1 (active default): a stored API key. Install the Claude
|
|
73
75
|
# GitHub App (https://github.com/apps/claude) and add
|
|
@@ -97,7 +99,11 @@ jobs:
|
|
|
97
99
|
# Optional: customize the trigger phrase (default: @claude)
|
|
98
100
|
# trigger_phrase: "/claude"
|
|
99
101
|
|
|
100
|
-
#
|
|
101
|
-
#
|
|
102
|
-
#
|
|
102
|
+
# Cap each run at 20 turns so a runaway loop stops well before the
|
|
103
|
+
# 30-minute job timeout (Anthropic's cost guidance recommends
|
|
104
|
+
# setting one). Raise it if larger tasks hit the cap.
|
|
105
|
+
claude_args: |
|
|
106
|
+
--max-turns 20
|
|
107
|
+
# Further CLI arguments go in the same block, for example, at the
|
|
108
|
+
# same indentation as `--max-turns 20`:
|
|
103
109
|
# --allowedTools "Bash(npm install),Bash(npm run build),Bash(npm run test:*)"
|
|
@@ -15,5 +15,5 @@
|
|
|
15
15
|
"packageScripts": {},
|
|
16
16
|
"verifySteps": []
|
|
17
17
|
},
|
|
18
|
-
"adoptNotes": "claude.yml only reacts to @claude mentions from a repository owner, member or collaborator (author_association), so an outside commenter on a public repository cannot start a job that holds contents: write and your auth secret. It also commits through the GitHub API (use_commit_signing) so a signed-commits ruleset accepts its work. claude-pr-review.yml runs on every non-bot, non-fork pull request, so it spends API credits on each push -- delete it and keep claude.yml if you only want on-demand help. Both workflows need one thing this pack cannot verify or install: an ANTHROPIC_API_KEY repository secret (the active default), or a CLAUDE_CODE_OAUTH_TOKEN from a Claude subscription, or a Workload Identity Federation setup in the Anthropic Console -- see the comments in .github/workflows/claude.yml for all three. An adopted project that already has its own .github/workflows/claude.yml or claude-pr-review.yml surfaces as an ordinary file conflict -- keep the existing one if it's already configured for that project's own auth choice, since this pack's version would just overwrite a working setup with its own generic defaults. The two workflows ship without an SPDX header on purpose (a header would carry a project-name token that stays literal in an adopt-mode install); a project that also installs `licensing` gets the headers from that pack's `check-license-headers.mjs --fix` backfill. These workflows used to ship inside the `github` pack; a project that installed that pack before the split keeps its files untouched."
|
|
18
|
+
"adoptNotes": "claude.yml only reacts to @claude mentions from a repository owner, member or collaborator (author_association), so an outside commenter on a public repository cannot start a job that holds contents: write and your auth secret. It also commits through the GitHub API (use_commit_signing) so a signed-commits ruleset accepts its work. Since claude-code-action v1.0.268 a mention on a pull request is skipped if the branch was pushed to after the mention, and the tracking comment asks for a new one. claude-pr-review.yml runs on every non-bot, non-fork pull request, so it spends API credits on each push -- delete it and keep claude.yml if you only want on-demand help. Both workflows need one thing this pack cannot verify or install: an ANTHROPIC_API_KEY repository secret (the active default), or a CLAUDE_CODE_OAUTH_TOKEN from a Claude subscription, or a Workload Identity Federation setup in the Anthropic Console -- see the comments in .github/workflows/claude.yml for all three. An adopted project that already has its own .github/workflows/claude.yml or claude-pr-review.yml surfaces as an ordinary file conflict -- keep the existing one if it's already configured for that project's own auth choice, since this pack's version would just overwrite a working setup with its own generic defaults. The two workflows ship without an SPDX header on purpose (a header would carry a project-name token that stays literal in an adopt-mode install); a project that also installs `licensing` gets the headers from that pack's `check-license-headers.mjs --fix` backfill. These workflows used to ship inside the `github` pack; a project that installed that pack before the split keeps its files untouched."
|
|
19
19
|
}
|