@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.
Files changed (55) hide show
  1. package/README.md +62 -13
  2. package/dist/harness/rules.js +1 -1
  3. package/dist/main.js +5 -15
  4. package/dist/merge-json.d.ts +3 -1
  5. package/dist/merge-json.js +1 -1
  6. package/package.json +1 -1
  7. package/plugin/skills/customize/SKILL.md +17 -0
  8. package/plugin/skills/customize/step-3-round-1.md +105 -20
  9. package/plugin/src/domain-map.ts +1 -1
  10. package/plugin/src/pack-map.ts +177 -44
  11. package/plugin/src/plugin-map.ts +277 -28
  12. package/templates/core/.claude/hooks/inject-decision-gate.mjs +4 -0
  13. package/templates/core/.claude/rules/agent-dispatch.md +46 -0
  14. package/templates/core/.claude/settings.json +11 -1
  15. package/templates/core/.claude/skills/creating-prs/SKILL.md +1 -0
  16. package/templates/core/.claude/skills/finishing-work/SKILL.md +1 -0
  17. package/templates/core/.claude/skills/harness-guidance/SKILL.md +1 -0
  18. package/templates/core/.claude/skills/starting-work/SKILL.md +20 -0
  19. package/templates/core/.claude/skills/triaging-ci/SKILL.md +1 -0
  20. package/templates/core/.claude/skills/typescript-guidance/SKILL.md +1 -0
  21. package/templates/core/.claude/skills/writing-commits/SKILL.md +1 -0
  22. package/templates/core/CLAUDE.md +44 -60
  23. package/templates/core/bin/check-exports.mjs +3 -1
  24. package/templates/core/bin/lib/harness-rules.mjs +1 -1
  25. package/templates/core/eslint.config.js +2 -0
  26. package/templates/core/vitest.config.ts +4 -3
  27. package/templates/packs/README.md +8 -3
  28. package/templates/packs/{github → claude-github}/files/.github/workflows/claude-pr-review.yml +1 -1
  29. package/templates/packs/{github → claude-github}/files/.github/workflows/claude.yml +1 -1
  30. package/templates/packs/claude-github/pack.json +19 -0
  31. package/templates/packs/frontend/files/.claude/agents/ui-reviewer.md +132 -0
  32. package/templates/packs/frontend/files/.claude/skills/new-component/SKILL.md +72 -0
  33. package/templates/packs/frontend/pack.json +19 -0
  34. package/templates/packs/github/files/.claude/skills/reviewing-dependabot-prs/SKILL.md +4 -0
  35. package/templates/packs/github/files/.claude/skills/triaging-scan-alerts/SKILL.md +3 -0
  36. package/templates/packs/github/files/.claude/skills/watching-pr-checks/SKILL.md +4 -0
  37. package/templates/packs/github/pack.json +3 -3
  38. package/templates/packs/harness-extras/files/.claude/hooks/guard-readonly-bash.mjs +1117 -122
  39. package/templates/packs/harness-extras/pack.json +3 -15
  40. package/templates/packs/licensing/pack.json +31 -0
  41. package/templates/packs/publishing/pack.json +3 -14
  42. package/templates/packs/quality/files/.claude/agents/type-design-analyzer.md +1 -1
  43. package/templates/packs/service/files/.claude/agents/performance-analyzer.md +96 -0
  44. package/templates/packs/service/files/.claude/skills/api-doc/SKILL.md +67 -0
  45. package/templates/packs/service/files/.claude/skills/api-doc/openapi-template.yaml +48 -0
  46. package/templates/packs/service/pack.json +19 -0
  47. package/templates/packs/statusline/pack.json +31 -0
  48. package/templates/packs/supply-chain/pack.json +1 -1
  49. package/templates/packs/worktrees/files/.claude/skills/working-in-worktrees/SKILL.md +20 -5
  50. package/templates/packs/worktrees/pack.json +2 -1
  51. /package/templates/packs/{publishing → licensing}/files/REUSE.toml +0 -0
  52. /package/templates/packs/{publishing → licensing}/files/bin/check-license-headers.mjs +0 -0
  53. /package/templates/packs/{harness-extras → statusline}/files/.claude/hooks/statusline-layout.mjs +0 -0
  54. /package/templates/packs/{harness-extras → statusline}/files/.claude/hooks/statusline.mjs +0 -0
  55. /package/templates/packs/{harness-extras → statusline}/files/.claude/hooks/subagent-statusline.mjs +0 -0
@@ -1,12 +1,12 @@
1
1
  {
2
2
  "schemaVersion": 1,
3
3
  "name": "harness-extras",
4
- "description": "Adds Claude Code session ergonomics on top of the baseline: a pair of hooks that carry a work summary across a context-window compaction, a hook that blocks non-read-only Bash commands from read-only review spokes, and a five-row statusLine (plus a per-subagent row renderer) -- the only documented surface carrying live context-window pressure.",
4
+ "description": "Adds Claude Code session ergonomics on top of the baseline: a pair of hooks that carry a work summary across a context-window compaction, and a hook that blocks non-read-only Bash commands from read-only review spokes. The status line is the separate `statusline` pack.",
5
5
  "modes": ["fresh", "adopt"],
6
6
  "budget": {
7
7
  "agents": 0,
8
8
  "skills": 0,
9
- "hooks": 6,
9
+ "hooks": 3,
10
10
  "workflows": 0,
11
11
  "scripts": 0
12
12
  },
@@ -51,20 +51,8 @@
51
51
  }
52
52
  ]
53
53
  },
54
- "settingsTopLevel": {
55
- "statusLine": {
56
- "type": "command",
57
- "command": "node \"$CLAUDE_PROJECT_DIR/.claude/hooks/statusline.mjs\"",
58
- "refreshInterval": 30,
59
- "padding": 1
60
- },
61
- "subagentStatusLine": {
62
- "type": "command",
63
- "command": "node \"$CLAUDE_PROJECT_DIR/.claude/hooks/subagent-statusline.mjs\""
64
- }
65
- },
66
54
  "packageScripts": {},
67
55
  "verifySteps": []
68
56
  },
69
- "adoptNotes": "The statusline and 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 statusline scripts read only the stdin payload, .git/HEAD (via node:fs, never a git subprocess) and process.availableMemory()/os.totalmem(), so they install anywhere a .claude/ directory exists -- no dependency on the baseline's file layout. The one real adopt risk is the two top-level settings keys: a project that already defines statusLine or subagentStatusLine collides, and its existing value must be shown and decided on, never overwritten -- if either is already set, skip that key and the three statusline scripts, and install the rest of this pack (the hooks) normally rather than failing the whole install. A statusLine in .claude/settings.local.json (or one passed with --settings) also shadows the project one; the user's own ~/.claude/settings.json ranks lower and does not -- check those before concluding the pack is wired. rate_limits.spend_limit and prompt_cache need Claude Code v2.1.251+, and the per-subagent model/contextWindowSize/effort fields need v2.1.205+/v2.1.214+, and the agentType label a row falls back to when a subagent has no name needs v2.1.293+; each renders only when present, so an older Claude Code degrades to fewer segments rather than breaking. The scripts behave the same on macOS and Linux; the memory segment uses process.availableMemory() (Node 22+), and on macOS with an older Node it is hidden rather than shown from os.freemem(), which undercounts there. Below roughly 40 columns the layout drops segments by priority rather than wrapping. The size-ratchet gate and the type-design-analyzer agent that used to ship here are now the separate `quality` pack."
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."
70
58
  }
@@ -0,0 +1,31 @@
1
+ {
2
+ "schemaVersion": 1,
3
+ "name": "licensing",
4
+ "description": "An SPDX/REUSE license-header gate for a new project: check-license-headers.mjs (a lint-group verify step that fails on any git-tracked file with neither an SPDX header nor a REUSE.toml annotation, and inserts missing headers with --fix) and a REUSE.toml template. Fresh mode only, because the one-time backfill fails an established project's pnpm verify until it has touched every file. Split from `publishing` so a project can take the header gate without the npm release pipeline, and the other way round.",
5
+ "modes": ["fresh"],
6
+ "budget": {
7
+ "agents": 0,
8
+ "skills": 0,
9
+ "hooks": 0,
10
+ "workflows": 0,
11
+ "scripts": 0
12
+ },
13
+ "wiring": {
14
+ "settings": {},
15
+ "packageScripts": {},
16
+ "verifySteps": [
17
+ {
18
+ "id": "license-headers",
19
+ "group": "lint",
20
+ "name": "Check SPDX license headers",
21
+ "cmd": ["node", "bin/check-license-headers.mjs"]
22
+ }
23
+ ]
24
+ },
25
+ "setupSteps": [
26
+ "git add -A",
27
+ "node bin/check-license-headers.mjs --fix",
28
+ "git add -A"
29
+ ],
30
+ "adoptNotes": "REQUIRED right after install, before the first pnpm verify: `git add -A`, then `node bin/check-license-headers.mjs --fix`, then `git add -A` again and commit the result (the gate only checks git-tracked files, so a fresh project with nothing staged passes it vacuously and fails on every file at its first push) -- templates/core has never had a license-header gate before this pack, so every one of its own files (hooks, bin/ scripts, CI workflows, the placeholder src/tests, and the workflows of any other installed pack such as `claude-github` or `supply-chain`) is missing the SPDX header this pack's gate now requires. The shipped REUSE.toml and gate header use NOASSERTION as the license identifier because the pack cannot know the project's license: edit REUSE.toml and the headerLines() function in bin/check-license-headers.mjs once it is decided (a LICENSE file, if one exists, is the source of truth). In a hand-copied install the CLI does not substitute tokens, so replace every literal `__PROJECT_NAME__` in the copied files (REUSE.toml, the SPDX headers) with the project's real name first. Fresh mode only: the backfill fails an established project's pnpm verify until it has touched every file, so it is staged like every other pack (at .groundwork/packs/licensing/) but never auto-installed in adopt mode -- if an adopted project wants it, copy .groundwork/packs/licensing/files/ by hand, dropping the `.staged` suffix from every name (or copy templates/packs/licensing/files/ from this repo directly) and run the backfill above. The license-headers verify step is a lint-group gate and installs anywhere a bin/verify.mjs-shaped gate runner exists; wire it into the project's real one if it differs. REUSE.toml also carries globs for `.gitleaks.toml` and `.worktreeinclude`, the files the `supply-chain` and `worktrees` packs add, so the gate's uncovered-file check passes whether or not those packs are installed. This gate used to ship in the `publishing` pack; a project that installed that pack before the split keeps its files untouched."
31
+ }
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "schemaVersion": 1,
3
3
  "name": "publishing",
4
- "description": "A release pipeline for a project that ships an npm package. Release half: release.yml (changesets version-PR / staged, provenance-attested npm publish via trusted publishing OIDC, including a direct check-publish-version.mjs call right before packing), .changeset/config.json + README.md, the pnpm-to-staged-publish shim (libnpmpublish, not the npm CLI), and one build-group gate (check-dts-deps.mjs). Also ships check-license-headers.mjs and a REUSE.toml template as a lint-group gate (secret scanning and Scorecard are the separate `supply-chain` pack). Not adopt-capable: the release flow assumes decisions (registry access, npm trusted-publisher setup, a GitHub App for the version PR) too project-specific to install blind -- see adoptNotes.",
4
+ "description": "A release pipeline for a project that ships an npm package. Release half: release.yml (changesets version-PR / staged, provenance-attested npm publish via trusted publishing OIDC, including a direct check-publish-version.mjs call right before packing), .changeset/config.json + README.md, the pnpm-to-staged-publish shim (libnpmpublish, not the npm CLI), and one build-group gate (check-dts-deps.mjs). The SPDX license-header gate is the separate `licensing` pack, and secret scanning and Scorecard are the separate `supply-chain` pack. Not adopt-capable: the release flow assumes decisions (registry access, npm trusted-publisher setup, a GitHub App for the version PR) too project-specific to install blind -- see adoptNotes.",
5
5
  "modes": ["fresh"],
6
6
  "budget": {
7
7
  "agents": 0,
@@ -22,20 +22,9 @@
22
22
  "group": "build",
23
23
  "name": "Check .d.ts dependency declarations",
24
24
  "cmd": ["node", "bin/check-dts-deps.mjs"]
25
- },
26
- {
27
- "id": "license-headers",
28
- "group": "lint",
29
- "name": "Check SPDX license headers",
30
- "cmd": ["node", "bin/check-license-headers.mjs"]
31
25
  }
32
26
  ]
33
27
  },
34
- "setupSteps": [
35
- "pnpm add -D @changesets/cli",
36
- "git add -A",
37
- "node bin/check-license-headers.mjs --fix",
38
- "git add -A"
39
- ],
40
- "adoptNotes": "REQUIRED right after install, before the first pnpm verify -- two one-time steps, or pnpm verify fails immediately, not from a real regression but from two setup gaps this pack cannot close itself: (1) `pnpm add -D @changesets/cli` -- the wiring contract only extends package.json's scripts, never its dependencies (see templates/packs/README.md), so the wired `changeset`/`version:packages` scripts reference a binary knip's own unlisted-binaries check correctly flags as missing until this is installed; (2) `git add -A`, then `node bin/check-license-headers.mjs --fix`, then `git add -A` again and commit the result (the gate only checks git-tracked files, so a fresh project with nothing staged passes it vacuously and fails on every file at its first push) -- templates/core has never had a license-header gate before this pack, so every one of its own files (hooks, bin/ scripts, CI workflows, the placeholder src/tests, and the workflows of any other installed pack such as `github` or `supply-chain`) is missing the SPDX header this pack's own license-headers gate now requires, the same one-time cost this repo itself paid when it adopted the same gate (see CLAUDE.md's Definition of Done). In a hand-copied install the CLI does not substitute tokens, so replace every literal `__PROJECT_NAME__` in the copied files (REUSE.toml, the SPDX headers in bin/, the workflows) with the project's real name first. Fresh mode only: a release pipeline encodes decisions (whether the package is actually public, which registry, whether a GitHub App backs the version PR) this pack cannot survey or guess at safely, so it is staged like every other pack (at .groundwork/packs/publishing/) but never auto-installed in adopt mode -- if an adopted project wants it, copy .groundwork/packs/publishing/files/ by hand, dropping the `.staged` suffix from every name (or copy templates/packs/publishing/files/ from this repo directly) and work through the one-time setup below. check-publish-version.mjs is deliberately NOT one of this pack's wired verify steps: with changesets, package.json's version on the release branch is always the one just published between releases, so a version-already-published check running on every ordinary push (via pnpm verify / pre-push) would fail every single time until the next version PR lands -- it is instead invoked directly as a step inside release.yml's pack job, the one place \"is this version about to collide with an already-published one\" is actually the right question to ask. The two remaining verify-group gates (dts-deps, license-headers) install anywhere a bin/verify.mjs-shaped gate runner exists; wire them into the project's real one if it differs. Both check-publish-version.mjs and check-dts-deps.mjs no-op (checked: 0, not a failure) on a package.json with `private: true` (the baseline's own default) or (check-dts-deps.mjs only) with no dist/**/*.d.ts yet -- flip `private` to `false` (and set a real `name`) once the package is actually meant to publish. The pack assumes a public package: `.changeset/config.json` ships `access: public`, npm refuses `restricted` for an unscoped name, and the publisher always requests provenance, which npm ties to a public source repository -- a private scoped package needs `access: restricted` and the `provenance: true` option removed from the libnpmpublish call in bin/npm-stage-publish.mjs. `@changesets/changelog-github` (and its `repo` option) is a drop-in swap for `.changeset/config.json`'s plain default changelog generator, once this project's GitHub repository is known, for changelog entries that link back to the originating PR/commit -- see `.changeset/README.md`. One-time setup before release.yml's first real run (distinct from the two pnpm-verify prerequisites above), distilled from this repo's own .claude/rules/releases.md: (1) npm cannot configure a trusted publisher for a package that doesn't exist yet -- publish once by hand with a temporary token first; (2) the trusted publisher is bound to the exact workflow filename `release.yml` -- renaming or moving it breaks publishing until reconfigured on npmjs.com; (3) set the trusted publisher's allowed actions to staged-only (staged publishing only, npm's own default and recommendation since 2026-09-03) -- a maintainer runs `npm stage approve <id>` (2FA, never automatable) before a version actually installs; (4) create an `npm-publish` GitHub environment (via `gh api`, not committed as JSON) with a required reviewer, restricted to the release branch, so the `publish` job itself pauses before the git tag/Release/stage-publish exist; (5) if branch protection requires status checks on every PR with no bypass actor, the version-PR job needs a GitHub App installation token (`APP_CLIENT_ID`/`APP_PRIVATE_KEY` repo secrets), not the default GITHUB_TOKEN, or those checks never trigger and the PR can never merge -- if this project has no such rule, `github-token: ${{ secrets.GITHUB_TOKEN }}` is enough and the app-token step can be dropped. release.yml pins `tools/release/` (the exact libnpmpublish and npm-registry-fetch versions the publish job installs; it stages through them, not the npm CLI, because the CLI's bundled dependencies cannot be patched by an override) but the baseline's dependabot.yml only covers the github-actions ecosystem, so that pin goes stale unless you add an `npm` entry with `directory: \"/tools/release\"` to the project's own .github/dependabot.yml. The staged id to approve is printed by the workflow's \"Show the staged ids to approve\" step (and annotated on the run), and the `npm stage approve <id>` command is also written to the job summary. The secret-scanning and Scorecard workflows that used to ship here are now the separate `supply-chain` pack."
28
+ "setupSteps": ["pnpm add -D @changesets/cli"],
29
+ "adoptNotes": "REQUIRED right after install, before the first pnpm verify -- one step, or pnpm verify fails immediately, not from a real regression but from a setup gap this pack cannot close itself: `pnpm add -D @changesets/cli` -- the wiring contract only extends package.json's scripts, never its dependencies (see templates/packs/README.md), so the wired `changeset`/`version:packages` scripts reference a binary knip's own unlisted-binaries check correctly flags as missing until this is installed. In a hand-copied install the CLI does not substitute tokens, so replace every literal `__PROJECT_NAME__` in the copied files (the SPDX headers in bin/, the workflows) with the project's real name first. Fresh mode only: a release pipeline encodes decisions (whether the package is actually public, which registry, whether a GitHub App backs the version PR) this pack cannot survey or guess at safely, so it is staged like every other pack (at .groundwork/packs/publishing/) but never auto-installed in adopt mode -- if an adopted project wants it, copy .groundwork/packs/publishing/files/ by hand, dropping the `.staged` suffix from every name (or copy templates/packs/publishing/files/ from this repo directly) and work through the one-time setup below. check-publish-version.mjs is deliberately NOT one of this pack's wired verify steps: with changesets, package.json's version on the release branch is always the one just published between releases, so a version-already-published check running on every ordinary push (via pnpm verify / pre-push) would fail every single time until the next version PR lands -- it is instead invoked directly as a step inside release.yml's pack job, the one place \"is this version about to collide with an already-published one\" is actually the right question to ask. The remaining verify-group gate (dts-deps) installs anywhere a bin/verify.mjs-shaped gate runner exists; wire it into the project's real one if it differs. Both check-publish-version.mjs and check-dts-deps.mjs no-op (checked: 0, not a failure) on a package.json with `private: true` (the baseline's own default) or (check-dts-deps.mjs only) with no dist/**/*.d.ts yet -- flip `private` to `false` (and set a real `name`) once the package is actually meant to publish. The pack assumes a public package: `.changeset/config.json` ships `access: public`, npm refuses `restricted` for an unscoped name, and the publisher always requests provenance, which npm ties to a public source repository -- a private scoped package needs `access: restricted` and the `provenance: true` option removed from the libnpmpublish call in bin/npm-stage-publish.mjs. `@changesets/changelog-github` (and its `repo` option) is a drop-in swap for `.changeset/config.json`'s plain default changelog generator, once this project's GitHub repository is known, for changelog entries that link back to the originating PR/commit -- see `.changeset/README.md`. One-time setup before release.yml's first real run (distinct from the pnpm-verify prerequisite above), distilled from this repo's own .claude/rules/releases.md: (1) npm cannot configure a trusted publisher for a package that doesn't exist yet -- publish once by hand with a temporary token first; (2) the trusted publisher is bound to the exact workflow filename `release.yml` -- renaming or moving it breaks publishing until reconfigured on npmjs.com; (3) set the trusted publisher's allowed actions to staged-only (staged publishing only, npm's own default and recommendation since 2026-09-03) -- a maintainer runs `npm stage approve <id>` (2FA, never automatable) before a version actually installs; (4) create an `npm-publish` GitHub environment (via `gh api`, not committed as JSON) with a required reviewer, restricted to the release branch, so the `publish` job itself pauses before the git tag/Release/stage-publish exist; (5) if branch protection requires status checks on every PR with no bypass actor, the version-PR job needs a GitHub App installation token (`APP_CLIENT_ID`/`APP_PRIVATE_KEY` repo secrets), not the default GITHUB_TOKEN, or those checks never trigger and the PR can never merge -- if this project has no such rule, `github-token: ${{ secrets.GITHUB_TOKEN }}` is enough and the app-token step can be dropped. release.yml pins `tools/release/` (the exact libnpmpublish and npm-registry-fetch versions the publish job installs; it stages through them, not the npm CLI, because the CLI's bundled dependencies cannot be patched by an override) but the baseline's dependabot.yml only covers the github-actions ecosystem, so that pin goes stale unless you add an `npm` entry with `directory: \"/tools/release\"` to the project's own .github/dependabot.yml. The staged id to approve is printed by the workflow's \"Show the staged ids to approve\" step (and annotated on the run), and the `npm stage approve <id>` command is also written to the job summary. The secret-scanning and Scorecard workflows that used to ship here are now the separate `supply-chain` pack. The SPDX/REUSE license-header gate that used to ship here is now the separate fresh-only `licensing` pack: this pack's own scripts and release.yml still carry SPDX headers with a NOASSERTION license identifier, which is harmless without that gate but is what it would check."
41
30
  }
@@ -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 every shell write route regardless), so a
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
+ }
@@ -0,0 +1,31 @@
1
+ {
2
+ "schemaVersion": 1,
3
+ "name": "statusline",
4
+ "description": "A five-row Claude Code statusLine (session, model, context, quota, work) plus a per-subagent row renderer -- the only documented surface carrying live context-window pressure. Three scripts and two top-level settings keys (`statusLine`, `subagentStatusLine`): no hook registrations, no verify step. Split from `harness-extras` so a project that already has its own status line can take that pack's hooks without a collision.",
5
+ "modes": ["fresh", "adopt"],
6
+ "budget": {
7
+ "agents": 0,
8
+ "skills": 0,
9
+ "hooks": 3,
10
+ "workflows": 0,
11
+ "scripts": 0
12
+ },
13
+ "wiring": {
14
+ "settings": {},
15
+ "settingsTopLevel": {
16
+ "statusLine": {
17
+ "type": "command",
18
+ "command": "node \"$CLAUDE_PROJECT_DIR/.claude/hooks/statusline.mjs\"",
19
+ "refreshInterval": 30,
20
+ "padding": 1
21
+ },
22
+ "subagentStatusLine": {
23
+ "type": "command",
24
+ "command": "node \"$CLAUDE_PROJECT_DIR/.claude/hooks/subagent-statusline.mjs\""
25
+ }
26
+ },
27
+ "packageScripts": {},
28
+ "verifySteps": []
29
+ },
30
+ "adoptNotes": "The statusline scripts read only the stdin payload, .git/HEAD (via node:fs, never a git subprocess) and process.availableMemory()/os.totalmem(), so they install anywhere a .claude/ directory exists -- no dependency on the baseline's file layout. The one real adopt risk is the two top-level settings keys: a project that already defines statusLine or subagentStatusLine collides, and its existing value must be shown and decided on, never overwritten -- if either is already set, skip that key and the script that renders it rather than failing the whole install; if both are set there is nothing left to install, so skip the pack. A statusLine in .claude/settings.local.json (or one passed with --settings) also shadows the project one; the user's own ~/.claude/settings.json ranks lower and does not -- check those before concluding the pack is wired. rate_limits.spend_limit and prompt_cache need Claude Code v2.1.251+, and the per-subagent model/contextWindowSize/effort fields need v2.1.205+/v2.1.214+, and the agentType label a row falls back to when a subagent has no name needs v2.1.293+; each renders only when present, so an older Claude Code degrades to fewer segments rather than breaking. The scripts behave the same on macOS and Linux; the memory segment uses process.availableMemory() (Node 22+), and on macOS with an older Node it is hidden rather than shown from os.freemem(), which undercounts there. Below roughly 40 columns the layout drops segments by priority rather than wrapping. These scripts used to ship inside the `harness-extras` pack; a project that installed that pack before the split keeps its files untouched."
31
+ }
@@ -15,5 +15,5 @@
15
15
  "packageScripts": {},
16
16
  "verifySteps": []
17
17
  },
18
- "adoptNotes": "An adopted project that already has its own .github/workflows/gitleaks.yml or scorecard.yml surfaces as an ordinary file conflict -- keep the existing one if it already works, since this pack's version would just replace a configured setup with its generic defaults. gitleaks.yml needs a free GITLEAKS_LICENSE repo secret for an organization-owned repository (gitleaks-action's own requirement); scorecard.yml assumes a public repository (`publish_results: true` needs one) -- set it `false` for a private repo. gitleaks.yml is read-only and scorecard.yml holds security-events: write and id-token: write in its analysis job; neither is a required check by default, so add either to branch protection once it has a clean run. The SPDX/REUSE license-header gate is not part of this pack: it lives in the fresh-only `publishing` pack, because it fails an established project's `pnpm verify` until a one-time backfill touches every file. 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 `publishing` gets the headers from that pack's `check-license-headers.mjs --fix` backfill."
18
+ "adoptNotes": "An adopted project that already has its own .github/workflows/gitleaks.yml or scorecard.yml surfaces as an ordinary file conflict -- keep the existing one if it already works, since this pack's version would just replace a configured setup with its generic defaults. gitleaks.yml needs a free GITLEAKS_LICENSE repo secret for an organization-owned repository (gitleaks-action's own requirement); scorecard.yml assumes a public repository (`publish_results: true` needs one) -- set it `false` for a private repo. gitleaks.yml is read-only and scorecard.yml holds security-events: write and id-token: write in its analysis job; neither is a required check by default, so add either to branch protection once it has a clean run. The SPDX/REUSE license-header gate is not part of this pack: it lives in the fresh-only `licensing` pack, because it fails an established project's `pnpm verify` until a one-time backfill touches every file. 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."
19
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 any of `.env`, `.env.local`, `.env.*.local` that exist in the main
47
- checkout into the new worktree (the same list as `.worktreeinclude`). `.worktreeinclude` (this pack ships one) only fires for a
48
- worktree Claude Code itself creates -- since this skill creates the
49
- directory with plain `git worktree add`, that processing never runs here,
50
- so the copy is done by hand.
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 --
@@ -39,6 +39,7 @@
39
39
  {
40
40
  "type": "command",
41
41
  "command": "node \"$CLAUDE_PROJECT_DIR/.claude/hooks/guard-worktree-only.mjs\"",
42
+ "onFailure": "block",
42
43
  "timeout": 30
43
44
  }
44
45
  ]
@@ -60,5 +61,5 @@
60
61
  "packageScripts": {},
61
62
  "verifySteps": []
62
63
  },
63
- "adoptNotes": "ensure-worktree-deps.mjs runs `pnpm install --frozen-lockfile --prefer-offline` automatically the first time a session starts inside a freshly created worktree with no node_modules yet -- this runs every dependency's lifecycle scripts the same way any `pnpm install` does, limited only by whatever `allowBuilds`/`onlyBuiltDependencies` policy the project's own pnpm config already sets (see typescript-guidance's pnpm supply-chain coverage if none is set). If node_modules in the worktree is a symlink (the usual result of `worktree.symlinkDirectories: [\"node_modules\"]` in .claude/settings.json, which this hook never reads), the hook detects the symlink and skips -- installing there would mutate the main checkout's own node_modules through the symlink. guard-worktree-only.mjs blocks every src/tests write outside a linked worktree under .claude/worktrees/, on any branch, for any caller (hub or writer spoke) -- this is stricter than guard-branch-isolation.mjs (which only blocks on main) and guard-hub-src-writes.mjs (which blocks the hub and any non-writer subagent); confirm the team actually wants every change routed through a worktree before installing this pack, since it changes the day-to-day workflow, not just adds a nicety. `.claude/worktrees/` should already be gitignored (the baseline's own .gitignore covers this); if adopting into a project with a hand-rolled .gitignore that doesn't, add it before installing. repair-core-bare.mjs resets `core.bare = true` to `false` in a non-bare repo's shared .git/config at session start and after EnterWorktree/ExitWorktree/Agent calls: Claude Code's worktree tools have been reported to leave it set (anthropics/claude-code#58345, #69802: user bug reports, both since closed as not planned, so whether it still reproduces is unconfirmed), which breaks `git status` in the main checkout. It only acts on a provably non-bare repository (its common git dir is named .git and contains an index), never on a genuine bare repo -- including a bare clone stored in a directory called .git -- and reports a failed repair on stdout rather than silently."
64
+ "adoptNotes": "ensure-worktree-deps.mjs runs `pnpm install --frozen-lockfile --prefer-offline` automatically the first time a session starts inside a freshly created worktree with no node_modules yet -- this runs every dependency's lifecycle scripts the same way any `pnpm install` does, limited only by whatever `allowBuilds`/`onlyBuiltDependencies` policy the project's own pnpm config already sets (see typescript-guidance's pnpm supply-chain coverage if none is set). If node_modules in the worktree is a symlink (the usual result of `worktree.symlinkDirectories: [\"node_modules\"]` in .claude/settings.json, which this hook never reads), the hook detects the symlink and skips -- installing there would mutate the main checkout's own node_modules through the symlink. guard-worktree-only.mjs is registered with `\"onFailure\": \"block\"` (Claude Code 2.1.295 or later; an older version ignores the key), so a hook that cannot start, times out, exits with a code other than 0 or 2 or prints invalid JSON blocks the write instead of letting it through. A project that installed this pack before it carried that key has the same registration without it: /customize adds the missing key when it installs the pack again, and otherwise add `\"onFailure\": \"block\"` to that registration in .claude/settings.json by hand. It blocks every src/tests write outside a linked worktree under .claude/worktrees/, on any branch, for any caller (hub or writer spoke) -- this is stricter than guard-branch-isolation.mjs (which only blocks on main) and guard-hub-src-writes.mjs (which blocks the hub and any non-writer subagent); confirm the team actually wants every change routed through a worktree before installing this pack, since it changes the day-to-day workflow, not just adds a nicety. `.claude/worktrees/` should already be gitignored (the baseline's own .gitignore covers this); if adopting into a project with a hand-rolled .gitignore that doesn't, add it before installing. repair-core-bare.mjs resets `core.bare = true` to `false` in a non-bare repo's shared .git/config at session start and after EnterWorktree/ExitWorktree/Agent calls: Claude Code's worktree tools have been reported to leave it set (anthropics/claude-code#58345, #69802: user bug reports, both since closed as not planned, so whether it still reproduces is unconfirmed), which breaks `git status` in the main checkout. It only acts on a provably non-bare repository (its common git dir is named .git and contains an index), never on a genuine bare repo -- including a bare clone stored in a directory called .git -- and reports a failed repair on stdout rather than silently."
64
65
  }