@monte3l/groundwork 1.0.5 → 1.1.1
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 +9 -2
- package/package.json +2 -2
- package/plugin/skills/customize/SKILL.md +17 -0
- package/plugin/skills/customize/step-3-round-1.md +82 -5
- package/plugin/src/pack-map.ts +57 -5
- package/plugin/src/plugin-map.ts +276 -27
- package/templates/core/.claude/rules/agent-dispatch.md +8 -6
- 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 +7 -4
- package/templates/core/package.json +2 -2
- package/templates/packs/README.md +5 -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 +8 -4
- 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/harness-extras/files/.claude/hooks/guard-readonly-bash.mjs +1117 -122
- package/templates/packs/harness-extras/pack.json +1 -1
- 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/worktrees/files/.claude/skills/working-in-worktrees/SKILL.md +20 -5
|
@@ -54,5 +54,5 @@
|
|
|
54
54
|
"packageScripts": {},
|
|
55
55
|
"verifySteps": []
|
|
56
56
|
},
|
|
57
|
-
"adoptNotes": "The compaction hooks install anywhere a .claude/ directory exists, but guard-readonly-bash.mjs imports ../../bin/lib/agent-roster.mjs (the baseline's list of writer spokes) -- copy that file alongside it in an adopted project, or skip that one hook. The PreCompact hook writes tmp/compact-handoff-<session_id>.json under the git worktree the session runs in (from the hook payload's cwd, since CLAUDE_PROJECT_DIR does not follow a session into a linked worktree) -- fresh mode's baseline .gitignore already lists tmp/ unconditionally, but an adopted project's own .gitignore was never touched by adopt mode, so add tmp/ there too before this pack's hooks run, or the handoff artifact can end up committed. The size-ratchet gate and the type-design-analyzer agent that used to ship here are now the separate `quality` pack. The status line that used to ship here is now the separate `statusline` pack, so installing this one never touches a project's own `statusLine` setting."
|
|
57
|
+
"adoptNotes": "The compaction hooks install anywhere a .claude/ directory exists, but guard-readonly-bash.mjs imports ../../bin/lib/agent-roster.mjs (the baseline's list of writer spokes) -- copy that file alongside it in an adopted project, or skip that one hook. The PreCompact hook writes tmp/compact-handoff-<session_id>.json under the git worktree the session runs in (from the hook payload's cwd, since CLAUDE_PROJECT_DIR does not follow a session into a linked worktree) -- fresh mode's baseline .gitignore already lists tmp/ unconditionally, but an adopted project's own .gitignore was never touched by adopt mode, so add tmp/ there too before this pack's hooks run, or the handoff artifact can end up committed. The size-ratchet gate and the type-design-analyzer agent that used to ship here are now the separate `quality` pack. The status line that used to ship here is now the separate `statusline` pack, so installing this one never touches a project's own `statusLine` setting. guard-readonly-bash.mjs judges a read-only spoke's Bash command against an ALLOWLIST of read verbs (the baseline's own toolchain: pnpm, npm, eslint, prettier, tsc, vitest, knip, publint, attw, plus git subcommands for reading and the usual shell readers), so in an adopted project on yarn, make, jest or biome a read-only spoke is blocked from running those directly: have it call a package.json script (pnpm <script> and npm run <script> still pass) or add the verb to READ_ONLY_VERBS in the copied hook. A script file run through node or a package script is not inspected, so the guard raises the bar and proves nothing."
|
|
58
58
|
}
|
|
@@ -178,7 +178,7 @@ case." Report what you found rather than chasing diminishing returns.
|
|
|
178
178
|
many changed exports can itself run you out of turn budget mid-report.
|
|
179
179
|
Return your report **inline in your response** — you hold no write tool and
|
|
180
180
|
cannot write any file (this project's read-only Bash guard,
|
|
181
|
-
`guard-readonly-bash.mjs`, blocks
|
|
181
|
+
`guard-readonly-bash.mjs`, blocks shell commands outside a read-only allowlist), so a
|
|
182
182
|
scratchpad handoff is never an option here. If the diff touches many
|
|
183
183
|
exports, keep the whole report within roughly 8,000 characters (~2,000
|
|
184
184
|
tokens — the sub-agent output band Anthropic documents): the one-line
|
|
@@ -0,0 +1,96 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: performance-analyzer
|
|
3
|
+
description: Read-only performance reviewer for server code. Does a static source review of changed handlers, queries and I/O for blocking calls, per-request cost and unbounded work, and reports anything that needs profiling or a load test as NOT CHECKED. Use after writing or changing a request path. 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: pink
|
|
10
|
+
---
|
|
11
|
+
|
|
12
|
+
You are a performance reviewer for this project. You are read-only: review
|
|
13
|
+
and report; **never edit**. In the hub-and-spoke pipeline you are a review
|
|
14
|
+
spoke — you assess code that a _different_ agent wrote (normally
|
|
15
|
+
`code-implementer`). That separation is the point: the author cannot grade
|
|
16
|
+
their own hot path.
|
|
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 a query inside a loop, a
|
|
26
|
+
synchronous call in a request handler, a list endpoint with no limit and an
|
|
27
|
+
outbound call with no timeout. You cannot see real latency, throughput, memory
|
|
28
|
+
growth, query plans or how the code behaves under load. Report those as **NOT
|
|
29
|
+
CHECKED** with what would settle them (profiling, a load test, a query plan,
|
|
30
|
+
production metrics), never as a pass. Never describe a cost as slow, fast or large, and never give a latency
|
|
31
|
+
formula or estimate (for example, roughly the number of orders times the
|
|
32
|
+
round trip): say what grows (round trips, bytes buffered, how long the event
|
|
33
|
+
loop is blocked) and leave how much to **NOT CHECKED**. Never state a number
|
|
34
|
+
you did not measure
|
|
35
|
+
and never say the code "is fast" or "performs well": say what you found in the
|
|
36
|
+
files you read, and what you did not check.
|
|
37
|
+
|
|
38
|
+
## Checklist
|
|
39
|
+
|
|
40
|
+
### Node.js (only when the project runs Node)
|
|
41
|
+
|
|
42
|
+
These come from the Node.js guide "Don't Block the Event Loop (or the Worker
|
|
43
|
+
Pool)" and apply only if the project runs Node. A server stays fast when the
|
|
44
|
+
work for each client at any moment is small, so look for anything that makes
|
|
45
|
+
one request's work large or blocking.
|
|
46
|
+
|
|
47
|
+
- **Synchronous APIs in a request path.** `crypto.pbkdf2Sync`,
|
|
48
|
+
`crypto.randomFillSync`, `zlib.inflateSync`, `zlib.deflateSync`,
|
|
49
|
+
`child_process.execSync`, `child_process.spawnSync`,
|
|
50
|
+
`child_process.execFileSync` and the synchronous fs APIs block the event loop
|
|
51
|
+
for every client. Fine at startup or in a build script; a Must-fix in a
|
|
52
|
+
handler.
|
|
53
|
+
- **Regular expressions that can backtrack badly (ReDoS).** Nested quantifiers
|
|
54
|
+
such as `(a+)*`, overlapping alternation such as `(a|a)*` and backreferences,
|
|
55
|
+
run over input a client controls.
|
|
56
|
+
- **JSON on large input.** `JSON.parse` and `JSON.stringify` cost time in
|
|
57
|
+
proportion to the size of the input; flag them on a body or payload with no
|
|
58
|
+
size bound. A streaming parser is the usual alternative.
|
|
59
|
+
- **Loops whose cost grows with client input**, such as a nested loop over a
|
|
60
|
+
value taken from the query string, with no cap on that value.
|
|
61
|
+
|
|
62
|
+
### Language-neutral heuristics (not sourced)
|
|
63
|
+
|
|
64
|
+
These are common review heuristics, **not sourced** from a specification, so
|
|
65
|
+
state them as likely problems and never as proven ones.
|
|
66
|
+
Tag each finding that comes from this list with `[heuristic]` in your report, at
|
|
67
|
+
any severity, so a Must-fix from this list is still read as a likely problem.
|
|
68
|
+
|
|
69
|
+
- **N+1 queries.** A database or service call inside a loop over the results of
|
|
70
|
+
an earlier call; look for a batched query or a join.
|
|
71
|
+
- **Unbounded list queries.** A query or endpoint that returns every row, with
|
|
72
|
+
no pagination or limit.
|
|
73
|
+
- **Serial awaits of independent calls.** Calls that do not depend on each
|
|
74
|
+
other, awaited one after another instead of together.
|
|
75
|
+
- **Outbound calls with no timeout.** An HTTP or database call that can wait
|
|
76
|
+
forever and hold a connection or worker.
|
|
77
|
+
- **Unbounded in-memory buffering.** Reading a whole request body, response or
|
|
78
|
+
file into memory when it could be streamed or capped.
|
|
79
|
+
|
|
80
|
+
## Severity
|
|
81
|
+
|
|
82
|
+
- **Must-fix** — a blocking call or unbounded work evident from the source you
|
|
83
|
+
read, in a path that serves requests.
|
|
84
|
+
- **Should-fix** — a likely cost that depends on something you could not see,
|
|
85
|
+
such as the size of a table or how often a path runs.
|
|
86
|
+
- **Nit** — minor, or a style point that improves robustness.
|
|
87
|
+
- **NOT CHECKED** — needs profiling, a load test, a query plan or production
|
|
88
|
+
metrics. List these, with the check that would settle each one.
|
|
89
|
+
|
|
90
|
+
## Report
|
|
91
|
+
|
|
92
|
+
Return a bounded digest inline, at most about 8,000 characters, and never write a file.
|
|
93
|
+
For each finding give `file:line`, what you saw, why it costs, and the
|
|
94
|
+
smallest fix. Group by Must-fix, Should-fix, Nit, then NOT CHECKED. Stop once
|
|
95
|
+
the checklist is answered for the files you were given: do not re-verify
|
|
96
|
+
indefinitely. If you found nothing in a category, say so in one line.
|
|
@@ -0,0 +1,67 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: api-doc
|
|
3
|
+
description: Writes or updates an OpenAPI description of a service's HTTP API from the routes the code actually defines, using the template in this skill. Use for /api-doc, "document the API", "write the OpenAPI spec", "add an endpoint to the API docs", or when the API docs are out of date with the routes.
|
|
4
|
+
argument-hint: "[output-path]"
|
|
5
|
+
---
|
|
6
|
+
|
|
7
|
+
# api-doc
|
|
8
|
+
|
|
9
|
+
An API description is only useful when it matches the code. This skill reads
|
|
10
|
+
the project's own routes and handlers, whatever the framework, and fills in an
|
|
11
|
+
OpenAPI document from them. It ships one template, `openapi-template.yaml`
|
|
12
|
+
beside this file, and no framework-specific code.
|
|
13
|
+
|
|
14
|
+
The output is a docs file, `docs/api/openapi.yaml` by default (or the project's
|
|
15
|
+
existing API description, if it has one). The skill never writes under `src/`
|
|
16
|
+
or `tests/`: the hub never writes source, and a description does not need to.
|
|
17
|
+
|
|
18
|
+
## What the OpenAPI Specification requires
|
|
19
|
+
|
|
20
|
+
Checked against spec.openapis.org (the version in the template header):
|
|
21
|
+
|
|
22
|
+
- `openapi` and `info` are required, and `info` needs a `title` and a
|
|
23
|
+
`version`.
|
|
24
|
+
- At least one of `components`, `paths` or `webhooks` must be present.
|
|
25
|
+
- Each key in `paths` starts with a `/`.
|
|
26
|
+
- `operationId` must be unique among all operations in the document (it is
|
|
27
|
+
optional, but unique if present).
|
|
28
|
+
- A path parameter must have `required: true`.
|
|
29
|
+
- A security requirement names a scheme declared under
|
|
30
|
+
`components.securitySchemes`.
|
|
31
|
+
|
|
32
|
+
## Steps
|
|
33
|
+
|
|
34
|
+
### 1 — Find the routes
|
|
35
|
+
|
|
36
|
+
Find where the project defines its HTTP routes or handlers: read the entry
|
|
37
|
+
point, the router files and any existing API description. Record, for each
|
|
38
|
+
route: method, path, path and query parameters, request body shape, the
|
|
39
|
+
responses it returns (status and shape) and how it authenticates. Read the
|
|
40
|
+
code, never infer from names alone.
|
|
41
|
+
|
|
42
|
+
If the project already has an OpenAPI file, update it in place instead of
|
|
43
|
+
starting from the template, and keep its `openapi` version.
|
|
44
|
+
|
|
45
|
+
### 2 — Fill the template
|
|
46
|
+
|
|
47
|
+
Copy `openapi-template.yaml` to the output path and replace its placeholders.
|
|
48
|
+
Document only routes that exist in the code, and never invent an endpoint,
|
|
49
|
+
parameter or response. Where the code does not settle a detail (a response
|
|
50
|
+
shape built dynamically, an error status a middleware adds), write it as a
|
|
51
|
+
`TODO` and mark it **unverified** in its `description`, so the reader knows
|
|
52
|
+
which parts a person still has to confirm.
|
|
53
|
+
|
|
54
|
+
Reuse schemas under `components` instead of repeating them, give every
|
|
55
|
+
operation a unique `operationId`, and give every response a `description`.
|
|
56
|
+
|
|
57
|
+
### 3 — Never add a dependency
|
|
58
|
+
|
|
59
|
+
You never add a dependency to generate or validate the description, and you
|
|
60
|
+
never write under src/ or tests/. If the project already has an OpenAPI
|
|
61
|
+
linter, run it on the result; if not, check the file by reading it against the
|
|
62
|
+
rules above.
|
|
63
|
+
|
|
64
|
+
### 4 — Report
|
|
65
|
+
|
|
66
|
+
Say which file was written, how many operations it documents, which routes you
|
|
67
|
+
could not document and why, and every `TODO` left as unverified.
|
|
@@ -0,0 +1,48 @@
|
|
|
1
|
+
# OpenAPI description template for the api-doc skill.
|
|
2
|
+
# Replace every placeholder; delete what the API does not have.
|
|
3
|
+
# Version 3.2.1 was the current OpenAPI Specification when this was written
|
|
4
|
+
# (https://spec.openapis.org/oas/latest.html): check that page and use the
|
|
5
|
+
# version the project's tooling supports.
|
|
6
|
+
openapi: "3.2.1"
|
|
7
|
+
info:
|
|
8
|
+
title: Example service API
|
|
9
|
+
version: "0.1.0"
|
|
10
|
+
description: What this API does, in one sentence.
|
|
11
|
+
servers:
|
|
12
|
+
- url: https://api.example.com
|
|
13
|
+
paths:
|
|
14
|
+
/items/{itemId}:
|
|
15
|
+
get:
|
|
16
|
+
# operationId is optional, but when present it must be unique among all
|
|
17
|
+
# operations in the document.
|
|
18
|
+
operationId: getItem
|
|
19
|
+
summary: Get one item
|
|
20
|
+
parameters:
|
|
21
|
+
- name: itemId
|
|
22
|
+
in: path
|
|
23
|
+
required: true
|
|
24
|
+
schema:
|
|
25
|
+
type: string
|
|
26
|
+
responses:
|
|
27
|
+
"200":
|
|
28
|
+
description: The item.
|
|
29
|
+
content:
|
|
30
|
+
application/json:
|
|
31
|
+
schema:
|
|
32
|
+
$ref: "#/components/schemas/Item"
|
|
33
|
+
"404":
|
|
34
|
+
description: No item has that id.
|
|
35
|
+
security:
|
|
36
|
+
- bearerAuth: []
|
|
37
|
+
components:
|
|
38
|
+
schemas:
|
|
39
|
+
Item:
|
|
40
|
+
type: object
|
|
41
|
+
required: [id]
|
|
42
|
+
properties:
|
|
43
|
+
id:
|
|
44
|
+
type: string
|
|
45
|
+
securitySchemes:
|
|
46
|
+
bearerAuth:
|
|
47
|
+
type: http
|
|
48
|
+
scheme: bearer
|
|
@@ -0,0 +1,19 @@
|
|
|
1
|
+
{
|
|
2
|
+
"schemaVersion": 1,
|
|
3
|
+
"name": "service",
|
|
4
|
+
"description": "Two aids for a project that serves an API, on top of the baseline: a read-only performance-analyzer agent that does a static review of changed server code for blocking calls, per-request cost and unbounded work and reports anything that needs profiling or a load test as NOT CHECKED, and an api-doc skill that writes an OpenAPI description from the routes the code actually defines, using a template inside the skill. No hooks, no settings, no gate, no framework templates.",
|
|
5
|
+
"modes": ["fresh", "adopt"],
|
|
6
|
+
"budget": {
|
|
7
|
+
"agents": 1,
|
|
8
|
+
"skills": 1,
|
|
9
|
+
"hooks": 0,
|
|
10
|
+
"workflows": 0,
|
|
11
|
+
"scripts": 0
|
|
12
|
+
},
|
|
13
|
+
"wiring": {
|
|
14
|
+
"settings": {},
|
|
15
|
+
"packageScripts": {},
|
|
16
|
+
"verifySteps": []
|
|
17
|
+
},
|
|
18
|
+
"adoptNotes": "Both files install anywhere a .claude/ directory exists and need no gate runner. performance-analyzer is a read-only review spoke (model claude-sonnet-5-5 at medium effort, tools Read, Grep and Glob only, so it never runs a command): nothing in the baseline's hub-and-spoke instructions dispatches it by name, so ask for it after changing server code, or add it to the project's own CLAUDE.md review step. It reviews source statically and cannot profile or load-test, so it reports those as NOT CHECKED instead of guessing. api-doc ships an OpenAPI template (openapi-template.yaml, inside the skill directory) and reads the project's own route or handler code to learn what to document, so it works for any framework; it writes a docs file (docs/api/openapi.yaml by default) and never touches src/ or tests/, and it marks anything it cannot confirm from the code as TODO and unverified."
|
|
19
|
+
}
|
|
@@ -8,6 +8,8 @@ description: >-
|
|
|
8
8
|
worktree", "what worktrees are open", "sync this worktree with main", or
|
|
9
9
|
"finish this worktree" -- and from `starting-work`'s own branch step, which
|
|
10
10
|
hands off here automatically when this skill is installed.
|
|
11
|
+
allowed-tools: Bash(git worktree list --porcelain) Bash(git status --porcelain)
|
|
12
|
+
argument-hint: "[start <slug> | status | sync <slug> | finish <slug> | fan-out]"
|
|
11
13
|
---
|
|
12
14
|
|
|
13
15
|
# working-in-worktrees
|
|
@@ -43,11 +45,24 @@ Hub-only. Never dispatched as a spoke's own tool.
|
|
|
43
45
|
a work tree", the manual fix is `git config --local core.bare false`. Prefer
|
|
44
46
|
the `path:` and `keep` forms used in this skill; `EnterWorktree(name: ...)` and
|
|
45
47
|
`ExitWorktree(remove)` are the calls the upstream reports tie to it.
|
|
46
|
-
4. Copy
|
|
47
|
-
checkout into the new worktree (the same list as
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
so
|
|
48
|
+
4. Copy each of `.env`, `.env.local` and the `.env.*.local` files that exist
|
|
49
|
+
in the main checkout into the new worktree (the same list as
|
|
50
|
+
`.worktreeinclude`; copy each file that exists by name, never pass an
|
|
51
|
+
unmatched glob to `cp`). The session's working directory is now the
|
|
52
|
+
worktree, so give both ends: `cp -n <main-checkout>/<file> .`, with
|
|
53
|
+
`<main-checkout>` as the first path that
|
|
54
|
+
`git worktree list --porcelain` prints. `-n` never overwrites an existing file; a skipped existing
|
|
55
|
+
file (a non-zero exit or a warning on some GNU versions) is not a denial.
|
|
56
|
+
`.worktreeinclude` (this pack ships one) only fires for a worktree Claude
|
|
57
|
+
Code itself creates -- since this skill creates the directory with plain
|
|
58
|
+
`git worktree add`, that processing never runs here, so the copy is done by
|
|
59
|
+
hand. Never read or print a file's contents to do it. The baseline's
|
|
60
|
+
`permissions.deny` rules block reading `.env*`, and Claude Code documents
|
|
61
|
+
that block for file commands it recognizes in Bash (`cat`, `head`, `tail`,
|
|
62
|
+
`sed`, `tee`, redirects) without listing `cp`, so the copy may or may not be
|
|
63
|
+
denied. If it is denied, stop, list the files, and ask the owner to copy
|
|
64
|
+
them themselves: never work around the block with a script, a different
|
|
65
|
+
command or a read.
|
|
51
66
|
5. `pnpm install --frozen-lockfile --prefer-offline` inside the worktree.
|
|
52
67
|
`ensure-worktree-deps.mjs`'s own `SessionStart` hook is a backstop for
|
|
53
68
|
`claude --worktree`/a resumed session, not a substitute for this step --
|