@monte3l/groundwork 1.0.4 → 1.1.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 +62 -13
- package/dist/harness/rules.js +1 -1
- package/dist/main.js +5 -15
- package/dist/merge-json.d.ts +3 -1
- package/dist/merge-json.js +1 -1
- package/package.json +1 -1
- package/plugin/skills/customize/SKILL.md +17 -0
- package/plugin/skills/customize/step-3-round-1.md +105 -20
- package/plugin/src/domain-map.ts +1 -1
- package/plugin/src/pack-map.ts +177 -44
- package/plugin/src/plugin-map.ts +277 -28
- package/templates/core/.claude/hooks/inject-decision-gate.mjs +4 -0
- package/templates/core/.claude/rules/agent-dispatch.md +46 -0
- package/templates/core/.claude/settings.json +11 -1
- package/templates/core/.claude/skills/creating-prs/SKILL.md +1 -0
- package/templates/core/.claude/skills/finishing-work/SKILL.md +1 -0
- package/templates/core/.claude/skills/harness-guidance/SKILL.md +1 -0
- package/templates/core/.claude/skills/starting-work/SKILL.md +20 -0
- package/templates/core/.claude/skills/triaging-ci/SKILL.md +1 -0
- package/templates/core/.claude/skills/typescript-guidance/SKILL.md +1 -0
- package/templates/core/.claude/skills/writing-commits/SKILL.md +1 -0
- package/templates/core/CLAUDE.md +44 -60
- package/templates/core/bin/check-exports.mjs +3 -1
- package/templates/core/bin/lib/harness-rules.mjs +1 -1
- package/templates/core/eslint.config.js +2 -0
- package/templates/core/vitest.config.ts +4 -3
- package/templates/packs/README.md +8 -3
- package/templates/packs/{github → claude-github}/files/.github/workflows/claude-pr-review.yml +1 -1
- package/templates/packs/{github → claude-github}/files/.github/workflows/claude.yml +1 -1
- package/templates/packs/claude-github/pack.json +19 -0
- package/templates/packs/frontend/files/.claude/agents/ui-reviewer.md +132 -0
- package/templates/packs/frontend/files/.claude/skills/new-component/SKILL.md +72 -0
- package/templates/packs/frontend/pack.json +19 -0
- package/templates/packs/github/files/.claude/skills/reviewing-dependabot-prs/SKILL.md +4 -0
- package/templates/packs/github/files/.claude/skills/triaging-scan-alerts/SKILL.md +3 -0
- package/templates/packs/github/files/.claude/skills/watching-pr-checks/SKILL.md +4 -0
- package/templates/packs/github/pack.json +3 -3
- package/templates/packs/harness-extras/files/.claude/hooks/guard-readonly-bash.mjs +1117 -122
- package/templates/packs/harness-extras/pack.json +3 -15
- package/templates/packs/licensing/pack.json +31 -0
- package/templates/packs/publishing/pack.json +3 -14
- package/templates/packs/quality/files/.claude/agents/type-design-analyzer.md +1 -1
- package/templates/packs/service/files/.claude/agents/performance-analyzer.md +96 -0
- package/templates/packs/service/files/.claude/skills/api-doc/SKILL.md +67 -0
- package/templates/packs/service/files/.claude/skills/api-doc/openapi-template.yaml +48 -0
- package/templates/packs/service/pack.json +19 -0
- package/templates/packs/statusline/pack.json +31 -0
- package/templates/packs/supply-chain/pack.json +1 -1
- package/templates/packs/worktrees/files/.claude/skills/working-in-worktrees/SKILL.md +20 -5
- package/templates/packs/worktrees/pack.json +2 -1
- /package/templates/packs/{publishing → licensing}/files/REUSE.toml +0 -0
- /package/templates/packs/{publishing → licensing}/files/bin/check-license-headers.mjs +0 -0
- /package/templates/packs/{harness-extras → statusline}/files/.claude/hooks/statusline-layout.mjs +0 -0
- /package/templates/packs/{harness-extras → statusline}/files/.claude/hooks/statusline.mjs +0 -0
- /package/templates/packs/{harness-extras → statusline}/files/.claude/hooks/subagent-statusline.mjs +0 -0
|
@@ -11,6 +11,10 @@
|
|
|
11
11
|
* instead of being discovered when `guard-branch-isolation.mjs` blocks a
|
|
12
12
|
* src/test write on `main`.
|
|
13
13
|
*
|
|
14
|
+
* It sees the line as typed: Claude Code runs `UserPromptSubmit` hooks before
|
|
15
|
+
* a skill or slash command expands (2.1.299), so `/creating-prs fix the lint`
|
|
16
|
+
* is judged on those words, and a bare `/starting-work` carries no change verb.
|
|
17
|
+
*
|
|
14
18
|
* It is advisory: it emits `additionalContext` and exits 0. It never blocks.
|
|
15
19
|
* The heuristic is deliberately loose (inject on any change-intent verb,
|
|
16
20
|
* stay quiet on obvious reads) -- a spurious reminder is cheap; a missed one
|
|
@@ -36,6 +36,52 @@ auto, `acceptEdits` or `bypassPermissions` mode overrides a spoke's
|
|
|
36
36
|
guards bound a spoke, not `permissionMode`. Source:
|
|
37
37
|
[sub-agents](https://code.claude.com/docs/en/sub-agents).
|
|
38
38
|
|
|
39
|
+
## Guard limits and overrides (detail)
|
|
40
|
+
|
|
41
|
+
Sources: [hooks](https://code.claude.com/docs/en/hooks),
|
|
42
|
+
[hooks guide](https://code.claude.com/docs/en/hooks-guide),
|
|
43
|
+
[managed settings](https://code.claude.com/docs/en/managed-settings),
|
|
44
|
+
[mods events](https://code.claude.com/docs/en/plugins/mods/events),
|
|
45
|
+
[sub-agents](https://code.claude.com/docs/en/sub-agents) and
|
|
46
|
+
[agent teams](https://code.claude.com/docs/en/agent-teams).
|
|
47
|
+
|
|
48
|
+
- **The `Bash` screen is conservative.** `guard-hub-src-writes.mjs` blocks
|
|
49
|
+
redirects, `tee`, `sed -i`, `cp`/`mv` into a guarded path, an interpreter
|
|
50
|
+
snippet that writes there, and a copy, move or removal of a parent
|
|
51
|
+
(`rsync -a /tmp/x/ ./`, `rm -rf .`). It cannot see an interpreter running a
|
|
52
|
+
script from a project file, an `eval`, a computed path, a parent of the
|
|
53
|
+
project root (`rm -rf ..`), a workspace container below the project root, a
|
|
54
|
+
build step, a formatter or fixer (`prettier --write`, `eslint --fix`),
|
|
55
|
+
`git rm`/`git mv`, `find -exec`, `xargs` with a computed operand,
|
|
56
|
+
`tar`/`curl -o`, or a very long interpreter call (allowed with a stderr
|
|
57
|
+
note).
|
|
58
|
+
- **Managed settings outrank every project file.** A `managed-settings.json`
|
|
59
|
+
file, an MDM policy or a console-managed policy has no project-level
|
|
60
|
+
override, and `allowManagedHooksOnly` and `allowManagedPermissionRulesOnly`
|
|
61
|
+
mean only managed hooks run and only managed permission rules apply. The
|
|
62
|
+
file lives outside any working tree, so nothing here can detect it. On a
|
|
63
|
+
machine you don't control, run `/status` and read its "Setting sources"
|
|
64
|
+
line: if `guard-hub-src-writes.mjs` and `guard-branch-isolation.mjs` aren't
|
|
65
|
+
running, treat hub-and-spoke as an unenforced checklist.
|
|
66
|
+
- **An installed mod sits below managed settings and above project hooks.** A
|
|
67
|
+
mod that handles `tool.check` can approve a call a non-managed `PreToolUse`
|
|
68
|
+
hook blocked, and project `PreToolUse` hooks run only after the last mod
|
|
69
|
+
calls `next`. Only managed hooks outrank a mod. Check `/plugin` alongside
|
|
70
|
+
`/status`.
|
|
71
|
+
- **Who counts as a writer.** The guard needs a writer-spoke `agent_type` and a
|
|
72
|
+
non-empty `agent_id`. A fork subagent (on by default in every surface since
|
|
73
|
+
Claude Code 2.1.302) is not a writer spoke, so unless its payload reports a
|
|
74
|
+
writer `agent_type` it is treated as the hub (the docs don't say what a
|
|
75
|
+
fork's payload carries). A fork cannot spawn further agents. With agent teams on, an in-process
|
|
76
|
+
teammate has a documented `agent_id`; one built from a writer definition that
|
|
77
|
+
also reports that `agent_type` passes as a writer. A split-pane teammate does
|
|
78
|
+
not get `disallowedTools` (only an in-process one does), so every spoke's
|
|
79
|
+
`tools` list also omits `Agent`.
|
|
80
|
+
- **What `onFailure: "block"` covers.** A failure is a hook that cannot start,
|
|
81
|
+
times out, exits with any code other than 0 or 2, or prints invalid JSON. It
|
|
82
|
+
has no effect on `Stop`, `SubagentStop`, `TaskCompleted`, `TeammateIdle` or
|
|
83
|
+
async hooks.
|
|
84
|
+
|
|
39
85
|
## Dispatch sizing
|
|
40
86
|
|
|
41
87
|
- **Decompose before you dispatch.** Scale the dispatch to task complexity —
|
|
@@ -1,7 +1,17 @@
|
|
|
1
1
|
{
|
|
2
2
|
"$schema": "https://json.schemastore.org/claude-code-settings.json",
|
|
3
3
|
"permissions": {
|
|
4
|
-
"deny": [
|
|
4
|
+
"deny": [
|
|
5
|
+
"Read(./.env)",
|
|
6
|
+
"Read(./.env.*)",
|
|
7
|
+
"Read(./secrets/**)",
|
|
8
|
+
"Read(**/credentials.json)",
|
|
9
|
+
"Read(**/secrets.yaml)",
|
|
10
|
+
"Edit(**/pnpm-lock.yaml)",
|
|
11
|
+
"Edit(**/package-lock.json)",
|
|
12
|
+
"Edit(**/yarn.lock)",
|
|
13
|
+
"Edit(**/.git/**)"
|
|
14
|
+
]
|
|
5
15
|
},
|
|
6
16
|
"hooks": {
|
|
7
17
|
"UserPromptSubmit": [
|
|
@@ -6,6 +6,7 @@ description: >-
|
|
|
6
6
|
path. Use for /creating-prs, "open a PR", "create a pull request", "ship
|
|
7
7
|
this for review", "get this merged", or after finishing a fix. Requires gh
|
|
8
8
|
CLI auth.
|
|
9
|
+
allowed-tools: Bash(git status --porcelain) Bash(git fetch origin) Bash(git log origin/main..HEAD --oneline) Bash(gh pr view *)
|
|
9
10
|
---
|
|
10
11
|
|
|
11
12
|
# creating-prs
|
|
@@ -9,6 +9,7 @@ description: >-
|
|
|
9
9
|
branch or stale refs linger -- even when it sounds like a one-line git
|
|
10
10
|
command, because deleting a branch that never merged loses work and this
|
|
11
11
|
skill checks first. GitHub stance: gh CLI.
|
|
12
|
+
allowed-tools: Bash(git status --porcelain) Bash(git worktree list --porcelain) Bash(gh pr view *)
|
|
12
13
|
---
|
|
13
14
|
|
|
14
15
|
# finishing-work
|
|
@@ -8,6 +8,7 @@ description: >-
|
|
|
8
8
|
seen the code yet. Inspects git state, recommends a branch (feat/fix <slug>)
|
|
9
9
|
and push target, and decides whether a PR is required, all confirmed before
|
|
10
10
|
any write. Skip for research and questions that change nothing.
|
|
11
|
+
allowed-tools: Bash(git status --porcelain) Bash(git rev-parse --abbrev-ref HEAD) Bash(git rev-parse --git-path hooks) Bash(node --version)
|
|
11
12
|
---
|
|
12
13
|
|
|
13
14
|
# starting-work
|
|
@@ -40,6 +41,25 @@ git status --porcelain # is the tree already dirty?
|
|
|
40
41
|
- **Re-run this inspection after any conversational gap, not just at the
|
|
41
42
|
start.** The branch is not a stable fact across a long session.
|
|
42
43
|
|
|
44
|
+
### 1a — Environment preflight (read-only)
|
|
45
|
+
|
|
46
|
+
Before recommending anything, check that the checkout can actually run the
|
|
47
|
+
project's gates. This only reads and will report findings: **never install** anything and
|
|
48
|
+
never change a file, since a missing piece is the owner's call.
|
|
49
|
+
|
|
50
|
+
- **Node.** Compare `node --version` with the major in `.node-version` (the
|
|
51
|
+
project's authority for it). A mismatch is a finding, not an error.
|
|
52
|
+
- **Dependencies.** `node_modules` should exist. If it is missing, the
|
|
53
|
+
hooks and `pnpm verify` will fail until `pnpm install` is run.
|
|
54
|
+
- **Git hooks.** `lefthook`'s hooks should be installed in the checkout (look
|
|
55
|
+
for `pre-commit` and `pre-push` under the directory `git rev-parse --git-path hooks`
|
|
56
|
+
prints, which honours `core.hooksPath` and linked worktrees). If they are
|
|
57
|
+
missing, nothing runs the gates before a commit or push.
|
|
58
|
+
|
|
59
|
+
Report each finding in one line and carry on: they feed the Step 4 summary
|
|
60
|
+
and never block the branch decision. Skip a check whose file does not exist in
|
|
61
|
+
this project (no `.node-version`, no `lefthook.yml`).
|
|
62
|
+
|
|
43
63
|
### 2 — Infer the change scope
|
|
44
64
|
|
|
45
65
|
From the task in front of you, work out **which paths will be edited** and
|
|
@@ -6,6 +6,7 @@ description: >-
|
|
|
6
6
|
command, and present 3-5 fix options. Use for /triaging-ci, "why did CI fail",
|
|
7
7
|
"CI is failing", "the build is red", "find the root cause of a failing
|
|
8
8
|
build", "debug the CI run", or a specific run ID/URL. GitHub stance: gh CLI.
|
|
9
|
+
allowed-tools: Bash(gh run list *) Bash(gh run view *) Bash(git rev-parse --abbrev-ref HEAD)
|
|
9
10
|
---
|
|
10
11
|
|
|
11
12
|
Diagnose why a GitHub Actions CI run failed by fetching its logs via `gh` and
|
|
@@ -15,6 +15,7 @@ description: >-
|
|
|
15
15
|
we missing", or before changing a compiler flag. Not for a general Claude
|
|
16
16
|
Code automation review, and not how this project's config is wired today
|
|
17
17
|
— that's CLAUDE.md and the config files.
|
|
18
|
+
argument-hint: "[research <question> | refresh | gaps]"
|
|
18
19
|
---
|
|
19
20
|
|
|
20
21
|
# typescript-guidance
|
|
@@ -5,6 +5,7 @@ description: >-
|
|
|
5
5
|
imperative subject ≤70 chars, decide whether a body is needed, structure it as
|
|
6
6
|
What → Why/How → semver impact, add Co-Authored-By when AI-assisted, then
|
|
7
7
|
commit. Use for "commit this", "write a commit", "stage and commit".
|
|
8
|
+
allowed-tools: Bash(git status --porcelain)
|
|
8
9
|
---
|
|
9
10
|
|
|
10
11
|
# writing-commits
|
package/templates/core/CLAUDE.md
CHANGED
|
@@ -87,73 +87,57 @@ Skills, each in `.claude/skills/<name>/`:
|
|
|
87
87
|
sweeps (see Freshness).
|
|
88
88
|
|
|
89
89
|
**The guard also screens `Bash`, but only conservatively.** The same hook
|
|
90
|
-
|
|
91
|
-
`
|
|
92
|
-
|
|
93
|
-
|
|
94
|
-
|
|
95
|
-
|
|
96
|
-
|
|
97
|
-
|
|
98
|
-
|
|
99
|
-
|
|
100
|
-
|
|
101
|
-
|
|
102
|
-
|
|
103
|
-
|
|
104
|
-
|
|
105
|
-
|
|
106
|
-
|
|
107
|
-
|
|
108
|
-
|
|
109
|
-
(`allowManagedHooksOnly`) and only managed permission rules apply
|
|
110
|
-
(`allowManagedPermissionRulesOnly`) (see
|
|
111
|
-
[Claude Code's managed-settings docs](https://code.claude.com/docs/en/managed-settings)).
|
|
112
|
-
Nothing in this project can detect or gate against that from inside the
|
|
113
|
-
repo -- the managed file lives outside any working tree, at an OS-level
|
|
114
|
-
path. Run `/status` on a machine you don't control before trusting
|
|
115
|
-
`guard-hub-src-writes.mjs`/`guard-branch-isolation.mjs`: its "Setting
|
|
116
|
-
sources" line names every active source, and if these hooks aren't among
|
|
117
|
-
what's actually running, treat hub-and-spoke as an unenforced checklist
|
|
118
|
-
until confirmed otherwise.
|
|
119
|
-
|
|
120
|
-
**An installed Claude Code mod is a second silent override, below managed
|
|
121
|
-
settings.** Per the
|
|
122
|
-
[hooks guide](https://code.claude.com/docs/en/hooks-guide), a mod that
|
|
123
|
-
handles `tool.check` "can approve a call that your `PreToolUse` hook blocked,
|
|
124
|
-
unless the hook is in managed settings", and project `PreToolUse` hooks run
|
|
125
|
-
only after the last mod calls `next` (see the
|
|
126
|
-
[mods events reference](https://code.claude.com/docs/en/plugins/mods/events)).
|
|
127
|
-
Only managed-settings hooks outrank a mod, and nothing in the repo can detect
|
|
128
|
-
one. Check `/plugin` for installed mods alongside `/status`.
|
|
90
|
+
blocks a `Bash` command that visibly writes into `src/` or `tests/` (redirects,
|
|
91
|
+
`tee`, `sed -i`, `cp`/`mv` into them, an interpreter snippet that writes there,
|
|
92
|
+
a copy, move or removal of a parent of `src/` such as `rm -rf .`) unless the caller is
|
|
93
|
+
`test-author` or `code-implementer`. It cannot catch an indirect write (a
|
|
94
|
+
script from a project file, an `eval`, a computed path, a build step, a
|
|
95
|
+
formatter or fixer, `git rm`/`git mv`, `tar`/`curl -o`), so hub-and-spoke is a
|
|
96
|
+
convention backed by a guard that raises the bar, not a proof. To override it
|
|
97
|
+
deliberately, run the command yourself with the `!` prefix at the Claude Code
|
|
98
|
+
prompt, or edit the hook's registration in `.claude/settings.json`.
|
|
99
|
+
|
|
100
|
+
**Managed settings and mods can silently disable the guards.** A managed
|
|
101
|
+
deployment (`managed-settings.json`, MDM, a console policy) outranks every file
|
|
102
|
+
here, and `allowManagedHooksOnly` runs only managed hooks. An installed mod
|
|
103
|
+
that handles `tool.check` can approve a call a project `PreToolUse` hook
|
|
104
|
+
blocked, and only managed hooks outrank a mod. Nothing in the repo can detect
|
|
105
|
+
either: on a machine you don't control, check `/status` ("Setting sources") and
|
|
106
|
+
`/plugin` before trusting `guard-hub-src-writes.mjs` and
|
|
107
|
+
`guard-branch-isolation.mjs`. Detail and sources:
|
|
108
|
+
`.claude/rules/agent-dispatch.md`.
|
|
129
109
|
|
|
130
110
|
**The guard keys on `agent_id` as well as `agent_type`.** A call counts as a
|
|
131
|
-
writer spoke only with both present, so
|
|
132
|
-
|
|
133
|
-
|
|
134
|
-
|
|
111
|
+
writer spoke only with both present, so one carrying `agent_type` alone is
|
|
112
|
+
treated as the hub and blocked, as is a fork subagent unless its payload
|
|
113
|
+
reports a writer `agent_type` with an `agent_id` (details and versions in
|
|
114
|
+
`.claude/rules/agent-dispatch.md`). An in-process
|
|
115
|
+
agent-teams teammate has a documented `agent_id`, so one built from a writer
|
|
116
|
+
definition that reports that `agent_type` would pass.
|
|
117
|
+
|
|
118
|
+
**Four guards block when they fail, and a secrets deny rule ships in
|
|
135
119
|
`settings.json`.** `guard-secret-writes`, `guard-hub-src-writes`,
|
|
136
120
|
`guard-branch-isolation` and `guard-protected-paths` carry
|
|
137
|
-
`"onFailure": "block"` (Claude Code 2.1.295 or later)
|
|
138
|
-
|
|
139
|
-
|
|
140
|
-
|
|
141
|
-
missing `node`
|
|
142
|
-
|
|
143
|
-
|
|
144
|
-
|
|
145
|
-
|
|
146
|
-
|
|
147
|
-
`
|
|
148
|
-
`
|
|
149
|
-
|
|
121
|
+
`"onFailure": "block"` (Claude Code 2.1.295 or later): a hook that cannot
|
|
122
|
+
start, times out, exits with any code other than 0 or 2, or prints invalid
|
|
123
|
+
JSON blocks the call instead of letting it through. Each guard still handles
|
|
124
|
+
bad input itself and exits 0 on purpose. Because `guard-hub-src-writes` is also
|
|
125
|
+
on `Bash`, a missing `node` blocks every `Bash` call until fixed (run the
|
|
126
|
+
command with the `!` prefix to get past it). The style guards and
|
|
127
|
+
`guard-git-push-signed` stay fail-open on purpose: the push guard has its own
|
|
128
|
+
parser and the remote's signed-commit rule is the authoritative layer.
|
|
129
|
+
`permissions.deny` blocks reading `.env`, `.env.*`, `secrets/`,
|
|
130
|
+
`credentials.json` and `secrets.yaml` (which also covers `cat`, `head` and
|
|
131
|
+
`tail` on them in `Bash`) and editing `pnpm-lock.yaml`, `package-lock.json`,
|
|
132
|
+
`yarn.lock` and the repository's `.git/` directory. It does not cover `grep -r`,
|
|
133
|
+
a script that opens the file itself, a subprocess such as `pnpm install`
|
|
134
|
+
rewriting the lock file, or a linked worktree, where `.git` is a file.
|
|
150
135
|
|
|
151
136
|
**A spoke's `permissionMode` can be overridden.** A session in auto,
|
|
152
137
|
`acceptEdits` or `bypassPermissions` mode overrides a spoke's `permissionMode`
|
|
153
|
-
(the field applies only
|
|
154
|
-
`
|
|
155
|
-
|
|
156
|
-
`disallowedTools: Agent` on every spoke is what keeps this roster flat.
|
|
138
|
+
(the field applies only in `default`, `dontAsk` or `plan`), so the hooks, not
|
|
139
|
+
`permissionMode`, bound a spoke. A subagent can spawn subagents three layers
|
|
140
|
+
deep by default; `disallowedTools: Agent` on every spoke keeps the roster flat.
|
|
157
141
|
|
|
158
142
|
Full dispatch-sizing and recovery guidance: `.claude/rules/agent-dispatch.md`
|
|
159
143
|
(auto-loads when editing `.claude/skills/**` or `.claude/agents/**`).
|
|
@@ -12,7 +12,9 @@
|
|
|
12
12
|
* types. Skips cleanly (exit 0, one warning) when the target has no
|
|
13
13
|
* `exports` field -- a project that isn't published doesn't need this gate,
|
|
14
14
|
* and `/customize` removes the step entirely for non-library project kinds
|
|
15
|
-
* rather than leaving a permanently-skipped one behind.
|
|
15
|
+
* rather than leaving a permanently-skipped one behind. attw resolves types
|
|
16
|
+
* with the TypeScript it bundles, not the project's own, so its verdict
|
|
17
|
+
* follows that resolver.
|
|
16
18
|
*/
|
|
17
19
|
import process from "node:process";
|
|
18
20
|
import { execFileSync } from "node:child_process";
|
|
@@ -691,7 +691,7 @@ const descriptionSubstance = {
|
|
|
691
691
|
} else if (description.length > DESCRIPTION_MAX) {
|
|
692
692
|
failures.push({
|
|
693
693
|
subject,
|
|
694
|
-
message: `description is ${description.length} chars; over ${DESCRIPTION_MAX}
|
|
694
|
+
message: `description is ${description.length} chars; over the ${DESCRIPTION_MAX}-char Agent Skills maximum (Claude Code also truncates description + when_to_use at 1,536 in its skill listing)`,
|
|
695
695
|
});
|
|
696
696
|
}
|
|
697
697
|
};
|
|
@@ -65,6 +65,8 @@ export default defineConfig(
|
|
|
65
65
|
"@typescript-eslint/no-non-null-assertion": "error",
|
|
66
66
|
"@typescript-eslint/no-floating-promises": "error",
|
|
67
67
|
"@typescript-eslint/switch-exhaustiveness-check": "error",
|
|
68
|
+
// Overlaps `verbatimModuleSyntax` (typescript-eslint warns the two can
|
|
69
|
+
// report the same import twice); kept for the rule's autofix.
|
|
68
70
|
"@typescript-eslint/consistent-type-imports": "error",
|
|
69
71
|
"@typescript-eslint/no-unused-vars": [
|
|
70
72
|
"error",
|
|
@@ -19,9 +19,10 @@ export default defineConfig({
|
|
|
19
19
|
// barrel pattern): a fresh scaffold's index.ts IS its real content,
|
|
20
20
|
// so excluding it would make this gate measure nothing at all.
|
|
21
21
|
exclude: ["**/*.d.ts"],
|
|
22
|
-
// json emits coverage-final.json: the
|
|
23
|
-
// are 100% on every metric
|
|
24
|
-
//
|
|
22
|
+
// json emits coverage-final.json: the text table can hide files that
|
|
23
|
+
// are 100% on every metric (Vitest sets `skipFull` when it detects an
|
|
24
|
+
// AI coding agent), so the JSON is the authoritative per-file record
|
|
25
|
+
// when investigating a suspected gap.
|
|
25
26
|
reporter: ["text", "html", "json"],
|
|
26
27
|
thresholds: {
|
|
27
28
|
// Scaffold-appropriate starting floor. Raise these to the project's
|
|
@@ -105,9 +105,14 @@ already enumerate groups rather than individual steps.
|
|
|
105
105
|
|
|
106
106
|
| Pack | Contents |
|
|
107
107
|
| ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
|
|
108
|
-
| `harness-extras` | Claude Code session
|
|
108
|
+
| `harness-extras` | Claude Code session hooks: the compaction-handoff hook pair (`PreCompact`, `SessionStart`) and a read-only Bash guard for review spokes. Registers hooks only; no top-level settings keys. |
|
|
109
|
+
| `statusline` | A five-row `statusLine` (session, model, context, quota, work) plus a per-subagent row renderer. The only pack that sets top-level settings keys (`statusLine`, `subagentStatusLine`); a project that already defines either must decide on it, see its `adoptNotes`. |
|
|
109
110
|
| `quality` | Two language-level review aids: a per-file size ratchet gate (`check-file-budget.mjs`, a `build`-group verify step) and a read-only `type-design-analyzer` agent. No hooks, no settings. Adopt-capable and recommended for every project kind. |
|
|
110
|
-
| `
|
|
111
|
-
| `
|
|
111
|
+
| `frontend` | Two aids for a project that builds UI: a read-only `ui-reviewer` agent (a static accessibility review of changed components, markup and styles against WCAG 2.2 at level AA, with anything needing a browser reported as `NOT CHECKED`) and a `new-component` skill that mirrors an existing sibling component's conventions and routes the work through `test-author`, `code-implementer` and `ui-reviewer`. No hooks, no settings, no gate, no framework templates. Adopt-capable; recommended only for the `frontend` kind. |
|
|
112
|
+
| `service` | Two aids for a project that serves an API: a read-only `performance-analyzer` agent (a static review of changed server code for blocking calls, per-request cost and unbounded work, with anything needing profiling or a load test reported as `NOT CHECKED`) and an `api-doc` skill that writes an OpenAPI description from the routes the code defines, using a template inside the skill. No hooks, no settings, no gate, no framework templates. Adopt-capable; recommended only for the `service` kind. |
|
|
113
|
+
| `claude-github` | Anthropic's official Claude Code GitHub Action: one workflow wired for `@claude` mention-mode and a second that posts an automated Claude review comment on every PR. A pure file drop: no hooks, no gate. The workflows need an auth secret this pack cannot create and the review spends API credits per PR; see its `adoptNotes`. |
|
|
114
|
+
| `github` | GitHub-hosted collaboration through the `gh` CLI: three skills — `reviewing-dependabot-prs`, `triaging-scan-alerts`, `watching-pr-checks`. No hooks, no gate, no workflows. `triaging-scan-alerts` needs code scanning turned on; see its `adoptNotes`. |
|
|
115
|
+
| `publishing` | A release pipeline: `release.yml` (changesets version-PR / staged, provenance-attested npm publish via trusted publishing), `check-publish-version.mjs` and `check-dts-deps.mjs`. Fresh mode only; see "The wiring contract" above and its `adoptNotes`. |
|
|
116
|
+
| `licensing` | An SPDX/REUSE license-header gate: `check-license-headers.mjs` (a `lint`-group verify step) and a `REUSE.toml` template. Fresh mode only: the one-time backfill (`setupSteps`) fails an established project's `pnpm verify` until it has touched every file; see its `adoptNotes`. |
|
|
112
117
|
| `supply-chain` | Secret scanning (`gitleaks.yml` with a `.gitleaks.toml`) and an OpenSSF Scorecard run (`scorecard.yml`) for any project on GitHub, published or not. A pure file drop of two workflows (read-only apart from the Scorecard job's `security-events` and `id-token` write): no hooks, no settings, no scripts, no gate. Adopt-capable and recommended for every project kind. |
|
|
113
118
|
| `worktrees` | Enforces that all src/tests development happens inside an isolated git worktree, on any branch, for any caller: a `working-in-worktrees` skill (start/status/sync/finish/fan-out), a `SessionStart` hook that installs dependencies into a freshly created worktree, a `PreToolUse` guard stricter than the baseline's own `guard-branch-isolation.mjs`/`guard-hub-src-writes.mjs`, a `repair-core-bare.mjs` hook (`SessionStart`, and `PostToolUse` after `EnterWorktree`/`ExitWorktree`/`Agent`) that resets the `core.bare = true` Claude Code's worktree tools are reported to leave in a normal repo's shared config, and a `.worktreeinclude` copying `.env`/`.env.local`/`.env.*.local` into every worktree Claude Code creates. Changes the day-to-day workflow, not just a nicety — see its `adoptNotes`. |
|
package/templates/packs/{github → claude-github}/files/.github/workflows/claude-pr-review.yml
RENAMED
|
@@ -86,7 +86,7 @@ jobs:
|
|
|
86
86
|
fetch-depth: 0
|
|
87
87
|
|
|
88
88
|
- id: claude
|
|
89
|
-
uses: anthropics/claude-code-action@
|
|
89
|
+
uses: anthropics/claude-code-action@db77d4d3c98f3f6380e7cd45ffba2342a3dbde3c # v1.0.254
|
|
90
90
|
with:
|
|
91
91
|
anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
|
|
92
92
|
# Swap in CLAUDE_CODE_OAUTH_TOKEN or the Workload Identity
|
|
@@ -67,7 +67,7 @@ jobs:
|
|
|
67
67
|
fetch-depth: 1
|
|
68
68
|
|
|
69
69
|
- name: Run Claude Code
|
|
70
|
-
uses: anthropics/claude-code-action@
|
|
70
|
+
uses: anthropics/claude-code-action@db77d4d3c98f3f6380e7cd45ffba2342a3dbde3c # v1.0.254
|
|
71
71
|
with:
|
|
72
72
|
# Option 1 (active default): a stored API key. Install the Claude
|
|
73
73
|
# GitHub App (https://github.com/apps/claude) and add
|
|
@@ -0,0 +1,19 @@
|
|
|
1
|
+
{
|
|
2
|
+
"schemaVersion": 1,
|
|
3
|
+
"name": "claude-github",
|
|
4
|
+
"description": "Anthropic's official Claude Code GitHub Action (anthropics/claude-code-action) on top of the baseline, as two workflows: claude.yml, wired for @claude mention-mode, and claude-pr-review.yml, which posts an automated Claude review comment on every pull request. Pure file drop: no hooks, no settings, no scripts, no verify step. Both need an auth secret this pack cannot create, and the review workflow spends API credits on every PR, so it is a separate pack from `github` rather than a default.",
|
|
5
|
+
"modes": ["fresh", "adopt"],
|
|
6
|
+
"budget": {
|
|
7
|
+
"agents": 0,
|
|
8
|
+
"skills": 0,
|
|
9
|
+
"hooks": 0,
|
|
10
|
+
"workflows": 2,
|
|
11
|
+
"scripts": 0
|
|
12
|
+
},
|
|
13
|
+
"wiring": {
|
|
14
|
+
"settings": {},
|
|
15
|
+
"packageScripts": {},
|
|
16
|
+
"verifySteps": []
|
|
17
|
+
},
|
|
18
|
+
"adoptNotes": "claude.yml only reacts to @claude mentions from a repository owner, member or collaborator (author_association), so an outside commenter on a public repository cannot start a job that holds contents: write and your auth secret. It also commits through the GitHub API (use_commit_signing) so a signed-commits ruleset accepts its work. claude-pr-review.yml runs on every non-bot, non-fork pull request, so it spends API credits on each push -- delete it and keep claude.yml if you only want on-demand help. Both workflows need one thing this pack cannot verify or install: an ANTHROPIC_API_KEY repository secret (the active default), or a CLAUDE_CODE_OAUTH_TOKEN from a Claude subscription, or a Workload Identity Federation setup in the Anthropic Console -- see the comments in .github/workflows/claude.yml for all three. An adopted project that already has its own .github/workflows/claude.yml or claude-pr-review.yml surfaces as an ordinary file conflict -- keep the existing one if it's already configured for that project's own auth choice, since this pack's version would just overwrite a working setup with its own generic defaults. The two workflows ship without an SPDX header on purpose (a header would carry a project-name token that stays literal in an adopt-mode install); a project that also installs `licensing` gets the headers from that pack's `check-license-headers.mjs --fix` backfill. These workflows used to ship inside the `github` pack; a project that installed that pack before the split keeps its files untouched."
|
|
19
|
+
}
|
|
@@ -0,0 +1,132 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: ui-reviewer
|
|
3
|
+
description: Read-only UI accessibility reviewer. Does a static source review of changed components, markup and styles against WCAG 2.2 (level AA) and reports anything that needs a browser, a measurement or assistive technology as NOT CHECKED. Use after writing or changing UI. Complements code-reviewer (general structure and SOLID).
|
|
4
|
+
tools: Read, Grep, Glob
|
|
5
|
+
disallowedTools: Agent
|
|
6
|
+
model: claude-sonnet-5-5
|
|
7
|
+
effort: medium
|
|
8
|
+
maxTurns: 40
|
|
9
|
+
color: purple
|
|
10
|
+
---
|
|
11
|
+
|
|
12
|
+
You are a UI accessibility reviewer for this project. You are read-only:
|
|
13
|
+
review and report; **never edit**. In the hub-and-spoke pipeline you are a
|
|
14
|
+
review spoke — you assess UI that a _different_ agent wrote
|
|
15
|
+
(normally `code-implementer`). That separation is the point: the author cannot grade
|
|
16
|
+
their own markup.
|
|
17
|
+
|
|
18
|
+
You have no shell. The hub names the files or directory to review in the
|
|
19
|
+
dispatch prompt; review exactly those. If you were given none,
|
|
20
|
+
return immediately with a request for a file list, since you cannot ask a
|
|
21
|
+
question mid-run. Do not widen the scope to the rest of the project.
|
|
22
|
+
|
|
23
|
+
## What you can and cannot know
|
|
24
|
+
|
|
25
|
+
This is a **static review of source**. You can see missing text
|
|
26
|
+
alternatives, missing labels, a click handler on a non-interactive element, a
|
|
27
|
+
removed focus outline and an animation with no reduced-motion rule. You
|
|
28
|
+
cannot see rendered contrast, real focus order, layout at a narrow width or
|
|
29
|
+
how a screen reader announces a control. Report those as **NOT CHECKED** with
|
|
30
|
+
what would settle them, never as a pass. Never state that a page "conforms" or
|
|
31
|
+
"passes" WCAG: say what you found in the files you read, and what you did not
|
|
32
|
+
check.
|
|
33
|
+
|
|
34
|
+
The target is WCAG 2.2 (a W3C Recommendation of 12 December 2024) at level
|
|
35
|
+
AA. Level A criteria are part of AA. A criterion at level AAA is a
|
|
36
|
+
recommendation, never a Must-fix.
|
|
37
|
+
|
|
38
|
+
## Checklist
|
|
39
|
+
|
|
40
|
+
Check each criterion only where the changed files give you something to look
|
|
41
|
+
at. Quote the criterion by number and title.
|
|
42
|
+
|
|
43
|
+
**Text alternatives and structure**
|
|
44
|
+
|
|
45
|
+
- **1.1.1 Non-text Content (A).** Every image, icon and non-text control has a
|
|
46
|
+
text alternative that serves the equivalent purpose; a purely decorative one
|
|
47
|
+
is hidden from assistive technology instead.
|
|
48
|
+
- **1.3.1 Info and Relationships (A).** Structure and relationships shown
|
|
49
|
+
visually are also in the markup: real headings, lists, tables and
|
|
50
|
+
form-control associations, not styled generic elements.
|
|
51
|
+
- **4.1.2 Name, Role, Value (A).** Every interactive component has a
|
|
52
|
+
programmatically determinable name and role, and its states can be set and
|
|
53
|
+
read. Prefer a native element (`button`, `a`, `input`) to a generic element
|
|
54
|
+
with a role added. The WAI-ARIA Authoring Practices Guide puts it plainly:
|
|
55
|
+
"No ARIA is better than Bad ARIA", because a role is a promise that the
|
|
56
|
+
element behaves like that role and ARIA adds no keyboard behaviour or styling
|
|
57
|
+
by itself.
|
|
58
|
+
|
|
59
|
+
**Keyboard and focus**
|
|
60
|
+
|
|
61
|
+
- **2.1.1 Keyboard (A).** All functionality works from a keyboard. A click
|
|
62
|
+
handler on a `div` or `span` that has no `tabindex` and no key handler cannot
|
|
63
|
+
be reached or operated from the keyboard, and fails this.
|
|
64
|
+
- **2.1.2 No Keyboard Trap (A).** Focus can move away from a component using
|
|
65
|
+
the keyboard alone. Look at dialogs and popovers: is there a keyboard-only
|
|
66
|
+
way out, such as Escape or a close button?
|
|
67
|
+
- **2.4.7 Focus Visible (AA).** A keyboard focus indicator is visible. Flag
|
|
68
|
+
`outline: none` or `outline: 0` (and an equivalent reset) with no replacement
|
|
69
|
+
style.
|
|
70
|
+
- **2.4.11 Focus Not Obscured (Minimum) (AA, new in WCAG 2.2).** A component
|
|
71
|
+
that receives keyboard focus is not entirely hidden by author-created
|
|
72
|
+
content such as a sticky header or a cookie banner. Usually **NOT CHECKED**
|
|
73
|
+
without a rendered page.
|
|
74
|
+
|
|
75
|
+
**Operable targets and forms**
|
|
76
|
+
|
|
77
|
+
- **2.5.8 Target Size (Minimum) (AA, new in WCAG 2.2).** A pointer target is at
|
|
78
|
+
least 24 by 24 CSS pixels, unless one of the criterion's exceptions applies
|
|
79
|
+
(enough spacing around an undersized target, an equivalent control on the
|
|
80
|
+
page, an inline target in a sentence, a size set by the user agent, or an
|
|
81
|
+
essential presentation). Flag explicit sizes below that on an interactive
|
|
82
|
+
element, and say which exception you checked.
|
|
83
|
+
- **3.3.2 Labels or Instructions (A).** A control that takes input has a label
|
|
84
|
+
or instructions. A `placeholder` that is the only label is a likely failure.
|
|
85
|
+
- **3.3.1 Error Identification (A).** An input error is identified and
|
|
86
|
+
described in text, not only by a colour or an icon.
|
|
87
|
+
|
|
88
|
+
**Colour, size and motion**
|
|
89
|
+
|
|
90
|
+
- **1.4.3 Contrast (Minimum) (AA).** Text has a contrast ratio of at least
|
|
91
|
+
4.5:1, or 3:1 for large-scale text (at least 18 point, or 14 point bold).
|
|
92
|
+
Incidental text has no requirement: inactive user interface components, pure
|
|
93
|
+
decoration, text that is not visible, and logotypes.
|
|
94
|
+
- **1.4.11 Non-text Contrast (AA).** The parts of a control needed to identify
|
|
95
|
+
it and its states, and the parts of a graphic needed to understand it, have a
|
|
96
|
+
contrast ratio of at least 3:1 against adjacent colours.
|
|
97
|
+
For both contrast criteria, state a ratio only when the foreground and
|
|
98
|
+
background are literal values in the files you read and you can compute it;
|
|
99
|
+
a colour from a theme, a token you cannot resolve or an image is **NOT
|
|
100
|
+
CHECKED**. A background the files never set is not a literal value: do not
|
|
101
|
+
assume white or any default background, and do not quote a ratio against
|
|
102
|
+
it. Do not write a ratio figure at all in that case, even hedged as "about
|
|
103
|
+
1.6:1" or "on white". Report it as **NOT CHECKED** and name the pair you would measure.
|
|
104
|
+
- **1.4.4 Resize Text (AA).** Text can be resized up to 200 percent without
|
|
105
|
+
loss of content or functionality.
|
|
106
|
+
- **1.4.10 Reflow (AA).** Content works at a width equivalent to 320 CSS pixels
|
|
107
|
+
without two-dimensional scrolling, except content that needs a
|
|
108
|
+
two-dimensional layout. Layout behaviour is **NOT CHECKED** unless a fixed
|
|
109
|
+
width in the source is clearly wider than that with no responsive rule.
|
|
110
|
+
- **2.3.3 Animation from Interactions (AAA).** Motion animation triggered by an
|
|
111
|
+
interaction can be disabled unless it is essential. Recommend a
|
|
112
|
+
`prefers-reduced-motion` rule for a new animation or transition, as a
|
|
113
|
+
Should-fix and never a Must-fix, because this criterion is level AAA.
|
|
114
|
+
|
|
115
|
+
## Severity
|
|
116
|
+
|
|
117
|
+
- **Must-fix** — a failure of a level A or AA criterion that is evident from
|
|
118
|
+
the source you read.
|
|
119
|
+
- **Should-fix** — a likely failure that depends on something you could not
|
|
120
|
+
see, or a level AAA recommendation worth doing.
|
|
121
|
+
- **Nit** — minor, or a style point that improves robustness.
|
|
122
|
+
- **NOT CHECKED** — needs a rendered page, a measurement or assistive
|
|
123
|
+
technology. List these, with the check that would settle each one.
|
|
124
|
+
|
|
125
|
+
## Report
|
|
126
|
+
|
|
127
|
+
Return a bounded digest inline, at most about 8,000 characters; never write a
|
|
128
|
+
file. For each finding give `file:line`, the criterion number and title, what
|
|
129
|
+
you saw, and the smallest fix. Group by Must-fix, Should-fix, Nit, then NOT
|
|
130
|
+
CHECKED. Stop once the checklist is answered for the files you were given: do
|
|
131
|
+
not re-verify indefinitely. If you found nothing in a category, say so in one
|
|
132
|
+
line.
|