plumbbob 0.4.4 → 0.4.11

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

@@ -1,5 +1,5 @@
 ---
-name: plan
+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."
 disable-model-invocation: true
 model: opus
@@ -10,10 +10,10 @@ allowed-tools: Read, Edit, Write, Bash(plumbbob status:*), Bash(plumbbob start:*
 
 Current session state (injected when this skill runs): !`plumbbob status 2>/dev/null || echo "plumbbob CLI not found - install the dep and re-run: npm i -g plumbbob && plumbbob init"`
 
-`/plumbbob:plan` is the **whole-goal** move — it opens a session and gets the deciding out
+`/plumbbob: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:build` until done. (Revising a single increment later is the separate `/plumbbob:step`
+`/plumbbob:pb-build` until done. (Revising a single increment later is the separate `/plumbbob:pb-step`
 move; do not confuse the two.)
 
 ## Three input modes (disambiguated for you — no quotes needed)
@@ -33,12 +33,12 @@ 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:build`. The argument only seeds how you get there.
+an agent can follow with `/plumbbob:pb-build`. The argument only seeds how you get there.
 
 ## What this skill does
 
 1. **Scaffold.** If there is no active session, run `plumbbob start "<title>"`
-   to create `.plumbbob/` (STATE=DESIGN, baseline recorded). If a session already
+   to create `.plumbbob/` (baseline recorded, session opened). If a session already
    exists, say so and edit the existing `intent.md` rather than starting over.
 2. **Frame** (`.plumbbob/intent.md`), with the human: the **Problem** in plain words,
    the **smallest thing** that solves it, what **done looks like**, and what you are
@@ -55,11 +55,11 @@ an agent can follow with `/plumbbob:build`. The argument only seeds how you get
       - seam: `<file>`, `<file>`
    ```
 
-   Every step needs a **done-when** `/plumbbob:verify` can check and a **seam** (the exact
+   Every step needs a **done-when** `/plumbbob: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:step`. Keep each small enough to
+   sharpened just-in-time when you reach them with `/plumbbob:pb-step`. Keep each small enough to
    verify in one review pass.
-5. **Offer to stress-test it.** Suggest `/plumbbob:refine` to attack the frame for holes (or
+5. **Offer to stress-test it.** Suggest `/plumbbob: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 +72,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:refine` to repair it.
+  They can also edit `intent.md` by hand at any time, or call `/plumbbob:pb-refine` to repair it.
 
 ## The hard contracts
 
-- **Deciding before code.** `/plumbbob:plan` writes `intent.md` only — never source.
+- **Deciding before code.** `/plumbbob: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/{refine → pb-refine}/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: refine
+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.
 disable-model-invocation: true
 model: opus
@@ -10,16 +10,16 @@ allowed-tools: Read, Edit, Bash(plumbbob status:*)
 
 Current session state (injected when this skill runs): !`plumbbob status 2>/dev/null || echo "plumbbob CLI not found - install the dep and re-run: npm i -g plumbbob && plumbbob init"`
 
-`/plumbbob:refine` keeps `intent.md` honest. Use it at **any point** — right after `/plumbbob:plan`
+`/plumbbob:pb-refine` keeps `intent.md` honest. Use it at **any point** — right after `/plumbbob: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:step` (which only
-sharpens the *next* step): `/plumbbob:refine` works the *whole* plan.
+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.
 
 ## No-session refusal
 
 This skill refines an existing plan, so it needs one. Read the state injected above: if
 it is `NO ACTIVE SESSION`, **refuse** in one line and tell the human to run
-`plumbbob start "<title>"` (or `/plumbbob:plan`) first, and edit nothing. Every active state
+`plumbbob start "<title>"` (or `/plumbbob:pb-plan`) first, and edit nothing. Every active state
 is fine — refining is always available.
 
 ## Two modes
@@ -41,5 +41,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
-  decision into a diff is `/plumbbob:build` or your own hands, never this skill.
+- **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.

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

@@ -1,6 +1,6 @@
 ---
-name: revert
-description: Human-triggered driver for `plumbbob revert` — git reset --hard to a checkpoint SHA (discarding the half-done step) and return to DESIGN.
+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.
 disable-model-invocation: true
 model: haiku
 allowed-tools: Bash(plumbbob status:*), Bash(plumbbob revert:*)
@@ -14,6 +14,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: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. `/plumbbob: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/{spike → pb-spike}/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: spike
+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`.
 disable-model-invocation: true
 model: haiku
@@ -14,6 +14,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:spike redis-cache`), or the literal `done` to tear the current spike down (`/plumbbob:spike done`). If neither is present, ask which and run nothing.
+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.
 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/{status → pb-status}/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: status
+name: pb-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
@@ -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:plan` to frame a goal.
+2. If it reads `NO ACTIVE SESSION`, tell the human to `/plumbbob:pb-plan` to frame a goal.

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

@@ -1,5 +1,5 @@
 ---
-name: step
+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.
 disable-model-invocation: true
 model: opus
@@ -10,21 +10,21 @@ allowed-tools: Read, Edit, Bash(plumbbob status:*)
 
 Current session state (injected when this skill runs): !`plumbbob status 2>/dev/null || echo "plumbbob CLI not found - install the dep and re-run: npm i -g plumbbob && plumbbob init"`
 
-`/plumbbob:plan` authors the **whole** step list up front, so `/plumbbob:step` is the
+`/plumbbob:pb-plan` authors the **whole** step list up front, so `/plumbbob: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:build` it. (Framing the whole goal
-is the separate `/plumbbob:plan` move.) It can also add or re-cut a step when scope genuinely
+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
 grew — but its everyday job is to sharpen, not to invent.
 
 ## Two ways to fire it
 
-- **`/plumbbob:step` (no input) → automatic sharpen.** Re-examine the next undone step
+- **`/plumbbob: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:step <what changed>` → directed revision.** Take the human's input and propose
+- **`/plumbbob: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 +33,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:verify` can validate, and a **seam** (exact paths, or a `dir/` grant). Keep it
+   `/plumbbob: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 +42,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:verify` can check
+- **One verifiable increment.** Each step carries a done-when `/plumbbob: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/{verify → pb-verify}/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: verify
+name: pb-verify
 description: "The verify tick — run the check, self-review the diff against intent, validate the step's done-when, pause for your approval, then checkpoint. Executor-agnostic: it reads the diff, not who wrote it."
 disable-model-invocation: true
 model: opus
@@ -11,7 +11,7 @@ allowed-tools: Read, Bash(plumbbob status:*), Bash(plumbbob check:*), Bash(plumb
 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:build`, your own hands, a vibe session, another harness —
+the current diff — `/plumbbob: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
@@ -31,16 +31,16 @@ this skill verifies it the same way: **it reads the diff, not the author** (D3).
    the human is the clock. Never checkpoint without it.
 5. **Checkpoint** *(only after approval)*. Commit the work — the human's
    commit-with-TIL skill for a rich message, or let `checkpoint` make the WIP commit
-   — then run `plumbbob checkpoint` to record the SHA, flip the step to done,
-   and return to DESIGN. Do **not** bump the version or touch the changelog — that is
-   the human's `/version` call.
+   — then run `plumbbob checkpoint` to record the SHA, flip the step to done, append the
+   step to the build-log's `## Log`, and return to DESIGN. Do **not** bump the version or
+   touch the changelog — that is the human's `/version` call.
 
 ## The hard contracts
 
 - **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:build`, by hand, vibed, or by another harness.
+  built by `/plumbbob: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/{wrap → pb-wrap}/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: wrap
+name: pb-wrap
 description: Wrap up the build — write the report (what shipped, decisions, parked/harvested items, deferred tangents), then safely archive intent + build-log + report before clearing for a fresh goal. Archive-then-clear, never destroy. Report by default, no gate.
 disable-model-invocation: true
 model: opus
@@ -10,15 +10,18 @@ allowed-tools: Read, Write, Bash(plumbbob status:*), Bash(plumbbob wrap:*)
 
 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:wrap` ends the build: it captures what happened, archives it, and clears the
+`/plumbbob: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.
 
 ## What this skill does, in order
 
-1. **Write the report** to `.plumbbob/report.md`, from `intent.md` + `build-log.md`:
-   - **What shipped** — the steps completed and what they delivered.
-   - **Decisions and why** — the settled calls that shaped the build.
+1. **Write the report** to `.plumbbob/report.md`, from `intent.md` + `build-log.md`.
+   The build-log's `## Log` is already the chronological history — `plumbbob checkpoint`
+   wrote a dated line for every step as it landed. **Read it as the spine; do not
+   re-narrate it.** The report adds only what the log does not already carry:
+   - **What shipped** — summarize from the `## Log` timeline; don't rebuild it step by step.
+   - **Decisions and why** — the settled calls that shaped the build (the *why* behind the log).
    - **Parked & harvested** — what was captured and how each was classified.
    - **Final status** — done or partial, and what is left.
    - **Deferred tangents** — the harvested items that become future work.
@@ -27,12 +30,15 @@ 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:plan` to frame the next one.
+3. **Point at the next goal** — `/plumbbob:pb-plan` to frame the next one.
 
 ## The hard contracts
 
 - **Report by default, never a gate.** Always offer the report; never wall the exit. A
   bug fix's report can be three lines — size it to the work.
+- **The log is the history; the report is the synthesis.** `checkpoint` already recorded
+  what shipped, step by step — wrap applies the *unique additions* (the why, the deferred
+  tangents, the final status), it does not rewrite the timeline.
 - **Archive-then-clear, never destroy** (C4). The archive is the record; the active
   files only clear once they are safely copied.
 - **No version bump, no docs phase.** Updating real docs is a separate, explicit ask;

package/templates/build-log.md

@@ -5,19 +5,20 @@ step boundaries. The antidote to "my plan got lost in the noise."
   Steps     : where you are. One step in flight at a time.
   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 audit trail. Feeds the /plumbbob:wrap report, then gets archived.
+  Log       : the build's history. `plumbbob checkpoint` appends a line per step as it
+              lands; feeds the /plumbbob:pb-wrap report, then gets archived.
 -->
 
 # Build log — {{TITLE}}
 
-**Current step:** none (DESIGN) · **STATE:** DESIGN
+**Current step:** none (at the boundary)
 **Heavy check:** {{CHECK}}
 
 ## 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:verify` or
-`/plumbbob:build`.)*
+is done only after a checkpoint — check green + checkpoint taken, via `/plumbbob:pb-verify` or
+`/plumbbob:pb-build`.)*
 
 - ☐ 1. <step>
 
@@ -25,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:park` composes it). Harvest happens only at the boundary.
+> Capture is one line (`/plumbbob:pb-park` composes it). Harvest happens only at the boundary.
 
-## Harvest  *(run `/plumbbob:harvest` at each step boundary, after green)*
+## Harvest  *(run `/plumbbob: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:revert`, fold into intent  |
+| **blocker**      | Plan was wrong/incomplete; can't proceed  | `/plumbbob: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.      |
 
@@ -47,8 +48,9 @@ Harvest results this boundary:
 
 ## Log
 
-*(Append-only. One decision or event per line, dated. What you point at to say "I
-did that — the LLM helped, but those were my calls." `/plumbbob:wrap` reads this for the
-report; `plumbbob wrap` archives it under `.plumbbob/archive/`.)*
-
-- <date> — <decision / event / what shipped this step>
+*(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
+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
+`.plumbbob/archive/`.)*

package/templates/intent.md

@@ -9,8 +9,7 @@ open. If the implementor (you-later, or the LLM) has to guess, the doc failed.
 
 # {{TITLE}}
 
-**STATE:** DESIGN
-**Phase** (bookkeeping while in DESIGN): frame
+**Phase** (your own bookkeeping while framing): frame
 **Size:** tiny | small | medium
 
 ## Frame
@@ -33,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:refine` surfaces, and as blockers fold in during BUILD.)*
+holes `/plumbbob: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:verify` and `/plumbbob:refine` read against these.)*
+*(Hard rules the build must honor. `/plumbbob:pb-verify` and `/plumbbob:pb-refine` read against these.)*
 
 - C1: <e.g. functional/procedural only; no new dependencies>
 
 ## Steps
 
-*(The build plan. `/plumbbob:plan` authors the **whole list up front** — each step a small,
+*(The build plan. `/plumbbob: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:build` records in `.plumbbob/SEAM` for orientation — awareness, not a lock
-in v2). Then drive `/plumbbob:build` until done. Later steps may be fuzzier than the first;
-sharpen the next one just-in-time with `/plumbbob:step` (empty input auto-syncs it), and use
-`/plumbbob:refine` to repair the whole plan when a blocker rewrites it.)*
+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.)*
 
 1. [ ] <step> — **done when:** <criterion, ideally a test or check result>
    - seam: `<file>`, `<file>`