@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 CHANGED
@@ -11,7 +11,7 @@
11
11
  [![OpenSSF Best Practices](https://www.bestpractices.dev/projects/14937/badge)](https://www.bestpractices.dev/projects/14937)
12
12
  [![OpenSSF Baseline](https://www.bestpractices.dev/projects/14937/baseline)](https://www.bestpractices.dev/projects/14937)
13
13
  [![Socket](https://badge.socket.dev/npm/package/@monte3l/groundwork)](https://socket.dev/npm/package/@monte3l/groundwork/overview)
14
- [![REUSE status](https://api.reuse.software/badge/github.com/monte3l/m3l-groundwork)](https://api.reuse.software/info/github.com/monte3l/m3l-groundwork)
14
+ [![REUSE](https://github.com/monte3l/m3l-groundwork/actions/workflows/reuse.yml/badge.svg?branch=main)](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 changesets in this repo's history for
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.1.0",
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.",
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.** `guard-hub-src-writes.mjs` blocks
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.** A
67
- mod that handles `tool.check` can approve a call a non-managed `PreToolUse`
68
- hook blocked, and project `PreToolUse` hooks run only after the last mod
69
- calls `next`. Only managed hooks outrank a mod. Check `/plugin` alongside
70
- `/status`.
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). A fork cannot spawn further agents. With agent teams on, an in-process
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
- 24
1
+ 26
@@ -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, and only managed hooks outrank a mod. Nothing in the repo can detect
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": "^24.13.3",
44
- "@vitest/coverage-v8": "^5.0.2",
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.2"
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 takes a CLI changeset whose summary starts with
21
- `pack(<name>):`. The checklist for working on a pack lives in the source
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@db77d4d3c98f3f6380e7cd45ffba2342a3dbde3c # v1.0.254
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@db77d4d3c98f3f6380e7cd45ffba2342a3dbde3c # v1.0.254
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
- # Optional: configure Claude's behavior with CLI arguments
101
- # claude_args: |
102
- # --max-turns 10
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
  }