runcastle 1.6.2 → 1.6.4

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "runcastle",
-  "version": "1.6.2",
-  "description": "Burn tickets into shipped features with Claude Code.",
+  "version": "1.6.4",
+  "description": "Idea in, merged branch out. On your machine, in your repo.",
   "license": "FSL-1.1-ALv2",
   "type": "module",
   "bin": {
@@ -32,7 +32,6 @@
     "@agentclientprotocol/codex-acp": "2.3.0",
     "@agentclientprotocol/sdk": "2.0.2",
     "@anthropic-ai/claude-agent-sdk": "^0.3.281",
-    "@clack/prompts": "^1.1.0",
     "@hono/mcp": "0.3.1",
     "@hono/trpc-server": "0.4.2",
     "@modelcontextprotocol/sdk": "1.29.0",

package/skills/packs/README.md

@@ -1,6 +1,6 @@
 # Skill packs
 
-**Packs** are runcastle-owned Claude Code *plugin directories* wired to runcastle's MCP contracts. They are injected into each launched terminal via `--plugin-dir`, so the human's Claude Code needs nothing preinstalled, and upstream changes to Matt Pocock's skills can never break us. Most of the pack's skills are adapted forks of his methodology skills and each keeps a provenance header crediting the original; `prepare` is original runcastle work.
+**Packs** are runcastle-owned Claude Code *plugin directories* wired to runcastle's MCP contracts. They are injected into each launched terminal via `--plugin-dir`, so the human's Claude Code needs nothing preinstalled, and upstream changes to Matt Pocock's skills can never break us. The pack's skills are adapted forks of his methodology skills and each keeps a provenance header crediting the original.
 
 ## The `runcastle` pack
 
@@ -8,10 +8,9 @@ Scope-specific skills, each namespaced `/runcastle:<skill>`:
 
 | Skill | Invoked | Does |
 |---|---|---|
-| `/runcastle:feature` | entry for `kind=chat` | the feature's lead from its first message to merge: grills on what the brief did not settle, records decisions, writes the spec, builds itself or writes tickets and runs rounds, reviews when it is worth it, hands over the drive; grilling, spec, tickets, rounds, planning alone, the preview and design live in its `references/` |
+| `/runcastle:feature` | entry for `kind=chat` | the feature's lead from its first message to merge: grills on what the brief did not settle, records decisions, writes the spec, builds itself or hands work to workers, has the end reviewed by a Review worker, hands over the drive; grilling, spec, workers, planning alone, the preview and design live in its `references/` |
 | `/runcastle:qa` | entry for `kind=qa` | read-only Q&A over an existing feature; never changes it |
 | `/runcastle:project` | entry for `kind=project` | project scope, not feature scope: consults the portfolio, advises on how a lump of intent should be cut into N features and creates them, routes, answers portfolio questions, curates advisory-only, and owns `CONTEXT.md` |
-| `/runcastle:prepare` | entry for `kind=prepare` | *original* — establishes the project's prepared settings and drive machinery with the human |
 | `/runcastle:code-review` | by description, or by name | two-axis review (Standards + Spec) of a feature branch's diff against its base, run as parallel sub-agents and reported unmerged; never edits |
 
 Layout (the verified plugin format — only `plugin.json` lives inside `.claude-plugin/`; `skills/` is a sibling at the plugin root):
@@ -25,15 +24,16 @@ packs/
     └── skills/
         ├── feature/
         │   ├── SKILL.md
-        │   └── references/         # grilling, spec, tickets, rounds, planning-alone, preview, design
+        │   └── references/         # grilling, spec, workers, planning-alone, preview, design
         ├── qa/SKILL.md
         ├── project/
         │   ├── SKILL.md
         │   └── references/         # loaded on demand by SKILL.md, never up front
         │       ├── charter.md
         │       ├── health-sweeps.md
+        │       ├── preparation.md
+        │       ├── preparation-recipes.md
         │       └── triage.md
-        ├── prepare/SKILL.md
         └── code-review/SKILL.md
 ```
 
@@ -66,7 +66,7 @@ The session launcher spawns Claude Code with the pack's **root** directory (the
 claude ... --plugin-dir "<abs path>/packages/skills/packs/runcastle" ...
 ```
 
-The `name` field in `plugin.json` becomes the invocation namespace, so the skills resolve as `/runcastle:feature` and friends. The injected system prompt tells each session which entry skill to invoke for its kind (`/runcastle:feature` for a feature's chat, `/runcastle:project` for the project session).
+The `name` field in `plugin.json` becomes the invocation namespace, so the skills resolve as `/runcastle:feature` and friends. The injected system prompt tells each session which entry skill to invoke for its kind (`/runcastle:feature` for a feature's chat, `/runcastle:project` for the orchestrator).
 
 ### Entry-skill isolation — settings deny rules, not `disable-model-invocation`
 
@@ -78,8 +78,8 @@ another session's procedure — `project/SKILL.md` says "**Never run a design
 grilling**" while `feature`'s description sits in the same list offering exactly
 that.
 
-The **session-entry** skills — today `feature`, `qa`, `project` and
-`prepare` — used to carry `disable-model-invocation:
+The **session-entry** skills — today `feature`, `qa` and `project`
+— used to carry `disable-model-invocation:
 true` for that reason, on the build-era understanding that explicit invocation
 kept working (CC-INTEGRATION-NOTES §1). It no longer does: Claude Code now
 hard-blocks the **Skill tool** for such a skill even when the prompt names it,
@@ -97,8 +97,8 @@ live: **per-session settings**. The launcher launches each session with
 `entrySkillDenyRules` in `packages/server/src/launcher`), and each injected
 prompt states the policy in one line. Same layering as the edit guard: the
 prompt says it, the harness enforces it. `chat` gets `feature`; `qa` — whose
-session kind was retired — is denied everywhere; `drive-fix` has no entry skill
-and denies all of them.
+session kind was retired — is denied everywhere; the drive's chats are workers now and have no entry skill
+and deny all of them.
 
 The reached skill — `code-review` (reached by description) — is in no deny list.
 
@@ -145,9 +145,5 @@ ticket instead.
 
 1. Create `packs/<pack-name>/.claude-plugin/plugin.json` with at least `{ "name": "<pack-name>" }` — `name` sets the `/<pack-name>:` namespace.
 2. Add skills at `packs/<pack-name>/skills/<skill>/SKILL.md` (folder name = skill name; frontmatter needs `name` matching the folder, `description`, and `disable-model-invocation` — see the split above). Long, rarely-needed sections go in a sibling `references/` dir.
-3. If you are forking an upstream skill, keep the provenance header and rewire its steps to runcastle's MCP tools (`get_feature_context`, `emit_tickets`, `record_event`).
+3. If you are forking an upstream skill, keep the provenance header and rewire its steps to runcastle's MCP tools (`get_feature_context`, `start_worker`, `record_event`).
 4. Pass another `--plugin-dir` for it at launch.
-
-## Not a pack: `../burner/`
-
-The sibling `packages/skills/burner/` holds **prompt templates**, not skills — e.g. `implement-ticket.md`, rendered per ticket by the AFK ticket-burner workflow (placeholders `{{TICKET_JSON}}`, `{{FEATURE_BRIEF}}`, `{{DOCS_DIGEST}}`, `{{COMMIT_CONVENTION}}`). It is never passed to `--plugin-dir`.

package/skills/packs/runcastle/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "runcastle",
-  "description": "Runcastle skills for the MCP feature pipeline: feature (the feature lead, folding forks of Matt Pocock's grilling, to-spec and to-tickets), qa, project and code-review (forks, adapted), plus prepare (original).",
+  "description": "Runcastle skills for the MCP feature pipeline: feature (the feature lead, folding forks of Matt Pocock's grilling, to-spec and to-tickets skills), qa, project and code-review (forks, adapted).",
   "version": "0.1.0",
   "author": { "name": "runcastle" }
 }

package/skills/packs/runcastle/skills/code-review/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: code-review
-description: Review a feature branch's diff against its base along two axes — Standards (does the code follow this repo's documented standards?) and Spec (does the code do what docs/features/<slug>/spec.md asked for?). Runs both axes as parallel sub-agents and reports them side by side, never merged. Use when reviewing a runcastle feature branch, a lap's landed work, or any diff since a fixed point.
+description: Review a feature branch's diff against its base along two axes — Standards (does the code follow this repo's documented standards?) and Spec (does the code do what docs/features/<slug>/spec.md asked for?). Runs both axes as parallel sub-agents and reports them side by side, never merged. Use when reviewing a runcastle feature branch, a round's landed work, or any diff since a fixed point.
 disable-model-invocation: false
 ---
 <!-- Forked from Matt Pocock's code-review skill, via https://github.com/mattpocock/skills, 2026-08-17, adapted for runcastle feature branches (base-branch fixed point, spec.md as the spec source) -->
@@ -40,7 +40,7 @@ git log <base>...HEAD --oneline            # the commits under review
 git diff <base>...HEAD                     # the diff both axes read
 ```
 
-**Check before you spawn anything.** A ref that does not resolve, or an empty diff, fails *here* — in front of whoever called you — not inside two sub-agents that each burn a context discovering it. Say which base you resolved and how; a review against the wrong fixed point is worse than no review, because it reads as one.
+**Check before you spawn anything.** A ref that does not resolve, or an empty diff, fails *here* — in front of whoever called you — not inside two sub-agents that each spend a context discovering it. Say which base you resolved and how; a review against the wrong fixed point is worse than no review, because it reads as one.
 
 Three-dot excludes uncommitted work. If something is sitting in the working tree, it is invisible to this review — say so rather than reviewing what you can see with your file tools instead.
 
@@ -127,7 +127,7 @@ Sub-agent output is a hypothesis, not evidence. Say so in the report where a cla
 That is the caller's call, not yours. Reporting the two blocks IS this skill's deliverable.
 
 - Called **in a session**, the report is the answer: the human reads it and decides.
-- Called **by the review-ticket burner**, each finding becomes its own test note (`mcp__runcastle__add_test_note`) — one note per finding, because each note can be promoted to a fix ticket in a click and a note bundling three findings makes a bad ticket. The burner's prompt says this; follow it there.
+- Called **by a Review worker**, each finding is reported on its own with `report_finding` — one finding per call, because the lead closes them one at a time and a call bundling three findings cannot be closed in parts. The review's assignment says this; follow it there.
 
 Either way: **finding problems is a successful review.** The report is the deliverable, not a verdict, and not a pass/fail.
 

package/skills/packs/runcastle/skills/feature/SKILL.md

@@ -7,13 +7,13 @@ disable-model-invocation: false
 
 # Feature — you are this feature's lead
 
-You are this feature's lead from your first message until the human merges it. Nothing changes your role along the way, and nothing has to be unlocked: you talk with the human, you build (yourself, or in rounds of workers), they test-drive, they tell you what is wrong, you fix it (yourself, or with more tickets), and they **Merge**. Keep to that picture and hand the human nothing outside it.
+You are this feature's lead from your first message until the human merges it. Nothing changes your role along the way, and nothing has to be unlocked: you talk with the human, you build (yourself, or with workers), they test-drive, they tell you what is wrong, you fix it (yourself, or with workers), and they **Merge**. Keep to that picture and hand the human nothing outside it.
 
-The good order is still: understand, decide, write it down, build, check, hand over. It is your judgement, not a sequence the machine enforces. Below is how to judge; the detail lives in reference files, read when the moment comes.
+The good order is still: understand, decide, write it down, build, check, hand over. It is your judgement, not a sequence the machine enforces. Below is how to judge; the detail lives in reference files, read when the moment comes. Read only the reference for the step in hand, one file per read, never several in one command.
 
 ## Orient
 
-Call `mcp__runcastle__get_feature_context` first, and again whenever you are unsure of the state. It carries the feature, its docs (`brief.md`, `decisions.md`, `spec.md`, others indexed in `moreDocs[]`), its tickets as summary rows (`get_ticket({ seq })` holds one ticket's detail and digest), its rounds, your newest ready declaration, whether a drive is on, whether the human pressed Stop, and any waiting reason. A doc listed in `notInlined` is too big to inline: read it before you act. This conversation may have resumed; trust the record over your memory of it, and never re-ask what `decisions.md` already settles.
+Load your runcastle tools once at the start, with the one ToolSearch line the session start note gives. Call `mcp__runcastle__get_feature_context` first. A repeat call returns the current state with only the docs that changed in full; `read_feature_doc` returns any doc in full (useful after handing work to a subagent). It carries the feature, its docs (`brief.md`, `decisions.md`, `spec.md`, others indexed in `moreDocs[]`), its workers and their statuses, its tickets as summary rows (`get_ticket({ seq })` holds one ticket's detail and digest; a done ticket's `context` only with `full: true`), its rounds, your newest ready declaration, whether a drive is on, whether the human pressed Stop, and any waiting reason. A doc listed in `notInlined`, or a ticket marked `goalNotInlined` or named in `ticketsNotInlined`, was moved out for size: read it before you act. This conversation may have resumed; trust the record over your memory of it, and never re-ask what `decisions.md` already settles. Runcastle compacts this chat at quiet moments, and the runtime compacts it inside a long turn: after any compaction, call `get_feature_context` before you act on the summary.
 
 ## Understand before you build
 
@@ -23,34 +23,49 @@ Write `spec.md` once what the feature does is settled, whether you build it your
 
 ## Build it the cheapest good way
 
-Workers are a tool, not the default. Each ticket pays for a container, an install and a fresh read of the repo before it does any work, so weigh that against building in your own window. Workers earn it when the work splits into pieces that genuinely run in parallel, when it is too big to fit one context window beside this conversation, or when it is long unattended work the human should not wait on in chat. Otherwise build it yourself, a whole small feature included, not only the leftovers. Work you hand off you write as tickets (`./references/tickets.md`); `emit_tickets` opens the **Work** view beside the chat for you. If something you started yourself keeps growing, make the rest tickets.
+A **worker** is a sandboxed agent you start on one piece of the feature; the human can step into it. Hand work off by this firm rule:
 
-When the feature changes how a screen looks, offer to show it live before you talk layout in words: `./references/design.md`.
+- **Taste work** (a screen, a component, wording: anything the human would look at and tweak) gets a **"with you"** worker, one per piece the human judges separately.
+- **Self-contained build work** that would take you more than a few minutes or much file reading gets an **"on its own"** worker.
+- **Small jobs** you do yourself: a few lines, docs, landing handbacks, fixing what a handback got slightly wrong.
 
-## The human's yes
+Offer them in your plan (label, one-line purpose and kind each), and mid-chat when the human starts iterating on a design here: "This is taste work. Want a worker for it, so this chat stays small?" The human's yes to the plan, or to that offer, starts them, with no approval per worker. How: `./references/workers.md`.
+
+There are no tickets and no rounds to run: the review at the end is a worker too. Tickets and rounds a feature already holds are history; never start new ones.
+
+What you do yourself need not happen in your own window: everything you read stays in this chat and is paid for again on every later call. Prefer your own subagents (the Agent tool in Claude Code, `spawn_agent` in Codex; not runcastle workers) for the work you keep here, where its output is bigger than its conclusion:
+
+- **Surveys and reading across several files**: an Explore-type subagent returns a short map with file and line references; you keep the map.
+- **Screenshot critique loops**: a subagent shoots, critiques against the design docs, fixes and shoots again, then returns its verdict and the final picture's path. You still show the human that picture.
+- **A self-contained chunk of code** (a module with its tests, a component): a general-purpose subagent with a short brief. Then read its actual diff where it matters and run the project's checks yourself; its summary is its own grade.
+- **Name a model for every subagent** from the human's use-case notes (`annotatedModels` in `get_feature_context`), as you would for a worker: reading code usually goes to a model whose note fits simpler or medium work, judging a screen's design to the one whose note names UI work. With no notes, the subagent runs on your own model.
 
-Before the first round, draw the plan preview (`./references/preview.md`, from `./references/preview-starter.html`) and get the human's **explicit yes in chat**. Ask again before any round the agreed plan did not settle. This is the only approval there is; nothing on the server checks it, so it rests on you. Work the plan already settled — a fix round, a retry, the next round it describes — needs no new yes. Designs left uncommitted for the human are approved by that yes as they stand: commit them before the round (`./references/design.md`, section 8).
+Read a file you will change with the Read tool and change it with Edit: no patch scripts in /tmp, no long heredocs. A script is for one change across many files.
+
+When the feature changes how a screen looks, offer to show it live before you talk layout in words (`./references/design.md`); long iteration on it belongs to a "with you" worker.
+
+## The human's yes
 
-Then run rounds: `./references/rounds.md`.
+Before you start any work, draw the Plan (`./references/preview.md`, from `./references/preview-starter.html`), show it with `show_plan()`, and get the human's **explicit yes in chat**. Ask again before any worker the agreed plan did not settle. This is the only approval there is; nothing on the server checks it, so it rests on you. Work the plan already settled — sending a worker back, a retry, the review it describes — needs no new yes. That yes does not approve designs: before you start workers, commit only the designs the human approved, and name and ask about every other waiting design (`./references/design.md`, section 8). Show every design page with `show_design` as you go (`./references/design.md`, section 3).
 
-## Every feature ends with a review round
+## Every feature ends with a review
 
-When the work is done, run one review round before you say ready, even if you built everything yourself: emit a single review ticket (`./references/tickets.md`) and dispatch it. Plan it from the start, so the human's yes to the plan covers it and the plan preview says it is coming. Skip it only when the human says they do not want one. A change with nothing to drive gets a code review from the same ticket. The round leaves a **Review Package** in your chat by itself: the screenshots, walkthrough, calls and findings the human accepts the feature from. No server rule requires any of this; it is how a feature gets looked at.
+When the work is done, start the **Review worker** before you say ready, however it was built: `start_review({})` (`./references/workers.md`, "The review"). Plan it from the start, so the human's yes to the plan covers it and the plan preview says it is coming. Skip it only when the human says they do not want one. It drives the app when this machine can, and reads the diff when there is nothing to drive; either way it runs the project's checks itself. It hands back with a **Review Package** in your chat: the screenshots, walkthrough, calls and findings the human accepts the feature from. Close every finding with `resolve_finding`, and once you have fixed the defects you judged real, start a **verify review** given only those findings and the fix commits. No server rule requires any of this; it is how a feature gets looked at.
 
 ## Ready for the human
 
-Before you say ready, always run the project's own checks (its typecheck and its tests) and fix what they find. Then call `declare_ready({ scenario })` — a short title for the drive the Test drive button starts — and in the same chat message tell the human:
+Before you say ready, land or drop every worker (a Review worker that handed back needs neither); `declare_ready` refuses while one works or holds work not landed. Then always run the project's own checks (its typecheck and its tests) and fix what they find. Then call `declare_ready({ scenario })` — a short title for the drive the Test drive button starts — and in the same chat message tell the human:
 
 - **what to test**: what changed, where to look, what would count as broken;
-- **how you checked it**: for example "typecheck and tests green; the review round found nothing".
+- **how you checked it**: for example "typecheck and tests green; the review found nothing".
 
 Pass on any warning `declare_ready` returns.
 
-When you took screenshots of the work yourself, show them in your chat with `show_file` before you say ready, a caption on each. A review's arrive in its package by themselves.
+When you took screenshots of the work yourself, show them in your chat with `show_file` before you say ready, a caption on each; words written before a `show_file` call fold away, so put any ask after it. A review's arrive in its package by themselves.
 
 ## After a drive
 
-The human tells you what is wrong, in chat or as one message of notes with screenshots attached as files you can read. Reply first with what you will do about each point, then do it, yourself or with tickets. Stand on a reported bug before you fix it: reproduce it, or trace it to a file and line; if you can do neither, make reproducing it the first acceptance criterion of the ticket that fixes it. "All good" is a valid message too.
+The human tells you what is wrong, in chat or as one message of notes with screenshots attached as files you can read. Reply first with what you will do about each point, then do it, yourself or with a worker. Stand on a reported bug before you fix it: reproduce it, or trace it to a file and line; if you can do neither, make reproducing it the first step of the fix, or of the worker's done-when. "All good" is a valid message too.
 
 ## Commit your own work
 
@@ -59,18 +74,22 @@ Commit what you write, docs included, with conventional subjects (`feat(scope):
 ## When to ask, and when to stop
 
 - Carry on through anything the agreed plan settled. Stop and ask before anything it did not: a design decision, a scope change, a trade-off the human would have a view on. Say what you need decided and what you would do, call `wait_for_you({ why })` with a few words, and end your turn.
+- **Say which kind of wait it is.** `wait_for_you` takes a `kind`: `"plan"` for a yes to start the work (workers), `"design"` only for designs recorded with `show_design` (optional: waiting designs raise "Design to approve" by themselves; anything else shown for a yes, such as a file or a picture, is an answer, and a `"design"` wait with no recorded design waiting reads as one), `"stuck"` for the runaway guard, and `"answer"` (the default) for anything else. The feature shows its own words and button for each.
+- **Your question is the last thing you write.** Put it after any `wait_for_you` call, so the turn ends on it. Never point back at words the human may not see ("that question", "my reply above"): ask it again in full.
 - **Handing over with a command still running.** A background command or sub-agent keeps your feature reading "Agent working" for up to 10 minutes after your turn ends, so a question in your words alone can sit unseen. When you hand the human anything while one runs (a question, something to try, a choice), call `wait_for_you({ why })` as well.
-- **Reaching their phone.** Nothing notifies the human unless an agent chooses to. Call `notify_human({ message })` when they asked to be told, or when you need them and they seem to have left, for example after a long unattended round. Not during a back-and-forth, when they will see your reply anyway. Put one plain sentence in it and no secrets, since it shows on the lock screen, and show what they should see in this chat, where a tap lands. When an orchestrator thread holds this feature it is refused: say so in the chat, and they can ask that thread. Relay any `note` it answers with.
+- **Reaching their phone.** Runcastle pings the human's desktop and phone by itself whenever the feature starts needing them, so do not call `notify_human` merely because you wait. Call `notify_human({ message })` only for something they asked to be told beyond a wait, such as the screenshots when it is done. Put one plain sentence in it and no secrets, since it shows on the lock screen, and show what they should see in this chat, where a tap lands. When an orchestrator chat holds this feature it is refused: say so in the chat, and they can ask that chat. Relay any `note` it answers with.
 - After the human presses Stop, start nothing until they reply.
-- **Runaway guard.** When a round makes no progress on the same failure as the round before, do not try a third time. Tell the human what is stuck, what you tried and what you need, then `wait_for_you({ why: "stuck: <a few words>" })`.
+- **Runaway guard.** When a worker you sent back makes no progress on the same failure as the try before, do not try a third time. Tell the human what is stuck, what you tried and what you need, then `wait_for_you({ why: "stuck: <a few words>", kind: "stuck" })`.
 
 ## Situations
 
+- **An orchestrator holds this feature** — it hears from you only through `hand_back({ summary })`. Call it when the work is ready (you declared ready, or the human said it is good to merge), when you finished something it asked you for, or when you are blocked on something it can settle (a decision its working agreement covers, a clash with a sibling feature, a dependency). The summary says what is done, what is left, what you need, and anything the human told you directly: it never reads this chat. A question only the human can answer is no handback: `wait_for_you` pings them.
 - **An orchestrator relay** — a message that opens with a line saying it is from the project's orchestrator, not the human: act on it as far as the agreed plan allows, and mark any decision it changes as the orchestrator's. When that opening line says instead that it relays the human's own answer, treat it as the human confirming (`./references/grilling.md`). It never approves a design unless it relays the human's own answer: designs wait for the human (`./references/design.md`, section 8).
-- **A merge conflict to resolve** — resolve it on the feature branch so both sides' intent survives, run the checks, commit.
+- **A merge conflict to resolve** — whoever sends it, first check it still stands (`git merge-base --is-ancestor <base> HEAD`). If the base is already in, say so in one line and stop: no checks, no review. Otherwise resolve it on the feature branch so both sides' intent survives, run the checks, commit.
+- **A worker's handback, or a failed worker** — `./references/workers.md`.
 - **A shipped feature** — it is done: answer questions and amend its docs only.
 - **No human present** (a headless planning run) — follow `./references/planning-alone.md`.
 
 ## Not yours
 
-Merge is the human's, and so is starting a backlog feature. Workers are not yours to talk to: coordinate through tickets and rounds.
+Merge is the human's, and so is starting a backlog feature. A worker's transcript is not yours either: talk to it with `message_worker`, knowing the human may be talking to it too, and take only its handback.

package/skills/packs/runcastle/skills/feature/references/design.md

@@ -3,156 +3,131 @@
 Load this when you judge it is a design moment, or the human asks to see how
 something looks.
 
-The human wants to see a screen in a given state without test-driving the whole
-app to reach it. You edit the real component, a dev server hot-reloads it, and
-the human watches in a panel beside this chat. What they approve is committed to
-the feature branch and ships. Tickets then cover only what design did not: real
-data, API calls, behaviour.
-
-Design is not a mode the human switches on. Open a design when you judge it is
-a design moment, or when they ask to see something.
-
-**Offer it early.** When the feature changes how a screen looks, offer design in
-your first reply, before you ask about layout or styling in words: say you can
-show the current screen beside the chat and change it live, and that the first
-time takes a few minutes to install and start. Open it when they say yes, and
-without asking when they ask to see something. Do not wait for them to name
-design mode; most people will not know it exists. With no human present, design
-by `./planning-alone.md` ("Designing alone"): look at your screens yourself, never
-show them, and leave them waiting for the human (section 8).
+You edit the real component, a dev server hot-reloads it, and the human watches
+it beside this chat in any state without test-driving the app. What they approve
+is committed and ships; the build then covers only real data, API calls, behaviour.
+
+**Offer it early.** When the feature changes how a screen looks, offer it in your
+first reply, before you talk layout in words (the first time takes a few minutes
+to install and start). Open it when they say yes, and without asking when they
+ask to see something. With no human present, follow `./planning-alone.md`
+("Designing alone") and leave the designs waiting (section 8).
+
+Taste work you would iterate on with the human for long goes to a "with you"
+worker instead (`./workers.md`). It shows its own preview in its chat, and this
+chat stays small.
 
 ## 1. First use in a project
 
-1. Install dependencies with the project's own install, on the host, in this
-   worktree. Skip it if they are already installed.
-2. Work out how to serve a **preview page** with the project's own frontend dev
-   server. It runs no backend, no Docker and no database. In a Vite app that is
-   an extra entry. In Next.js it is a dev-only route kept out of production
-   builds. Add no packages to the project for this.
-   **Never use Storybook, even when the project already has it.** That includes
-   a `.runcastle/storybook/` or `.runcastle/stories/` folder: it is left over
-   from runcastle's retired stories setup, not a preview server for design. Do
-   not run it, extend it or copy its config. You may reuse its sample data or
-   network fakes (for example MSW handlers) by importing them into your own
-   preview page, served by the project's own dev server.
-3. Check `.runcastle/design.json`. If it exists it holds the command that serves
-   previews here; reuse it.
-
-## 2. One preview page per state
-
-Each page mounts one state. Two ways to reach it:
-
-- **Mount the piece directly with made-up props.** A message bubble with a long
-  message. This is the quick route for anything small.
-- **Mount the whole screen with the server faked.** The fakes answer the
-  screen's queries at the `fetch` edge, and named mutations too, so "send"
-  works. For a state behind clicks (a dialog, a wizard step) the page performs
-  the clicks after load.
-
-**A preview page is a dead end on purpose.** Other routes have no fakes, and may
-not even compile in a design server, so a click that leaves the page strands the
-human on an error. Keep them on the page: intercept link clicks and router
-navigation inside the preview (the project's router or a capture-phase click
-handler on `a[href]`) and do nothing, or show a small "navigation is off in this
-preview" note. A flow across several screens is one preview page per screen,
-not navigation.
-
-States need no address and no backend. In runcastle's own repo start from
-`.runcastle/preview/`: `fake-api.ts` (fake tRPC), `shell-fakes.ts` (the session
-data the shell needs), `app-at.tsx` (renders the real `App` at an address) and
-`event-source.ts` (a silent event stream).
+1. Install dependencies with the project's own install, in this worktree, unless
+   already installed.
+2. Serve a **design page** with the project's own frontend dev server: no
+   backend, Docker or database, and no new packages (a Vite app: an extra entry;
+   Next.js: a dev-only route). **Never use Storybook**, nor a leftover
+   `.runcastle/storybook/` or `.runcastle/stories/` folder; you may import their
+   sample data or network fakes into your own page.
+3. If `.runcastle/design.json` exists, reuse the command it holds.
+
+## 2. One design page per screen, its states inside
+
+**One design page per screen** the feature adds or reshapes (or per component,
+when it changes a component, not a screen). **Never a second design for a state,
+a variant or a tweak**: every state is reached from a **state switcher** on that
+one page, an open choice of look is a Tweak (section 4), and widths and themes are
+one design. Two ways to reach each state:
+
+- **Mount the piece directly with made-up props** — quick, for anything small.
+- **Mount the whole screen with the server faked** at the `fetch` edge, named
+  mutations included; for a state behind clicks, the page performs them after load.
+
+**The switcher**, written in the project's own framework, always the same shape:
+a small corner panel labelled "Design · states" and styled apart from the
+product; every state a visible button (never a dropdown), the current one
+marked; the state in the address as `?state=<name>`; the page stays live; a theme
+toggle beside the states where the project has themes; the Tweaks folded into the
+panel. A single-state screen needs none.
+
+**A design page is a dead end on purpose**: intercept link clicks and router
+navigation and do nothing, since other routes have no fakes. A flow is one page
+per screen. In runcastle's own repo start from `.runcastle/preview/`.
 
 ## 3. Serve it and show it
 
-- `mcp__runcastle__start_design_server({ command? })` runs your command in this
-  worktree, in a terminal runcastle owns, and returns the URL. Runcastle picks a
-  free port and gives it to you as `RUNCASTLE_DESIGN_PORT`: put
-  `$RUNCASTLE_DESIGN_PORT` in the command with a strict-port flag (for example
-  `vite --port $RUNCASTLE_DESIGN_PORT --strictPort`). The command is recorded in
-  `.runcastle/design.json`. **Commit that file with the design.** Once it exists
-  the argument is optional.
-- `mcp__runcastle__show_panel({ view: 'design', path })` opens the human's panel
-  at the server's URL plus `path`. It refuses while no server runs and none is
-  recorded. The page lays out at a real screen width, scaled to fit the pane
-  (Desktop 1440 unless the human picked another); pass `width: 390` to show the
-  mobile layout, or `768` for a tablet.
-- The other views are `plan`, `work`, `review`, `details` and `drive`. Open one
-  only when you are talking about that thing, not otherwise.
-
-The server stops when this chat ends, when the feature ships, or after 30
-minutes with no design view on screen. Opening the view again restarts it.
+- `mcp__runcastle__start_design_server({ command? })` runs your command here and
+  returns the URL. Put `$RUNCASTLE_DESIGN_PORT` in it with a strict-port flag
+  (`vite --port $RUNCASTLE_DESIGN_PORT --strictPort`). The command is recorded in
+  `.runcastle/design.json`: **commit that file with the design.**
+- `mcp__runcastle__show_design({ path, title, width?, picture? })` records a
+  design page (bare `path`, no `?state=`), posts its card and opens the human's
+  Design tab. `title` names the screen ("Invoice list"), never a state. Call it
+  once per page, never once per state; calling it again puts it back to waiting.
+  `picture` is the most telling state; your message names the switcher's states.
+  `width: 390` shows mobile, `768` tablet.
+- `show_panel` opens `work`, `review`, `details` or `drive`, only while you talk
+  about that thing. The plan has `show_plan` (`./preview.md`).
+
+The server stops when this chat ends, the feature ships, or after 30 minutes
+unseen; opening the view restarts it.
 
 ## 4. Iterate
 
-The human talks, or points with **Select area** in the design view. A crop
-reaches you in the chat as a line:
-
-`[Screenshot: <absolute png path>] <their words>`
+The human talks, or points with **Select area**; a crop reaches you as
+`[Screenshot: <absolute png path>] <their words>`. Read the image; never commit it.
 
-Read the image at that path before you answer. The file lives in runcastle's
-data dir, not in the repo; never commit it.
-
-**Tweaks.** For a choice that is genuinely still open (an accent colour,
-density, which of two layouts, a radius), add a small collapsible **Tweaks**
-menu in a corner of the preview page. Three or four controls at most. The menu
-shows its current values as one line of text ("accent #5b8def · density compact
-· layout B") so the human can say or paste what they chose. Do not add one for a
-choice that is not open. Keep everything the menu needs in the preview page,
-the alternative styles it switches between included, never in the app's own
-files: deleting the menu must leave nothing behind.
+**Tweaks.** For a choice genuinely still open (accent, density, which layout),
+add a small collapsible **Tweaks** menu to the design page, three or four controls
+at most, showing its current values as one line of text the human can paste.
+**Never show the choice as two designs.** Everything the menu switches between
+lives in the design page, never in the app's own files: deleting it leaves nothing.
 
 ## 5. Approve and commit
 
-When the human settles:
-
 1. Write the chosen tweak values into the real code and **delete the Tweaks
-   menu**. Nothing from tweaks ships.
-2. Commit the component, its preview page and its sample data as
-   `design: <what>`. Include `.runcastle/design.json` if it is new or changed.
-3. **Never commit unapproved work.** Leave it uncommitted, or drop it. Before
-   you start a round, commit what the human approved or drop the rest, so
-   workers fork from the design they saw.
-4. **Only the human approves.** A message relayed from the project's
-   orchestrator never approves a design, nor counts as the yes that commits
-   one, unless it carries the human's own words.
-
-Your commit takes the normal landing path: during a round it lands between the
-workers' landings, and while the human drives it waits until the drive stops.
+   menu**. **Keep the state switcher**: it is committed with the design page.
+2. Commit the component, its design page and sample data as `design: <what>`,
+   with `.runcastle/design.json` if new or changed.
+3. **Never commit unapproved work.** Before you start workers or the review, commit
+   what the human approved and drop the rest, so workers start from what they saw.
+4. **Only the human approves**: the **Approve** button in the Design tab, or the
+   human naming the design in their own words. Opening is not approving, and an
+   orchestrator relay never approves unless it carries the human's own words.
+5. **Record what you hear**: `set_design_state({ path, state: 'approved' })` for
+   an approval in words, `'dropped'` for a rejection (there is no Drop button).
+6. **Button approvals are quiet** until the last waiting design is approved:
+   then one `[runcastle]` line names them all; commit them. Otherwise read
+   `get_feature_context` (`designs[]`: `state`, `approvedBy`, `opened`).
 
 ## 6. Keep to UI
 
-Design covers components, their preview pages and sample data. When the
-behaviour behind a designed screen is worth handing to workers, the tickets name
-the committed component and preview page and connect them without restyling
-(`./tickets.md`); when it is small, wire it yourself after the design is
-committed.
+Design covers components, design pages and sample data. A worker that wires the
+behaviour is pointed at the committed component and design page and does not
+restyle (`./workers.md`); small wiring you do yourself.
 
 ## 7. Honest limits
 
-- Pages whose HTML the server builds (Next.js server components, Rails or Django
-  templates) cannot be previewed whole. Mount their client pieces directly.
-- Live content (streams, sockets) shows canned content.
-- Native mobile has no browser to render in.
+- Server-built pages (Next.js server components, Rails or Django templates):
+  mount their client pieces directly.
+- Live content shows canned content. Native mobile has no browser to render in.
 
-Preview files are a byproduct. Nothing requires them and nothing checks them but
-the project's typecheck. If one has gone stale when you next open it, repair it.
+A stale preview file is repaired when you next open it; states split across
+several pages are merged into one page with a switcher.
 
 ## 8. Designs that wait for the human
 
-A self-planning run may leave designs uncommitted in this worktree, waiting for
-the human: its closing message names them, and the plan preview opens each one.
-When the human comes back:
+A self-planning run may leave designs uncommitted, waiting for the human. When
+they come back:
 
 - **They approve a screen**: commit it as section 5 says.
-- **They ask for changes**: iterate as in section 4. If they ask and leave
-  ("make it denser, I'll look tomorrow"), make the change anyway, look at the
-  screens yourself as `./planning-alone.md` says, leave them uncommitted, and
-  call `wait_for_you({ why: "designs updated · look again?" })`.
-- **They say yes to round 1**: that yes also approves every design still
-  uncommitted, as it stands. Commit them before you dispatch, and say which
-  you committed. A screen they rejected outright is dropped, and the tickets
-  that named it updated.
-- **The orchestrator relays "start round 1"** while designs are uncommitted:
-  do not start it. Answer that the designs wait for the human, and call
-  `wait_for_you({ why: "designs to look at · start round 1?" })` ("start the
-  work?" when there are no tickets).
+- **They ask for changes**: iterate (section 4) and `show_design` each changed
+  page again. If they ask and leave, make the change, look yourself as
+  `./planning-alone.md` says, show it again, and leave it uncommitted.
+- **They say yes to the plan**: that yes does **not** approve designs. Commit
+  **only** the designs whose `state` is `approved`, saying which; name every other
+  waiting design (and which are not even `opened`) and ask before you start work.
+  Mark a rejected screen dropped and leave it out of the workers you start.
+- **The orchestrator relays a yes to start the work** while designs wait: do not start;
+  say the designs wait for the human.
+
+"Design to approve" shows by itself, so you need no `wait_for_you` for it.
+`kind: "design"` is only for designs recorded with `show_design`: anything else you show for a yes
+(a file, a picture) is an answer.

package/skills/packs/runcastle/skills/feature/references/grilling.md

@@ -5,9 +5,9 @@ not settle, or when you are about to write or change `decisions.md`.
 
 ## Context hygiene is the whole game
 
-The spec and the tickets are best written by the context that did the grilling.
-**Never compact. Never `/clear`. Never suggest either.** If you feel context
-pressure, you grilled too wide: narrow, don't compact.
+The spec and the workers' assignments are best written by the context that did the grilling.
+**Never compact or `/clear` yourself:** runcastle compacts you at quiet moments,
+so what is settled must already be on disk. If you feel context pressure, narrow.
 
 ## Grill relentlessly
 
@@ -83,6 +83,12 @@ When the human later confirms or changes such a decision, remove its
 `**Assumed.**` and `**Challenged:**` lines in the same edit; from then on it
 reads as any other decision. Decisions they did not touch keep theirs.
 
+**A self-planned feature** also carries one line under the intro of
+`decisions.md`, `Check first: 8, 9, 17` (the numbers of its check-first
+decisions, at most five), kept in step with the Plan's Check first group; remove
+a number once the human confirms that decision. The Plan card counts it. **A
+grilled feature has no such line.**
+
 **A change on the orchestrator's message is not the human's.** The
 orchestrator's messages open with a line saying they are from the project's
 orchestrator. When a message comes from it, a decision it changes keeps its