plumbbob 0.6.1 → 0.6.4

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "plumbbob",
   "displayName": "PlumbBob",
-  "version": "0.6.1",
+  "version": "0.6.4",
   "description": "Attention-first build process — driver skills + a CLI that keep you the decider; guidance, not enforcement.",
   "author": { "name": "Rob McLarty", "email": "hello@robmclarty.com", "url": "https://robmclarty.com" },
   "homepage": "https://github.com/robmclarty/plumbbob#readme",

package/README.md

@@ -1,7 +1,7 @@
 # PlumbBob
 
 <p align="center">
-  <img src="hero.jpg" alt="A row of plumb bobs of varying shapes hanging from strings" width="600">
+  <img src="hero.svg" alt="A row of plumb bobs of varying shapes hanging from strings" width="600">
 </p>
 
 PlumbBob is a Claude Code plugin — twelve `/pb-*` skills and a small CLI — that runs
@@ -80,7 +80,7 @@ In Claude Code, inside any git repo with a clean tree:
 
 1. **Plan.** Fire `/pb-plan` and give it whatever you have — nothing (it interviews
    you), a rough line (`/pb-plan rate-limit POST /login, 5/min/IP, return 429`), or a
-   path to a spec file. Together you fill `.plumbbob/intent.md`. No code is written
+   path to a spec file. Together you fill the build's `intent.md`. No code is written
    yet.
 2. **Build.** Fire `/pb-build`. It implements the next undone step, runs the
    heavy check gate, reviews its own diff against the plan, and stops:
@@ -115,21 +115,40 @@ every move, and `/pb-status` always names your next one. (Claude Code namespaces
 under the plugin — the real command is `/plumbbob:pb-plan`; for readability these docs
 write the short form `/pb-plan`.)
 
-| Skill | Does |
-|-------|------|
+**The happy path** — the three moves every session makes; many sessions need
+nothing else:
+
+| Skill <img alt="" width="110" height="1"> | Does |
+|------------------------------------|------|
 | `/pb-plan` | plan the whole goal — open the session and author intent's Frame, Decisions, Constraints, **and all Steps** |
+| `/pb-build` | implement the next planned step, then verify it to the pause — `--auto` self-approves and chains to done; a range like `1-3` self-approves through step 3, then pauses |
+| `/pb-finish` | finish up — write the report, make the final commit, clear for a fresh goal |
+
+**Plan-shaping moves** — optional, for when the plan needs work mid-flight:
+
+| Skill <img alt="" width="110" height="1"> | Does |
+|------------------------------------|------|
 | `/pb-step` | revise/sharpen the next step (empty input auto-syncs it to reality) |
-| `/pb-build` | *(optional)* implement the next planned step, then verify it to the pause — `--auto` self-approves and chains to done |
-| `/pb-verify` | the tick — check → self-review → validate → **PAUSE** → checkpoint |
-| `/pb-park` | capture a mid-build idea without chasing it |
+| `/pb-refine` | attack the frame for holes, or repair a drifted plan |
+| `/pb-spike` | throwaway worktree experiment for a fork the plan can't settle |
+
+**Helpers** — orient, verify, recover, diagnose:
+
+| Skill <img alt="" width="110" height="1"> | Does |
+|------------------------------------|------|
 | `/pb-status` | orient — where you are, the next step's done-when and seam, and the next move |
+| `/pb-verify` | the tick, standalone — check → self-review → validate → **PAUSE** → checkpoint, for a diff `/pb-build` didn't write |
+| `/pb-revert` | recover — `git reset --hard` to a recorded checkpoint |
+| `/pb-doctor` | check the install from inside a session |
+
+**Capture** — the park/harvest loop for mid-build ideas:
+
+| Skill <img alt="" width="110" height="1"> | Does |
+|------------------------------------|------|
+| `/pb-park` | capture a mid-build idea without chasing it |
 | `/pb-harvest` | triage parked ideas between steps (blocker / tangent / pivot) |
-| `/pb-finish` | finish up — write the report, make the final commit, clear for a fresh goal |
 
-Three power moves round it out — `/pb-revert` (recover to a checkpoint), `/pb-spike`
-(throwaway worktree experiment for a fork the plan can't settle), and `/pb-refine`
-(attack the frame for holes or repair a drifted plan) — plus `/pb-doctor` to check
-your install. All twelve, with inputs and effects, are in
+All twelve, with inputs and effects, are in
 [`docs/skills-reference.md`](docs/skills-reference.md).
 
 Under the skills ships a lean `plumbbob` CLI (the mechanical verbs the
@@ -139,10 +158,10 @@ flow), and a `.plumbbob/` sidecar you can open and edit by hand at any time —
 that rides the branch into the PR, plus an untracked control plane (`settings.local.json`,
 the session sentinel, the in-flight markers).
 
-**`/pb-build` is optional.** It's one executor, not the loop. Implement a step by
-hand — or vibe it in another session, or in another harness entirely — and run
-`/pb-verify` instead: same checks, same pause, same checkpoint. It reads the *diff,
-not the author*.
+**`/pb-build` is the default engine, not the only one.** It's one executor — the
+loop doesn't care who writes the code. Implement a step by hand — or vibe it in
+another session, or in another harness entirely — and run `/pb-verify` instead:
+same checks, same pause, same checkpoint. It reads the *diff, not the author*.
 
 **Bring your own agents.** Because the executor is author-blind, you can plug your
 own in. A **user-authored agent** is any executable that speaks one small JSON
@@ -194,7 +213,7 @@ actually learning is the method: decisions before code, one verified step at a
 time, capture instead of chase. That transfers to whatever tool wins. If
 something better ships, you walk away with your archives and your habits intact.
 
-**…admit the pause is unenforceable?** It is — on purpose (D10/D13 in
+**…admit the pause is unenforceable?** It is — on purpose ([D10](docs/decisions.md#d10)/[D13](docs/decisions.md#d13) in
 [`docs/decisions.md`](docs/decisions.md)). A hard lock buys ritual, not control:
 a determined model routes around it. So PlumbBob enforces deterministically where
 it can — `checkpoint` refuses on a red check, `revert` restores only recorded
@@ -211,7 +230,8 @@ Each doc answers one question — in rough reading order for a new user:
 - *Should I / can I / what about…?* → [`docs/faq.md`](docs/faq.md) — the adoption questions, answered straight.
 - *What is each method for?* → [`docs/techniques.md`](docs/techniques.md) — steps, seams, the pause, park/harvest, spikes.
 - *What does each skill do?* → [`docs/skills-reference.md`](docs/skills-reference.md) — all twelve `/pb-*` skills: inputs, effects, when to reach for each.
-- *How do I plug in my own agent?* → [`docs/agents.md`](docs/agents.md) — the subprocess envelope, the manifest, `harness.json`, and a working example.
+- *How do I plug in my own agent?* → [`docs/agents.md`](docs/agents.md) — the subprocess envelope, the manifest, `harness.json`, and working examples (including a local-model reviewer via Ollama).
+- *How do I get a local model reviewing my steps?* → [`docs/local-model-review.md`](docs/local-model-review.md) — the ollama-reviewer example walked end to end, install to every-pause review.
 - *How do I install it, exactly?* → [`docs/install.md`](docs/install.md) — the full guide and the agent-neutral roadmap.
 - *What does the CLI underneath do?* → [`docs/cli-reference.md`](docs/cli-reference.md) — every verb, flag, exit code, and the `.plumbbob/` sidecar.
 - *Something's broken.* → [`docs/troubleshooting.md`](docs/troubleshooting.md) — fixes for the common snags.

package/dist/verbs/build.js

@@ -13,6 +13,13 @@ export function build(cwd, args) {
     }
     const { build: slug, rest } = resolveBuild(root, args);
     const raw = rest.find((a) => !a.startsWith('--'));
+    // A step range like `1-3` is a `/pb-build` skill affordance (auto-approve
+    // through the range, then pause), not a CLI capability — the CLI records one
+    // in-flight step at a time. Name it rather than bounce off the generic usage.
+    if (raw !== undefined && /^\d+-\d*$/.test(raw)) {
+        process.stderr.write(`plumbbob: build takes one step number; \`${raw}\` step ranges are a \`/pb-build\` feature (auto-approve through the range, then pause). Try \`plumbbob build ${raw.split('-')[0]}\`.\n`);
+        return 1;
+    }
     if (raw === undefined || !/^\d+$/.test(raw) || Number(raw) < 1) {
         process.stderr.write('plumbbob: build needs a step number. Try: plumbbob build 2.\n');
         return 1;

package/package.json

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

package/skills/pb-build/SKILL.md

@@ -1,18 +1,18 @@
 ---
 name: pb-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.
-argument-hint: "[step-number] [--auto]"
+description: The default engine — read the next planned step from intent, implement it (its done-when, seam, Decisions, Constraints), then verify it through to the approval pause. Swappable — build by hand/vibed/another harness and run /pb-verify instead. `--auto` self-approves and chains to done; a step range like `1-3` self-approves through step 3, then pauses.
+argument-hint: "[step-number | step-range] [--auto]"
 disable-model-invocation: true
 model: opus
 allowed-tools: Read, Edit, Write, Bash(plumbbob status:*), Bash(plumbbob build:*), Bash(plumbbob check:*), Bash(plumbbob checkpoint:*), Bash(plumbbob agent:*), Bash(git diff:*)
 ---
 
-# PlumbBob — build a step (the optional engine)
+# PlumbBob — build a step (the default engine)
 
 Current session state (injected when this skill runs): !`plumbbob status 2>/dev/null || echo "plumbbob CLI not on PATH in this session. Marketplace install: confirm the plugin is enabled in /plugin, then /reload-plugins. Skills-dir/global install: 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
+This is the **bundled executor** — the default engine, not the only one. It is
+**swappable** (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.
@@ -23,9 +23,11 @@ at the pause for your approval. **Re-firing `/pb-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. `/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.
+1. **Pick the step.** Use the number you were invoked with (e.g. `/pb-build 4`) — or,
+   if you were given a range like `/pb-build 1-3`, start at the first number and treat
+   the second as the auto-approve ceiling (see the range note under `--auto`). With no
+   argument, take 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 build <n>` (records the in-flight STEP +
    SEAM so `/pb-status` shows the step in flight; the seam is awareness, not a
    lock).
@@ -92,21 +94,45 @@ and approves in the human's place**, and it **chains**:
 - **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
   bound agent returns `blocked` or `drift` (unblock-and-re-run, or `/pb-refine` — an
-  agent cannot advance the loop, C6), a new decision is needed, or no planned steps
-  remain.
+  agent cannot advance the loop, C6), a new decision is needed, no planned steps
+  remain, or the top of a requested range is reached.
 
-`--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.
+`--auto` and a step range are the only paths that checkpoint without a human pause, and
+only because the human asked for it by name; a range re-imposes the pause at its top.
+The default — no flag, no range — always ends at the pause.
+
+### A step range (`N-M`) is a bounded `--auto`
+
+`/pb-build 1-3` self-approves steps 1 through 3 exactly as `--auto` does, then **pauses
+after step 3** instead of chaining to done. The range *is* the opt-in — you do not also
+pass `--auto`. Run it as the `--auto` loop with one extra halt: **stop before building
+any next step whose plan number is past the top of the range.** It adds no machinery —
+just the one more entry already in the halt list above.
+
+- **`N-M` with N ≤ M** — build N…M, self-approving and checkpointing each, then pause at
+  M. `N-N` is just the single step `N` (which already ends at the pause).
+- **N > M** (e.g. `3-1`) — that is not a range you can walk; report it and stop rather
+  than guess the intent.
+- **M past the last planned step** (e.g. `1-9` with three steps) — build through the
+  last planned step and stop; that is the existing "no planned steps remain" halt, not
+  an error.
+- **A step inside the range won't build** (missing, or its seam won't parse) — `plumbbob
+  build <n>` fails exactly as it always does; surface it and stop, the same as a red
+  check. Do not skip past the gap.
+- **N is above the next undone step** — you are jumping over earlier planned work; note
+  that you are skipping the steps before N, then proceed (the same latitude as a
+  single-number jump like `/pb-build 4`).
 
 ## The hard contracts
 
-- **Optional, never required.** The loop works without this skill; `/pb-verify`
+- **Swappable, 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.
 - **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.
+  checkpoint without it. Only an explicit `--auto` or a step range lets the agent approve
+  in your place, and it still halts on a red check or any mismatch — a range also stops
+  at its top.
 - **Agents feed the beat; they never advance it** (C6/D45). `before` loads context,
   `build` writes the diff, `after` is advisory — none can checkpoint, flip a step, or
   chain. `blocked` → unblock and re-run; `drift` → `/pb-refine`. You are still the one