plumbbob 0.2.3 → 0.3.1

package/dist/verbs/check.js

@@ -0,0 +1,17 @@
+// `plumbbob check` — run the heavy gate (D16/D24) and report, with NO state
+// change. The read-only half of the verify tick: `/pb-verify` runs this before the
+// pause so the human approves on a known-green check. Exits with the check's own
+// code (0 = green).
+import { findRepoRoot } from "../lib/git.js";
+import { hasSession } from "../lib/sidecar.js";
+import { runCheck } from "../lib/check.js";
+export function check(cwd) {
+    const root = findRepoRoot(cwd);
+    if (root === null || !hasSession(root)) {
+        process.stderr.write('plumbbob: no active session. Run `plumbbob start "<title>"` first.\n');
+        return 1;
+    }
+    const code = runCheck(root);
+    process.stdout.write(code === 0 ? '\nplumbbob: check green.\n' : '\nplumbbob: check RED — fix it before checkpointing.\n');
+    return code;
+}

package/dist/verbs/checkpoint.js

@@ -0,0 +1,83 @@
+// `plumbbob checkpoint [<n>] [-m <msg>]` — the executor-agnostic commit tick (D3).
+// Unlike v1 `done`, it does NOT require BUILD state or a STEP file: the step is
+// whatever you pass, else the in-flight STEP, else the next undone step in intent.
+// It gates on a green check, then commits any pending work (or records the existing
+// HEAD when the tree is already clean — the human's commit skill may have committed
+// first), records the SHA, flips the intent checkbox to `[x]`, clears any STEP/SEAM,
+// and returns to DESIGN. The diff's author is irrelevant: `/pb-build`, your hands,
+// a vibe session, or another harness all checkpoint the same way.
+import { appendFileSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { commit, findRepoRoot, headSha, isDirty, stageAll } from "../lib/git.js";
+import { checkpointsPath, hasSession, intentPath, seamPath, stepPath, writeState } from "../lib/sidecar.js";
+import { runCheck } from "../lib/check.js";
+import { markStepDone, parseSteps } from "../lib/orient.js";
+export function checkpoint(cwd, args) {
+    const root = findRepoRoot(cwd);
+    if (root === null || !hasSession(root)) {
+        process.stderr.write('plumbbob: no active session. Run `plumbbob start "<title>"` first.\n');
+        return 1;
+    }
+    const step = resolveStep(root, args);
+    if (step === null) {
+        process.stderr.write('plumbbob: no step to checkpoint — pass a number, or plan a step in intent.md first.\n');
+        return 1;
+    }
+    if (runCheck(root) !== 0) {
+        process.stderr.write('plumbbob: check failed (red) — checkpoint refuses on red. Fix it and re-run.\n');
+        return 1;
+    }
+    let sha;
+    if (isDirty(root)) {
+        stageAll(root);
+        sha = commit(root, messageArg(args) ?? `plumbbob: step ${step} done`);
+    }
+    else {
+        sha = headSha(root);
+    }
+    appendFileSync(checkpointsPath(root), `step ${step} ${sha}\n`);
+    flipIntent(root, step);
+    rmSync(seamPath(root), { force: true });
+    rmSync(stepPath(root), { force: true });
+    writeState(root, 'DESIGN');
+    process.stdout.write(`plumbbob: step ${step} checkpointed — ${sha.slice(0, 9)}. STATE=DESIGN.\n`);
+    return 0;
+}
+// Step resolution (D3): explicit arg > in-flight STEP file > first undone step in
+// intent.md. Returns null when none can be determined.
+function resolveStep(root, args) {
+    const explicit = args.find((a) => /^\d+$/.test(a));
+    if (explicit !== undefined) {
+        return Number(explicit);
+    }
+    const inFlight = readStep(root);
+    if (inFlight !== null) {
+        return inFlight;
+    }
+    try {
+        return parseSteps(readFileSync(intentPath(root), 'utf8')).find((s) => !s.done)?.n ?? null;
+    }
+    catch {
+        return null;
+    }
+}
+function flipIntent(root, step) {
+    try {
+        writeFileSync(intentPath(root), markStepDone(readFileSync(intentPath(root), 'utf8'), step));
+    }
+    catch {
+        // best-effort bookkeeping; the checkpoint SHA is the source of truth.
+    }
+}
+function messageArg(args) {
+    const i = args.indexOf('-m');
+    return i !== -1 && i + 1 < args.length ? (args[i + 1] ?? null) : null;
+}
+function readStep(root) {
+    try {
+        const raw = readFileSync(stepPath(root), 'utf8').trim();
+        return /^\d+$/.test(raw) ? Number(raw) : null;
+    }
+    catch {
+        return null;
+    }
+}

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/reset.js

@@ -0,0 +1,54 @@
+// `plumbbob reset` (D9) — the v2 close-out, replacing the v1
+// wrap → report → docs → finish ceremony. It archives intent + build-log + report
+// (the `/pb-reset` skill writes the report by default) under .plumbbob/archive/,
+// clears the active files, and deletes the control state (STATE last). Unlike v1
+// `finish` there is NO refuse-without-report gate — guidance offers the artifact, it
+// does not wall the exit. Archive-then-clear, never destroy (C4); git untouched (C5).
+import { appendFileSync, existsSync, readFileSync, rmSync } from 'node:fs';
+import { join, relative } from 'node:path';
+import { findRepoRoot } from "../lib/git.js";
+import { buildLogPath, checkpointsPath, hasSession, intentPath, seamPath, sidecarDir, stepPath } from "../lib/sidecar.js";
+import { archiveSession, reportPath } from "../lib/archive.js";
+export function reset(cwd) {
+    const root = findRepoRoot(cwd);
+    if (root === null || !hasSession(root)) {
+        process.stderr.write('plumbbob: no active session. Run `plumbbob start "<title>"` first.\n');
+        return 1;
+    }
+    if (existsSync(reportPath(root))) {
+        appendCheckpointShas(root);
+    }
+    else {
+        process.stderr.write('plumbbob: note — no report.md found; archiving intent + build-log without one ' +
+            '(/pb-reset normally writes the report first). No gate (D9).\n');
+    }
+    const archived = archiveSession(root);
+    // Clear the active files — now safely archived — then the control state, STATE
+    // last so "no session" flips exactly at the end.
+    rmSync(intentPath(root), { force: true });
+    rmSync(buildLogPath(root), { force: true });
+    rmSync(reportPath(root), { force: true });
+    rmSync(seamPath(root), { force: true });
+    rmSync(stepPath(root), { force: true });
+    rmSync(join(sidecarDir(root), 'STATE'), { force: true });
+    process.stdout.write(`plumbbob: reset — archived to ${relative(root, archived)}. Sidecar cleared. ` +
+        'Run `/pb-plan` (or `plumbbob start "<title>"`) to frame the next goal.\n');
+    return 0;
+}
+// Append the recorded checkpoints (baseline + each `step n <sha>`) to the report so
+// the archived report lists the SHAs.
+function appendCheckpointShas(root) {
+    let raw = '';
+    try {
+        raw = readFileSync(checkpointsPath(root), 'utf8');
+    }
+    catch {
+        raw = '';
+    }
+    const lines = raw
+        .split('\n')
+        .map((l) => l.trim())
+        .filter((l) => l.length > 0)
+        .map((l) => `- ${l}`);
+    appendFileSync(reportPath(root), ['', '## Checkpoints', '', ...lines, ''].join('\n'));
+}

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.
@@ -24,14 +29,15 @@ import { join, sep } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { findRepoRoot } from "../lib/git.js";
 import { mergeRegistration, readSettings, stripRegistration, writeSettings } from "../lib/settings.js";
-const HOOK_FILES = ['pre-edit.sh', 'bash-guard.sh', 'post-edit.sh'];
+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/dist/verbs/status.js

@@ -1,13 +1,32 @@
-// `plumbbob status` — print the session state, or NO ACTIVE SESSION. Read-only,
-// always exits 0. Skills pre-inject this output to gate their own behavior.
+// `plumbbob status` — the orientation dashboard (D8/D15), or NO ACTIVE SESSION.
+// Read-only, always exits 0. Skills pre-inject this output to gate their own
+// behavior, so the `NO ACTIVE SESSION` sentinel is kept exact.
+import { readFileSync } from 'node:fs';
 import { findRepoRoot } from "../lib/git.js";
-import { hasSession, readState } from "../lib/sidecar.js";
+import { buildLogPath, checkpointsPath, hasSession, intentPath, readState, stepPath } from "../lib/sidecar.js";
+import { formatOrientation, orient } from "../lib/orient.js";
+function readOr(path) {
+    try {
+        return readFileSync(path, 'utf8');
+    }
+    catch {
+        return '';
+    }
+}
 export function status(cwd) {
     const root = findRepoRoot(cwd);
     if (root === null || !hasSession(root)) {
         process.stdout.write('NO ACTIVE SESSION\n');
         return 0;
     }
-    process.stdout.write(`STATE: ${readState(root) ?? 'UNKNOWN'}\n`);
+    const inFlightRaw = readOr(stepPath(root)).trim();
+    const orientation = orient({
+        state: readState(root) ?? 'UNKNOWN',
+        intent: readOr(intentPath(root)),
+        buildLog: readOr(buildLogPath(root)),
+        checkpoints: readOr(checkpointsPath(root)),
+        inFlight: /^\d+$/.test(inFlightRaw) ? Number(inFlightRaw) : null,
+    });
+    process.stdout.write(`${formatOrientation(orientation)}\n`);
     return 0;
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "plumbbob",
-  "version": "0.2.3",
-  "description": "Attention-first build process: a CLI + hooks that enforce the deciding/executing boundary.",
+  "version": "0.3.1",
+  "description": "Attention-first build process: eight skills + a CLI that keep you the decider — guidance, not enforcement.",
   "keywords": [
     "claude-code",
     "claude",

package/skills/pb-build/SKILL.md

@@ -1,19 +1,49 @@
 ---
 name: pb-build
-description: Human-triggered driver for `plumbbob build <n>` — write the SEAM for a step and enter BUILD (edits unlocked to those paths only), from the chat.
+description: The optional engine — read the current planned step from intent, implement it (its done-when, seam, Decisions, Constraints), then verify it through to the approval pause. Skip it entirely to implement by hand, vibed, or with another harness.
 disable-model-invocation: true
-model: haiku
-allowed-tools: Bash(__PLUMBBOB_BIN__ status:*), Bash(__PLUMBBOB_BIN__ build:*)
+model: opus
+allowed-tools: Read, Edit, Write, Bash(__PLUMBBOB_BIN__ status:*), Bash(__PLUMBBOB_BIN__ build:*), Bash(__PLUMBBOB_BIN__ check:*), Bash(__PLUMBBOB_BIN__ checkpoint:*), Bash(git diff:*)
 ---
 
-# Plumbbob — build a step (driver)
+# 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 a **driver skill** — a chat-side trigger for the mechanical `plumbbob build` 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.
+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
+another harness and go straight to `/pb-verify` instead — plumbbob does not care how
+the diff appeared. When you do run it, it reads the plan, writes the step, and
+carries straight through to the verify pause.
 
-## What it does
+## What this skill does, in order
 
-1. Read the step number from the way you were invoked (e.g. `/pb-build 3` → step `3`). If no number is present, ask for one and run nothing.
-2. Run `__PLUMBBOB_BIN__ build <n>` via Bash.
-3. Report the verb's output verbatim — the SEAM it wrote and the new state, or any refusal.
+1. **Pick the step.** Use the number you were invoked with (e.g. `/pb-build 4`), else
+   the next undone, planned step in `.plumbbob/intent.md`. If there is no planned step
+   to build, stop and tell the human to `/pb-step` first.
+2. **Enter the step.** Run `__PLUMBBOB_BIN__ build <n>` (records the in-flight STEP +
+   SEAM so `/pb-status` shows the step in flight; in v2 the seam is awareness, not a
+   lock).
+3. **Read the plan.** Read the step's **done-when**, its **seam**, and the
+   **Decisions** and **Constraints** in `intent.md`. Build to *that* — the deciding
+   already happened, off the chat.
+4. **Implement** the step, and only that step, staying within the declared seam. A
+   new problem or "ooh what if" that surfaces mid-build is a `/pb-park`, **not** an
+   edit — capture it and stay on the step. If you genuinely cannot finish without
+   touching more than the seam, that is scope drift: surface it to the human rather
+   than sprawling.
+5. **Verify, through to the pause.** Run the verify tick exactly as `/pb-verify`
+   does: `__PLUMBBOB_BIN__ check` → self-review the diff against the done-when, the
+   Decisions, and the Constraints (a single structured read, D16) → validate → **PAUSE
+   for the human's approval** → only on approval, checkpoint with
+   `__PLUMBBOB_BIN__ checkpoint`. Do **not** bump the version or changelog — that is
+   the human's `/version` call.
+
+## The hard contracts
+
+- **Optional, never required.** The loop works without this skill; `/pb-verify`
+  checkpoints a hand-built or vibed diff just the same (D3).
+- **Build the decided step, not a new one.** Implement what `intent.md` settled. A
+  new idea mid-build is a `/pb-park`, not an edit.
+- **Always end at the pause.** Implement → verify → wait for approval. Never
+  checkpoint without it; the human is the clock.

package/skills/pb-harvest/SKILL.md

@@ -0,0 +1,47 @@
+---
+name: pb-harvest
+description: Triage the park list at a step boundary — propose one class (blocker/tangent/pivot) per parked item, write only after the human confirms each, record under ## Harvest, and fold a confirmed blocker into intent.
+disable-model-invocation: true
+model: opus
+allowed-tools: Read, Edit, Bash(__PLUMBBOB_BIN__ status:*)
+---
+
+# Plumbbob — harvest the park list
+
+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.
+
+## When to run it — wrong-state refusal
+
+Harvest at a **step boundary**: after a step is checkpointed and you are back in
+DESIGN, not mid-step. Read the state injected above:
+
+- `NO ACTIVE SESSION` — **refuse**; tell the human to `plumbbob start "<title>"` first.
+- `BUILD` — a step is in flight; **refuse** and suggest finishing it with `/pb-verify`
+  before harvesting. Chasing parked items mid-step is the disease parking prevents.
+- `DESIGN` (and other settled states) — go ahead.
+
+## What this skill does
+
+Walk the **Park list** in `build-log.md` item by item and, for each, **propose exactly
+one class**:
+
+- **blocker** — the plan was wrong or incomplete; can't proceed. Folds into `intent.md`
+  and is handled now.
+- **tangent** — a different path, not clearly better. **The default** — defer or kill.
+- **pivot signal** — real evidence the whole approach is wrong. Stop and replan.
+
+## The one hard contract
+
+You **propose**; the **human calls it**. For each item, state your proposed class and
+one line of reasoning, then **wait for the human to confirm or override**. Write
+**only after** per-item confirmation:
+
+- Record each confirmed class in `build-log.md`'s `## Harvest` section.
+- **Flip the harvested item** from `- [ ]` to `- [x]` in the Park list, so `/pb-status`
+  stops counting it as open.
+- A confirmed **blocker** also folds its decision into `intent.md`.
+- Never reclassify or resolve an item the human hasn't confirmed, and default every
+  uncertain item to **tangent**, never to blocker.

package/skills/pb-park/SKILL.md

@@ -0,0 +1,40 @@
+---
+name: pb-park
+description: Compose one tidy tagged park line, get the human's OK in-turn, then capture it by shelling `plumbbob park` — never by editing a file. The capture half of the park/harvest loop.
+disable-model-invocation: true
+model: haiku
+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 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
+it — is the whole point: it protects the step in flight.
+
+## Wrong-state refusal
+
+Parking needs an **active session** to capture into. Read the state injected above: if
+it is `NO ACTIVE SESSION`, **refuse** and tell the human to run `plumbbob start
+"<title>"` first. Every active state (`DESIGN`, `BUILD`, `SPIKE`, `FINISH`) is fine —
+capture is always available, which is the whole point of parking.
+
+## What this skill does
+
+Take the idea, problem, or "ooh what if" the human just had and **compose it into one
+tidy, tagged line** — short, legible, self-contained, so it still reads cleanly weeks
+later. Then:
+
+1. **Show the composed line to the human** and wait for **in-turn approval** — they
+   confirm it as-is or edit the wording.
+2. **Only after** that approval, capture it by running `__PLUMBBOB_BIN__ park "<the
+   approved line>"` via Bash.
+
+## The one hard contract
+
+The capture itself is the **dumb CLI**, never an edit. This skill carries **no Edit and
+no Write tool** on purpose: you may not append to `build-log.md` yourself. Compose, get
+approval, then shell `__PLUMBBOB_BIN__ park` — that is the only write path. If approval
+never comes, capture nothing.

package/skills/pb-plan/SKILL.md

@@ -0,0 +1,38 @@
+---
+name: pb-plan
+description: Frame a fresh goal — scaffold the session and author the intent's Frame, Decisions, and Constraints before any code. Steps stay empty; they come one at a time from /pb-step.
+disable-model-invocation: true
+model: opus
+allowed-tools: Read, Edit, Write, Bash(__PLUMBBOB_BIN__ status:*), Bash(__PLUMBBOB_BIN__ start:*)
+---
+
+# Plumbbob — frame a goal (the whole-goal move)
+
+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
+the separate `/pb-step` move; do not confuse the two.)
+
+## What this skill does
+
+1. **Scaffold.** If there is no active session, run `__PLUMBBOB_BIN__ start "<title>"`
+   to create `.plumbbob/` (STATE=DESIGN, baseline recorded). If a session already
+   exists, say so and edit the existing `intent.md` rather than starting over.
+2. **Frame** (`.plumbbob/intent.md`), with the human: the **Problem** in plain words,
+   the **smallest thing** that solves it, what **done looks like**, and what you are
+   **explicitly NOT doing**. This is the human's convergence — propose wording, but
+   the human decides every line.
+3. **Decisions & Constraints.** Record the settled calls (one line each, with the
+   *because*) and the hard rules the build must honor. An unresolved hole goes to
+   **Open questions**, never guessed into a Decision.
+4. **Leave `## Steps` empty.** Steps are planned just-in-time (D6) — one at a time
+   with `/pb-step` — so do not write the build plan here.
+
+## The hard contracts
+
+- **Deciding before code.** `/pb-plan` writes `intent.md` only — never source.
+- **The human converges.** You surface options and draft wording; the human picks.
+  An unresolved hole is an Open question, not a guessed Decision.
+- **Size to the work.** A small change fills Frame + a couple of Decisions and stops;
+  ceremony on a one-liner is the failure mode, not thoroughness.