plumbbob 0.3.1 → 0.4.4

package/dist/verbs/doctor.js

@@ -1,22 +1,21 @@
-// `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';
+// `plumbbob doctor` — diagnose the global plugin link end to end. Read-only: it
+// inspects, it never writes. After `plumbbob init`, plumbbob lives as a symlink at
+// ~/.claude/skills/plumbbob pointing at the installed package; Claude Code loads it
+// in place as a plugin (skills `/plumbbob:*`, the post-edit hook from hooks.json).
+// doctor verifies the link resolves to a package carrying the manifest, the skills,
+// and the hook — and names the fix for anything missing. The failure class it
+// exists for is SILENT (a `/plumbbob:status` that opens an empty dashboard because the
+// plugin never linked). Functional, node builtins only (C1/C2).
+import { existsSync, lstatSync, readdirSync, readlinkSync } from 'node:fs';
 import { homedir } from 'node:os';
-import { basename, join } from 'node:path';
+import { 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).
+// The plumbbob package's own skills/ dir (the canonical set), 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.
+// Skill directories (those carrying a SKILL.md) under `dir`.
 function listSkills(dir) {
     try {
         return readdirSync(dir).filter((n) => existsSync(join(dir, n, 'SKILL.md')));
@@ -25,148 +24,51 @@ function listSkills(dir) {
         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}`);
+// Resolve the dir the plugin link points at: a symlink's target, or the path
+// itself if a real directory was copied there. null if nothing is linked.
+function linkedPackage(link) {
+    try {
+        const st = lstatSync(link);
+        if (st.isSymbolicLink()) {
+            return readlinkSync(link);
         }
+        return st.isDirectory() ? link : null;
+    }
+    catch {
+        return null;
     }
-    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');
+function buildChecks(link, pkg, shipped) {
+    const installed = listSkills(join(pkg, 'skills'));
     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' },
+        { ok: true, label: `linked (${link} → ${pkg})` },
+        existsSync(join(pkg, '.claude-plugin', 'plugin.json'))
+            ? { ok: true, label: 'plugin manifest present (.claude-plugin/plugin.json)' }
+            : { ok: false, label: 'plugin manifest missing — the link does not point at a plumbbob package', fix: 're-link: plumbbob init' },
+        installed.length >= shipped.length && shipped.length > 0
+            ? { ok: true, label: `skills present (${installed.length}) — load as /plumbbob:*` }
+            : { ok: false, label: `skills incomplete (${installed.length}/${shipped.length})`, fix: 're-link: plumbbob init' },
+        existsSync(join(pkg, 'hooks', 'hooks.json'))
+            ? { ok: true, label: 'post-edit hook present (hooks/hooks.json, auto-registers)' }
+            : { ok: false, label: 'hook missing (hooks/hooks.json)', fix: 're-link: plumbbob init' },
     ];
 }
-export function doctor(cwd) {
+export function doctor() {
     const home = process.env.HOME ?? homedir();
+    const link = join(home, '.claude', 'skills', 'plumbbob');
     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',
-            },
-        ];
-    }
+    const pkg = linkedPackage(link);
+    const checks = pkg === null ? [{ ok: false, label: `not linked — no plugin at ${link}`, fix: 'run: plumbbob init' }] : buildChecks(link, pkg, shipped);
+    const out = ['plumbbob doctor — global plugin install'];
     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.`);
+        ? 'plumbbob: all checks passed. If a skill still misbehaves, restart Claude Code (or /reload-plugins).'
+        : `plumbbob: ${failed} problem(s) — apply the → fixes, then restart Claude Code.`);
+    out.push('plumbbob: skills shell a bare `plumbbob` — ensure it is on PATH (`npm i -g plumbbob`). Sessions are per-project via `plumbbob start`.');
     process.stdout.write(`${out.join('\n')}\n`);
     return failed === 0 ? 0 : 1;
 }

package/dist/verbs/init.js

@@ -0,0 +1,81 @@
+// `plumbbob init [--uninstall]` — link plumbbob into Claude Code as an in-place
+// skills-directory plugin. This is the whole install: it symlinks the installed
+// package into ~/.claude/skills/plumbbob, where Claude Code discovers it as
+// `plumbbob@skills-dir` — the skills load namespaced (`/plumbbob:*`) and the
+// post-edit hook auto-registers from hooks/hooks.json. Global-only by design:
+// plumbbob is a personal tool (like firecrawl/gh), and install scope is NOT
+// session scope — sessions stay per-project via `plumbbob start`. Idempotent +
+// reversible (`--uninstall` drops the link); it NEVER writes settings.json.
+// Functional, node builtins only (C1/C2).
+import { lstatSync, mkdirSync, readlinkSync, rmSync, symlinkSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+// The installed package root (parent of .claude-plugin/, skills/, hooks/, dist/),
+// off this module's URL — the global install when run as the published bin, the
+// checkout in dev. No trailing slash, so it compares clean against a readlink.
+function packageRoot() {
+    return fileURLToPath(new URL('../../', import.meta.url)).replace(/\/+$/, '');
+}
+function linkPath(home) {
+    return join(home, '.claude', 'skills', 'plumbbob');
+}
+// lstat-based existence: true even for a broken symlink (existsSync follows the
+// link and would miss one whose target moved).
+function present(path) {
+    try {
+        lstatSync(path);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+// The symlink's target (no trailing slash), or null if `path` is not a symlink.
+function symlinkTarget(path) {
+    try {
+        return lstatSync(path).isSymbolicLink() ? readlinkSync(path).replace(/\/+$/, '') : null;
+    }
+    catch {
+        return null;
+    }
+}
+export function init(args) {
+    const home = process.env.HOME ?? homedir();
+    const link = linkPath(home);
+    const target = packageRoot();
+    if (args.includes('--uninstall')) {
+        return uninstall(link);
+    }
+    mkdirSync(join(home, '.claude', 'skills'), { recursive: true });
+    if (present(link)) {
+        const current = symlinkTarget(link);
+        if (current === null) {
+            process.stderr.write(`plumbbob: ${link} already exists and is not a plumbbob link. Move or remove it, then re-run \`plumbbob init\`.\n`);
+            return 1;
+        }
+        if (current === target) {
+            process.stdout.write(`plumbbob: already linked (${link} → ${target}). Nothing to do.\n`);
+            return 0;
+        }
+        rmSync(link); // a stale link from an earlier install location — repoint it
+    }
+    symlinkSync(target, link);
+    process.stdout.write(`plumbbob: linked ${link} → ${target}.\n` +
+        'plumbbob: Claude Code loads it as a plugin — skills as `/plumbbob:*`, the post-edit hook auto-registered from hooks.json. Restart Claude Code (or /reload-plugins) to activate.\n' +
+        'plumbbob: nothing else under ~ is touched and settings.json is left alone. Sessions are per-project — run `plumbbob start "<goal>"` in any repo, then `plumbbob doctor` to verify.\n');
+    return 0;
+}
+function uninstall(link) {
+    if (!present(link)) {
+        process.stdout.write(`plumbbob: nothing to uninstall — no link at ${link}.\n`);
+        return 0;
+    }
+    if (symlinkTarget(link) === null) {
+        process.stderr.write(`plumbbob: ${link} is not a plumbbob link (a real directory/file) — leaving it untouched.\n`);
+        return 1;
+    }
+    rmSync(link);
+    process.stdout.write(`plumbbob: unlinked ${link}. Restart Claude Code to drop the plugin.\n`);
+    return 0;
+}

package/dist/verbs/{reset.js → wrap.js}

@@ -1,6 +1,6 @@
-// `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/,
+// `plumbbob wrap` (D9) — the v2 close-out, replacing the v1 four-verb
+// finish ceremony. It archives intent + build-log + report
+// (the `/plumbbob:wrap` 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).
@@ -9,7 +9,7 @@ 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) {
+export function wrap(cwd) {
     const root = findRepoRoot(cwd);
     if (root === null || !hasSession(root)) {
         process.stderr.write('plumbbob: no active session. Run `plumbbob start "<title>"` first.\n');
@@ -20,7 +20,7 @@ export function reset(cwd) {
     }
     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');
+            '(/plumbbob:wrap 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
@@ -31,8 +31,8 @@ export function reset(cwd) {
     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');
+    process.stdout.write(`plumbbob: wrap — archived to ${relative(root, archived)}. Sidecar cleared. ` +
+        'Run `/plumbbob: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

package/hooks/hooks.json

@@ -0,0 +1,12 @@
+{
+  "hooks": {
+    "PostToolUse": [
+      {
+        "matcher": "Edit|Write|MultiEdit|NotebookEdit",
+        "hooks": [
+          { "type": "command", "command": "sh \"${CLAUDE_PLUGIN_ROOT}/hooks/post-edit.sh\"" }
+        ]
+      }
+    ]
+  }
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "plumbbob",
-  "version": "0.3.1",
-  "description": "Attention-first build process: eight skills + a CLI that keep you the decider — guidance, not enforcement.",
+  "version": "0.4.4",
+  "description": "Attention-first build process: 11 skills + a CLI that keep you the decider — guidance, not enforcement.",
   "keywords": [
     "claude-code",
     "claude",
@@ -24,6 +24,7 @@
     "pb": "dist/cli.js"
   },
   "files": [
+    ".claude-plugin",
     "dist",
     "hooks",
     "skills",
@@ -57,6 +58,6 @@
     "check:astgrep": "ast-grep scan",
     "check:test": "vitest run",
     "check:knip": "knip",
-    "check:md": "markdownlint --config .markdownlint.jsonc \"**/*.md\" --ignore node_modules"
+    "check:md": "markdownlint --config .markdownlint.jsonc \"**/*.md\" --ignore node_modules --ignore research"
   }
 }

package/skills/build/SKILL.md

@@ -0,0 +1,70 @@
+---
+name: build
+description: The optional engine — read the next planned step from intent, implement it (its done-when, seam, Decisions, Constraints), then verify it through to the approval pause. Skip it to build by hand/vibed/another harness. `--auto` self-approves and chains to done.
+disable-model-invocation: true
+model: opus
+allowed-tools: Read, Edit, Write, Bash(plumbbob status:*), Bash(plumbbob build:*), Bash(plumbbob check:*), Bash(plumbbob checkpoint:*), Bash(git diff:*)
+---
+
+# Plumbbob — build a step (the optional engine)
+
+Current session state (injected when this skill runs): !`plumbbob status 2>/dev/null || echo "plumbbob CLI not found - install the dep and re-run: npm i -g plumbbob && plumbbob init"`
+
+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 `/plumbbob: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.
+
+Since `/plumbbob:plan` lays down the whole step list up front, the happy path is to fire
+`/plumbbob:build` once per step until done — each run builds the next undone step and stops
+at the pause for your approval. **Re-firing `/plumbbob:build` is itself the clock tick.**
+
+## What this skill does, in order
+
+1. **Pick the step.** Use the number you were invoked with (e.g. `/plumbbob: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 `/plumbbob:step` first.
+2. **Enter the step.** Run `plumbbob build <n>` (records the in-flight STEP +
+   SEAM so `/plumbbob: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 `/plumbbob: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 `/plumbbob:verify`
+   does: `plumbbob 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 checkpoint`. Do **not** bump the version or changelog — that is
+   the human's `/version` call.
+
+## `--auto` — let the agent be the clock (opt-in)
+
+`/plumbbob:build --auto` is the explicit escape hatch when the human wants unattended
+progress instead of approving each step. It does the same work, but **the agent reviews
+and approves in the human's place**, and it **chains**:
+
+- Build the next step → `check` → self-review → **if the check is green AND the
+  self-review finds no done-when / Decision / Constraint mismatch, checkpoint** and move
+  straight on to the next planned step. Repeat.
+- **Stop and hand back to the human** the moment any of these is true: the check is red,
+  the self-review finds a mismatch (surface exactly what, and do not checkpoint it), a
+  new decision is needed, or no planned steps remain.
+
+`--auto` is the only path that checkpoints without a human pause, and only because the
+human asked for it by name. The default — no flag — always ends at the pause.
+
+## The hard contracts
+
+- **Optional, never required.** The loop works without this skill; `/plumbbob: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 `/plumbbob:park`, not an edit.
+- **Default ends at the pause.** Implement → verify → wait for approval; never
+  checkpoint without it. Only an explicit `--auto` lets the agent approve in your place,
+  and it still halts on a red check or any mismatch.

package/skills/{pb-harvest → harvest}/SKILL.md

@@ -1,16 +1,16 @@
 ---
-name: pb-harvest
+name: 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:*)
+allowed-tools: Read, Edit, Bash(plumbbob 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"`
+Current session state (injected when this skill runs): !`plumbbob status 2>/dev/null || echo "plumbbob CLI not found - install the dep and re-run: npm i -g plumbbob && plumbbob init"`
 
-`/pb-harvest` is the complement of `/pb-park` (D7): you parked ideas as seeds during a
+`/plumbbob:harvest` is the complement of `/plumbbob: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
@@ -19,7 +19,7 @@ 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`
+- `BUILD` — a step is in flight; **refuse** and suggest finishing it with `/plumbbob:verify`
   before harvesting. Chasing parked items mid-step is the disease parking prevents.
 - `DESIGN` (and other settled states) — go ahead.
 
@@ -40,7 +40,7 @@ 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`
+- **Flip the harvested item** from `- [ ]` to `- [x]` in the Park list, so `/plumbbob: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

package/skills/{pb-park → park}/SKILL.md

@@ -1,16 +1,16 @@
 ---
-name: pb-park
+name: 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:*)
+allowed-tools: Bash(plumbbob status:*), Bash(plumbbob 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"`
+Current session state (injected when this skill runs): !`plumbbob status 2>/dev/null || echo "plumbbob CLI not found - install the dep and re-run: npm i -g plumbbob && plumbbob init"`
 
-`/pb-park` is the **capture** half of the loop; `/pb-harvest` is where parked items
+`/plumbbob:park` is the **capture** half of the loop; `/plumbbob: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.
 
@@ -29,12 +29,12 @@ 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
+2. **Only after** that approval, capture it by running `plumbbob 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
+approval, then shell `plumbbob park` — that is the only write path. If approval
 never comes, capture nothing.

package/skills/plan/SKILL.md

@@ -0,0 +1,85 @@
+---
+name: plan
+description: "Frame a fresh goal and author the whole plan — Frame, Decisions, Constraints, and all Steps — before any code. Three input modes: no arg interviews you; a file path absorbs a spec; any other text expands your inline intent."
+disable-model-invocation: true
+model: opus
+allowed-tools: Read, Edit, Write, Bash(plumbbob status:*), Bash(plumbbob start:*)
+---
+
+# Plumbbob — plan a goal (the whole-goal move)
+
+Current session state (injected when this skill runs): !`plumbbob status 2>/dev/null || echo "plumbbob CLI not found - install the dep and re-run: npm i -g plumbbob && plumbbob init"`
+
+`/plumbbob: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. By default it authors the
+**complete plan, including all the Steps**, so the happy path afterward is just
+`/plumbbob:build` until done. (Revising a single increment later is the separate `/plumbbob:step`
+move; do not confuse the two.)
+
+## Three input modes (disambiguated for you — no quotes needed)
+
+Look at the argument the human gave and pick the mode yourself:
+
+1. **No argument → interview.** Walk the human through a short, friendly Q&A to draw
+   the plan out of their head (see *The interview* below).
+2. **The argument is a path to a file that exists → absorb the spec.** Read that file
+   and distill it into `intent.md`, **retaining enough detail that `intent.md` stands
+   on its own** — don't just link to the source. Add a one-line provenance
+   (`*Source: <path>*`) and, for anything sizable, a `## Source` appendix preserving
+   the original text. (Probe with the `Read` tool; if it isn't a real file, fall to
+   mode 3.)
+3. **Any other text → expand the inline intent.** Treat the text as the human's
+   rough plan, expand it into the full `intent.md`, and ask only about what is
+   genuinely ambiguous.
+
+All three modes converge on the **same artifact**: a complete, standalone `intent.md`
+an agent can follow with `/plumbbob:build`. The argument only seeds how you get there.
+
+## What this skill does
+
+1. **Scaffold.** If there is no active session, run `plumbbob 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. **Author the Steps.** Write the **full build plan** under `## Steps` — each step a
+   small, verifiable increment in the exact format the parser reads:
+
+   ```markdown
+   1. [ ] <title> — **done when:** <criterion, ideally a test or check result>
+      - seam: `<file>`, `<file>`
+   ```
+
+   Every step needs a **done-when** `/plumbbob:verify` can check and a **seam** (the exact
+   paths it touches). Later steps may be fuzzier than the first — that's fine; they get
+   sharpened just-in-time when you reach them with `/plumbbob:step`. Keep each small enough to
+   verify in one review pass.
+5. **Offer to stress-test it.** Suggest `/plumbbob:refine` to attack the frame for holes (or
+   to repair the plan as it drifts). Optional, the human's call.
+
+## The interview (mode 1)
+
+Make it easy and non-intrusive:
+
+- **Triage size first.** A tiny change earns a 3-line Frame and one Step, fast — never
+  ceremony on a one-liner. Scale the questions to the work.
+- **Propose, don't interrogate.** Offer concrete suggestions the human can **accept as-is
+  without typing** ("done-when: the 6th request in 60s returns 429 — good?"), while
+  taking arbitrary detail when they want to give it, including pointers to other files.
+- **Let them double back.** They will revise as the picture sharpens; that's expected.
+  They can also edit `intent.md` by hand at any time, or call `/plumbbob:refine` to repair it.
+
+## The hard contracts
+
+- **Deciding before code.** `/plumbbob: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.
+- **Stands on its own.** Whatever the input mode, the finished `intent.md` carries
+  enough detail to be followed without the chat or the external source.
+- **Size to the work.** A small change fills Frame + a couple of Decisions + a step or
+  two and stops; ceremony on a one-liner is the failure mode, not thoroughness.