plumbbob 0.4.11 → 0.4.13

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "plumbbob",
   "displayName": "PlumbBob",
-  "version": "0.4.11",
+  "version": "0.4.13",
   "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

@@ -4,272 +4,116 @@
   <img src="hero.jpg" alt="A row of plumb bobs of varying shapes hanging from strings" width="600">
 </p>
 
-A guidance-first build process for working *with* an LLM instead of being dragged
-behind one. It's the layer below Ridgeline: where Ridgeline runs autonomously
-without you, Plumbbob keeps you in the driver's seat for the small-to-medium work
-that doesn't justify a full autonomous build — a feature, a bug, a refactor — while
-staying deliberate rather than vibing. You decide on a surface outside the chat;
-Plumbbob orients you, runs each step's labor, and then **stops and waits for you to
-advance** — the human is the clock, not a lock.
+A [guidance-first build process](docs/attention-first-development.md) for working
+*with* an LLM instead of being dragged behind one. It's the layer below [Ridgeline](https://github.com/robmclarty/ridgeline):
+where Ridgeline runs autonomously without you, PlumbBob keeps you in the driver's seat
+for the small-to-medium work that doesn't justify a full autonomous build — a feature,
+a bug, a refactor — while staying deliberate rather than vibing. You decide on a surface
+outside the chat; PlumbBob orients you, runs each step's labor, and then **stops and
+waits for you to advance** — the human is the clock, not a lock.
+
+> Establish *plumb* before you build. The LLM is a hand, not a head.
+
+The name is the method. A plumb bob is a weight on a string — gravity pulls it into
+a perfectly straight vertical line, the builder's oldest reference for *true*: the
+fixed mark you hold the work against so it never drifts out of square. PlumbBob hangs
+your **intent** as that line and keeps every step aligned to it, so the build stays
+plumb with what you decided instead of wandering off behind the model.
+
+Its one law is **vibe to execute, never vibe to decide**: the human owns every
+decision, the LLM owns the labor, and the boundary between them is a **pause you
+advance**, not a wall that refuses you. The *why* behind that — attention as the
+scarce resource — is the subject of the guidance-first article above; the *how* of
+each method is in [`docs/techniques.md`](docs/techniques.md). This repository was
+built using PlumbBob, dogfooded on its own build under its own loop.
 
-> Ridgeline is the line. Plumbbob establishes *true* before you build.
-> The LLM is a hand, not a head.
-
-This repository was built using Plumbbob v2, dogfooded on its own build under its
-own loop.
-
-## The one law
-
-**Vibe to execute, never vibe to decide.**
-
-Vibing is fine — *once every decision being carried out was already made on a
-surface outside the chat.* It becomes a slot machine only when the deciding happens
-inside the stream while code is flowing. The whole job of Plumbbob is to keep
-decisions and execution from fusing:
-
-- The **human** owns convergence. You decide, choose, pick the branch.
-- The **LLM** owns divergence in design (finding holes, generating options) and
-  convergence *only* in build (executing a decided step).
-- The **boundary** between deciding and executing is held by a **pause you
-  advance**, not a wall that refuses you.
-
-If you feel tired and lost, those two activities have fused again. The fix is never
-"prompt better." It's "stop, leave the chat, go decide, come back."
-
-## Why it works: get the plan out of your head
-
-The exhaustion is a working-memory problem. You can't *produce* intent and
-*consume* the model's output at once — consuming overwrites producing. So Plumbbob
-externalizes your plan onto durable surfaces that survive the flood:
-
-- `intent.md` — what you decided, before any code. Your canonical intent.
-- `build-log.md` — the live ledger of steps, parked ideas, and decisions.
-
-When the model floods you, you read the page, not your memory. The chat is
-ephemeral; the docs persist. **The chat is a hand; the docs are the head.**
-
-## The shift: a clock, not a lock
-
-Plumbbob v1 enforced the deciding/executing boundary with a hard file lock — a
-pre-edit muzzle that *refused* code edits unless you were in the right state. It
-provided no real security (a determined model routed around it), so its only product
-was forced ritual.
-
-v2 replaces the lock with a **clock**. Nothing blocks your edits. Instead, the
-system does a step's work, then pauses at a verify gate for your approval before it
-checkpoints. You stay the decider not because a wall refuses you, but because the
-loop pulls up to a line — the verify pause — and idles there until you approve.
-Pull, not block. The pause *is* the product; it is the moment your judgment enters,
-and it cannot be skipped.
-
-## The eight skills
-
-You drive the whole loop from your IDE with eight `/plumbbob:*` skills — no step numbers to
-remember, no raw CLI to type. Each is `disable-model-invocation`, so *you* fire
-every move, and `/plumbbob:pb-status` always names your next one.
-
-| Skill | Does |
-|-------|------|
-| `/plumbbob:pb-plan` | plan the whole goal — scaffold the session + author intent's Frame, Decisions, Constraints, **and all Steps** |
-| `/plumbbob:pb-step` | revise/sharpen the next step (empty input auto-syncs it to reality) |
-| `/plumbbob:pb-build` | *(optional)* implement the next planned step, then verify it to the pause — `--auto` self-approves and chains to done |
-| `/plumbbob:pb-verify` | the tick — check → self-review → validate → **PAUSE** → checkpoint |
-| `/plumbbob:pb-park` | capture an idea without chasing it |
-| `/plumbbob:pb-status` | orient — where you are, the next step's done-when + seam, and the next move |
-| `/plumbbob:pb-harvest` | triage parked ideas at a boundary (blocker / tangent / pivot) |
-| `/plumbbob:pb-wrap` | wrap up — write the report, archive safely, clear for a fresh goal |
-
-Three optional power moves survive for when you need them: `/plumbbob:pb-revert` (recover to
-a checkpoint), `/plumbbob:pb-spike` (throwaway worktree experiment), and `/plumbbob:pb-refine` (attack
-the frame for holes, or repair the plan when it drifts — usable at any point).
-
-## The loop
-
-The happy path is **plan the whole thing up front, then drive `/plumbbob:pb-build` until
-done** — approving each step at its verify pause:
-
-```text
-/plumbbob:pb-plan                      author the whole plan (incl. all steps)   (once)
-  └ per step:
-       /plumbbob:pb-status             review the next step (done-when + seam)
-       /plumbbob:pb-step   (optional)  sharpen/revise it first if needed
-       /plumbbob:pb-build  (or DIY)    implement it → verify → PAUSE → checkpoint
-       /plumbbob:pb-park               capture strays mid-build
-       /plumbbob:pb-harvest            triage them at a boundary
-  /plumbbob:pb-wrap                    report + archive + clear                  (once)
-```
-
-Each `/plumbbob:pb-build` builds the next undone step and stops at the pause for your
-approval — re-firing it is itself the clock tick. (`/plumbbob:pb-build --auto` is the opt-in
-that lets the agent self-approve and chain to done, halting on a red check or any
-mismatch.) For a worked example that walks one goal end to end — planning, building
-each step, wrapping up, archiving, and starting the next task — see
-[`docs/happy-path.md`](docs/happy-path.md).
-
-**Three ways to plan.** `/plumbbob:pb-plan` produces the same artifact — a complete, standalone
-`intent.md` — from whichever seed you give it: **no argument** runs a short interview;
-**a file path** absorbs an out-of-band spec (retaining its detail so the plan stands on
-its own); **any other text** expands your inline intent. No quotes required — it
-disambiguates the mode itself.
-
-**The pluggable executor.** `/plumbbob:pb-build` is one way to turn a planned step into code
-— it is *optional*. Implement by hand, in a vibe session, or with another harness,
-and run `/plumbbob:pb-verify` instead: it reads the *diff, not the author*. Plumbbob is the
-harness-agnostic spine; how the diff appears is a slot you fill however you like.
-
-## Calibration: size everything to the work
-
-The fastest way to abandon this is ceremony on a one-liner. The discipline is
-*decisions before code*, not *always produce three files*.
-
-- **Tiny** (typo, one-liner): no session. Just fix it.
-- **Small** (a contained bug/change): `/plumbbob:pb-plan` a frame + 2–3 decisions; one or two
-  steps; build → verify → checkpoint.
-- **Medium** (a feature touching a few modules): the full loop above.
-- **Large / architectural**: that's Ridgeline's job, not Plumbbob's.
-
-Calibration is the skill. When in doubt, smaller.
-
-## What ships
-
-- A `plumbbob` CLI (TypeScript, run natively by Node ≥ 22.18, zero runtime
-  dependencies) — the dumb mechanical verbs the skills shell out to. You never type
-  it by hand (beyond `plumbbob --help` and `plumbbob --version`). The marketplace
-  plugin carries it on PATH via `bin/` shims; `npm i -g` installs it globally.
-- The eight `/plumbbob:*` skills plus the optional power moves, each
-  `disable-model-invocation` so *you* fire every move.
-- One session-gated Claude Code hook — `post-edit.sh`, a non-blocking light-feedback
-  pass that injects file-scoped lint into the model's context so it self-corrects in
-  flow. (v1's pre-edit muzzle, seam-guard, and bash-guard are gone — guidance, not
-  enforcement.)
-- A `.plumbbob/` sidecar of flat files: `STATE` (the session sentinel — its presence
-  means a session is live), `intent.md`, `build-log.md`, `checkpoints`, and `archive/`.
-
-## Gates — two tiers, different jobs
-
-- **Light** — the non-blocking `post-edit` feedback above. Per changed file. Never
-  blocks an edit. It exists only because Claude can't see your editor's LSP, so the
-  light tier *serves the model*.
-- **Heavy** — the full `pnpm check` (tsc, oxlint, ast-grep, vitest, knip,
-  markdownlint). Not a hook: it runs *inside* `/plumbbob:pb-verify`, which refuses to
-  checkpoint while red. The hard gate lives on the deliberate boundary, not the
-  keystroke.
-
-## Position is derived, not stored
-
-There is no stored state machine. The dashboard's phase — `DESIGN`, `BUILD`, or `SPIKE` —
-is *derived* from what's on disk: a `STEP` file means a step is in flight (BUILD), the
-`SPIKE` marker means a fork is open (SPIKE), otherwise you're at a boundary (DESIGN). The
-position gates nothing — it's a label on a map, read by `/plumbbob:pb-status` to tell you
-where you are and what to do next, never a locked door. `.plumbbob/STATE` is just the
-session sentinel: its presence means a session is live, and the post-edit hook is gated on
-it, so a repo with no `.plumbbob/STATE` behaves exactly like plain Claude Code.
-
-## Git footprint — additive only
+## Install
 
-Plumbbob commits cheap checkpoint markers (`plumbbob: step n done`) on your feature
-branch and reverts to its own recorded SHAs. It **never rewrites pushed history**;
-your normal squash-merge collapses the checkpoints at PR time. `start` records the
-baseline HEAD; `revert [--to n]` does `git reset --hard` to a recorded SHA; `wrap`
-archives plain markdown under `.plumbbob/archive/` and never touches git.
+PlumbBob installs **once, globally** — like `gh` or your dotfiles — in one of two
+co-equal, mutually-exclusive ways (both register a Claude Code plugin named
+`plumbbob`).
 
-## The `.plumbbob/` folder
+**Marketplace plugin** — self-contained; ships the skills *and* the CLI on PATH, so
+it needs neither `npm` nor `init`:
 
 ```text
-.plumbbob/
-  STATE          # session sentinel — its presence means a session is live
-  SEAM           # the in-flight step's declared paths (awareness, not a lock)
-  STEP           # the in-flight step number (its presence is the BUILD phase)
-  SPIKE          # marker — present while a spike fork is open
-  config         # key=value; check=<heavy-check command> (defaults to pnpm run check)
-  checkpoints    # "baseline <sha>" then "step N <sha>", one per verified step
-  intent.md      # canonical intent
-  build-log.md   # live ledger
-  archive/
-    <date>-<slug>/
-      intent.md
-      build-log.md
-      report.md
+/plugin install plumbbob@<marketplace>
 ```
 
-## Install
-
-Plumbbob installs **once, globally** — like `gh` or your dotfiles. There are two co-equal,
-mutually-exclusive ways to do it (both register a Claude Code plugin named `plumbbob`;
-running both collides over the `/plumbbob:*` namespace).
-
-**npm global + `init`** — the npm package ships the CLI, the skills, and the hook; `plumbbob
-init` links them into Claude Code as an in-place plugin:
+**npm global + `init`** — installs the CLI, then links the skills and hook into
+Claude Code in place:
 
 ```sh
 npm i -g plumbbob      # the CLI (also a `pb` shorthand)
 plumbbob init          # link it into Claude Code; --uninstall to undo
 ```
 
-`init` symlinks the package into `~/.claude/skills/plumbbob`, where Claude Code loads it as a
-plugin; the post-edit hook auto-registers from `hooks.json`. Because it's a symlink, a later
-`npm i -g plumbbob@latest` stays live with no re-link.
-
-**The marketplace plugin** — self-contained: it ships the skills *and* the `plumbbob`/`pb`
-CLI on PATH (via its `bin/` shims), so it needs neither `npm i -g` nor `plumbbob init`:
-
-```text
-/plugin install plumbbob@<marketplace>
-```
-
-Either way, Claude Code namespaces the skills as `/plumbbob:<skill>`, so they appear as
-`/plumbbob:pb-plan`, `/plumbbob:pb-status`, and the rest. Nothing else under `~` is touched
-and `settings.json` is left alone — restart Claude Code (or `/reload-plugins`) to activate.
-If a marketplace plumbbob is already installed, `plumbbob init` refuses rather than create
-the collision (`--force` overrides), and `plumbbob doctor` flags a double-install.
+Restart Claude Code (or `/reload-plugins`) to activate, then run `plumbbob doctor`
+(or `/pb-doctor` in-session) to confirm the wiring. The full guide — namespacing,
+per-project sessions, the agent-neutral roadmap — is in
+[`docs/install.md`](docs/install.md).
 
-**Sessions are per-project.** Install scope is not session scope: you install the
-tool once, but each goal lives in its own repo — `plumbbob start "<goal>"` writes a
-`.plumbbob/` sidecar there, independent of the one global link.
+## Features
 
-**Other agents (roadmap).** The npm package is the agent-neutral carrier; a future
-`plumbbob init --host codex|cursor|zed` will place the same skills where those tools
-look. Claude Code is the first, first-class target.
+You drive the whole loop from your IDE with `/plumbbob:*` skills — no step numbers to
+remember, no raw CLI to type. Each is `disable-model-invocation`, so *you* fire every
+move, and `/pb-status` always names your next one. (For readability these docs write
+the short form: `/pb-plan` means `/plumbbob:pb-plan`.)
 
-### Verify
+| Skill | Does |
+|-------|------|
+| `/pb-plan` | plan the whole goal — scaffold the session and author intent's Frame, Decisions, Constraints, **and all Steps** |
+| `/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 an idea without chasing it |
+| `/pb-status` | orient — where you are, the next step's done-when + seam, and the next move |
+| `/pb-harvest` | triage parked ideas at a boundary (blocker / tangent / pivot) |
+| `/pb-wrap` | wrap up — write the report, archive safely, clear for a fresh goal |
+
+Three power moves round it out — `/pb-revert` (recover to a checkpoint), `/pb-spike`
+(throwaway worktree experiment), and `/pb-refine` (attack the frame for holes or
+repair a drifted plan) — plus `/pb-doctor` to check your install.
+
+Under the skills ships a zero-dependency `plumbbob` CLI (the mechanical verbs the
+skills shell out to), one session-gated post-edit hook (non-blocking lint feedback in
+flow), and a `.plumbbob/` sidecar of flat files (`intent.md`, `build-log.md`,
+checkpoints, archive). `/pb-build` is just one executor — implement a step by hand or
+in any other harness and run `/pb-verify` instead; it reads the *diff, not the author*.
+
+## Getting started
+
+The happy path is **plan the whole thing up front, then drive `/pb-build` until
+done** — approving each step at its verify pause:
 
-```sh
-plumbbob doctor
+```text
+/pb-plan                      author the whole plan (incl. all steps)   (once)
+  └ per step:
+       /pb-status             review the next step (done-when + seam)
+       /pb-step   (optional)  sharpen/revise it first if needed
+       /pb-build  (or DIY)    implement it → verify → PAUSE → checkpoint
+       /pb-park               capture strays mid-build
+       /pb-harvest            triage them at a boundary
+  /pb-wrap                    report + archive + clear                  (once)
 ```
 
-`doctor` works for either install path: it confirms a marketplace plugin, or checks that the
-skills-dir link resolves to the plugin manifest, the skills, and the hook — flagging a
-double-install collision — and prints the exact fix for anything broken. The terminal command
-above is for the **global / skills-dir** install; a **marketplace** plugin puts the CLI on
-PATH only *inside a Claude Code session*, so run **`/plumbbob:pb-doctor`** there instead. Run
-it first if a `/plumbbob:*` skill ever opens with an empty dashboard;
-[`docs/troubleshooting.md`](docs/troubleshooting.md) covers the rest.
-
-## Development
-
-```sh
-pnpm install
-pnpm check     # tsc, oxlint, ast-grep, vitest, knip, markdownlint
-pnpm build     # emit dist/ (what the published bin runs)
-```
+Each `/pb-build` builds the next undone step and stops at the pause for your
+approval — re-firing it is itself the clock tick. (`/pb-build --auto` is the opt-in
+that lets the agent self-approve and chain to done, halting on a red check or any
+mismatch.) For one goal walked end to end — planning, building each step, wrapping
+up, and starting the next — see [`docs/happy-path.md`](docs/happy-path.md).
 
 ## Documentation
 
+- [`docs/install.md`](docs/install.md) — the full install guide and the agent-neutral roadmap.
 - [`docs/techniques.md`](docs/techniques.md) — the methods behind the loop, each on its own.
 - [`docs/happy-path.md`](docs/happy-path.md) — one goal walked end to end.
-- [`docs/cli-reference.md`](docs/cli-reference.md) — every verb, flag, and exit code.
+- [`docs/cli-reference.md`](docs/cli-reference.md) — every verb, flag, exit code, and the `.plumbbob/` sidecar.
 - [`docs/troubleshooting.md`](docs/troubleshooting.md) — fixes for the common snags.
 - [`docs/decisions.md`](docs/decisions.md) — the `D#` / `C#` design-decision key.
 - [`docs/attention-first-development.md`](docs/attention-first-development.md) — the philosophy: attention as the scarce resource.
 - [`CONTRIBUTING.md`](CONTRIBUTING.md) — setup, conventions, and how to submit changes.
 
-## The shape, in one line
-
-The human owns convergence; the LLM owns divergence in design and convergence only
-in implementation; and the boundary between deciding and executing is a **pause you
-advance**, not a lock you fight — the system does the labor and waits for you to be
-the clock.
-
 ## License
 
 Licensed under the [Apache License 2.0](LICENSE).

package/dist/lib/orient.js

@@ -161,7 +161,7 @@ export function formatOrientation(o) {
     const cp = o.lastCheckpoint;
     const cpLine = cp === null ? 'last checkpoint  none yet' : `last checkpoint  step ${cp.n} · ${cp.sha.slice(0, 7)}`;
     return [
-        `Plumbbob — ${o.title ?? '(untitled)'}   [${o.phase}]`,
+        `PlumbBob — ${o.title ?? '(untitled)'}   [${o.phase}]`,
         '',
         stepsBlock,
         '',

package/dist/verbs/start.js

@@ -16,7 +16,7 @@ export function start(cwd, args) {
     }
     const root = findRepoRoot(cwd);
     if (root === null) {
-        process.stderr.write('plumbbob: not a git repository. Plumbbob records a baseline commit — run `git init` and make an initial commit first.\n');
+        process.stderr.write('plumbbob: not a git repository. PlumbBob records a baseline commit — run `git init` and make an initial commit first.\n');
         return 1;
     }
     if (!hasCommit(root)) {

package/package.json

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

package/skills/pb-build/SKILL.md

@@ -1,42 +1,43 @@
 ---
 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]"
 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)
+# 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:pb-verify` instead — plumbbob does not care how
+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.
 
-Since `/plumbbob:pb-plan` lays down the whole step list up front, the happy path is to fire
-`/plumbbob:pb-build` once per step until done — each run builds the next undone step and stops
-at the pause for your approval. **Re-firing `/plumbbob:pb-build` is itself the clock tick.**
+Since `/pb-plan` lays down the whole step list up front, the happy path is to fire
+`/pb-build` once per step until done — each run builds the next undone step and stops
+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. `/plumbbob:pb-build 4`), else
+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 `/plumbbob:pb-step` first.
+   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 `/plumbbob:pb-status` shows the step in flight; in v2 the seam is awareness, not a
+   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 `/plumbbob:pb-park`, **not** an
+   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 `/plumbbob:pb-verify`
+5. **Verify, through to the pause.** Run the verify tick exactly as `/pb-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
@@ -46,7 +47,7 @@ at the pause for your approval. **Re-firing `/plumbbob:pb-build` is itself the c
 
 ## `--auto` — let the agent be the clock (opt-in)
 
-`/plumbbob:pb-build --auto` is the explicit escape hatch when the human wants unattended
+`/pb-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**:
 
@@ -62,10 +63,10 @@ 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:pb-verify`
+- **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 `/plumbbob:pb-park`, not an edit.
+  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.

package/skills/pb-doctor/SKILL.md

@@ -6,7 +6,7 @@ model: haiku
 allowed-tools: Bash(plumbbob doctor:*)
 ---
 
-# Plumbbob — doctor (the is-it-installed-right move)
+# PlumbBob — doctor (the is-it-installed-right move)
 
 Install diagnostic (injected when this skill runs): !`if command -v plumbbob >/dev/null 2>&1; then plumbbob doctor 2>&1; else 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."; fi`
 

package/skills/pb-harvest/SKILL.md

@@ -6,11 +6,11 @@ model: opus
 allowed-tools: Read, Edit, Bash(plumbbob status:*)
 ---
 
-# Plumbbob — harvest the park list
+# PlumbBob — harvest the park list
 
 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:pb-harvest` is the complement of `/plumbbob:pb-park` (D7): you parked ideas as seeds during a
+`/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 — boundary only
@@ -20,7 +20,7 @@ DESIGN boundary, not mid-step. Read the dashboard injected above:
 
 - `NO ACTIVE SESSION` — **refuse**; tell the human to `plumbbob start "<title>"` first.
 - A step in flight (the dashboard reads `[BUILD]`, and `next →` points at finishing the
-  step) — **refuse** and suggest finishing it with `/plumbbob:pb-verify` before harvesting.
+  step) — **refuse** and suggest finishing it with `/pb-verify` before harvesting.
   Chasing parked items mid-step is the disease parking prevents.
 - At the boundary (the dashboard reads `[DESIGN]`) — go ahead.
 
@@ -41,7 +41,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 `/plumbbob:pb-status`
+- **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

package/skills/pb-park/SKILL.md

@@ -1,16 +1,17 @@
 ---
 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.
+argument-hint: "[idea]"
 disable-model-invocation: true
 model: haiku
 allowed-tools: Bash(plumbbob status:*), Bash(plumbbob park:*)
 ---
 
-# Plumbbob — park an idea (capture, don't chase)
+# PlumbBob — park an idea (capture, don't chase)
 
 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:pb-park` is the **capture** half of the loop; `/plumbbob:pb-harvest` is where parked items
+`/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.
 

package/skills/pb-plan/SKILL.md

@@ -1,19 +1,20 @@
 ---
 name: pb-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."
+argument-hint: "[spec-path | 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)
+# 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:pb-plan` is the **whole-goal** move — it opens a session and gets the deciding out
+`/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. By default it authors the
 **complete plan, including all the Steps**, so the happy path afterward is just
-`/plumbbob:pb-build` until done. (Revising a single increment later is the separate `/plumbbob:pb-step`
+`/pb-build` until done. (Revising a single increment later is the separate `/pb-step`
 move; do not confuse the two.)
 
 ## Three input modes (disambiguated for you — no quotes needed)
@@ -33,7 +34,7 @@ Look at the argument the human gave and pick the mode yourself:
    genuinely ambiguous.
 
 All three modes converge on the **same artifact**: a complete, standalone `intent.md`
-an agent can follow with `/plumbbob:pb-build`. The argument only seeds how you get there.
+an agent can follow with `/pb-build`. The argument only seeds how you get there.
 
 ## What this skill does
 
@@ -55,11 +56,11 @@ an agent can follow with `/plumbbob:pb-build`. The argument only seeds how you g
       - seam: `<file>`, `<file>`
    ```
 
-   Every step needs a **done-when** `/plumbbob:pb-verify` can check and a **seam** (the exact
+   Every step needs a **done-when** `/pb-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:pb-step`. Keep each small enough to
+   sharpened just-in-time when you reach them with `/pb-step`. Keep each small enough to
    verify in one review pass.
-5. **Offer to stress-test it.** Suggest `/plumbbob:pb-refine` to attack the frame for holes (or
+5. **Offer to stress-test it.** Suggest `/pb-refine` to attack the frame for holes (or
    to repair the plan as it drifts). Optional, the human's call.
 
 ## The interview (mode 1)
@@ -72,11 +73,11 @@ Make it easy and non-intrusive:
   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:pb-refine` to repair it.
+  They can also edit `intent.md` by hand at any time, or call `/pb-refine` to repair it.
 
 ## The hard contracts
 
-- **Deciding before code.** `/plumbbob:pb-plan` writes `intent.md` only — never source.
+- **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.
 - **Stands on its own.** Whatever the input mode, the finished `intent.md` carries

package/skills/pb-refine/SKILL.md

@@ -1,25 +1,26 @@
 ---
 name: pb-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.
+argument-hint: "[focus]"
 disable-model-invocation: true
 model: opus
 allowed-tools: Read, Edit, Bash(plumbbob status:*)
 ---
 
-# Plumbbob — refine the plan
+# 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:pb-refine` keeps `intent.md` honest. Use it at **any point** — right after `/plumbbob:pb-plan`
+`/pb-refine` keeps `intent.md` honest. Use it at **any point** — right after `/pb-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:pb-step` (which only
-sharpens the *next* step): `/plumbbob:pb-refine` works the *whole* plan.
+code is actually doing. It is the document-level complement to `/pb-step` (which only
+sharpens the *next* step): `/pb-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:pb-plan`) first, and edit nothing. Every active state
+`plumbbob start "<title>"` (or `/pb-plan`) first, and edit nothing. Every active state
 is fine — refining is always available.
 
 ## Two modes
@@ -41,5 +42,5 @@ is fine — refining is always available.
   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:pb-refine` touches `intent.md` only — turning a
-  decision into a diff is `/plumbbob:pb-build` or your own hands, never this skill.
+- **Refine the plan, not the code.** `/pb-refine` touches `intent.md` only — turning a
+  decision into a diff is `/pb-build` or your own hands, never this skill.

package/skills/pb-revert/SKILL.md

@@ -1,12 +1,13 @@
 ---
 name: pb-revert
 description: Human-triggered driver for `plumbbob revert` — git reset --hard to a checkpoint SHA (discarding the half-done step) and return to the boundary.
+argument-hint: "[--to <step>]"
 disable-model-invocation: true
 model: haiku
 allowed-tools: Bash(plumbbob status:*), Bash(plumbbob revert:*)
 ---
 
-# Plumbbob — revert to a checkpoint (driver)
+# PlumbBob — revert to a checkpoint (driver)
 
 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"`
 
@@ -14,6 +15,6 @@ This is a **driver skill** — a chat-side trigger for the mechanical `plumbbob
 
 ## What it does
 
-1. Read an optional target step from the way you were invoked (e.g. `/plumbbob:pb-revert --to 2` → step `2`). With no target, revert goes to the last done-checkpoint.
+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 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/SKILL.md

@@ -1,12 +1,13 @@
 ---
 name: pb-spike
 description: Human-triggered driver for `plumbbob spike` — open a throwaway worktree experiment for a genuine fork, or tear it down with `spike done`.
+argument-hint: "<slug> | done"
 disable-model-invocation: true
 model: haiku
 allowed-tools: Bash(plumbbob status:*), Bash(plumbbob spike:*)
 ---
 
-# Plumbbob — spike an experiment (driver)
+# PlumbBob — spike an experiment (driver)
 
 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"`
 
@@ -14,6 +15,6 @@ This is a **driver skill** — a chat-side trigger for the mechanical `plumbbob
 
 ## What it does
 
-1. Read the spike target from the way you were invoked: a slug to open one (e.g. `/plumbbob:pb-spike redis-cache`), or the literal `done` to tear the current spike down (`/plumbbob:pb-spike done`). If neither is present, ask which and run nothing.
+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 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/SKILL.md

@@ -6,7 +6,7 @@ model: haiku
 allowed-tools: Bash(plumbbob status:*)
 ---
 
-# Plumbbob — orient (the where-am-I move)
+# PlumbBob — orient (the where-am-I 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"`
 
@@ -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 `/plumbbob:pb-plan` to frame a goal.
+2. If it reads `NO ACTIVE SESSION`, tell the human to `/pb-plan` to frame a goal.

package/skills/pb-step/SKILL.md

@@ -1,30 +1,31 @@
 ---
 name: pb-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.
+argument-hint: "[what-changed]"
 disable-model-invocation: true
 model: opus
 allowed-tools: Read, Edit, Bash(plumbbob status:*)
 ---
 
-# Plumbbob — revise the next step (the single-increment move)
+# 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:pb-plan` authors the **whole** step list up front, so `/plumbbob:pb-step` is the
+`/pb-plan` authors the **whole** step list up front, so `/pb-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:pb-build` it. (Framing the whole goal
-is the separate `/plumbbob:pb-plan` move.) It can also add or re-cut a step when scope genuinely
+build has actually taught you, right before you `/pb-build` it. (Framing the whole goal
+is the separate `/pb-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:pb-step` (no input) → automatic sharpen.** Re-examine the next undone step
+- **`/pb-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:pb-step <what changed>` → directed revision.** Take the human's input and propose
+- **`/pb-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.
 
@@ -33,7 +34,7 @@ grew — but its everyday job is to sharpen, not to invent.
 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:pb-verify` can validate, and a **seam** (exact paths, or a `dir/` grant). Keep it
+   `/pb-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 —
@@ -42,7 +43,7 @@ grew — but its everyday job is to sharpen, not to invent.
 
 ## The hard contracts
 
-- **One verifiable increment.** Each step carries a done-when `/plumbbob:pb-verify` can check
+- **One verifiable increment.** Each step carries a done-when `/pb-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.

package/skills/pb-verify/SKILL.md

@@ -6,12 +6,12 @@ model: opus
 allowed-tools: Read, Bash(plumbbob status:*), Bash(plumbbob check:*), Bash(plumbbob checkpoint:*), Bash(git diff:*), Bash(git status:*)
 ---
 
-# Plumbbob — verify a step (the tick)
+# PlumbBob — verify a step (the tick)
 
 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 **tick** — the one beat where the human is the clock. Whatever produced
-the current diff — `/plumbbob:pb-build`, your own hands, a vibe session, another harness —
+the current diff — `/pb-build`, your own hands, a vibe session, another harness —
 this skill verifies it the same way: **it reads the diff, not the author** (D3).
 
 ## What this skill does, in order
@@ -40,7 +40,7 @@ this skill verifies it the same way: **it reads the diff, not the author** (D3).
 - **Never skip the pause.** Check → self-review → validate, then wait. Approval is
   the only thing that triggers the checkpoint.
 - **Read the diff, not the author** (D3). Verify identically whether the code was
-  built by `/plumbbob:pb-build`, by hand, vibed, or by another harness.
+  built by `/pb-build`, by hand, vibed, or by another harness.
 - **Red means stop, not pause.** A failing check is not an approval decision; report
   it and end your turn.
 - **You review; you do not build.** If the self-review finds a problem, surface it

package/skills/pb-wrap/SKILL.md

@@ -6,11 +6,11 @@ model: opus
 allowed-tools: Read, Write, Bash(plumbbob status:*), Bash(plumbbob wrap:*)
 ---
 
-# Plumbbob — wrap the build (the close-out)
+# PlumbBob — wrap the build (the close-out)
 
 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:pb-wrap` ends the build: it captures what happened, archives it, and clears the
+`/pb-wrap` ends the build: it captures what happened, archives it, and clears the
 sidecar for the next goal. **Report by default** (D9) — no refuse-without-report gate,
 and no separate docs phase.
 
@@ -30,7 +30,7 @@ and no separate docs phase.
    to the report, archives intent + build-log + report to
    `.plumbbob/archive/<date>-<slug>/`, and clears the sidecar (STATE last). Git is not
    touched.
-3. **Point at the next goal** — `/plumbbob:pb-plan` to frame the next one.
+3. **Point at the next goal** — `/pb-plan` to frame the next one.
 
 ## The hard contracts
 

package/templates/build-log.md

@@ -6,7 +6,7 @@ step boundaries. The antidote to "my plan got lost in the noise."
   Park list : where ideas go so you do not chase them. CAPTURE, never act inline.
   Harvest   : the boundary ritual that keeps you on one branch.
   Log       : the build's history. `plumbbob checkpoint` appends a line per step as it
-              lands; feeds the /plumbbob:pb-wrap report, then gets archived.
+              lands; feeds the /pb-wrap report, then gets archived.
 -->
 
 # Build log — {{TITLE}}
@@ -17,8 +17,8 @@ step boundaries. The antidote to "my plan got lost in the noise."
 ## Steps
 
 *(Mirror of intent.md's Steps, with live status. Only ONE step is in flight. A step
-is done only after a checkpoint — check green + checkpoint taken, via `/plumbbob:pb-verify` or
-`/plumbbob:pb-build`.)*
+is done only after a checkpoint — check green + checkpoint taken, via `/pb-verify` or
+`/pb-build`.)*
 
 - ☐ 1. <step>
 
@@ -26,16 +26,16 @@ is done only after a checkpoint — check green + checkpoint taken, via `/plumbb
 
 > Mid-step, every new problem / idea / "ooh what if" lands HERE, untouched, and you
 > go straight back to the step. Acting the instant an idea arrives is the disease.
-> Capture is one line (`/plumbbob:pb-park` composes it). Harvest happens only at the boundary.
+> Capture is one line (`/pb-park` composes it). Harvest happens only at the boundary.
 
-## Harvest  *(run `/plumbbob:pb-harvest` at each step boundary, after green)*
+## Harvest  *(run `/pb-harvest` at each step boundary, after green)*
 
 Classify each parked item as exactly ONE. Naming it before acting is what keeps you
 from sprawling across branches.
 
 | Class            | Meaning                                   | Action                          |
 |------------------|-------------------------------------------|---------------------------------|
-| **blocker**      | Plan was wrong/incomplete; can't proceed  | `/plumbbob:pb-revert`, fold into intent  |
+| **blocker**      | Plan was wrong/incomplete; can't proceed  | `/pb-revert`, fold into intent  |
 | **tangent**      | A different path, not clearly better      | Defer or kill. Default here.    |
 | **pivot signal** | Evidence the whole approach is wrong      | Stop. Replan deliberately.      |
 
@@ -49,8 +49,8 @@ Harvest results this boundary:
 ## Log
 
 *(The build's history, oldest first. `plumbbob checkpoint` appends a dated line here
-every time a step lands — via `/plumbbob:pb-build` or `/plumbbob:pb-verify` — so this
+every time a step lands — via `/pb-build` or `/pb-verify` — so this
 fills in as you go, not at the end. Add your own decision/event lines too: this is what
 you point at to say "I did that — the LLM helped, but those were my calls."
-`/plumbbob:pb-wrap` reads this for the report; `plumbbob wrap` archives it under
+`/pb-wrap` reads this for the report; `plumbbob wrap` archives it under
 `.plumbbob/archive/`.)*

package/templates/intent.md

@@ -32,24 +32,24 @@ open. If the implementor (you-later, or the LLM) has to guess, the doc failed.
 ## Decisions
 
 *(One line each. Settled, not re-litigated in the chat. Grows as you resolve the
-holes `/plumbbob:pb-refine` surfaces, and as blockers fold in during BUILD.)*
+holes `/pb-refine` surfaces, and as blockers fold in during BUILD.)*
 
 - D1: <decision> — *because* <the one reason that mattered>
 
 ## Constraints
 
-*(Hard rules the build must honor. `/plumbbob:pb-verify` and `/plumbbob:pb-refine` read against these.)*
+*(Hard rules the build must honor. `/pb-verify` and `/pb-refine` read against these.)*
 
 - C1: <e.g. functional/procedural only; no new dependencies>
 
 ## Steps
 
-*(The build plan. `/plumbbob:pb-plan` authors the **whole list up front** — each step a small,
+*(The build plan. `/pb-plan` authors the **whole list up front** — each step a small,
 verifiable increment with its own **done-when** and **seam** (the paths it will touch,
-which `/plumbbob:pb-build` records in `.plumbbob/SEAM` for orientation — awareness, not a lock
-in v2). Then drive `/plumbbob:pb-build` until done. Later steps may be fuzzier than the first;
-sharpen the next one just-in-time with `/plumbbob:pb-step` (empty input auto-syncs it), and use
-`/plumbbob:pb-refine` to repair the whole plan when a blocker rewrites it.)*
+which `/pb-build` records in `.plumbbob/SEAM` for orientation — awareness, not a lock
+in v2). Then drive `/pb-build` until done. Later steps may be fuzzier than the first;
+sharpen the next one just-in-time with `/pb-step` (empty input auto-syncs it), and use
+`/pb-refine` to repair the whole plan when a blocker rewrites it.)*
 
 1. [ ] <step> — **done when:** <criterion, ideally a test or check result>
    - seam: `<file>`, `<file>`