monkeyshape 0.1.0 → 0.2.0

package/README.md

@@ -19,49 +19,24 @@ src/core/client.ts  arch/host-access
 mshape check failed: 2 problems
 ```
 
-## Install
+## Quick start
 
 ```sh
-bun add -d monkeyshape effect @biomejs/biome typescript @types/bun
+bunx --package monkeyshape mshape init my-app
 ```
 
-monkeyshape runs on Bun and asks your `tsc` and `biome` which files they cover; `effect` is a
-peer dependency. Add these files (the tests build a repo from exactly these blocks):
+A new repo whose gate (`bun run check`) passes, with one starter test: Bun, TypeScript, Effect,
+beads, the configs, CI, and five skills for your coding agent. Then the working loop, one chat each:
 
-```jsonc
-// tsconfig.json
-{ "extends": "monkeyshape/tsconfig.base.json", "include": ["src", "test", "shape.config.ts"] }
-```
-
-```jsonc
-// biome.json
-{
-  "root": true,
-  "extends": ["monkeyshape/biome"],
-  "files": { "includes": ["src/**", "test/**", "shape.config.ts", "*.json"] }
-}
-```
-
-```ts
-// shape.config.ts
-import { defineConfig } from "monkeyshape";
-
-export default defineConfig({
-  arch: {
-    modules: {
-      core: { description: "Deterministic logic. No host I/O." },
-      adapters: { description: "Host I/O behind services.", mayImport: ["core"], hostAccess: true },
-    },
-  },
-});
-```
-
-```md
-<!-- AGENTS.md -->
-# My project: commands, gotchas and decision authority for agents, in 150 lines or fewer.
-```
+1. `/roadmap` with a brain-dump: the direction, and one deferred epic per goal.
+2. `/milestone` with your priorities: a plan with acceptance on real data, beads, and
+   tracks, each its own worktree from `mshape track new`.
+3. `/track` in each track's worktree: the agent works its queue and opens PRs.
+4. `/handoff` when a chat's context runs low; a fresh chat runs `/track` to continue.
+5. `/review-pr <n>` in its own chat; you merge.
 
-Then make it your gate: `tsc && biome ci --error-on-warnings && mshape check && bun test`.
+The conventions in full: [docs/workflow.md](docs/workflow.md). An existing repo:
+[docs/adopting.md](docs/adopting.md).
 
 ## What `mshape check` enforces
 
@@ -72,6 +47,7 @@ Then make it your gate: `tsc && biome ci --error-on-warnings && mshape check &&
 | `refs` | Docs and comments that point at paths, scripts or decisions that don't exist |
 | `budgets` | Bloated `AGENTS.md`, decision logs and memories; oversized files |
 | `coverage` | Code that escaped the typechecker or the linter and rots silently |
+| `skills` | Installed skills that agents can't see (a broken `.claude/skills` link) or that lag the package |
 
 Existing violations can be grandfathered with `mshape baseline --init`; counts may then only
 go down. Every escape hatch (`// shape-ignore <rule>: <reason>`, config allowances) needs a reason.

package/docs/workflow.md

@@ -0,0 +1,131 @@
+# The working loop
+
+How a repo made by `mshape init` is worked, by a human and coding agents together. Read this
+once after `init`; the skills it names carry the detail, so you don't need it again.
+
+The split: **skills carry judgement, the `mshape` CLI carries everything deterministic.** A
+skill interviews, proposes, writes prose and grooms beads; it never builds a worktree or a
+file layout by hand, because the CLI does that and is tested. Each skill is started by name
+in a fresh chat, so your message can be just the skill and your intent.
+
+## Three horizons, three files
+
+Plan in detail only what is near. Each horizon has one home and one way of staying true.
+
+| Horizon | Home | Written by | Kept true by |
+|---|---|---|---|
+| Direction: months | docs/roadmap.md, plus one deferred beads epic per goal | `/roadmap` | Rewritten in place at each milestone boundary |
+| Milestone: several PRs from several agents | plan/MILESTONE.md | `/milestone` | Frozen for the milestone, replaced at the next |
+| Track state: today | the track's handoff, in `.handoffs` | `/track`, `/handoff` | Overwritten at every handoff |
+
+- **The roadmap** opens with a status table, so nobody reads the design as a spec. It is
+  never cited by code or by normative docs (AGENTS.md, DECISIONS.md, skills): name the file,
+  but the refs check rejects links into its sections. Its goals are deferred epics with no children until a milestone pulls them
+  in, so they never crowd `bd ready`.
+- **The milestone plan** says the goal and how you'll know it is met on real data, where
+  things stand, the tracks with their beads and acceptance, the interfaces between tracks,
+  decision points and what is deferred. When a track diverges from it, the track says so in
+  its handoff; a divergence that changes another track's work is a conversation with the
+  human, not an edit to the plan. Only handoffs and beads cite it.
+- **A handoff** is what a fresh chat reads to continue a track, and what the human reads to
+  decide what to relay. Handoffs live inside git's directory and are linked into every
+  checkout as `.handoffs`; they are never committed, so there is one live copy.
+
+What a change did and what it showed goes in the **PR body**, which is the narrative the
+human actually reads. Long investigations go in a dated note under `notes/`, which nothing
+normative may cite.
+
+Everything else has one home too:
+
+- A rule a machine can check is **a check**, whose message gives the reason and the fix. A
+  domain invariant is **a test named after it**. The local reason for some code is **a
+  comment at that code**.
+- **DECISIONS.md** holds only live decisions worth their budget: a surprising external fact
+  that was measured, or a choice between real alternatives that would be expensive to undo.
+  The best entries name the tempting wrong fix. A feature design isn't one; it goes in the
+  code.
+- **Notes** are immutable: write a new one instead of updating an old one. A lesson that
+  should apply going forward is promoted to a check, a test or a decision.
+
+## The loop
+
+| Step | Started by | What happens |
+|---|---|---|
+| Init | you: `mshape init <name>` | A new repo whose gate passes, with one starter test: template, toolchain, beads, the five skills, the handoffs store. |
+| Long term | chat: `/roadmap` + a brain-dump | Interview until goals are clear; write docs/roadmap.md; one deferred epic per goal; open a PR. |
+| Mid term | chat: `/milestone` + priorities | Retrospective on the last milestone; agree a goal with acceptance on real data; write plan/MILESTONE.md; groom beads and the roadmap; garden; create the tracks with `mshape track new`; remove finished ones. |
+| Short term | chat in a track's worktree: `/track` | Read the handoff and the track's queue; work; open PRs. |
+| Hand off | you, near 75% of a chat's context: `/handoff` | The handoff is rewritten so a fresh chat can continue; open one in the same worktree and run `/track`. |
+| Review | chat: `/review-pr <number>` | Review against real data in a scratch worktree (`mshape review <n>`); findings go on the PR; you merge. |
+
+A first repo goes: `mshape init`, then `/roadmap`, then `/milestone`, then one chat per track
+running `/track`. The first milestone of a new repo is "a first result on a real target".
+
+## Tracks
+
+A track is one line of parallel work: a name, a git worktree, a branch, a beads label and a
+handoff, all derived from the name by `mshape track`:
+
+- `mshape track new <name>` creates the worktree `.agents/worktrees/<repo>@<name>`, the branch
+  `track/<name>` and the handoff, and links the shared paths from `shape.config.ts`
+  (gitignored data such as a dataset) into the worktree.
+- `mshape track list` shows the tracks and each one's open beads; `mshape track current`
+  names the track of the current directory, and fails with a reason anywhere else.
+- `mshape track rm <name>` removes a finished track. It refuses while the worktree has
+  uncommitted work or the branch has unmerged commits, and says which; `--force` discards
+  them. Merged means in `main` or in its upstream, which `rm` fetches first, so a PR merged
+  on the remote counts before anyone pulls; a merge commit, a rebase and a squash all count. It also refuses while any bead labelled `track:<name>` isn't closed, and `--force`
+  doesn't override that: close each one, or move it to the track that will do it.
+
+Its beads carry the label `track:<name>`; its queue is `bd ready --label track:<name>`. An
+empty queue doesn't mean the track is done: `bd ready` leaves out beads in progress or blocked.
+The track is done when `mshape track list` shows it with 0 open beads and `merged: yes`.
+
+**Ad-hoc tracks.** For work that didn't come from a milestone, run `mshape track new <name>`
+yourself, open a chat in the worktree it prints and run `/track`. The handoff starts as a
+stub, so `/track` interviews you about the work and writes the charter and its beads.
+`mshape track rm <name>` when it's merged.
+
+**When to hand off.** At a natural break, around 75% of the context window. A handoff
+records state, lessons not yet promoted, traps and messages for other tracks; you relay
+those messages by pasting them where they belong, or by asking the track's next chat to read
+the other handoff.
+
+## Pull requests and review
+
+- Agents commit, push and open PRs; the human merges. A track has one PR open at a time, from
+  its branch. Batch a track's beads into PRs of one theme, typically 1k to 2.5k changed
+  lines: many small PRs cost more review than a few large ones. That is a default for
+  batching, not a gate: a small PR is fine when it unblocks work or keeps docs in step with
+  code.
+- The PR body says what changed and why, the evidence on real data, the gate output, the bug
+  class a new check closes, what is not done, and the beads closed or filed.
+- `bun run check` is the gate, the same locally and in CI. It is green before every PR.
+- `/review-pr` runs in its own chat, in a detached worktree at the PR's head that
+  `mshape review <n>` makes and `mshape review rm <n>` removes. A review is not a track: it
+  has no handoff, and everything about it lives on the PR. A review holds the PR to 95%,
+  not 100%: a blocker is a defect the PR would ship, and the skill says what counts. It
+  takes as many rounds as that needs, and LGTM means nothing is open. You merge, and can
+  step in at any point.
+
+## Beads
+
+- A bead points to intent; it isn't a spec. Keep it short: the intent, why, and an outcome
+  as acceptance.
+- Three kinds: deferred direction epics (no children), milestone stories labelled by track,
+  and interface beads between tracks with an owner and a consumer.
+- **Process beads.** When the process itself gets in the way, file a bead labelled
+  `process` saying what broke (`bd create --labels process ...`). `/milestone` reviews them
+  at the boundary, and fixes that are general land upstream in monkeyshape.
+
+## The milestone boundary
+
+The only ceremony, and `/milestone` runs all of it; the skill holds the steps. Between
+boundaries, tracks just work their queues.
+
+## Who decides
+
+AGENTS.md has a decision-authority section; fill it in for your repo. The default: humans
+own priorities, milestones, merging, spend above a cap and anything that leaves the machine.
+Agents decide design, refactors, docs, checks and beads within the milestone, and explain
+what they did in the PR body. When in doubt, an agent acts and explains.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "monkeyshape",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Opinionated checks, configs and conventions for humans and coding agents building together on Bun, TypeScript, Effect and beads.",
   "keywords": [
     "bun",
@@ -40,14 +40,18 @@
   "files": [
     "src",
     "config",
+    "template",
+    "skills",
     "!src/**/*.test.ts",
     "README.md",
+    "docs/workflow.md",
     "LICENSE"
   ],
   "scripts": {
     "typecheck": "tsc -p .",
     "lint": "biome ci --error-on-warnings .",
     "fix": "biome check --write .",
+    "mshape": "bun src/cli/main.ts",
     "shape": "bun src/cli/main.ts check",
     "check": "bun run typecheck && bun run lint && bun run shape && bun test"
   },

package/skills/handoff/SKILL.md

@@ -0,0 +1,54 @@
+---
+name: handoff
+description: Use when the human says /handoff, or asks to wrap up a track's chat because the context is running out or the session is ending. Rewrites the track's handoff so a fresh chat running /track can continue with nothing else.
+---
+
+# Handoff: hand a track to a fresh chat
+
+The next session knows only the repo, the beads and the handoff you write now. Write for an
+agent as capable as you who wasn't here: what it needs to continue, not what you did. What a
+change did belongs in its PR body and commits, not here.
+
+## 1. Which track
+
+Run `mshape track current`. If it exits 1, tell the human its reason and stop: a handoff
+belongs to a track.
+
+## 2. Leave nothing only in this chat
+
+- **Uncommitted work:** if no PR is open from the track branch, commit it there, as a WIP
+  commit if it isn't finished, and push. If one is open, a push would add it to the PR:
+  leave it uncommitted (the next chat opens in this same worktree) and list it in State.
+  Never stash: the stash is shared by every worktree.
+- **Beads:** close what merged; claim what is half done; file what you found and didn't do.
+- **Open PRs:** note each one's number and what it waits on.
+
+## 3. Rewrite the handoff
+
+Overwrite `.handoffs/<name>.md`; don't append. Other tracks write to its Messages while you
+work, so read the file again just before writing, and keep every message you hadn't seen.
+
+Keep its format: the title, `Status:` and `Queue:` lines, then exactly the sections Charter,
+State (with today's date), Lessons not yet promoted, Traps, Messages, in that order, with
+`###` for headings inside them. About 120 lines at most.
+
+- **Charter:** leave it unless the work changed what the track is for; then rewrite it, and
+  say in State that it changed and why.
+- **State:** done (PRs and beads, by number), in flight (the branch, the PR, what is half
+  done and the next command to run), and next. Concrete enough to act on without asking.
+- **Lessons not yet promoted:** what you learned that should become a check, a test, an
+  AGENTS.md gotcha or a decision. If promoting one is quick, do it now instead and delete
+  it here. A lesson that is really a bead becomes one.
+- **Traps:** what will bite the next session. Delete traps that are no longer true.
+- **Messages:** delete the answered ones and keep the open ones. Your messages to other
+  tracks go in their handoffs, not here.
+
+## 4. Check it and hand over
+
+Run `mshape track list`: this track must show `stub` (if the charter isn't agreed yet:
+leave it empty, never write one the human hasn't agreed) or `active`, never `invalid`. If it
+shows `invalid`, each problem is printed under its row: fix them all and run it again. Then
+tell the human, in a few lines: what is done and in flight, any messages they need to relay to another track or decide on, and "open a
+fresh chat in this worktree and run `/track`".
+
+Review this skill when a fresh chat had to rediscover something the last one knew.

package/skills/milestone/SKILL.md

@@ -0,0 +1,107 @@
+---
+name: milestone
+description: Use at a milestone boundary, when the human brings priorities for the next stretch of work, or when the repo has a roadmap but no milestone plan yet. Runs the retrospective, agrees a goal with acceptance on real data, writes plan/MILESTONE.md, grooms beads and the roadmap, gardens, and creates the tracks with mshape track.
+---
+
+# Milestone: the mid horizon and the boundary
+
+A milestone is the next significant delivery: several PRs from each of several parallel
+tracks. The boundary is the repo's only ceremony, and this skill runs all of it, in order.
+The human owns priorities and approves the plan; you bring the evidence and the proposal.
+
+Run this in the main checkout, on an up-to-date `main`, in a fresh chat.
+
+## 1. Gather
+
+- plan/MILESTONE.md (the milestone ending), docs/roadmap.md, AGENTS.md.
+- `mshape track list`, and every track's handoff in `.handoffs`: state, lessons not yet
+  promoted, messages nobody answered.
+- The milestone's epic and its children (`bd list --parent <epic> --all`), and
+  `bd list --label process` for what got in the way.
+- Merged PRs since the plan was written (`gh pr list --state merged`), and their bodies'
+  "not done" sections.
+- `mshape garden`.
+
+On a repo's first milestone there is nothing to look back on: skip to step 3.
+
+## 2. Retrospective
+
+Tell the human, briefly: what shipped against each acceptance line, what slipped and why,
+what the process beads and handoff lessons say, and what you would change. Facts with
+links (PRs, beads), not a story. Ask what they saw that you didn't.
+
+## 3. Agree the goal
+
+Propose one goal, from the human's priorities and the roadmap, with **acceptance on real
+data**: a run on a named real target, or a real repo or user doing the thing, never "tests
+pass". A new repo's first milestone is "a first result on a real target". Say what you
+would defer to make it fit, and why. Iterate until the human agrees; don't write the plan
+before that.
+
+## 4. Write plan/MILESTONE.md
+
+First move the old plan to notes/, named with today's date (YYYY-MM-DD-milestone-<n>.md).
+Then write the new one, about 500 lines at most:
+
+- **Goal, and how we'll know:** the acceptance agreed above.
+- **Where we are:** a gap table, measured where it can be.
+- **What changed since the last milestone, and why.**
+- **Interfaces the tracks share:** every path, command, format or schema two tracks both
+  touch, with its owner and consumer, settled before anyone starts. This is the section
+  that keeps parallel work from colliding; spend the effort here.
+- **Tracks:** a table of name, charter, beads and acceptance. Split into as many parallel
+  tracks as the work allows: each touches disjoint files and meets the others only at the
+  interfaces. Derive the number from the work, not a habit: up to about five is usual, and
+  one is fine when the work is sequential. When a track ends up holding far more than the
+  others, or the riskiest work alongside everything else, split it.
+- **Decision points**, **spend** for big runs, and **deferred items, each with a reason**.
+
+The plan is frozen once tracks start. Say so at its top.
+
+## 5. Groom
+
+- Create the milestone epic, and its stories as children labelled `track:<name>`, with
+  dependencies (`bd dep add`). An interface gets its own bead, owned by one track. A bead
+  is intent and an outcome as acceptance, about 1,500 characters at most, not a spec.
+- Pull roadmap epics in with `bd undefer`; close epics whose work is done.
+- Close, defer or rewrite every open story the milestone doesn't need, with a reason. A
+  story deferred out of the milestone drops its `track:` label.
+- P1 is the critical path only.
+- Re-verify each bd memory (`bd memories`) against the code; rewrite or delete stale ones.
+- Every `TODO(<bead id>)` in code whose bead is now closed: fix it or re-point it.
+
+## 6. Garden
+
+Act on `mshape garden`: anything over budget or grown since the last boundary gets pruned,
+not waived. Promote each handoff lesson to a check, a test, an AGENTS.md gotcha or a
+decision, or delete it. Try to turn each prose rule into a check, and each review finding
+that recurred into one. A process bead whose fix is general belongs upstream in monkeyshape:
+tell the human; filing outside the repo is theirs to approve.
+
+## 7. Roadmap and PR
+
+Update docs/roadmap.md: the status table, and what this milestone taught. Then one PR with
+the plan, the roadmap and the garden changes, gate green, the body saying what was decided
+and why. The human merges.
+
+## 8. Tracks
+
+Once the PR is merged (or the human says to start):
+
+- `mshape track rm <name>` for each finished track whose `beads` column in
+  `mshape track list` shows 0. A `-` means beads weren't counted, and `rm` may then remove
+  the track with only a note. So first get `bd` working, or check by hand that
+  `bd list --label track:<name> --limit 0` lists nothing (it hides only closed beads).
+  If `rm` refuses, report the reason; never reach for `--force` without the human. If the
+  reason is open beads, `--force` won't help, and grooming has already decided each one:
+  move it to the track the new plan gives it, or close it if it's done, and list what you
+  did in your report. Ask the human only when the plan doesn't say.
+- `mshape track new <name>` for each new track. Fill its handoff: `Status: active`, the
+  charter (its beads, the interfaces it owns or consumes), the state ("not started", and
+  how to start), the traps you already know, and messages from the plan.
+
+Finish by telling the human what to launch: for each track, the worktree path and "open a
+chat there and run `/track`".
+
+Review this skill after each boundary it runs: what the retrospective found about the
+process applies to this file too.

package/skills/review-pr/SKILL.md

@@ -0,0 +1,135 @@
+---
+name: review-pr
+description: Use when asked to review a pull request (a number or URL), to re-review one after its author replied or pushed fixes, or to review a follow-up PR that answers an earlier review's findings. Runs the change on real data in a scratch worktree, probes what it claims to enforce, posts every finding on the PR with a severity, and re-reviews until it can say "LGTM".
+---
+
+# Review a pull request
+
+A review is judged by what it **ran and read**, not by what it guessed from the diff. Every
+finding carries its evidence: the input that breaks it, a real-data output, or the line of
+code it rests on. Read AGENTS.md first: it holds the rules the PR is reviewed against.
+
+**Ground rules**
+- **The PR is the review's only home.** Findings, evidence, replies and what is still open
+  all go on it; nothing about the review is kept anywhere else. A fresh chat re-reviewing
+  reads the thread.
+- **Don't fix the PR yourself**: the author fixes findings in the same PR.
+- **Hold the PR to 95%, not 100%.** A blocker is a defect the PR would ship and someone
+  would hit, shown by a concrete failing input or a real-data result. "Could be better", or
+  an edge nobody has, is a nit, in any round. Style never blocks: the linter owns style.
+- **A nit stays open until it's settled:** fixed in this PR, declined with a reason you
+  accept, or filed by the author as a bead when it is real work beyond the PR. Never call a
+  blocker a nit to close a review.
+- **As many rounds as that takes.** If each fix keeps opening a new blocker, tell the human:
+  the design may need rethinking more than another patch. The human can step in at any point.
+- Real data may be read and run freely; spend past the repo's cap, or writes to shared data,
+  need the human first (see AGENTS.md).
+
+## 1. A worktree at the PR's head
+
+```bash
+N=<pr number>
+gh pr view $N --json title,body,files,commits
+gh api repos/{owner}/{repo}/pulls/$N -q .head.sha   # the head you review and anchor to
+mshape review $N         # detached worktree at that head, shared data linked; prints its path
+cd <that path> && bun install --frozen-lockfile
+```
+
+Never review in your own checkout. If the review's head and the API's differ, the author
+pushed meanwhile: run `mshape review $N` again.
+
+**A follow-up PR** that answers an earlier review: read that PR's thread first
+(`gh pr view <earlier> --comments`, and its inline comments as in step 5). Each finding it
+claims to answer is a re-review item (step 5), on top of reviewing its own diff.
+
+## 2. Read the diff
+
+Read the PR body and every changed file. Then go through it for:
+
+- **The invariants it claims.** If a schema, check or test says it enforces something, list
+  the inputs that should fail. Those are your probes in step 3.
+- **Docs it touches, or should have.** Do AGENTS.md, DECISIONS.md, the skills and the
+  handoffs still agree with the change? Grep for prose it made stale.
+- **The usual misses.** New code outside the gate (a tsconfig `include`, a test glob)? A
+  check that a free-text field walks around? A check-then-write that isn't atomic? A path
+  that breaks in a worktree, a symlink or a fresh clone? An error message that doesn't say
+  what to do?
+
+## 3. Run it
+
+From cheapest to most expensive:
+
+1. **Run what the PR adds**, on real data, in every mode it has. Do the numbers in the PR
+   body reproduce? Does each exit code mean what its doc says?
+2. **Probe checks adversarially**: throwaway scripts that build inputs which should be
+   rejected, one variation each, from a real artifact where there is one. **A bad input
+   that passes is a finding**, and the probe's input and output are its evidence on the PR.
+   Probes are scratch and are never committed or kept: one worth keeping is a regression
+   test, and that is the author's to add (step 4). **When the PR adds a check**, also probe
+   it with valid input it must pass: a false failure reaches everyone who runs the check,
+   and is a blocker.
+3. **Run the real workflow** when the claim is about what it produces end to end.
+
+Don't rerun the gate on the first pass if the PR body shows it green; do on a re-review whose
+fix touched code.
+
+## 4. Post on the PR
+
+Post **one review**, inline comments anchored to the head commit, built as a JSON file so
+the quoting survives:
+
+```bash
+# review.json: {commit_id, event: "COMMENT", body, comments: [{path, line, side: "RIGHT", body}]}
+gh api repos/{owner}/{repo}/pulls/$N/reviews --input review.json -q .html_url
+```
+
+Anchor each comment to a head-commit line that is in the diff; a finding with no such line
+goes in the review body. Each comment opens with a **bold one-sentence finding** and its
+severity (blocker or nit), then the evidence, then a suggested fix.
+
+- **A blocker in code asks for a regression test** in the PR: one that fails on this head
+  and passes once fixed. A blocker in prose (two docs that disagree, a wrong instruction)
+  asks for the fix; there is nothing to test.
+- **If a check could rule out the whole class**, say so: the PR body's "Class closed by"
+  line is where the author answers it.
+
+The body says what was run and what came out, the blockers, the nits with no line, and what
+looked good. Use `COMMENT`: GitHub refuses approve and request-changes on your own
+account's PR. Then tell the human in a few lines: what you ran, each finding and its
+severity, the review link. **Stop and wait** for the author.
+
+## 5. Re-review
+
+When told the author responded, read the thread: every reply, the new commits and the fix
+diff (`gh pr view $N --comments`, `gh api repos/{owner}/{repo}/pulls/$N/comments`). The head
+you reviewed last is your previous review's `commit_id`
+(`gh api repos/{owner}/{repo}/pulls/$N/reviews`). Run `mshape review $N` to move the
+worktree to the new head; it prints the previous one too.
+
+1. **"Fixed" is a claim.** For each code blocker, find its regression test and run it on
+   both heads. It must fail on the old one and pass on the new:
+
+   ```bash
+   git switch --detach <old head> && git checkout <new head> -- <test file> <files it needs>
+   bun test <test file>                                   # must fail
+   git reset -q --hard && git switch --detach <new head>
+   bun test <test file>                                   # must pass
+   ```
+
+   The failure on the old head must be the test's own assertion, saying what the finding
+   said: a load or import error means it never reached the bug, so check out the helpers
+   and fixtures it imports too, and rerun `bun install` if the dependencies changed. A test
+   that passes on the old head doesn't test the bug: that is a finding. For a prose
+   blocker, read the fix. Rerun the real-data runs the findings rested on.
+2. Look for what the fix opened: a new unchecked field, the mirror case of a new check.
+3. **Pushback is an argument, not a refusal.** If it holds, say so and drop the point; if it
+   doesn't, answer with evidence.
+4. Reply in the threads, then post a short summary review: what was re-verified, what is
+   resolved, what is still open. Tell the human.
+
+**When nothing is open, say "LGTM"** explicitly, on the PR and to the human: every blocker
+resolved and verified, every nit settled. Never while a finding is open or unverified.
+Merging is the human's call. When the review is over, `mshape review rm $N`: it lists what
+it discards, which in a review worktree is only scratch, then removes it.
+
+Review this skill when a blocker it should have caught reaches `main`.

package/skills/roadmap/SKILL.md

@@ -0,0 +1,66 @@
+---
+name: roadmap
+description: Use when the human brings a brain-dump about where the repo is heading (new goals, a change of direction, a fresh repo after mshape init), or asks to rewrite the roadmap. Interviews until the goals are clear, writes docs/roadmap.md with a status table first, keeps one deferred beads epic per goal, and opens a PR.
+---
+
+# Roadmap: the long horizon
+
+The roadmap is direction, not a spec: months ahead, coarse, rewritten in place, never cited
+by code or normative docs. Your job is to turn a brain-dump into goals clear enough that a
+later `/milestone` can pick one and give it acceptance on real data.
+
+Run this in the main checkout, on an up-to-date `main`, in a fresh chat.
+
+## 1. Read what exists
+
+- docs/roadmap.md, if there is one, and AGENTS.md.
+- The direction epics: `bd list --type epic --all`. Deferred ones are goals not yet pulled
+  into a milestone; open ones are in flight; closed ones shipped.
+- If a milestone is running, plan/MILESTONE.md, only to know what is already committed.
+
+## 2. Interview
+
+Ask in small batches, and propose answers rather than asking open questions: "I read this as
+X; is that right?" is cheaper for the human than "what do you mean?". Keep going until you
+could write, for every goal:
+
+- **The consumer:** who or what uses it first. No goal without one.
+- **What done looks like** on real data or a real target, not a feature list.
+- **Why now, or why later**, and what it depends on.
+- **What is out of scope**, said out loud, so the next agent doesn't build it.
+- **Spend or authority** it will need from the human (money, public releases, data).
+
+Push back where the brain-dump conflicts with the code, with the repo's principles in
+AGENTS.md, or with itself. The human owns priorities; you own pointing out that two of them
+collide. Stop interviewing when another question would not change what you write.
+
+## 3. Write docs/roadmap.md
+
+Rewrite it in place; git has the history, so keep no revision log and no frozen copy.
+
+- **Open with a status table**: one row per goal, with status `Shipped`, `Milestone N` (in
+  progress), `Later` or `Idea`, and the epic id. A reader learns what exists without reading
+  the design.
+- Then scope (who it's for, what it is not), then a section per goal: the intent, the
+  consumer, what done looks like, and what was learned so far. Far-off detail belongs here,
+  not in beads.
+- No dated promises, no restating AGENTS.md or DECISIONS.md, and nothing other docs would
+  need to cite: if something must be enforced, it becomes a check, a test or a decision.
+
+## 4. One deferred epic per goal
+
+For each goal without an epic: `bd create --type epic --title "<goal>" --description "..."`
+with the goal, two or three lines of why, and the roadmap section it comes from, then
+`bd defer <id>`. **No child stories:** a milestone creates those when it pulls the epic in.
+For goals that changed, rewrite the epic; for goals dropped, close it with the reason. Put
+each epic's id in the status table.
+
+## 5. PR
+
+Branch from `main`, commit, push, and open a PR whose body says what changed in the
+direction and why, which epics were created, rewritten or closed, and what the interview
+left open. Gate green first (`bun run check`). The human merges.
+
+Then tell the human the next step: `/milestone` in a fresh chat, with their priorities.
+
+Review this skill when a roadmap written with it was hard for `/milestone` to plan from.