@codewizard-dt/bootstrap 3.1.0 → 4.0.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/bin/cli.js +0 -5
- package/lib/hooks/README.md +14 -5
- package/lib/hooks/lib/command-parse.js +28 -0
- package/lib/hooks/package-install-consent.js +60 -2
- package/lib/scripts/README.md +21 -12
- package/lib/scripts/bootstrap-prefs.js +20 -1
- package/lib/scripts/install-global.sh +14 -2
- package/lib/scripts/templates/bootstrap-prefs-schema.json +18 -0
- package/lib/skills/README.md +1 -0
- package/lib/skills/bootstrap-config/SKILL.md +1 -1
- package/lib/skills/bug-assess/SKILL.md +137 -0
- package/lib/skills/git-commit/SKILL.md +47 -13
- package/lib/skills/roadmap-assess/SKILL.md +51 -13
- package/package.json +2 -4
- package/.github/workflows/docker-harness.yml +0 -26
- package/.github/workflows/security.yml +0 -24
- package/.gitleaks.toml +0 -15
- package/lib/prompts/setup-deployment.md +0 -322
- package/lib/scripts/setup-deployment.sh +0 -113
- package/raw/guides/deployment-strategy.md +0 -448
package/bin/cli.js
CHANGED
|
@@ -10,8 +10,6 @@ const SCRIPTS = {
|
|
|
10
10
|
setup: { script: 'setup-project.sh', args: ['.'] },
|
|
11
11
|
update: { script: 'update-project.sh', args: ['.'] },
|
|
12
12
|
install: { script: 'install-global.sh', args: [] },
|
|
13
|
-
deploy: { script: 'setup-deployment.sh', args: ['.', ...extraArgs] },
|
|
14
|
-
deployment: { script: 'setup-deployment.sh', args: ['.', ...extraArgs] },
|
|
15
13
|
migrate: { script: 'migrate-project.sh', args: ['.', ...extraArgs] },
|
|
16
14
|
typechecks: { script: 'setup-strict-typechecks.sh', args: extraArgs },
|
|
17
15
|
dashboard: { script: 'wiki-dashboard-server.js', args: ['.', ...extraArgs] },
|
|
@@ -24,9 +22,6 @@ if (!command || !SCRIPTS[command]) {
|
|
|
24
22
|
console.error(' setup Set up a new project with Claude Code configurations');
|
|
25
23
|
console.error(' update Sync wiki scaffold and install skills globally');
|
|
26
24
|
console.error(' install Install skills globally into ~/.claude/skills/');
|
|
27
|
-
console.error(' deploy Scaffold CI/CD (.github/ workflows + .gitleaks.toml) into the project');
|
|
28
|
-
console.error(' Optional: pass extra context for the Claude agent as a quoted string');
|
|
29
|
-
console.error(' e.g. bootstrap deploy "backend is on port 8080, use s-2vcpu-4gb droplet"');
|
|
30
25
|
console.error(' migrate Migrate a legacy .docs/ project to the wiki structure (Claude-driven)');
|
|
31
26
|
console.error(' Pass --dry-run to preview; runs on a fresh wiki-migration branch');
|
|
32
27
|
console.error(' typechecks Run strict typecheck setup via Claude (optional: language list)');
|
package/lib/hooks/README.md
CHANGED
|
@@ -341,11 +341,20 @@ unaffected, while the same `npm install -g @playwright/mcp@latest` typed at the
|
|
|
341
341
|
prompt IS gated. Both are correct: consent was given once for the setup script as
|
|
342
342
|
a whole; an ad-hoc install carries no such consent.
|
|
343
343
|
|
|
344
|
-
**Known friction, real and expected
|
|
345
|
-
`lib/skills/frontend-taste/SKILL.md:29` instructs Claude to
|
|
346
|
-
`cd ~/code/house-style/preview && npm i && npm run dev`. That command *is*
|
|
347
|
-
hook-visible and
|
|
348
|
-
|
|
344
|
+
**Known friction, real and expected — no longer resolvable only by running the
|
|
345
|
+
command yourself.** `lib/skills/frontend-taste/SKILL.md:29` instructs Claude to
|
|
346
|
+
run `cd ~/code/house-style/preview && npm i && npm run dev`. That command *is*
|
|
347
|
+
hook-visible and gates by default, which remains the correct behaviour for a
|
|
348
|
+
project that has not opted in to anything — it is the one genuine friction
|
|
349
|
+
point this gate introduces in-repo, not a bug, and the deny message's escape
|
|
350
|
+
hatch is still to approve it by running it yourself. A project can now change
|
|
351
|
+
that default going forward: `packageInstall.consent` (TASK-075) is a
|
|
352
|
+
bootstrap-prefs key, scope `project`, read fresh on every match. `ask` hands the
|
|
353
|
+
call to Claude Code's native permission prompt instead of denying it (`node
|
|
354
|
+
~/.claude/bootstrap-prefs.js --set packageInstall.consent --value ask --project
|
|
355
|
+
.`); `true` allows the match outright (`--value true`). `false`/unset/any read
|
|
356
|
+
failure denies exactly as before — the gate still fails closed, it just now has
|
|
357
|
+
a documented, standing opt-out alongside the per-call rephrasing escape hatch.
|
|
349
358
|
|
|
350
359
|
**Not covered, deliberately:** bare `uvx <pkg>` with no `--from`; `npx`; and a
|
|
351
360
|
manager that is not the segment's first token, so `claude mcp add … -- uvx --from
|
|
@@ -63,9 +63,37 @@ function deny(reason) {
|
|
|
63
63
|
process.exit(0);
|
|
64
64
|
}
|
|
65
65
|
|
|
66
|
+
function allow(reason) {
|
|
67
|
+
console.log(JSON.stringify({
|
|
68
|
+
hookSpecificOutput: {
|
|
69
|
+
hookEventName: 'PreToolUse',
|
|
70
|
+
permissionDecision: 'allow',
|
|
71
|
+
permissionDecisionReason: String(reason),
|
|
72
|
+
},
|
|
73
|
+
}));
|
|
74
|
+
process.exit(0);
|
|
75
|
+
}
|
|
76
|
+
|
|
77
|
+
// `defer` hands the decision back to Claude Code's own native permission
|
|
78
|
+
// handling; the contract does not document permissionDecisionReason as
|
|
79
|
+
// meaningless there, so — same as `allow`/`deny` — we keep passing it
|
|
80
|
+
// through rather than risk silently dropping useful context.
|
|
81
|
+
function defer(reason) {
|
|
82
|
+
console.log(JSON.stringify({
|
|
83
|
+
hookSpecificOutput: {
|
|
84
|
+
hookEventName: 'PreToolUse',
|
|
85
|
+
permissionDecision: 'defer',
|
|
86
|
+
permissionDecisionReason: String(reason),
|
|
87
|
+
},
|
|
88
|
+
}));
|
|
89
|
+
process.exit(0);
|
|
90
|
+
}
|
|
91
|
+
|
|
66
92
|
module.exports = {
|
|
67
93
|
readHookInput,
|
|
68
94
|
splitSegments,
|
|
69
95
|
tokenize,
|
|
70
96
|
deny,
|
|
97
|
+
allow,
|
|
98
|
+
defer,
|
|
71
99
|
};
|
|
@@ -42,7 +42,10 @@
|
|
|
42
42
|
// coverage rather than failure: a manager or invocation form absent from the
|
|
43
43
|
// tables below is allowed, which is also why the scope note above holds.
|
|
44
44
|
|
|
45
|
-
const {
|
|
45
|
+
const { execFileSync } = require('child_process');
|
|
46
|
+
const os = require('os');
|
|
47
|
+
const path = require('path');
|
|
48
|
+
const { readHookInput, splitSegments, tokenize, deny, allow, defer } = require('./lib/command-parse');
|
|
46
49
|
|
|
47
50
|
// Manager basename → install subcommand phrases (space-separated so multi-token
|
|
48
51
|
// forms like `uv pip install` are expressible). `uvx` is absent here: its
|
|
@@ -133,12 +136,51 @@ function matchedInstall(tokens) {
|
|
|
133
136
|
return null;
|
|
134
137
|
}
|
|
135
138
|
|
|
139
|
+
// The installed location of bootstrap-prefs.js — this file runs from
|
|
140
|
+
// ~/.claude/hooks/ after install, not from a checkout of this repo, so it must
|
|
141
|
+
// resolve the helper the same way every other cross-reference to it does: a
|
|
142
|
+
// fixed, project-independent home under the user's HOME, not a path relative
|
|
143
|
+
// to __dirname. os.homedir() (not process.env.HOME) is what makes this follow
|
|
144
|
+
// a redirected HOME in tests, matching bootstrap-prefs.js's own convention.
|
|
145
|
+
const PREFS_SCRIPT = path.join(os.homedir(), '.claude', 'bootstrap-prefs.js');
|
|
146
|
+
|
|
147
|
+
// A plain fs read (bootstrap-prefs.js --get) is normally sub-millisecond.
|
|
148
|
+
// 2000ms mirrors interpreter-indirection-guard.js's SIBLING_TIMEOUT_MS for the
|
|
149
|
+
// same reason: generous enough that normal load never false-triggers it, short
|
|
150
|
+
// enough that a genuine hang does not stall the user's Bash call noticeably.
|
|
151
|
+
const PREFS_TIMEOUT_MS = 2000;
|
|
152
|
+
|
|
153
|
+
// Consults the packageInstall.consent preference for `cwd`. Returns the
|
|
154
|
+
// trimmed stdout ("true" | "ask" | "false" | "unset") on a clean run, or null
|
|
155
|
+
// on ANY trouble — missing helper, corrupt JSON, non-zero exit, a thrown
|
|
156
|
+
// error, or a timeout. null is handled identically to "false"/"unset" by the
|
|
157
|
+
// caller: this function never distinguishes "no" from "couldn't ask", because
|
|
158
|
+
// only an exact "true" or "ask" may loosen the default deny.
|
|
159
|
+
function packageInstallConsent(cwd) {
|
|
160
|
+
try {
|
|
161
|
+
const stdout = execFileSync(
|
|
162
|
+
process.execPath,
|
|
163
|
+
[PREFS_SCRIPT, '--get', 'packageInstall.consent', '--project', cwd],
|
|
164
|
+
{ encoding: 'utf8', timeout: PREFS_TIMEOUT_MS }
|
|
165
|
+
);
|
|
166
|
+
return stdout.trim();
|
|
167
|
+
} catch (err) {
|
|
168
|
+
return null;
|
|
169
|
+
}
|
|
170
|
+
}
|
|
171
|
+
|
|
136
172
|
readHookInput(data => {
|
|
137
173
|
if (data.tool_name !== 'Bash') return;
|
|
138
174
|
|
|
139
175
|
const fullCmd = String(data.tool_input?.command ?? '').trim();
|
|
140
176
|
if (!fullCmd) return;
|
|
141
177
|
|
|
178
|
+
// Mirrors protected-write-guard.js:189 / claude-settings-guard.js:192: `cwd`
|
|
179
|
+
// is a top-level field on the hook payload (the session's directory), not
|
|
180
|
+
// `data.tool_input.cwd` — Bash tool calls carry no such field — and it can
|
|
181
|
+
// differ from this process's own process.cwd().
|
|
182
|
+
const cwd = typeof data.cwd === 'string' && data.cwd ? data.cwd : process.cwd();
|
|
183
|
+
|
|
142
184
|
for (const segment of splitSegments(fullCmd)) {
|
|
143
185
|
const tokens = stripInvocationPrefix(tokenize(segment));
|
|
144
186
|
if (!tokens.length) continue;
|
|
@@ -148,6 +190,20 @@ readHookInput(data => {
|
|
|
148
190
|
const install = matchedInstall(tokens);
|
|
149
191
|
if (!install) continue;
|
|
150
192
|
|
|
193
|
+
const consent = packageInstallConsent(cwd);
|
|
194
|
+
if (consent === 'true') {
|
|
195
|
+
allow(
|
|
196
|
+
`Package install allowed (\`${install}\`) — this project's stored preference is ` +
|
|
197
|
+
`\`packageInstall.consent = true\`.`
|
|
198
|
+
);
|
|
199
|
+
}
|
|
200
|
+
if (consent === 'ask') {
|
|
201
|
+
defer(
|
|
202
|
+
`Package install (\`${install}\`) needs consent — this project's stored preference is ` +
|
|
203
|
+
`\`packageInstall.consent = ask\`, deferring to Claude Code's native permission prompt.`
|
|
204
|
+
);
|
|
205
|
+
}
|
|
206
|
+
|
|
151
207
|
// The segment is echoed verbatim, not rebuilt from tokens: the entire value
|
|
152
208
|
// of this gate over a deny rule is that the user can copy the exact string
|
|
153
209
|
// back out and run it. Re-joining tokens would silently drop quoting.
|
|
@@ -156,7 +212,9 @@ readHookInput(data => {
|
|
|
156
212
|
`without an explicit human decision. To approve, run it yourself:\n\n` +
|
|
157
213
|
` ${segment}\n\n` +
|
|
158
214
|
`If the dependency is not actually needed, say so and it will be dropped rather ` +
|
|
159
|
-
`than worked around
|
|
215
|
+
`than worked around. Or stop this gate from asking for this project's future installs: ` +
|
|
216
|
+
`\`node ~/.claude/bootstrap-prefs.js --set packageInstall.consent --value ask --project .\` ` +
|
|
217
|
+
`(or \`--value true\` to skip the prompt entirely).`
|
|
160
218
|
);
|
|
161
219
|
}
|
|
162
220
|
});
|
package/lib/scripts/README.md
CHANGED
|
@@ -10,7 +10,7 @@ All scripts use `set -euo pipefail`. Every script that touches a target project
|
|
|
10
10
|
|--------|---------------------|---------------|
|
|
11
11
|
| `setup-project.sh` | `setup` | Preflight-checks `claude` and `uv` are installed, then runs the full new-project sequence: global hooks/skills/settings install first (offline-safe, via `install-global.sh --skip-mcps` — includes the deny-list and hooks-wiring merges), then the interactive MCP install (guarded — a failure warns and continues), wiki scaffold + tiered guides sync (optional guides prompted), `.gitignore` merge, and Serena `project.yml` bootstrap. Does **not** scaffold deployment — that's explicit via `deploy`. |
|
|
12
12
|
| `update-project.sh` | `update` | Re-runs the same shared sequence as `setup` (global hooks/skills/settings via `install-global.sh --skip-mcps`, then the guarded interactive MCP install) and re-syncs the wiki scaffold + tiered `wiki/guides/` into an existing project. Detects legacy `.docs/`-layout families (`tasks`, `uat`, `adr`, `prd`, `bugs`, `roadmaps`) and warns without touching them — migration is a separate, explicit step (`migrate`). Never touches `.github/`. |
|
|
13
|
-
| `install-global.sh` | `install` | Installs/updates hooks, skills, settings, and MCPs globally with **no project path** — the shared step both `setup` and `update` delegate to. Local/offline-safe steps run first: hooks rsync to `~/.claude/hooks/` (stderr warning if `lib/hooks` is missing), skills install (pruning stale skill folders from the wiki rename — `adr-*` → `decision-*`, `prd-*` → `req-*`), the canonical permission deny-list merge into `~/.claude/settings.json` via `merge-settings-deny.js`, then the hooks-wiring merge via `merge-settings-hooks.js` — registering the copied hook scripts in the settings `hooks` key, with a restart-your-session reminder when the wiring was created or changed. Then copies `templates/file-suggestion.sh` → `~/.claude/file-suggestion.sh` and registers it as the `fileSuggestion` `@`-autocomplete picker (`merge-settings-deny.js --set-key` mode) — printing a restart note on fresh registration, or leaving a pre-existing different `fileSuggestion` untouched. Then step 6 installs the preference helper — `bootstrap-prefs.js` → `~/.claude/bootstrap-prefs.js` and `templates/bootstrap-prefs-schema.json` → `~/.claude/templates/bootstrap-prefs-schema.json`, the layout that lets a skill read a preference with no `--schema` flag (see [Preference helper notes](#preference-helper-notes)); a missing helper or schema warns and continues. Step 7 then settles the
|
|
13
|
+
| `install-global.sh` | `install` | Installs/updates hooks, skills, settings, and MCPs globally with **no project path** — the shared step both `setup` and `update` delegate to. Local/offline-safe steps run first: hooks rsync to `~/.claude/hooks/` (stderr warning if `lib/hooks` is missing), skills install (pruning stale skill folders from the wiki rename — `adr-*` → `decision-*`, `prd-*` → `req-*`), the canonical permission deny-list merge into `~/.claude/settings.json` via `merge-settings-deny.js`, then the hooks-wiring merge via `merge-settings-hooks.js` — registering the copied hook scripts in the settings `hooks` key, with a restart-your-session reminder when the wiring was created or changed. Then copies `templates/file-suggestion.sh` → `~/.claude/file-suggestion.sh` and registers it as the `fileSuggestion` `@`-autocomplete picker (`merge-settings-deny.js --set-key` mode) — printing a restart note on fresh registration, or leaving a pre-existing different `fileSuggestion` untouched. Then step 6 installs the preference helper — `bootstrap-prefs.js` → `~/.claude/bootstrap-prefs.js` and `templates/bootstrap-prefs-schema.json` → `~/.claude/templates/bootstrap-prefs-schema.json`, the layout that lets a skill read a preference with no `--schema` flag (see [Preference helper notes](#preference-helper-notes)); a missing helper or schema warns and continues. Step 7 then settles the seven `consumer: skill` preferences that have never been answered — asked once, in a batch, at global scope, gated on a tty as a whole, so a non-interactive run prints one note and writes no answers and no preferences file. MCPs install **last** (step 8) — the only network-dependent step, guarded so a failure warns instead of aborting the local installs — and `--skip-mcps` skips them when the caller already handled MCP install interactively. |
|
|
14
14
|
| `setup-deployment.sh` | `deploy` / `deployment` | Reads `raw/guides/deployment-strategy.md` as a prompt template, copies it into the target's `wiki/guides/` (deploy-only guide tier — the wiki sync never ships it), and runs `claude` to scaffold `.github/workflows/`, `Makefile` Docker targets, and `.gitleaks.toml` into the target project. Deliberately **not** called by `setup`/`update` — CI files get hand-customized per project (Dockerfile paths, runner labels, deploy steps) and must never be created or clobbered implicitly. `security.yml` is always overwritten (generic); `build.yml`/`.gitleaks.toml` are copy-once; `Makefile` targets are merged. |
|
|
15
15
|
| `migrate-project.sh` | `migrate` | Claude-driven migration of a legacy `.docs/`-layout project to the LLM Wiki structure (`wiki/knowledge/` + `wiki/work/`). Preflight requires a clean git tree; runs on a fresh `wiki-migration` branch so the whole migration is one reviewable diff. Scaffolds first via `sync-wiki-scaffold.sh --interactive`, assembles `wiki/guides/mcp-tools.md` via `build-mcp-guide.sh`, then drives the semantic conversion (frontmatter synthesis, ID renames, link rewrites, family indexes) with the prompt at `lib/prompts/migrate-wiki.md`. `git mv` before edit, so history is preserved. `--dry-run` prints the file inventory only and does not touch anything. |
|
|
16
16
|
| `setup-strict-typechecks.sh` | `typechecks` | Loads `lib/prompts/setup-strict-typechecks.md`, appends an optional language list (space- or comma-separated), and runs `claude` to detect languages, research current strict-mode conventions, install toolchains, and wire `make typecheck`. |
|
|
@@ -39,7 +39,6 @@ These are **not** referenced by `bin/cli.js` or by any other script — they're
|
|
|
39
39
|
|--------|---------|
|
|
40
40
|
| `setup-runner.sh` | Generalized GitHub Actions self-hosted runner installer. Run as root on a target droplet: `RUNNER_TOKEN=<token> REPO_URL=<url> bash setup-runner.sh`. Registers the runner, installs it as a service, and configures GHCR login. |
|
|
41
41
|
| `startup.sh` | One-shot droplet bootstrap: updates apt, installs zsh/curl/make, and installs Docker + the Compose plugin from Docker's official apt repo. Typically run once before `setup-runner.sh` on a fresh VM. |
|
|
42
|
-
| [`test/docker/fresh-machine/`](../../test/docker/fresh-machine/README.md) | Docker-based harness that emulates running `setup`/`update` on a completely fresh machine with no prior Claude Code infrastructure. `./run.sh [shell\|setup\|update]`. |
|
|
43
42
|
|
|
44
43
|
## `templates/`
|
|
45
44
|
|
|
@@ -345,13 +344,19 @@ after an older version touches it, and the user can see what was kept.
|
|
|
345
344
|
|
|
346
345
|
### Why every `consumer: skill` key says `install-global.sh`
|
|
347
346
|
|
|
348
|
-
|
|
349
|
-
including `gitCommit.versionBump` and `gitCommit.autoPush` — which
|
|
350
|
-
`/git-commit` until this was settled. The field records the **settling**
|
|
351
|
-
the one site that writes the answer. For
|
|
347
|
+
Seven of the eight `consumer: skill` keys name `install-global.sh` as their
|
|
348
|
+
`askedBy`, including `gitCommit.versionBump` and `gitCommit.autoPush` — which
|
|
349
|
+
named `/git-commit` until this was settled. The field records the **settling**
|
|
350
|
+
prompt: the one site that writes the answer. For those seven keys that site is
|
|
352
351
|
`install-global.sh`'s step 7 sync pass, which asks each unanswered key once, in a
|
|
353
352
|
batch, at global scope.
|
|
354
353
|
|
|
354
|
+
`packageInstall.consent` is the one exception, naming `/bootstrap-config`
|
|
355
|
+
instead. There is no scripted installer moment that could settle it the same
|
|
356
|
+
way: a brand-new project has no `.claude/bootstrap-prefs.json` yet the first
|
|
357
|
+
time someone hits the block, so the only way to answer it is manually, after
|
|
358
|
+
the fact, via `/bootstrap-config`.
|
|
359
|
+
|
|
355
360
|
`/git-commit` does still prompt — but only once the key is already settled *to a
|
|
356
361
|
value that means "keep asking"* (`confirm` for `versionBump`, `ask` for
|
|
357
362
|
`autoPush`). That is a consumer honouring a stored answer, not the question being
|
|
@@ -369,7 +374,7 @@ real `lib/scripts/` file or one real `lib/skills/<name>/SKILL.md`, so
|
|
|
369
374
|
`"install-global.sh, /git-commit"` fails the suite by construction. Where a
|
|
370
375
|
run-time prompt exists, it is documented in the key's `detail`.
|
|
371
376
|
|
|
372
|
-
### The key registry — all
|
|
377
|
+
### The key registry — all 25 entries
|
|
373
378
|
|
|
374
379
|
Every key in `templates/bootstrap-prefs-schema.json`, grouped by `consumer` —
|
|
375
380
|
`installer` first, then `skill` — which is the same grouping and the same order
|
|
@@ -408,21 +413,25 @@ Unicode-aware slug rule for `gitignore.section.*` are in
|
|
|
408
413
|
above; `gitignore.section.*`'s deliberate one-value grammar is in
|
|
409
414
|
[the section after it](#gitignoresection-has-a-one-value-grammar-on-purpose).
|
|
410
415
|
|
|
411
|
-
#### `consumer: skill` —
|
|
416
|
+
#### `consumer: skill` — 8 entries, read by slash commands at run time
|
|
412
417
|
|
|
413
418
|
| Key | Scope | Consumer | Values | Default | Asked by | What it does |
|
|
414
419
|
|-----|-------|----------|--------|---------|----------|--------------|
|
|
415
420
|
| `gitCommit.versionBump` | either | skill | `auto \| confirm \| never` | `auto` | `install-global.sh` | How `/git-commit` handles the version bump before committing |
|
|
416
421
|
| `gitCommit.autoPush` | either | skill | `true \| false \| ask` | `false` | `install-global.sh` | Whether `/git-commit` pushes after a successful commit |
|
|
422
|
+
| `gitCommit.lint` | either | skill | `true \| false` | `false` | `install-global.sh` | Whether `/git-commit` runs the /lint fix-cycle before committing |
|
|
423
|
+
| `packageInstall.consent` | project | skill | `true \| false \| ask` | `false` | `/bootstrap-config` | Whether `package-install-consent.js` allows package-manager installs for this project |
|
|
417
424
|
| `research.persistToRaw` | either | skill | `true \| false \| ask` | `true` | `install-global.sh` | Whether `/research` writes its report and sources to `raw/research/` |
|
|
418
425
|
| `research.autoIngest` | either | skill | `true \| false \| ask` | `false` | `install-global.sh` | Whether `/research` automatically wiki-ingests its saved report |
|
|
419
426
|
| `uatGenerate.promoteTests` | either | skill | `sibling \| never \| dedicated` | `dedicated` | `install-global.sh` | Where `/uat-generate` writes the unit tests it promotes out of UAT cases |
|
|
420
427
|
| `gitignore.offerSectionUpdates` | either | skill | `true \| false \| ask` | `true` | `install-global.sh` | Master gate for the `.gitignore` template section review pass |
|
|
421
428
|
|
|
422
|
-
|
|
423
|
-
|
|
424
|
-
|
|
425
|
-
|
|
429
|
+
Seven of these eight are the entire `scope: either` population — a key that
|
|
430
|
+
changes what a slash command does is exactly the kind of key a user may want to
|
|
431
|
+
answer once machine-wide and then override in one checkout. `packageInstall.consent`
|
|
432
|
+
is the exception: `scope: project` on purpose, because a package-install
|
|
433
|
+
trust decision is inherently per-project, not something to settle once for
|
|
434
|
+
every checkout on the machine.
|
|
426
435
|
|
|
427
436
|
**Every `installer` key has `default: null`; every `skill` key carries a real
|
|
428
437
|
default.** That asymmetry has a consequence worth stating: `prefs_get` alone
|
|
@@ -7,6 +7,11 @@
|
|
|
7
7
|
// global ~/.claude/bootstrap-prefs.json
|
|
8
8
|
// project <project>/.claude/bootstrap-prefs.json
|
|
9
9
|
//
|
|
10
|
+
// --project <dir> resolves to <dir>'s git repo root (walking up for `.git`),
|
|
11
|
+
// not <dir> itself — a caller running from a subdirectory still hits the
|
|
12
|
+
// one project-scoped file (see findProjectRoot). Non-git dirs fall back to
|
|
13
|
+
// the literal path unchanged.
|
|
14
|
+
//
|
|
10
15
|
// Four states per key: `unset` / a settled value / `false` / `ask`.
|
|
11
16
|
// ABSENCE IS `unset`. `null` is never written and "unset" is never stored as a
|
|
12
17
|
// string — deleting a key is how you re-open a question.
|
|
@@ -143,7 +148,7 @@ function parseArgs(argv) {
|
|
|
143
148
|
} else if (arg === '--global') {
|
|
144
149
|
opts.global = true;
|
|
145
150
|
} else if (arg === '--project') {
|
|
146
|
-
opts.projectDir = argv[++i];
|
|
151
|
+
opts.projectDir = findProjectRoot(argv[++i]);
|
|
147
152
|
} else if (arg === '--target') {
|
|
148
153
|
opts.target = argv[++i];
|
|
149
154
|
} else if (arg === '--schema') {
|
|
@@ -187,6 +192,20 @@ function projectFile(dir) {
|
|
|
187
192
|
return path.join(dir, '.claude', 'bootstrap-prefs.json');
|
|
188
193
|
}
|
|
189
194
|
|
|
195
|
+
// Resolves to the repo root, not the caller's cwd — a Bash command run from
|
|
196
|
+
// a subdirectory would otherwise miss the project's real prefs file. `.git`
|
|
197
|
+
// may be a file (worktrees) or a directory; falls back to the literal path
|
|
198
|
+
// (absolute) when none is found, leaving non-git test scratch dirs unaffected.
|
|
199
|
+
function findProjectRoot(dir) {
|
|
200
|
+
let current = path.resolve(dir);
|
|
201
|
+
while (true) {
|
|
202
|
+
if (fs.existsSync(path.join(current, '.git'))) return current;
|
|
203
|
+
const parent = path.dirname(current);
|
|
204
|
+
if (parent === current) return path.resolve(dir);
|
|
205
|
+
current = parent;
|
|
206
|
+
}
|
|
207
|
+
}
|
|
208
|
+
|
|
190
209
|
// ---------------------------------------------------------------- schema ----
|
|
191
210
|
|
|
192
211
|
// A missing or malformed schema is a warning, not a crash, and not a stop: the
|
|
@@ -173,7 +173,7 @@ echo ""
|
|
|
173
173
|
# mechanism exists to remove.
|
|
174
174
|
#
|
|
175
175
|
# GLOBAL SCOPE. install-global.sh takes no project path, so it cannot know
|
|
176
|
-
# which checkout the user means. All
|
|
176
|
+
# which checkout the user means. All seven keys are `scope: either`, so the
|
|
177
177
|
# answer recorded here is the machine-wide default and a project file can
|
|
178
178
|
# still override it per checkout later.
|
|
179
179
|
#
|
|
@@ -183,7 +183,7 @@ echo ""
|
|
|
183
183
|
# One CI run must never bake a permanent answer into a user's store.
|
|
184
184
|
PREFS_ASKED=0
|
|
185
185
|
|
|
186
|
-
# <key> <question> — the yes/no/ask shape shared by four of the
|
|
186
|
+
# <key> <question> — the yes/no/ask shape shared by four of the seven keys.
|
|
187
187
|
# `skip` is the resolved value for a bare Enter or EOF and records nothing, so
|
|
188
188
|
# an accidental keystroke leaves the question open instead of settling it.
|
|
189
189
|
settle_skill_pref() {
|
|
@@ -232,6 +232,18 @@ else
|
|
|
232
232
|
|
|
233
233
|
settle_skill_pref gitCommit.autoPush \
|
|
234
234
|
"Should /git-commit push the current branch after committing? (Default no — this turns a local action into a published one. It never creates a branch either way.)"
|
|
235
|
+
# gitCommit.lint's grammar is true|false only (no `ask`), so it can't use settle_skill_pref's generic yes/no/ask/skip shape.
|
|
236
|
+
if ! prefs_stored_global gitCommit.lint; then
|
|
237
|
+
echo ""
|
|
238
|
+
echo " Should /git-commit run the /lint fix-cycle before committing? (Default no — linting is opt-in, so a fresh install never lints without you saying yes.)"
|
|
239
|
+
LINT_ANSWER="$(prompt_letter_choice skip " [y]es / [n]o / [s]kip for now: " yes no skip)"
|
|
240
|
+
case "$LINT_ANSWER" in
|
|
241
|
+
yes) prefs_set gitCommit.lint --global true ; echo " gitCommit.lint = true" ;;
|
|
242
|
+
no) prefs_set gitCommit.lint --global false ; echo " gitCommit.lint = false" ;;
|
|
243
|
+
*) echo " gitCommit.lint left unanswered — today's behavior (no lint) is unchanged, and you will be asked again next sync." ;;
|
|
244
|
+
esac
|
|
245
|
+
PREFS_ASKED=$(( PREFS_ASKED + 1 ))
|
|
246
|
+
fi
|
|
235
247
|
settle_skill_pref research.persistToRaw \
|
|
236
248
|
"Should /research save its report and sources to raw/research/ by default? (Findings always appear in the reply; this governs the file write only, and you can still decline any single report.)"
|
|
237
249
|
settle_skill_pref research.autoIngest \
|
|
@@ -172,6 +172,24 @@
|
|
|
172
172
|
"default": false,
|
|
173
173
|
"askedBy": "install-global.sh"
|
|
174
174
|
},
|
|
175
|
+
"gitCommit.lint": {
|
|
176
|
+
"scope": "either",
|
|
177
|
+
"consumer": "skill",
|
|
178
|
+
"summary": "Whether /git-commit runs the /lint fix-cycle before committing",
|
|
179
|
+
"detail": "true runs the full /lint workflow (all cycles until clean or issues are skipped) before assessing changes; false (and unset) skip it entirely — this is an opt-in, not an opt-out, so a fresh install never lints without the user having said yes. There is deliberately no 'ask' value: /git-commit never prompts about this per run, it only reads the stored answer.",
|
|
180
|
+
"values": "true | false",
|
|
181
|
+
"default": false,
|
|
182
|
+
"askedBy": "install-global.sh"
|
|
183
|
+
},
|
|
184
|
+
"packageInstall.consent": {
|
|
185
|
+
"scope": "project",
|
|
186
|
+
"consumer": "skill",
|
|
187
|
+
"summary": "Whether package-install-consent.js allows package-manager installs for this project",
|
|
188
|
+
"detail": "package-install-consent.js is a PreToolUse hook that today denies every package-manager install command (npm install, pip install, uvx --from, etc.) unconditionally. false (and unset, the default) keeps denying exactly as today — no behavior change for a project that has not opted in. 'ask' makes the hook emit permissionDecision: \"defer\", handing the decision back to Claude Code's own native permission prompt instead of denying outright — this is safe even under headless/bypass runs because Claude Code's own permission system is the one deciding, not this hook blocking. true makes the hook emit permissionDecision: \"allow\" outright, skipping any prompt at all.",
|
|
189
|
+
"values": "true | false | ask",
|
|
190
|
+
"default": false,
|
|
191
|
+
"askedBy": "/bootstrap-config"
|
|
192
|
+
},
|
|
175
193
|
"research.persistToRaw": {
|
|
176
194
|
"scope": "either",
|
|
177
195
|
"consumer": "skill",
|
package/lib/skills/README.md
CHANGED
|
@@ -67,6 +67,7 @@ Most skills operate on the LLM Wiki (`wiki/`, `raw/`) described in the root `CLA
|
|
|
67
67
|
| Skill | Purpose |
|
|
68
68
|
|-------|---------|
|
|
69
69
|
| `bug-file` | File a new bug report with required-on-report fields; append it to the bug index |
|
|
70
|
+
| `bug-assess` | Survey all active bugs together — batch-triage any still-open reports first, then rank the active set by priority, severity, and impact into a single prioritized fix order with a status update for each bug |
|
|
70
71
|
| `bug-triage` | Set priority/assignee/tags/impact, then advance to `in-progress`, keep `triaged`, or reject (wontfix/duplicate/cannot-reproduce) and archive |
|
|
71
72
|
| `bug-close` | Close an in-progress bug — record root cause and resolution, require a regression test, move to `archive/` |
|
|
72
73
|
|
|
@@ -112,7 +112,7 @@ Skip this question entirely when a mode word was supplied as an argument — but
|
|
|
112
112
|
5. When the chosen key has `consumer: skill`, print this heavier banner:
|
|
113
113
|
> This is a **skill preference**. Changing it changes what a slash command actually does the next time it runs — not merely whether the installer asks you a question.
|
|
114
114
|
|
|
115
|
-
Name the affected command from the entry's `askedBy` / `summary` — e.g. `gitCommit.versionBump` changes what `/git-commit` does on every commit. The `consumer: skill` population is `gitCommit.versionBump`, `gitCommit.autoPush`, `research.persistToRaw`, `research.autoIngest`, `uatGenerate.promoteTests`, and `gitignore.offerSectionUpdates`. Every other key is `consumer: installer` and gets the lighter framing: it only affects whether a setup/update script prompts you.
|
|
115
|
+
Name the affected command from the entry's `askedBy` / `summary` — e.g. `gitCommit.versionBump` changes what `/git-commit` does on every commit. The `consumer: skill` population is `gitCommit.versionBump`, `gitCommit.autoPush`, `gitCommit.lint`, `packageInstall.consent`, `research.persistToRaw`, `research.autoIngest`, `uatGenerate.promoteTests`, and `gitignore.offerSectionUpdates`. Every other key is `consumer: installer` and gets the lighter framing: it only affects whether a setup/update script prompts you.
|
|
116
116
|
|
|
117
117
|
## Step E — Choose the value and the layer (edit mode)
|
|
118
118
|
|
|
@@ -0,0 +1,137 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: bug-assess
|
|
3
|
+
description: Survey all active bugs together — batch-triage any still-open reports first, then rank the full active set by priority, severity, impact, and blocking relationships into a single prioritized fix order with a status update for each bug
|
|
4
|
+
category: researching
|
|
5
|
+
model: claude-sonnet-5
|
|
6
|
+
disable-model-invocation: false
|
|
7
|
+
user-invocable: true
|
|
8
|
+
---
|
|
9
|
+
**Prereqs:** obey `wiki/guides/mcp-tools.md`; run /primer if not done this session.
|
|
10
|
+
|
|
11
|
+
# Bug Assessment
|
|
12
|
+
|
|
13
|
+
Assess every active bug in `wiki/work/bugs/` together — this is the multi-bug counterpart to `/bug-triage`, which operates on exactly one bug you've already picked. Use this skill when several bugs are active and you need to decide which to fix next, based on priority, severity, impact, and the blocking relationships between them.
|
|
14
|
+
|
|
15
|
+
This skill is read-mostly with one deliberate exception: if any bug is still `status: open`, it runs a batch-triage pass first (with user confirmation per bug) so the ranking rests on real priorities rather than blanks. Deeper triage outcomes — starting work, rejecting — remain `/bug-triage`'s job.
|
|
16
|
+
|
|
17
|
+
---
|
|
18
|
+
|
|
19
|
+
## Step 1: Discover active bugs
|
|
20
|
+
|
|
21
|
+
`list_dir` `wiki/work/bugs/` for `BUG-*.md` files **directly** in it (not `archive/`); skip `lifecycle.md`, `index.md`. None found → STOP: `No bugs found in wiki/work/bugs/. Use /bug-file <description> to file one.`
|
|
22
|
+
|
|
23
|
+
A single active bug is still worth assessing — the status update in Step 6d is useful on its own.
|
|
24
|
+
|
|
25
|
+
## Step 2: Parse every bug
|
|
26
|
+
|
|
27
|
+
For each file, `Read` it in full and extract:
|
|
28
|
+
|
|
29
|
+
- **Frontmatter**: `id`, `title`, `status`, `severity`, `priority`, `assignee`, `tags`, `created`, `updated`.
|
|
30
|
+
- **Body signals**: `## Impact` (who is affected, what it blocks), `## Related` (duplicate-of, related bugs, blocking references), reproducibility, workaround.
|
|
31
|
+
- **Typed links**: inline `rel::[[BUG-NNNN]]`, `blocks::[[BUG-NNNN]]`, `depends_on::[[BUG-NNNN]]` anywhere in the body — a bug can gate another without a `## Related` entry. Merge these into the same per-bug reference set.
|
|
32
|
+
|
|
33
|
+
Cross-check each bug against `wiki/work/bugs/index.md`: note any bug whose index row is missing or whose status/priority text is stale. Report the drift in Step 6e — fix a row only if the Step 3 triage pass touches that bug anyway.
|
|
34
|
+
|
|
35
|
+
## Step 3: Batch-triage pass
|
|
36
|
+
|
|
37
|
+
**Run only if at least one bug is `status: open`.** Otherwise skip to Step 4.
|
|
38
|
+
|
|
39
|
+
For each open bug, derive a proposal from its body: a priority (`P0`–`P3`), a confirmed-or-revised severity, and suggested tags. Then confirm with the user via `AskUserQuestion` — batch up to 4 bugs per call, one question per bug, with your proposal as the recommended first option. Always include a **"needs full triage"** option: picking it leaves the bug `open`, untouched, and listed in Step 6b with `Next: /bug-triage BUG-NNNN`.
|
|
40
|
+
|
|
41
|
+
For each confirmed bug, apply the updates per the Step 6/7 procedure in `lib/skills/bug-triage/SKILL.md` — do not restate its edit mechanics, follow them as written: `Edit` the bug file (flip `status: open` → `triaged`, set `priority:` / `tags:`, confirm `severity:`, bump `updated:` to today) and update its `wiki/work/bugs/index.md` row's status/priority text.
|
|
42
|
+
|
|
43
|
+
Outcomes this pass does **not** handle: starting work (`in-progress`) and rejection (`wontfix` / `duplicate` / `cannot-reproduce`). Those require the impact/workaround/resolution rigor of `/bug-triage` — never shortcut them here.
|
|
44
|
+
|
|
45
|
+
Append **one** combined entry to `wiki/log.md` for the whole pass, not one per bug:
|
|
46
|
+
|
|
47
|
+
```
|
|
48
|
+
## [YYYY-MM-DD] bug-assess | batch triage
|
|
49
|
+
Triaged BUG-NNNN, BUG-MMM, … open → triaged with confirmed priorities. <one sentence>
|
|
50
|
+
```
|
|
51
|
+
|
|
52
|
+
## Step 4: Blocking analysis
|
|
53
|
+
|
|
54
|
+
From each bug's merged reference set (Step 2), build directed edges `blocking_bug → blocked_bug` — the bug named in a `depends_on::` / "blocked by" reference blocks the bug holding the reference; a `blocks::` reference points the other way.
|
|
55
|
+
|
|
56
|
+
A **duplicate-of** reference on an active bug is a red flag, not an edge: duplicates should have been rejected and archived at triage. Surface it in Step 6e — don't fix it here.
|
|
57
|
+
|
|
58
|
+
Deduplicate edges. Walk the graph via DFS to detect cycles — if found, flag them in Step 6e rather than silently picking a winner.
|
|
59
|
+
|
|
60
|
+
## Step 5: Rank bugs
|
|
61
|
+
|
|
62
|
+
Order all active bugs, highest priority first, using this precedence:
|
|
63
|
+
|
|
64
|
+
1. **Hard blocking order** (from Step 4) — a bug that blocks others always outranks the bugs it blocks. Never violate this to satisfy the signals below.
|
|
65
|
+
2. **Priority** — `P0` first, descending to `P3`. A bug with no priority (`—`) ranks after `P3` with a note — it shouldn't exist after Step 3 unless the user declined triage.
|
|
66
|
+
3. **Severity** — `critical` → `high` → `medium` → `low`.
|
|
67
|
+
4. **Impact** — a judgment call from `## Impact`, reproducibility, and workaround (no workaround outranks an easy one). Record a one-sentence rationale per bug in the report — this is a judgment call the user can override, not a fact.
|
|
68
|
+
5. **Tie-break only** — `in-progress` ranks above `triaged` (finishing in-flight fixes compounds value faster than starting new ones); then `BUG-NNNN` ascending.
|
|
69
|
+
|
|
70
|
+
Bugs left `open` (declined batch triage) are still ranked on the signals available, but marked **not actionable until triaged** — `/bug-triage` is their next step, not a fix.
|
|
71
|
+
|
|
72
|
+
## Step 6: Report
|
|
73
|
+
|
|
74
|
+
Print, in this order:
|
|
75
|
+
|
|
76
|
+
### 6a. Triaged this run (omit if none)
|
|
77
|
+
|
|
78
|
+
```
|
|
79
|
+
Batch-triaged (open → triaged):
|
|
80
|
+
• BUG-NNNN — <title> — P<N>, <severity>
|
|
81
|
+
```
|
|
82
|
+
|
|
83
|
+
### 6b. Untriaged (omit if none)
|
|
84
|
+
|
|
85
|
+
```
|
|
86
|
+
## Warning: Untriaged Bugs
|
|
87
|
+
|
|
88
|
+
These bugs are still `open` — not actionable until triaged:
|
|
89
|
+
|
|
90
|
+
| Bug | Severity | Next |
|
|
91
|
+
|-----|----------|------|
|
|
92
|
+
| BUG-NNNN — <title> | <severity> | `/bug-triage BUG-NNNN` |
|
|
93
|
+
```
|
|
94
|
+
|
|
95
|
+
### 6c. Prioritized Bugs
|
|
96
|
+
|
|
97
|
+
```
|
|
98
|
+
## Prioritized Bugs
|
|
99
|
+
|
|
100
|
+
| Rank | Bug | Priority | Severity | Status | Rationale | Blocks / Blocked by |
|
|
101
|
+
|------|-----|----------|----------|--------|-----------|---------------------|
|
|
102
|
+
| 1 | BUG-NNNN — <title> | P1 | high | triaged | <one sentence> | blocks BUG-MMM |
|
|
103
|
+
| 2 | BUG-MMM — <title> | P1 | medium | in-progress | <one sentence> | blocked by BUG-NNNN |
|
|
104
|
+
```
|
|
105
|
+
|
|
106
|
+
`Blocks / Blocked by` lists the hard edges from Step 4, or `—` if none.
|
|
107
|
+
|
|
108
|
+
### 6d. Status update per bug
|
|
109
|
+
|
|
110
|
+
One block per bug, in ranked order:
|
|
111
|
+
|
|
112
|
+
```
|
|
113
|
+
### BUG-NNNN — <title>
|
|
114
|
+
- Assignee: <assignee, or "unassigned">
|
|
115
|
+
- Status: <open | triaged | in-progress>
|
|
116
|
+
- Impact: <one line>
|
|
117
|
+
- Next: <see below>
|
|
118
|
+
```
|
|
119
|
+
|
|
120
|
+
`Next` by status:
|
|
121
|
+
|
|
122
|
+
- `open` → `/bug-triage BUG-NNNN`
|
|
123
|
+
- `triaged` → `/bug-triage BUG-NNNN` to start work, or suggest `/task-add` for a fix task
|
|
124
|
+
- `in-progress` → continue the fix; `/bug-close BUG-NNNN` when the fix commit and regression test land
|
|
125
|
+
|
|
126
|
+
### 6e. Warnings (omit if none found)
|
|
127
|
+
|
|
128
|
+
Flag, each as its own short block: dependency cycles (`BUG-NNNN → BUG-MMM → BUG-NNNN — these block each other; resolve manually`), active bugs carrying a duplicate-of reference (should have been rejected at triage — `/bug-triage BUG-NNNN`), and index drift from Step 2 (missing or stale rows in `wiki/work/bugs/index.md`).
|
|
129
|
+
|
|
130
|
+
---
|
|
131
|
+
|
|
132
|
+
## Constraints
|
|
133
|
+
|
|
134
|
+
- Read-only except the Step 3 batch-triage edits (status flip to `triaged`, triage fields, index row text, one combined log entry) — never flip to `in-progress` or a terminal status, never archive, never create task files. That is `/bug-triage`, `/bug-close`, and `/task-add`'s job once the user acts on this report.
|
|
135
|
+
- Permitted tools: `list_dir`, `find_file`, `Read`, `Edit`, `AskUserQuestion` (Step 3 confirmations only — otherwise this skill should run to completion without prompting).
|
|
136
|
+
- Never bash reads (`cat`/`find`/`grep`/`sed`/`ls`).
|
|
137
|
+
- Keep the report terse — no preamble, no closing summary beyond the tables above.
|