plumbbob 0.9.3 → 0.10.0

package/skills/plan/SKILL.md

@@ -1,27 +1,27 @@
 ---
 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 (or @-mention) absorbs a spec; any other text expands your inline intent."
+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 (or @-mention) absorbs a spec; any other text expands your inline intent."
 argument-hint: "[spec-path | intent]"
 disable-model-invocation: true
 allowed-tools: Read, Edit, Write, Bash(plumbbob status:*), Bash(plumbbob start:*), Bash(plumbbob checkpoint:*), Bash(plumbbob agent list:*)
 ---
 
-# 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 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."`
 
-`/plumbbob:plan` is the **whole-goal** move — it opens a session and gets the deciding out
+`/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.)
 
-A model note: this skill **inherits the session model** — nothing pins or switches
+A model note: this skill **inherits the session model**; nothing pins or switches
 it. Planning is where frontier-class judgment pays for itself, so if the session is
-running a small model, suggest `/model opus` (or better) before framing — the
+running a small model, suggest `/model opus` (or better) before framing: the
 human's call, never a gate.
 
-## Three input modes (disambiguated for you — no quotes needed)
+## Three input modes (disambiguated for you; no quotes needed)
 
 Look at the argument the human gave and pick the mode yourself:
 
@@ -32,10 +32,10 @@ Look at the argument the human gave and pick the mode yourself:
    the token with the `Read` tool; if Claude Code has already injected the referenced
    file's contents into your context, treat that as the spec rather than re-fetching.
    Read the spec 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
+   `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. Any prose wrapped around the reference (e.g. "absorb
-   @spec.md") is extra intent — fold it in. (If the token isn't a real file, fall to
+   preserving the original text. Any prose wrapped around the reference (for example "absorb
+   @spec.md") is extra intent; fold it in. (If the token 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
@@ -50,73 +50,77 @@ an agent can follow with `/plumbbob:build`. The argument only seeds how you get
    to create `.plumbbob/` (baseline recorded, session opened). If a session already
    exists, say so and edit the existing `intent.md` rather than starting over.
    - **If `start` warns that the gate sees no code checks**, surface that to the
-     human now — while they're still deciding, not at the first refused
-     checkpoint — and offer to set the `check` key in `.plumbbob/settings.json`
-     (e.g. `"check": "npm test"`) before any step is built.
+     human now (while they're still deciding, not at the first refused
+     checkpoint) and offer to set the `check` key in `.plumbbob/settings.json`
+     (for example `"check": "npm test"`) before any step is built.
 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
+   **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. **Slug each at birth** — mint a
-   two- or three-word slug where the item is born (`D1 (default-waves): …`,
-   `C1 (no-new-deps): …`) and copy that slug at every reference site, so a later
-   mention reads `D4 (default-waves)` and stays legible: **never a bare `D4`/`C6`/`Q2`
-   reference — always carry its gloss**, so a cold reader never has to hunt the number
-   down. An unresolved hole goes to **Open questions**, never guessed into a Decision —
-   and it goes in the expanded form the template shows: a slugged opener (the hole as a
-   question), a `*plain:*` sub-line (what's at stake, in plain words, enough to judge it
-   cold), then a `*lean:*` sub-line (your proposed resolution — one answer to react to,
-   not a menu), so the human settles it in one pass without a round-trip. (A tiny,
-   obvious question may stay one bare line; the sub-lines earn their keep only when a
-   human decision genuinely waits on it.)
-4. **Author the Steps.** Write the **full build plan** under `## Steps` — each step a
-   small, verifiable increment in the exact format the parser reads:
+   *because*) and the hard rules the build must honor. **Anchor and slug each at birth**:
+   mint a two- or three-word slug where the item is born and give it an anchor for
+   references to land on (`- <a id="d1"></a>**D1 (default-waves)**: …`,
+   `- <a id="c1"></a>**C1 (no-new-deps)**: …`), then cite it everywhere else in the file
+   as `[D4 (default-waves)](#d4)`, carrying that slug verbatim: **never a bare
+   `D4`/`C6`/`Q2` reference, and never a linkless one**: one link to the definition,
+   one glance at the gloss, so a cold reader never has to hunt the number down.
+   An unresolved hole goes to **Open questions**, never guessed into a Decision,
+   and it goes in the expanded form the template shows: an anchored, slugged opener
+   (the hole as a question, `- <a id="q1"></a>**Q1 (default-waves)**: …`, so
+   `[Q1 (default-waves)](#q1)` has somewhere to land), a `*plain:*` sub-line (what's at
+   stake, in plain words, enough to judge it cold), then a `*lean:*` sub-line (your
+   proposed resolution: one answer to react to, not a menu), so the human settles it in
+   one pass without a round-trip. (A tiny, obvious question may stay one bare line; the
+   sub-lines earn their keep only when a human decision genuinely waits on it.)
+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. [ ] feat(scope): <title> — **done when:** <criterion, ideally a test or check result>
+   1. [ ] feat(scope): <title>, **done when:** <criterion, ideally a test or check result>
       - seam: `<file>`, `<file>`
-      - model: <optional — smallest that can carry it, with the one-phrase why>
+      - model: <optional; smallest that can carry it, with the one-phrase why>
    ```
 
    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
+   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.
 
-   **The title *is* the commit subject — author it as one** *(D1)*: write each
+   **The title *is* the commit subject; author it as one**
+   ([D68 (conventional-subjects)](https://github.com/robmclarty/plumbbob/blob/main/docs/decisions.md#d68)): write each
    `<title>` as a plain, single-line Conventional-Commit subject,
    `type(scope): description`, and it lands in `git log` verbatim (its breaking `!`
-   honored) — this is how each step lands a *real* `feat`/`fix`/`chore` in the history.
-   Keep load-bearing detail — file paths, module names — in `seam` and `done-when`; it is
-   **never jammed into the title** (D2), which has to read as plain English and as a clean
-   subject at once. Aim for **≤72 characters** (GitHub's subject convention) — soft
-   guidance you eyeball at plan time, no lint, no gate (D9).
-
-   **Set the build's default scope, then let steps override it** *(D8)*: fill the
-   `**Scope:**` header once with a short feature-level name — the catch-all every step
-   inherits — and give a step its own `(scope)` when it touches a distinct code area
+   honored); this is how each step lands a *real* `feat`/`fix`/`chore` in the history.
+   Keep load-bearing detail (file paths, module names) in `seam` and `done-when`; it is
+   **never jammed into the title**, which has to read as plain English and as a clean
+   subject at once. Aim for **≤72 characters** (GitHub's subject convention): soft
+   guidance you eyeball at plan time, no lint, no gate.
+
+   **Set the build's default scope, then let steps override it**: fill the
+   `**Scope:**` header once with a short feature-level name (the catch-all every step
+   inherits) and give a step its own `(scope)` when it touches a distinct code area
    (`plan`, `commitmsg`, `docs`). A step's `(scope)` names the *code area*; the header
    names the *feature*, so scopes stay consistent and greppable across builds. Scope
    resolves title-scope → `**Scope:**` default → build slug → bare, and type resolves
    title-type → `feat`, so a scopeless plain title still yields a clean
-   `feat(<slug>): <title>` unchanged ([D68](../../docs/decisions.md#d68), D3).
+   `feat(<slug>): <title>` unchanged.
 
    **Recommend a model per step where the signal is clear** *(optional)*: the
    `- model:` sub-line names the **smallest model that can carry the step**, with the
-   one-phrase why — the human buys capability only where the step needs it. E.g.
-   `model: sonnet — mechanical, fully specified by the done-when` for rote edits;
-   `model: opus — strong-assertion test authoring` where the tests do the thinking;
-   `model: fable — subtle cross-cutting design` for judgment-heavy or creative work.
-   It is advisory metadata for the human — `/plumbbob:status` surfaces it before each build —
+   one-phrase why; the human buys capability only where the step needs it. E.g.
+   `model: sonnet (mechanical, fully specified by the done-when)` for rote edits;
+   `model: opus (strong-assertion test authoring)` where the tests do the thinking;
+   `model: fable (subtle cross-cutting design)` for judgment-heavy or creative work.
+   It is advisory metadata for the human (`/plumbbob:status` surfaces it before each build),
    never a gate, and nothing switches models automatically. Write it plain (no
    backticks) and omit it when any model would do.
 5. **Offer harness bindings** *(optional)*. If the build will lean on
    user-authored agents, author `harness.json` in the build folder (beside `intent.md`)
-   and review it at the **same plan pause**, alongside the steps — bindings are
+   and review it at the **same plan pause**, alongside the steps; bindings are
    plan-adjacent configuration, so they converge with the plan. It binds agents to a
-   step's three lifecycle slots — `before` (context in), `build` (the diff), `after`
-   (advisory review) — with an optional prose `note`; a `defaults` block binds every
+   step's three lifecycle slots, `before` (context in), `build` (the diff), and `after`
+   (advisory review), with an optional prose `note`; a `defaults` block binds every
    step. Run `plumbbob agent list` to see what's resolvable, per step:
 
    ```json
@@ -128,31 +132,37 @@ an agent can follow with `/plumbbob:build`. The argument only seeds how you get
    ```
 
    Keep it **bindings + prose only, never a conditional**: the file says *which*
-   agent, not *when* — the host model reads each manifest's `when` prose and a step's
-   `note` and decides when to fire one mid-build. Skip the file entirely when no step
-   uses an agent — the loop runs identically without it. The plan commit picks it
+   agent, not *when*; the host model reads each manifest's `when` prose and a step's
+   `note` and decides when to run one mid-build. Skip the file entirely when no step
+   uses an agent; the loop runs identically without it. The plan commit picks it
    up automatically (it lives in the build folder).
 6. **Commit the plan.** Once the human approves the frame and steps, run
-   `plumbbob checkpoint --plan` to commit the scaffold on its own — subject
+   `plumbbob checkpoint --plan` to commit the scaffold on its own: subject
    `chore(<scope>): plan` (with a `plumbbob plan` body marker), only `.plumbbob/builds/<slug>/`,
    a `plan <sha>` line in
    `checkpoints`. This keeps the first step's diff clean, so history reads
    baseline → plan → steps. Pass a proportional `--body` (the single-quoted stdin
    heredoc) when the rationale is worth carrying; skip it for a small plan. Do this
-   only on the human's approval — the plan is their convergence.
+   only on the human's approval; the plan is their convergence.
    - **The plan commit is latched too.** Once the turn ledger exists, `checkpoint
      --plan` refuses to land in the same turn `start` stamped it: present the plan,
      **end the turn**, and the human's approving message is the tick that lets it
-     commit on re-fire — the refusal *is* the plan pause. Never route around it with a
+     commit on the next run; the refusal *is* the plan pause. Never route around it with a
      raw `git commit`. (One documented seam: the very first plan of a brand-new
      session runs `start` *before* the turn hook has ever ticked, so that single
-     commit predates the ledger and stays guidance-governed — it lands without a
+     commit predates the ledger and stays guidance-governed; it lands without a
      refusal.)
    - **Say what the commit publishes.** The close-out line names the tracked folder:
      `.plumbbob/builds/<slug>/` now rides this branch into the PR, so teammates will
      see the plan and build record in review. In the same breath, offer the way out:
      a repo that won't track a tool folder can restart with `plumbbob start --local`
      (a fully untracked sidecar) before any steps are built.
+     - **Record-only variant.** When the repo's own `.gitignore` excludes `.plumbbob/`,
+       the folder can't ride the branch; `start` flags this up front, and the plan
+       commit lands *record-only*: an empty commit whose message carries the plan
+       (the `--body` earns its keep here), the files staying untracked. Say that
+       instead: the rationale is published in `git log`, not the folder, so pass a
+       fuller `--body` than you otherwise would, since the message is the whole record.
 7. **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.
 
@@ -160,17 +170,17 @@ an agent can follow with `/plumbbob:build`. The argument only seeds how you get
 
 Make it easy and non-intrusive:
 
-- **Triage size first.** A tiny change earns a 3-line Frame and one Step, fast — never
+- **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
+  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.
+- **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

package/skills/recover/SKILL.md

@@ -0,0 +1,28 @@
+---
+name: recover
+description: "Human-triggered driver for `plumbbob recover`; reconcile the control plane when the session looks wrong: a cursor pointing at a build that is gone, a step marked in flight that the plan no longer has, leftovers from an interrupted spike. Reports by default; `--fix` repairs the stale files it can."
+argument-hint: "[--fix]"
+disable-model-invocation: true
+model: haiku
+allowed-tools: Bash(plumbbob status:*), Bash(plumbbob recover:*)
+---
+
+# PlumbBob: reconcile the control plane (driver)
+
+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 a **driver skill**: a chat-side trigger for the mechanical `plumbbob recover` 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.
+
+Reach for it when the dashboard and reality disagree: `status` shows a build you thought you finished, or an empty plan for a build you know you wrote, or a step in flight you have no memory of starting. Those are the shapes a crashed session, a lost context window, or a mid-step build switch leaves behind. `/plumbbob:doctor` answers "is plumbbob installed correctly"; this answers "is this session's own state telling the truth".
+
+## What it does
+
+1. Run `plumbbob recover` via Bash. It reads the control plane (the active-build cursor, the step and spike markers, the latch's stamp, the agent handoff ledger, and any leftover spike worktrees) and prints one line per check.
+2. Report that output verbatim, `✓` and `✗` lines alike. Every problem carries a `→` line naming the fix; relay those as written rather than paraphrasing them into your own advice.
+3. **Only if the human asks for the repair**, run `plumbbob recover --fix`. It clears stale untracked control files and re-points a cursor when exactly one build survives. It never touches intent.md, the build log, the checkpoints ledger, a report, or git history, and it never lands or advances a step.
+
+## What it will not do for you
+
+- **Spike leftovers are reported, never removed.** Those worktrees sit outside the repo and may hold the only copy of what a spike learned, so the verb prints the exact `git worktree remove` / `git branch -D` commands and stops. Relay them; do not run them yourself.
+- **A contradictory phase is yours to settle.** A spike and a step both marked in flight, or a step number the plan no longer contains, need a decision about which one is real; `--fix` deliberately leaves them alone.
+- **It is not a rewind.** Recovering reconciles bookkeeping; it never restores lost work. Discarding a half-done step is `/plumbbob:revert`, and that is a different, destructive move the human asks for by name.

package/skills/refine/SKILL.md

@@ -1,16 +1,16 @@
 ---
 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.
+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
 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 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."`
 
-`/plumbbob:refine` keeps `intent.md` honest. Use it at **any point** — right after `/plumbbob:plan`
+`/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.
@@ -20,34 +20,37 @@ sharpens the *next* step): `/plumbbob:refine` works the *whole* plan.
 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.
+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,
+  **Architecture sketch** a cold, adversarial read and surface holes: ambiguities,
   unhandled edge cases, hidden assumptions, collisions with the existing code. Append
-  each under `## Open questions` in the expanded form the template shows — an opener
-  line (the hole as a question, slugged at birth: `- Q2 (some-slug): …`), a `*plain:*`
-  sub-line (what's at stake in plain words, enough to judge it cold), and a `*lean:*`
-  sub-line (your proposed resolution — one answer to react to, not a menu). Never
-  append a hole as a Decision: resolving it is the human's convergence, not yours —
+  each under `## Open questions` in the expanded form the template shows: an opener
+  line (the hole as a question, anchored and slugged at birth like any Decision,
+  `- <a id="q2"></a>**Q2 (some-slug)**: …`, so a `[Q2 (some-slug)](#q2)` reference
+  elsewhere in the file lands on it), a `*plain:*` sub-line (what's at stake in plain
+  words, enough to judge it cold), and a `*lean:*` sub-line (your proposed resolution:
+  one answer to react to, not a menu). Never
+  append a hole as a Decision: resolving it is the human's convergence, not yours;
   the lean proposes; this mode surfaces, it does not decide. (A tiny, obvious question
   may stay one bare line; the sub-lines earn their keep only when a human decision
   genuinely waits on it.)
 
   Then walk the human through it in the chat: list every hole you appended, each as
-  its explanation first and its lean second, and invite per-question answers — the
+  its explanation first and its lean second, and invite per-question answers; the
   human can settle any of them right there in one message, no doc-flipping, no extra
   round-trip per hole.
-- **Repair (re-sync to reality).** When the plan has drifted — a Decision was overtaken
+- **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, or a
-  **step's title no longer describes what the diff actually does** — propose the edits
+  **step's title no longer describes what the diff actually does**), propose the edits
   that bring `intent.md` back in line with the truth. A step title *is* its checkpoint
-  commit subject (D1), so bringing a drifted one back in line means keeping it a plain,
-  single-line `type(scope): description` subject, with load-bearing detail (file paths,
-  module names) in `seam` and `done-when`, **never jammed into the title** (D2) — the
-  checkpoint body pass then reconciles and lands that subject at the verify pause (D5).
+  commit subject ([D68 (conventional-subjects)](https://github.com/robmclarty/plumbbob/blob/main/docs/decisions.md#d68)), so bringing a drifted one back in line
+  means keeping it a plain, single-line `type(scope): description` subject, with
+  load-bearing detail (file paths, module names) in `seam` and `done-when`,
+  **never jammed into the title**; the checkpoint body pass then reconciles and lands
+  that subject at the verify pause.
   Show the before/after for each, and **write only what the human approves**.
 
 ## The hard contracts
@@ -56,5 +59,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:refine` touches `intent.md` only — turning a
+- **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/revert/SKILL.md

@@ -1,20 +1,20 @@
 ---
 name: 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.
+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 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 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.
+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. `/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.
+1. Read an optional target step from the way you were invoked (for example `/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/spike/SKILL.md

@@ -1,29 +1,29 @@
 ---
 name: spike
-description: Human-triggered driver for `plumbbob spike` — open a throwaway worktree experiment for a genuine fork, scaffold a spike report for a spike-as-step, or tear it down with `spike done`.
+description: "Human-triggered driver for `plumbbob spike`: open a throwaway worktree experiment for a genuine fork, scaffold a spike report for a spike-as-step, or tear it down with `spike done`."
 argument-hint: "<slug> | report <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 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 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.
+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. `/plumbbob:spike redis-cache`), `report <slug>` to scaffold a report without worktrees (`/plumbbob:spike report auth-store`), or the literal `done` to tear the current spike down (`/plumbbob:spike done`). If none is present, ask which and run nothing.
+1. Read the spike target from the way you were invoked: a slug to open one (for example `/plumbbob:spike redis-cache`), `report <slug>` to scaffold a report without worktrees (`/plumbbob:spike report auth-store`), or the literal `done` to tear the current spike down (`/plumbbob:spike done`). If none is present, ask which and run nothing.
 2. Run `plumbbob spike "<slug>"`, `plumbbob spike report "<slug>"`, or `plumbbob spike done` via Bash.
-3. Report the verb's output verbatim — the worktree it created or removed, the spike report it scaffolded, or any refusal. When the verb names a `spike-NN-<slug>.md` report, point the human at it; when `spike done` nudges that a verdict is unrecorded, relay that nudge verbatim.
+3. Report the verb's output verbatim: the worktree it created or removed, the spike report it scaffolded, or any refusal. When the verb names a `spike-NN-<slug>.md` report, point the human at it; when `spike done` nudges that a verdict is unrecorded, relay that nudge verbatim.
 
-## The spike report (D70)
+## The spike report ([D70 (spike-reports)](https://github.com/robmclarty/plumbbob/blob/main/docs/decisions.md#d70))
 
-Every spike leaves a durable `spike-NN-<slug>.md` in the build folder, beside `intent.md`/`report.md`, so the fork's verdict rides the branch into the PR instead of evaporating. The CLI scaffolds it from a template and numbers it — you never create or number the file:
+Every spike leaves a durable `spike-NN-<slug>.md` in the build folder, beside `intent.md`/`report.md`, so the fork's verdict rides the branch into the PR instead of evaporating. The CLI scaffolds it from a template and numbers it; you never create or number the file:
 
 - **`/plumbbob:spike <slug>`** scaffolds the report *at open*, so findings accrue while the throwaway worktrees are still live. Fill its **Findings** and **Verdict** before `/plumbbob:spike done`.
-- **`/plumbbob:spike report <slug>`** is for a *spike-as-step* — a planned step titled `spike: …`, where the increment itself is the experiment and there are no worktrees. It stamps the report's provenance as `step <n>` when a step is in flight.
+- **`/plumbbob:spike report <slug>`** is for a *spike-as-step*: a planned step titled `spike: …`, where the increment itself is the experiment and there are no worktrees. It stamps the report's provenance as `step <n>` when a step is in flight.
 
-This skill stays Write-less: the CLI owns the file. Your job is to run the verb and, between runs, help the human fill the report's prose — but the edits land through the normal build flow, not this driver.
+This skill stays Write-less: the CLI owns the file. Your job is to run the verb and, between runs, help the human fill the report's prose, but the edits land through the normal build flow, not this driver.

package/skills/status/SKILL.md

@@ -1,26 +1,26 @@
 ---
 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`.
+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 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 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 a **thin driver** for `plumbbob status`. The dashboard above is your
-orientation — the intent, the step list, the parked/open-question counts, and the
+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
 **never retry**, and never edit a file to change what the orientation says.
 
 ## What it does
 
-1. Surface the injected `status` output — the dashboard and its suggested next move.
+1. Surface the injected `status` output: the dashboard and its suggested next move.
 2. If the next step's detail carries a `model:` line, point it out: it is the
    plan's recommendation of the smallest model that can carry that step, so the human
-   can switch (e.g. `/model sonnet`) before firing `/plumbbob:build` — or ignore it. Guidance,
+   can switch (for example `/model sonnet`) before firing `/plumbbob:build`, or ignore it. Guidance,
    never a gate.
 3. If it reads `NO ACTIVE SESSION`, tell the human to `/plumbbob:plan` to frame a goal.

package/skills/step/SKILL.md

@@ -1,12 +1,12 @@
 ---
 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.
+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
 allowed-tools: Read, Edit, Write, Bash(plumbbob status:*), Bash(plumbbob agent list:*)
 ---
 
-# 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 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."`
 
@@ -14,14 +14,14 @@ Current session state (injected when this skill runs): !`plumbbob status 2>/dev/
 **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.
+grew, but its everyday job is to sharpen, not to invent.
 
-## Two ways to fire it
+## Two ways to run 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
+  make the obvious revisions to its **done-when** and **seam** so it matches reality:
+  for example 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
@@ -38,21 +38,21 @@ grew — but its everyday job is to sharpen, not to invent.
    what you changed and why. Re-check the optional `- model:` recommendation too:
    a step that sharpened into rote work can drop to a smaller model; one that grew subtle
    earns a frontier one. Advisory, plain text (no backticks), never a gate.
-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. Keep the
+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. Keep the
    sharpened `<title>` a plain, single-line Conventional-Commit subject,
-   `type(scope): description` — it lands in `git log` verbatim, so as the step tightens
+   `type(scope): description`; it lands in `git log` verbatim, so as the step tightens
    keep load-bearing detail (file paths, module names) in `seam` and `done-when`,
-   **never jammed into the title** (D1/D2). A sharpened step carries its own `(scope)`
-   when it touches a distinct code area — one that **overrides the build-default**
+   **never jammed into the title**. A sharpened step carries its own `(scope)`
+   when it touches a distinct code area, one that **overrides the build-default**
    `**Scope:**` header; drop the scope and it falls back to that default → build slug →
-   bare, and the type to `feat` ([D68](../../docs/decisions.md#d68), D8). Aim for a soft
-   ≤72 chars, no gate (D9). Revise the existing step in place; only append when you are
+   bare, and the type to `feat` ([D68 (conventional-subjects)](https://github.com/robmclarty/plumbbob/blob/main/docs/decisions.md#d68)). Aim for a soft
+   ≤72 chars, no gate. Revise the existing step in place; only append when you are
    genuinely adding an increment.
 4. **Revise the step's harness bindings if they drifted too** *(optional)*. If the
    build carries a `harness.json` (beside `intent.md`) and the reality that moved the
    step also changed which agents it wants, sharpen that step's slot bindings
-   (`before`/`build`/`after`) and `note` at the same time — this is the just-in-time
+   (`before`/`build`/`after`) and `note` at the same time; this is the just-in-time
    counterpart to `/plumbbob:plan`'s plan-time binding. `plumbbob agent list` shows what's
    resolvable. Same rule as the plan move: bindings + prose only, never a conditional
   . Leave it untouched when the step's agents are still right, or when the build
@@ -62,6 +62,11 @@ grew — but its everyday job is to sharpen, not to invent.
 
 - **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
+- **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.
+- **Cite the plan's own numbers in the linked form.** A `D`/`C`/`Q` you write into a
+  step's done-when, seam, or notes reads `[D4 (default-waves)](#d4)`; the slug travels
+  with the number, and the link lands on the `<a id="d4">` anchor minted where the item
+  was born. Never a bare `D4`; if the item you want to cite has no anchor yet, that is a
+  `/plumbbob:refine` repair, not something to invent here.
 - **The human approves the revision** before it lands. You propose; they decide.