plumbbob 0.3.0 → 0.3.1

package/README.md

@@ -77,6 +77,14 @@ plumbbob setup --global
 
 This copies the hook and skills under `~/.claude/` and registers them in `~/.claude/settings.json`. Restart Claude Code (or reload settings) after install.
 
+### Verify the install
+
+```sh
+pnpm exec plumbbob doctor    # or `plumbbob doctor` for a global install
+```
+
+`doctor` checks the four things that must be true — the skills are present, their bin resolves, the CLI is installed, and the post-edit hook is registered — and prints the exact fix for anything broken. Run it first if a `/pb-*` skill ever opens with an empty dashboard.
+
 ## STATE is orientation, not a gate
 
 The one-word `.plumbbob/STATE` (`DESIGN` / `BUILD` / `SPIKE`) is read by `/pb-status` to tell you where you are and what to do next. It no longer gates edits — a wrong state is a mislabeled position on a map, not a locked door. The post-edit hook is session-gated: a repo with no `.plumbbob/STATE` behaves exactly like plain Claude Code.

package/dist/cli.js

@@ -12,6 +12,7 @@ import { revert } from "./verbs/revert.js";
 import { spike } from "./verbs/spike.js";
 import { reset } from "./verbs/reset.js";
 import { setup } from "./verbs/setup.js";
+import { doctor } from "./verbs/doctor.js";
 const VERBS = [
     { name: 'start', summary: 'scaffold .plumbbob/; STATE=DESIGN; record the baseline commit' },
     { name: 'status', summary: 'print the session state, or NO ACTIVE SESSION' },
@@ -23,6 +24,7 @@ const VERBS = [
     { name: 'spike', summary: 'spike "<slug>" | spike done: throwaway worktree experiment' },
     { name: 'reset', summary: 'v2 close-out: archive intent+log+report (no gate), clear the sidecar, STATE off' },
     { name: 'setup', summary: 'install hooks + skills; register them (self-contained per-project by default; --global for ~/.claude)' },
+    { name: 'doctor', summary: 'diagnose the install (skills, bin, hook) and print the fix for anything broken' },
 ];
 // Plumbbob v2 (D1/D10/D13): the deciding/executing boundary is no longer a lock,
 // so there is nothing to defend — every verb runs the same whether a human or the
@@ -56,6 +58,8 @@ function dispatch(verb, cwd, rest) {
             return reset(cwd);
         case 'setup':
             return setup(cwd, rest);
+        case 'doctor':
+            return doctor(cwd);
         default:
             process.stderr.write(`plumbbob: unknown verb '${verb}'. Run 'plumbbob help' for the verb table.\n`);
             return 1;

package/dist/verbs/doctor.js

@@ -0,0 +1,172 @@
+// `plumbbob doctor` — diagnose a project's install end to end and print the fix
+// for anything broken. Read-only: it inspects, it never writes. The failure
+// class it exists for is SILENT — a skill's status pre-injection resolving to an
+// empty/garbled bin (e.g. the pre-0.3 `$CLAUDE_PROJECT_DIR` form, a hooks-only
+// variable that expands empty in a skill's bash) leaves an empty dashboard with
+// no error. doctor names the problem and the remedy instead. Functional,
+// node builtins only (C1/C2).
+import { existsSync, readFileSync, readdirSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { basename, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { findRepoRoot } from "../lib/git.js";
+import { readSettings } from "../lib/settings.js";
+// The plumbbob package's own skills/ dir (the canonical set setup installs). Off
+// this module's URL so it resolves the same from src/ (dev) and dist/ (published).
+function packageDir(name) {
+    return fileURLToPath(new URL(`../../${name}/`, import.meta.url));
+}
+// The pb-* skill directories under `dir` that actually carry a SKILL.md.
+function listSkills(dir) {
+    try {
+        return readdirSync(dir).filter((n) => existsSync(join(dir, n, 'SKILL.md')));
+    }
+    catch {
+        return [];
+    }
+}
+// Pull the bin token out of a skill's status pre-injection — the text between
+// `!`` and ` status`. Returns null if the skill carries no injection line.
+function injectionBin(body) {
+    const m = body.match(/!`(.+?) status\b/);
+    return m === null ? null : (m[1] ?? null);
+}
+// The distinct bin tokens the installed skills inject. They should be uniform; a
+// set surfaces a partial/failed setup that left some skills on the old token.
+function installedBins(skillsDir, skills) {
+    const bins = skills
+        .map((n) => injectionBin(readFileSync(join(skillsDir, n, 'SKILL.md'), 'utf8')))
+        .filter((b) => b !== null);
+    return [...new Set(bins)];
+}
+// Classify the injected bins: ok, or a list of human-readable problems. Catches
+// the unresolved placeholder (setup never substituted) and the legacy
+// $CLAUDE_PROJECT_DIR form (empty in a skill), and verifies an absolute bin
+// actually exists on disk. A bare `plumbbob` resolves from PATH — accepted.
+function binProblems(bins) {
+    const problems = [];
+    for (const bin of bins) {
+        if (bin.includes('__PLUMBBOB_BIN__')) {
+            problems.push('placeholder not substituted (setup did not finish)');
+        }
+        else if (bin.includes('$CLAUDE_PROJECT_DIR')) {
+            problems.push('legacy $CLAUDE_PROJECT_DIR bin — expands empty in a skill (pre-0.3 install)');
+        }
+        else if (bin.startsWith('/') && !existsSync(bin)) {
+            problems.push(`absolute bin not found on disk: ${bin}`);
+        }
+    }
+    return problems;
+}
+// True iff any registered hook command points into our hooks dir (the marker the
+// settings module also uses for strip/merge).
+function hasOurHook(settings) {
+    const hooks = settings.hooks ?? {};
+    return Object.values(hooks).some((list) => (list ?? []).some((e) => (e.hooks ?? []).some((h) => (h.command ?? '').includes('plumbbob/hooks/'))));
+}
+// The repo-scoped (self-contained) install: skills under <repo>/.claude, the CLI
+// and hook in <repo>/node_modules, registration in either settings file.
+function selfChecks(repoRoot, shipped) {
+    const skillsDir = join(repoRoot, '.claude', 'skills');
+    const installed = listSkills(skillsDir);
+    const bins = installedBins(skillsDir, installed);
+    const problems = binProblems(bins);
+    const localFile = join(repoRoot, '.claude', 'settings.local.json');
+    const projFile = join(repoRoot, '.claude', 'settings.json');
+    const registeredIn = [localFile, projFile].filter((f) => hasOurHook(readSettings(f)));
+    const hookScript = join(repoRoot, 'node_modules', 'plumbbob', 'hooks', 'post-edit.sh');
+    return [
+        installed.length >= shipped.length
+            ? { ok: true, label: `skills installed (${installed.length}) in .claude/skills` }
+            : {
+                ok: false,
+                label: `skills incomplete (${installed.length}/${shipped.length}) in .claude/skills`,
+                fix: 'rerun: pnpm exec plumbbob setup --local',
+            },
+        problems.length === 0
+            ? { ok: true, label: `skill bin resolves (${bins.join(', ') || 'n/a'})` }
+            : { ok: false, label: `skill bin broken — ${problems.join('; ')}`, fix: 'rerun: pnpm exec plumbbob setup --local' },
+        existsSync(join(repoRoot, 'node_modules', 'plumbbob'))
+            ? { ok: true, label: 'plumbbob dependency present (node_modules/plumbbob)' }
+            : { ok: false, label: 'plumbbob is not a project dependency', fix: 'add it: pnpm add -D plumbbob' },
+        existsSync(join(repoRoot, 'node_modules', '.bin', 'plumbbob'))
+            ? { ok: true, label: 'CLI shim present (node_modules/.bin/plumbbob)' }
+            : { ok: false, label: 'CLI shim missing (node_modules/.bin/plumbbob)', fix: 'reinstall deps: pnpm install' },
+        registeredIn.length > 0
+            ? { ok: true, label: `post-edit hook registered (${registeredIn.map((f) => basename(f)).join(', ')})` }
+            : {
+                ok: false,
+                label: 'post-edit hook not registered in .claude/settings*.json',
+                fix: 'rerun: pnpm exec plumbbob setup --local',
+            },
+        existsSync(hookScript)
+            ? { ok: true, label: 'hook script resolves (node_modules/plumbbob/hooks/post-edit.sh)' }
+            : {
+                ok: false,
+                label: 'hook script missing (node_modules/plumbbob/hooks/post-edit.sh)',
+                fix: 'reinstall the dep so the registered hook resolves: pnpm add -D plumbbob',
+            },
+    ];
+}
+// The global install: skills + hook copied under ~/.claude, the CLI on PATH from
+// `npm i -g`. The bare on-PATH bin can't be probed from here without spawning, so
+// this scope verifies the copied artifacts and the registration.
+function globalChecks(home, shipped) {
+    const skillsDir = join(home, '.claude', 'skills');
+    const installed = listSkills(skillsDir);
+    const problems = binProblems(installedBins(skillsDir, installed));
+    const hookScript = join(home, '.claude', 'plumbbob', 'hooks', 'post-edit.sh');
+    return [
+        installed.length >= shipped.length
+            ? { ok: true, label: `skills installed (${installed.length}) in ~/.claude/skills` }
+            : { ok: false, label: `skills incomplete (${installed.length}/${shipped.length})`, fix: 'rerun: plumbbob setup --global' },
+        problems.length === 0
+            ? { ok: true, label: 'skill bin resolves (plumbbob, on PATH from the global install)' }
+            : { ok: false, label: `skill bin broken — ${problems.join('; ')}`, fix: 'rerun: plumbbob setup --global' },
+        existsSync(hookScript)
+            ? { ok: true, label: 'hook script present (~/.claude/plumbbob/hooks/post-edit.sh)' }
+            : { ok: false, label: 'hook script missing under ~/.claude/plumbbob/hooks', fix: 'rerun: plumbbob setup --global' },
+        hasOurHook(readSettings(join(home, '.claude', 'settings.json')))
+            ? { ok: true, label: 'post-edit hook registered (~/.claude/settings.json)' }
+            : { ok: false, label: 'post-edit hook not registered (~/.claude/settings.json)', fix: 'rerun: plumbbob setup --global' },
+    ];
+}
+export function doctor(cwd) {
+    const home = process.env.HOME ?? homedir();
+    const shipped = listSkills(packageDir('skills'));
+    const repoRoot = findRepoRoot(cwd);
+    const repoSkills = repoRoot === null ? [] : listSkills(join(repoRoot, '.claude', 'skills'));
+    const globalSkills = listSkills(join(home, '.claude', 'skills'));
+    const out = [`plumbbob doctor — ${repoRoot ?? cwd}`];
+    let checks;
+    if (repoSkills.length > 0 && repoRoot !== null) {
+        out.push('install shape: self-contained (<repo>/.claude)');
+        checks = selfChecks(repoRoot, shipped);
+    }
+    else if (globalSkills.length > 0) {
+        out.push('install shape: global (~/.claude)');
+        checks = globalChecks(home, shipped);
+    }
+    else {
+        out.push('install shape: none detected');
+        checks = [
+            {
+                ok: false,
+                label: 'no pb-* skills found under <repo>/.claude/skills or ~/.claude/skills',
+                fix: repoRoot === null
+                    ? 'global install: npm i -g plumbbob && plumbbob setup --global'
+                    : 'project install: pnpm add -D plumbbob && pnpm exec plumbbob setup --local',
+            },
+        ];
+    }
+    for (const c of checks) {
+        out.push(c.ok ? `  ✓ ${c.label}` : `  ✗ ${c.label}\n      → ${c.fix}`);
+    }
+    const failed = checks.filter((c) => !c.ok).length;
+    out.push('');
+    out.push(failed === 0
+        ? 'plumbbob: all checks passed. If a skill still misbehaves, restart Claude Code to reload settings.'
+        : `plumbbob: ${failed} problem(s) found — apply the → fixes above, then restart Claude Code.`);
+    process.stdout.write(`${out.join('\n')}\n`);
+    return failed === 0 ? 0 : 1;
+}

package/dist/verbs/setup.js

@@ -3,9 +3,14 @@
 //   self-contained (default when plumbbob is a project-local dep; --local /
 //     --project to force) — NOTHING is written under ~/.claude. The hooks are
 //     referenced in place at $CLAUDE_PROJECT_DIR/node_modules/plumbbob/hooks/,
-//     and the skills are copied into <repo>/.claude/skills/ with their bin
-//     invocation pointed at $CLAUDE_PROJECT_DIR/node_modules/.bin/plumbbob. The
-//     registration lands in:
+//     and the skills are copied into <repo>/.claude/skills/. A skill's bin
+//     invocation can NOT use $CLAUDE_PROJECT_DIR — that variable is defined only
+//     in Claude Code's hook context and expands EMPTY in a skill's bash — so
+//     setup resolves the bin at install time (see selfBin): --local bakes the
+//     absolute path to <repo>/node_modules/.bin/plumbbob (personal + untracked,
+//     so a machine path is fine); --project uses a bare `plumbbob` (committed +
+//     shared, so it stays portable — Claude Code resolves it from the project's
+//     node_modules/.bin, which it prepends to PATH). The registration lands in:
 //       --local   (default) <repo>/.claude/settings.local.json  — personal, untracked
 //       --project           <repo>/.claude/settings.json         — committable, enrolls the team
 //     This is the "run it from the project root, no global install" shape.
@@ -28,10 +33,11 @@ const HOOK_FILES = ['post-edit.sh'];
 // The placeholder every skill carries in place of its `plumbbob` invocation;
 // setup substitutes it with the form the chosen install shape resolves.
 const BIN_PLACEHOLDER = '__PLUMBBOB_BIN__';
-// Self-contained installs address everything through Claude Code's project-root
-// variable so committed/portable files carry no machine-absolute path.
+// The hook is registered in settings.json, whose `command` runs in Claude Code's
+// hook context — the one place $CLAUDE_PROJECT_DIR is defined — so the portable
+// project-root variable resolves correctly here. (A skill's bash does NOT get
+// that variable; the skill bin is resolved separately, by selfBin.)
 const SELF_HOOKS_DIR = '$CLAUDE_PROJECT_DIR/node_modules/plumbbob/hooks';
-const SELF_BIN = '$CLAUDE_PROJECT_DIR/node_modules/.bin/plumbbob';
 export function setup(cwd, args) {
     const home = process.env.HOME ?? homedir();
     const mode = resolveMode(cwd, home, args);
@@ -72,20 +78,36 @@ function installGlobal(home, settingsFile) {
 // their bin invocation rewritten to the project-local binary.
 function installSelfContained(mode) {
     const skillsDir = join(mode.repoRoot, '.claude', 'skills');
+    const bin = selfBin(mode);
     cpSync(packageDir('skills'), skillsDir, { recursive: true });
-    substituteSkillBins(skillsDir, SELF_BIN);
+    substituteSkillBins(skillsDir, bin);
     writeSettings(mode.settingsFile, mergeRegistration(readSettings(mode.settingsFile), SELF_HOOKS_DIR, true));
     const note = existsSync(join(mode.repoRoot, 'node_modules', 'plumbbob', 'hooks'))
         ? ''
         : 'plumbbob: note — node_modules/plumbbob/ is not present in this repo yet. Add plumbbob as a dependency (e.g. `pnpm add -D plumbbob`) so the registered hooks resolve.\n';
     const scope = mode.settingsFile.endsWith('settings.local.json') ? 'local' : 'project';
-    process.stdout.write(`plumbbob: copied skills → ${skillsDir} (bin → ${SELF_BIN}). Nothing was written under ~/.claude.\n` +
+    process.stdout.write(`plumbbob: copied skills → ${skillsDir} (bin → ${bin}). Nothing was written under ~/.claude.\n` +
         `plumbbob: referenced the hooks at ${SELF_HOOKS_DIR} and registered them in ${mode.settingsFile} (${scope} scope).\n` +
         note +
         'plumbbob: restart Claude Code (or reload settings) for the hooks to take effect.\n' +
         'plumbbob: drive the workflow from the chat with the `pb-*` driver skills. Keep the transition verbs OUT of your settings allowlist — each driver skill self-authorizes its own verb, so a stray model-initiated transition still surfaces a permission prompt.\n');
     return 0;
 }
+// Resolve the bin string baked into the copied skills. A skill's `!`...``
+// injection and its allowed-tools prefix can NOT rely on $CLAUDE_PROJECT_DIR (a
+// hooks-only variable that expands empty in a skill's bash context), so we
+// resolve at install time. --local is personal and untracked, so bake the
+// absolute path to the project-local binary — fully resolved, no runtime
+// lookup. --project is committed and shared, so a machine-absolute path can't
+// travel; fall back to a bare `plumbbob`, which Claude Code resolves from the
+// project's node_modules/.bin (it prepends that to PATH). A repo path with
+// whitespace can't sit unquoted in the injection or an allowed-tools prefix
+// either, so use the PATH-resolved bare form there too.
+function selfBin(mode) {
+    const committed = !mode.settingsFile.endsWith('settings.local.json');
+    const abs = join(mode.repoRoot, 'node_modules', '.bin', 'plumbbob');
+    return committed || /\s/.test(abs) ? 'plumbbob' : abs;
+}
 // Resolve which install shape and settings file to use. Explicit flags win;
 // with no flag, auto-detect — a project-local plumbbob installs self-contained
 // (personal, into settings.local.json), anything else installs global. Returns

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "plumbbob",
-  "version": "0.3.0",
+  "version": "0.3.1",
   "description": "Attention-first build process: eight skills + a CLI that keep you the decider — guidance, not enforcement.",
   "keywords": [
     "claude-code",

package/skills/pb-build/SKILL.md

@@ -8,7 +8,7 @@ allowed-tools: Read, Edit, Write, Bash(__PLUMBBOB_BIN__ status:*), Bash(__PLUMBB
 
 # Plumbbob — build a step (the optional engine)
 
-Current session state (injected when this skill runs): !`__PLUMBBOB_BIN__ status`
+Current session state (injected when this skill runs): !`__PLUMBBOB_BIN__ status 2>/dev/null || echo "plumbbob CLI not found - install the dep and re-run: npx plumbbob setup"`
 
 This is the **bundled executor** — one way to turn a planned step into code. It is
 **optional** (D3): you can implement any step by hand, in a vibe session, or with

package/skills/pb-harvest/SKILL.md

@@ -8,7 +8,7 @@ allowed-tools: Read, Edit, Bash(__PLUMBBOB_BIN__ status:*)
 
 # Plumbbob — harvest the park list
 
-Current session state (injected when this skill runs): !`__PLUMBBOB_BIN__ status`
+Current session state (injected when this skill runs): !`__PLUMBBOB_BIN__ status 2>/dev/null || echo "plumbbob CLI not found - install the dep and re-run: npx plumbbob setup"`
 
 `/pb-harvest` is the complement of `/pb-park` (D7): you parked ideas as seeds during a
 build; now, at a boundary, you harvest them — decide what each one is.

package/skills/pb-park/SKILL.md

@@ -8,7 +8,7 @@ allowed-tools: Bash(__PLUMBBOB_BIN__ status:*), Bash(__PLUMBBOB_BIN__ park:*)
 
 # Plumbbob — park an idea (capture, don't chase)
 
-Current session state (injected when this skill runs): !`__PLUMBBOB_BIN__ status`
+Current session state (injected when this skill runs): !`__PLUMBBOB_BIN__ status 2>/dev/null || echo "plumbbob CLI not found - install the dep and re-run: npx plumbbob setup"`
 
 `/pb-park` is the **capture** half of the loop; `/pb-harvest` is where parked items
 get triaged later (D7). Capturing the instant an idea arrives — instead of acting on

package/skills/pb-plan/SKILL.md

@@ -8,7 +8,7 @@ allowed-tools: Read, Edit, Write, Bash(__PLUMBBOB_BIN__ status:*), Bash(__PLUMBB
 
 # Plumbbob — frame a goal (the whole-goal move)
 
-Current session state (injected when this skill runs): !`__PLUMBBOB_BIN__ status`
+Current session state (injected when this skill runs): !`__PLUMBBOB_BIN__ status 2>/dev/null || echo "plumbbob CLI not found - install the dep and re-run: npx plumbbob setup"`
 
 `/pb-plan` is the **whole-goal** move — it opens a session and gets the deciding out
 of your head and onto `intent.md` *before* any code. (Planning a single increment is

package/skills/pb-reset/SKILL.md

@@ -8,7 +8,7 @@ allowed-tools: Read, Write, Bash(__PLUMBBOB_BIN__ status:*), Bash(__PLUMBBOB_BIN
 
 # Plumbbob — reset for a new goal (the close-out)
 
-Current session state (injected when this skill runs): !`__PLUMBBOB_BIN__ status`
+Current session state (injected when this skill runs): !`__PLUMBBOB_BIN__ status 2>/dev/null || echo "plumbbob CLI not found - install the dep and re-run: npx plumbbob setup"`
 
 `/pb-reset` ends the build: it captures what happened, archives it, and clears the
 sidecar for the next goal. **Report by default** (D9) — no refuse-without-report gate,

package/skills/pb-revert/SKILL.md

@@ -8,7 +8,7 @@ allowed-tools: Bash(__PLUMBBOB_BIN__ status:*), Bash(__PLUMBBOB_BIN__ revert:*)
 
 # Plumbbob — revert to a checkpoint (driver)
 
-Current session state (injected when this skill runs): !`__PLUMBBOB_BIN__ status`
+Current session state (injected when this skill runs): !`__PLUMBBOB_BIN__ status 2>/dev/null || echo "plumbbob CLI not found - install the dep and re-run: npx plumbbob setup"`
 
 This is a **driver skill** — a chat-side trigger for the mechanical `plumbbob revert` verb, so the whole workflow runs from the agent window instead of a terminal. It is `disable-model-invocation: true`: only the human fires it. It carries **no Edit and no Write tool** — its only action is to shell the verb and report the verb's output verbatim, including any refusal. The CLI is the source of truth: never retry a refused transition, and never edit a file to work around one.
 

package/skills/pb-spike/SKILL.md

@@ -8,7 +8,7 @@ allowed-tools: Bash(__PLUMBBOB_BIN__ status:*), Bash(__PLUMBBOB_BIN__ spike:*)
 
 # Plumbbob — spike an experiment (driver)
 
-Current session state (injected when this skill runs): !`__PLUMBBOB_BIN__ status`
+Current session state (injected when this skill runs): !`__PLUMBBOB_BIN__ status 2>/dev/null || echo "plumbbob CLI not found - install the dep and re-run: npx plumbbob setup"`
 
 This is a **driver skill** — a chat-side trigger for the mechanical `plumbbob spike` verb, so the whole workflow runs from the agent window instead of a terminal. It is `disable-model-invocation: true`: only the human fires it. It carries **no Edit and no Write tool** — its only action is to shell the verb and report the verb's output verbatim, including any refusal. The CLI is the source of truth: never retry a refused transition, and never edit a file to work around one.
 

package/skills/pb-status/SKILL.md

@@ -8,7 +8,7 @@ allowed-tools: Bash(__PLUMBBOB_BIN__ status:*)
 
 # Plumbbob — orient (the where-am-I move)
 
-Current session state (injected when this skill runs): !`__PLUMBBOB_BIN__ status`
+Current session state (injected when this skill runs): !`__PLUMBBOB_BIN__ status 2>/dev/null || echo "plumbbob CLI not found - install the dep and re-run: npx plumbbob setup"`
 
 This is a **thin driver** for `__PLUMBBOB_BIN__ status`. The dashboard above is your
 orientation — the intent, the step list, the parked/open-question counts, and the

package/skills/pb-step/SKILL.md

@@ -8,7 +8,7 @@ allowed-tools: Read, Edit, Bash(__PLUMBBOB_BIN__ status:*)
 
 # Plumbbob — plan the next step (the single-increment move)
 
-Current session state (injected when this skill runs): !`__PLUMBBOB_BIN__ status`
+Current session state (injected when this skill runs): !`__PLUMBBOB_BIN__ status 2>/dev/null || echo "plumbbob CLI not found - install the dep and re-run: npx plumbbob setup"`
 
 `/pb-step` plans the **next increment** just-in-time (D6) — the smallest verifiable
 piece of the framed goal, planned only when you reach it. (Framing the whole goal is

package/skills/pb-verify/SKILL.md

@@ -8,7 +8,7 @@ allowed-tools: Read, Bash(__PLUMBBOB_BIN__ status:*), Bash(__PLUMBBOB_BIN__ chec
 
 # Plumbbob — verify a step (the tick)
 
-Current session state (injected when this skill runs): !`__PLUMBBOB_BIN__ status`
+Current session state (injected when this skill runs): !`__PLUMBBOB_BIN__ status 2>/dev/null || echo "plumbbob CLI not found - install the dep and re-run: npx plumbbob setup"`
 
 This is the **tick** — the one beat where the human is the clock. Whatever produced
 the current diff — `/pb-build`, your own hands, a vibe session, another harness —

package/skills/plumbbob-interrogate/SKILL.md

@@ -8,7 +8,7 @@ allowed-tools: Read, Edit, Bash(__PLUMBBOB_BIN__ status:*)
 
 # Plumbbob — interrogate the frame
 
-Current session state (injected when this skill runs): !`__PLUMBBOB_BIN__ status`
+Current session state (injected when this skill runs): !`__PLUMBBOB_BIN__ status 2>/dev/null || echo "plumbbob CLI not found - install the dep and re-run: npx plumbbob setup"`
 
 ## Wrong-state refusal