plumbbob 0.3.0 → 0.4.2

package/dist/verbs/doctor.js

@@ -0,0 +1,74 @@
+// `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 { join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+// 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));
+}
+// Skill directories (those carrying a SKILL.md) under `dir`.
+function listSkills(dir) {
+    try {
+        return readdirSync(dir).filter((n) => existsSync(join(dir, n, 'SKILL.md')));
+    }
+    catch {
+        return [];
+    }
+}
+// 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;
+    }
+}
+function buildChecks(link, pkg, shipped) {
+    const installed = listSkills(join(pkg, 'skills'));
+    return [
+        { 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() {
+    const home = process.env.HOME ?? homedir();
+    const link = join(home, '.claude', 'skills', 'plumbbob');
+    const shipped = listSkills(packageDir('skills'));
+    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 (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.0",
-  "description": "Attention-first build process: eight skills + a CLI that keep you the decider — guidance, not enforcement.",
+  "version": "0.4.2",
+  "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`
+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`
+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.

package/skills/refine/SKILL.md

@@ -0,0 +1,45 @@
+---
+name: refine
+description: Keep intent.md true — attack the plan for holes (append as Open questions) and refine or repair the Frame, Decisions, Constraints, and Steps to match reality. Usable at any point; you propose, the human approves.
+disable-model-invocation: true
+model: opus
+allowed-tools: Read, Edit, Bash(plumbbob status:*)
+---
+
+# Plumbbob — refine the plan
+
+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:refine` keeps `intent.md` honest. Use it at **any point** — right after `/plumbbob:plan`
+to stress-test a fresh frame, or mid-build to repair a plan that drifted from what the
+code is actually doing. It is the document-level complement to `/plumbbob:step` (which only
+sharpens the *next* step): `/plumbbob:refine` works the *whole* plan.
+
+## No-session refusal
+
+This skill refines an existing plan, so it needs one. Read the state injected above: if
+it is `NO ACTIVE SESSION`, **refuse** in one line and tell the human to run
+`plumbbob start "<title>"` (or `/plumbbob:plan`) first, and edit nothing. Every active state
+is fine — refining is always available.
+
+## Two modes
+
+- **Attack (diverge in the problem space).** Hand the **Frame**, **Decisions**, and
+  **Architecture sketch** a cold, adversarial read and surface holes — ambiguities,
+  unhandled edge cases, hidden assumptions, collisions with the existing code. Append
+  each as a one-line question under `## Open questions`, **never** as a Decision:
+  resolving a hole is the human's convergence, not yours. This mode surfaces; it does
+  not decide.
+- **Repair (re-sync to reality).** When the plan has drifted — a Decision was overtaken
+  by what you built, a Constraint changed, a Step no longer matches the seam — propose
+  the edits that bring `intent.md` back in line with the truth. Show the before/after for
+  each, and **write only what the human approves**.
+
+## The hard contracts
+
+- **You propose; the human converges.** Surface holes and draft repairs, but the human
+  approves every change to `intent.md`. Never guess a hole into a Decision.
+- **Open questions for holes, edits for drift.** New uncertainty goes to
+  `## Open questions`; settled drift gets repaired in place once the human OKs it.
+- **Refine the plan, not the code.** `/plumbbob:refine` touches `intent.md` only — turning a
+  decision into a diff is `/plumbbob:build` or your own hands, never this skill.

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

@@ -1,19 +1,19 @@
 ---
-name: pb-revert
+name: revert
 description: Human-triggered driver for `plumbbob revert` — git reset --hard to a checkpoint SHA (discarding the half-done step) and return to DESIGN.
 disable-model-invocation: true
 model: haiku
-allowed-tools: Bash(__PLUMBBOB_BIN__ status:*), Bash(__PLUMBBOB_BIN__ revert:*)
+allowed-tools: Bash(plumbbob status:*), Bash(plumbbob 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 status 2>/dev/null || echo "plumbbob CLI not found - install the dep and re-run: npm i -g plumbbob && plumbbob init"`
 
 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.
 
 ## What it does
 
-1. Read an optional target step from the way you were invoked (e.g. `/pb-revert --to 2` → step `2`). With no target, revert goes to the last done-checkpoint.
-2. Run `__PLUMBBOB_BIN__ revert` (or `__PLUMBBOB_BIN__ revert --to <n>`) via Bash. This is a `git reset --hard` — it discards the current in-progress step. Run it exactly as the human asked; do not add or drop the `--to` on your own.
+1. Read an optional target step from the way you were invoked (e.g. `/plumbbob:revert --to 2` → step `2`). With no target, revert goes to the last done-checkpoint.
+2. Run `plumbbob revert` (or `plumbbob revert --to <n>`) via Bash. This is a `git reset --hard` — it discards the current in-progress step. Run it exactly as the human asked; do not add or drop the `--to` on your own.
 3. Report the verb's output verbatim — which checkpoint it reset to, or any refusal.

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

@@ -1,19 +1,19 @@
 ---
-name: pb-spike
+name: spike
 description: Human-triggered driver for `plumbbob spike` — open a throwaway worktree experiment for a genuine fork, or tear it down with `spike done`.
 disable-model-invocation: true
 model: haiku
-allowed-tools: Bash(__PLUMBBOB_BIN__ status:*), Bash(__PLUMBBOB_BIN__ spike:*)
+allowed-tools: Bash(plumbbob status:*), Bash(plumbbob 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 status 2>/dev/null || echo "plumbbob CLI not found - install the dep and re-run: npm i -g plumbbob && plumbbob init"`
 
 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.
 
 ## What it does
 
-1. Read the spike target from the way you were invoked: a slug to open one (e.g. `/pb-spike redis-cache`), or the literal `done` to tear the current spike down (`/pb-spike done`). If neither is present, ask which and run nothing.
-2. Run `__PLUMBBOB_BIN__ spike "<slug>"` or `__PLUMBBOB_BIN__ spike done` via Bash.
+1. Read the spike target from the way you were invoked: a slug to open one (e.g. `/plumbbob:spike redis-cache`), or the literal `done` to tear the current spike down (`/plumbbob:spike done`). If neither is present, ask which and run nothing.
+2. Run `plumbbob spike "<slug>"` or `plumbbob spike done` via Bash.
 3. Report the verb's output verbatim — the worktree it created or removed, or any refusal.

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

@@ -1,16 +1,16 @@
 ---
-name: pb-status
+name: status
 description: Show the orientation dashboard — where you are, what's done, what's parked, and the next move. A thin trigger for `plumbbob status`.
 disable-model-invocation: true
 model: haiku
-allowed-tools: Bash(__PLUMBBOB_BIN__ status:*)
+allowed-tools: Bash(plumbbob 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 status 2>/dev/null || echo "plumbbob CLI not found - install the dep and re-run: npm i -g plumbbob && plumbbob init"`
 
-This is a **thin driver** for `__PLUMBBOB_BIN__ status`. The dashboard above is your
+This is a **thin driver** for `plumbbob status`. The dashboard above is your
 orientation — the intent, the step list, the parked/open-question counts, and the
 inferred next move. Report it verbatim and point the human at that next move. This
 skill carries **no Edit and no Write tool**: the CLI is the source of truth, so
@@ -19,4 +19,4 @@ skill carries **no Edit and no Write tool**: the CLI is the source of truth, so
 ## What it does
 
 1. Surface the injected `status` output — the dashboard and its suggested next move.
-2. If it reads `NO ACTIVE SESSION`, tell the human to `/pb-plan` to frame a goal.
+2. If it reads `NO ACTIVE SESSION`, tell the human to `/plumbbob:plan` to frame a goal.

package/skills/step/SKILL.md

@@ -0,0 +1,49 @@
+---
+name: step
+description: Revise the next increment just-in-time — sharpen the next undone step against what's now true, or (with input) re-cut, split, or add a step. Empty input runs an automatic sharpen. One at a time; the human approves.
+disable-model-invocation: true
+model: opus
+allowed-tools: Read, Edit, Bash(plumbbob status:*)
+---
+
+# Plumbbob — revise the next step (the single-increment 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` authors the **whole** step list up front, so `/plumbbob:step` is the
+**just-in-time revision** move: it keeps the *next* undone step honest against what the
+build has actually taught you, right before you `/plumbbob:build` it. (Framing the whole goal
+is the separate `/plumbbob:plan` move.) It can also add or re-cut a step when scope genuinely
+grew — but its everyday job is to sharpen, not to invent.
+
+## Two ways to fire it
+
+- **`/plumbbob:step` (no input) → automatic sharpen.** Re-examine the next undone step
+  against the completed code, the Decisions, the Constraints, and the build-log, then
+  make the obvious revisions to its **done-when** and **seam** so it matches reality —
+  e.g. a file moved, a decision narrowed the scope, an earlier step already did part of
+  it. This is the zero-effort "keep my next step in sync" move: if the human does
+  nothing else, the next step stays current.
+- **`/plumbbob:step <what changed>` → directed revision.** Take the human's input and propose
+  the matching change: tighten the done-when, adjust the seam, split the step in two, or
+  add a new increment the plan was missing.
+
+## What this skill does
+
+1. **Read the plan and the reality.** Read `intent.md`'s Frame, Decisions, Constraints,
+   and the steps already done, plus the next undone step, to see what it *should* now be.
+2. **Propose the revision** (or the new/split step): a one-line **title**, a **done-when**
+   `/plumbbob:verify` can validate, and a **seam** (exact paths, or a `dir/` grant). Keep it
+   small enough to verify in one review pass. Show the before/after so the human can see
+   what you changed and why.
+3. **Get the human's OK**, then write it into `## Steps` in the standard format —
+   `N. [ ] <title> — **done when:** <criterion>` with a `- seam:` sub-line. Revise the
+   existing step in place; only append when you are genuinely adding an increment.
+
+## The hard contracts
+
+- **One verifiable increment.** Each step carries a done-when `/plumbbob:verify` can check
+  and a seam small enough to review in one pass.
+- **Edit `## Steps` only**, in the standard format `status` and `build` parse — never
+  the Roadmap, never loose prose. A done step (`[x]`) is history; do not rewrite it.
+- **The human approves the revision** before it lands. You propose; they decide.