runcastle 1.6.2 → 1.6.4

package/skills/packs/runcastle/skills/feature/references/planning-alone.md

@@ -7,12 +7,20 @@ instead (`./grilling.md`); nothing here binds that conversation.
 You still look facts up, model the domain and park scope creep as
 `./grilling.md` says. What changes is who answers.
 
+**Survey the code through a subagent.** This chat goes on to build the feature,
+so every file you read here is carried into every later call. Send the codebase
+survey to one Explore-type subagent, its model picked from the human's
+use-case notes (SKILL.md, "Build it the cheapest good way"), with your
+questions, and keep the short map it returns. Read a
+file yourself only to settle one fact the map left open.
+
 **This run plans; it does not build.** Whatever the plan says,
-never call `dispatch_round` in this run: no round starts without the human's
-yes. You write the feature's docs (`decisions.md`, `spec.md`, `preview.html`)
-and, when the work is worth handing to workers, its tickets. The one exception
+never call `start_worker` or `start_review` in this run: nothing starts
+without the human's yes. You write the feature's docs (`decisions.md`,
+`spec.md`, `preview.html`), and the preview names the workers you would start.
+The one exception
 is designing its screens (**Designing alone**, below): for that, and only that,
-you may install dependencies and write components, preview pages and sample
+you may install dependencies and write components, design pages and sample
 data. Write no other code.
 
 - **One turn.** Do the whole plan in this one turn. Never end the turn to ask a
@@ -44,16 +52,28 @@ data. Write no other code.
   first.
 - **A timed-out tool is not a refused one.** A timeout is no answer, and the
   call may have landed anyway. Retry it once, checking first that it did not
-  land: before repeating `emit_tickets`, `update_ticket` or `cancel_ticket`,
-  read `list_tickets` and send only what is missing. If the retry times out
+  land. If the retry times out
   too, carry on and say so in the closing message.
 - **Check first.** Pick at most five decisions for the human to check first:
   guesses about their intent the brief did not settle, decisions that force
   several others, and decisions the challenger disagreed with. They open the
-  preview's decisions part (`./preview.md`).
-- **Design, but never show.** You may design the feature's screens
-  (**Designing alone**, below), but never call `show_panel`: nobody is there to
-  look, and the human opens the designs when they choose.
+  Plan's decisions part (`./preview.md`). Record them in `decisions.md` as one
+  line under its intro, `Check first: 8, 9, 17` (the numbers, at most five),
+  kept in step with the Plan's Check first group; the Plan card counts it. Drop
+  a number once the human confirms that decision.
+- **For the human.** Every decision that changes what the human gets — what
+  they or their users see, how the app or runcastle behaves for them, a setting
+  of their own — gets a `**For the human.**` line under its `**Assumed.**`
+  line, whether or not it is one of the five to check first. Each one is put to
+  the human before your plan gets its yes. A decision only about how the feature
+  is built gets no mark. Never override a setting the human set themselves
+  without marking it. A decision the brief records under
+  `## Decided with the human` is already theirs: copy it into `decisions.md`
+  without `**Assumed.**`.
+- **Show with cards, never the panel.** You may design the feature's screens
+  (**Designing alone**, below) and call `show_design` and `show_plan`: they post
+  cards and open nothing, so the human finds them when they are back. Never call
+  `show_panel`: nobody is there to look.
 
 ## Designing alone
 
@@ -62,61 +82,72 @@ visual change (a colour, a label, one control) is described in the plan
 instead: it would not repay the install. A feature with no screen designs
 nothing.
 
-- **When.** Once the decisions are recorded and before the spec, so the spec,
-  the tickets and the preview can name the designed components.
+- **When.** Once the decisions are recorded and before the spec, so the spec
+  and the preview can name the designed components.
 - **How.** As `./design.md` says for an attended chat: the project's own
-  install, the project's own frontend dev server, one preview page per state,
+  install, the project's own frontend dev server, one design page per screen
+  with its states on a switcher (never a design per state or variant),
   sample data, navigation off, real components, the project's design docs.
   Design against the components on the feature's base branch; never read
   another feature's worktree. If a screen needs a shared component changed, change
   it here and say so in the closing message.
 - **Tweaks for taste.** Where a look is genuinely open (two layouts, a density,
-  an accent), leave a Tweaks menu on that preview page instead of guessing
+  an accent), leave a Tweaks menu on that design page instead of guessing
   (`./design.md`, Tweaks). **At most two
   open choices per screen**: past that, pick, and list your picks in the
   closing message. Everything the menu needs, the alternative styles included,
-  lives in the preview page, never in the app's own files.
+  lives in the design page, never in the app's own files.
 - **Look at your own screens.** Call `start_design_server({ command })`, which
-  also records the command so the human's Open in design starts it later. Then
-  check every preview page. With `agent-browser` on the PATH: `agent-browser
-  open <url>`, `agent-browser screenshot <path>` (a temporary path, never in the
-  repo), read the image, critique it against the project's design docs, fix it,
-  and look again; `agent-browser close` when done. Without it, check that each
+  also records the command so the human's Design tab can start it later. Then
+  check every state of every design page (each `?state=` address). With
+  `agent-browser` on the PATH, hand the loop to a subagent on the model the
+  human's notes give UI work:
+  it runs `agent-browser open <url>`, `agent-browser screenshot <path>` (a
+  temporary path, never in the repo), reads the image, critiques it against the
+  project's design docs, fixes it and looks again, closes with
+  `agent-browser close`, and returns its verdict and the final picture's path
+  for `show_design`. Do not read the images yourself. Without it, check that each
   page compiles and serves, and say in the closing message that you never saw
   them. The design server stops by itself when this run ends.
+- **Record every design.** Once a page is right, call `show_design({ path, title,
+  width? , picture? })` for it with a human title and the width you laid it out
+  at, passing the final screenshot you took of its most telling state as
+  `picture`, once per page, never once per state. It posts a design card
+  and records the design for the Design tab; it opens nothing in this run.
 - **A screen you cannot serve** (no frontend dev server you can work out, a
   page the server builds, native mobile) is a hand mock in `preview.html`, as
   any plan draws one. Say so in the closing message. Do not stop or ask.
-- **Leave the designs uncommitted.** Never commit a component, preview page,
+- **Leave the designs uncommitted.** Never commit a component, design page,
   sample data or `.runcastle/design.json` you designed: only the human's
   approval commits them. Commit your docs by path, so nothing designed rides
   along.
-- **In the preview**, each designed screen is a designed-screen entry
-  (`./preview.md`, Designed screens) naming its component file and preview page.
-  A ticket that wires one follows `./tickets.md` on designed screens.
+- **In the Plan**, each designed screen is a designed-screen entry
+  (`./preview.md`, Designed screens) naming its title, the states its switcher
+  holds, its component file and design page, with no button.
+  A worker that wires one follows `./workers.md` on designed screens.
 
 ## Straight through, then ask
 
 1. Write `spec.md` (`./spec.md`) once the decisions are recorded.
-2. Write the tickets only if the work is worth handing to workers (SKILL.md,
-   "Build it the cheapest good way"; then `./tickets.md`). Otherwise the plan
-   says you will build it yourself, and that is the usual answer for a small
-   feature.
+2. Plan the workers by the offering rule (SKILL.md, "Build it the cheapest good
+   way"): each with its label, one-line purpose and kind, in the preview. Start
+   none. With none, the plan says you will build it yourself, and that is the
+   usual answer for a small feature.
 3. Draw the preview and run its self-check (`./preview.md`).
 4. Commit the docs.
-5. **End with one closing chat message** that covers the plan only: that it was
+5. Call `show_plan()` once, before the closing message.
+6. **End with one closing chat message** that covers the plan only: that it was
    made without the human, how many decisions it holds and which are to check
-   first (by number and title), whether it is tickets or work you will do
+   first (by number and title), which workers it offers and what you will do
    yourself, and anything that stopped you doing the job (a refused or failed
    tool the plan needed, and what you decided without it). Leave out the state
    of tools and connectors the plan did not need. **If you designed**, also
-   name each designed screen, the open Tweaks choices, any shared component you
+   name each designed screen and the states its switcher holds, the open Tweaks choices, any shared component you
    changed, and whether you saw the screens in screenshots or only checked that
-   they compile, and say that the yes commits the designs as they stand. Close the message by asking
-   the human for their yes to start round 1 (or to start the work, if there are
-   no tickets).
-6. Call `mcp__runcastle__wait_for_you({ why: "start round 1?" })`, or
-   `mcp__runcastle__wait_for_you({ why: "designs to look at · start round 1?" })`
-   if you designed. With no tickets, say "start the work?" in place of "start
-   round 1?". Then end the turn. The human answers in this chat when they
+   they compile, and say that only designs the human approves are committed. Close the message by asking
+   the human for their yes to start the work.
+7. Call `mcp__runcastle__wait_for_you({ why: "start the work?", kind: "plan" })`.
+   (Waiting designs raise "Design to approve" by themselves; no design-kind wait
+   is needed.) Write nothing after step 6's question, so the turn ends on
+   it, and then end the turn. The human answers in this chat when they
    are back; their yes is what starts the work, in a later turn.

package/skills/packs/runcastle/skills/feature/references/preview-starter.html

@@ -3,6 +3,7 @@
 <head>
 <meta charset="utf-8">
 <meta name="viewport" content="width=device-width, initial-scale=1">
+<!-- FILL:title -->
 <title>[Feature title] preview</title>
 <style>
 /* ---- runcastle theme: dark is the default, light is a full peer.
@@ -10,10 +11,10 @@
    Token names and values are the app's own (apps/web/src/theme.css): keep them in step. ---- */
 :root{
   color-scheme:dark;
-  --color-canvas:#0a0c11;--color-surface:#10131a;--color-surface-raised:#161a24;--color-surface-hover:color-mix(in oklab, var(--color-text) 3.5%, transparent);--color-surface-selected:color-mix(in oklab, var(--color-text) 6%, transparent);--color-fill-card:color-mix(in oklab, var(--color-text) 2.5%, transparent);--color-fill-well:color-mix(in oklab, var(--color-text) 6%, transparent);--color-surface-inset:#0c0e14;
-  --color-border:#222837;--color-border-subtle:rgb(200 215 255 / 0.06);--color-border-strong:#333a4d;
-  --color-text:#eceef4;--color-text-secondary:#a2a8b9;--color-text-tertiary:#8a91a5;--color-text-disabled:#4b5163;--color-icon:#8990a4;
-  --color-primary:#eceef4;--color-on-primary:#0a0c11;
+  --color-canvas:#04060b;--color-surface:#080c13;--color-surface-raised:#0e131e;--color-surface-hover:color-mix(in oklab, var(--color-text) 3%, transparent);--color-surface-selected:color-mix(in oklab, var(--color-text) 6%, transparent);--color-fill-card:var(--color-surface-hover);--color-fill-well:var(--color-surface-selected);--color-surface-inset:var(--color-canvas);
+  --color-border:#181f2d;--color-border-subtle:rgb(200 215 255 / 0.06);--color-border-strong:#293243;
+  --color-text:#eceef4;--color-text-secondary:#a9b1c1;--color-text-tertiary:#798294;--color-text-disabled:#424a5b;--color-icon:var(--color-text-tertiary);
+  --color-primary:#eceef4;--color-on-primary:var(--color-canvas);
   --color-accent:#4f8ef7;--color-accent-text:#7aaafa;--color-accent-subtle:#16213a;
   --color-success:#46b67a;--color-warning:#e2a53b;--color-danger:#f06363;--color-danger-subtle:#2a1515;
   --color-scrim:rgb(0 0 0 / 0.6);
@@ -23,9 +24,9 @@
 }
 :root[data-theme="light"]{
   color-scheme:light;
-  --color-canvas:#f4f6f9;--color-surface:#ffffff;--color-surface-raised:#ffffff;--color-surface-hover:color-mix(in oklab, var(--color-text) 4%, transparent);--color-surface-selected:color-mix(in oklab, var(--color-text) 7%, transparent);--color-fill-card:color-mix(in oklab, var(--color-text) 3%, transparent);--color-fill-well:color-mix(in oklab, var(--color-text) 7%, transparent);--color-surface-inset:#f4f6f9;
+  --color-canvas:#f4f6f9;--color-surface:#ffffff;--color-surface-raised:#ffffff;--color-surface-hover:color-mix(in oklab, var(--color-text) 3.5%, transparent);--color-surface-selected:color-mix(in oklab, var(--color-text) 7%, transparent);
   --color-border:#dfe3ec;--color-border-subtle:rgb(22 30 50 / 0.07);--color-border-strong:#cdd2de;
-  --color-text:#161a24;--color-text-secondary:#596075;--color-text-tertiary:#676e82;--color-text-disabled:#a4aab9;--color-icon:#7a8195;
+  --color-text:#161a24;--color-text-secondary:#454f62;--color-text-tertiary:#677083;--color-text-disabled:#a4aab9;
   --color-primary:#161a24;--color-on-primary:#ffffff;
   --color-accent:#3a7ef0;--color-accent-text:#2361d4;--color-accent-subtle:#ecf2fe;
   --color-success:#23955a;--color-warning:#c06e00;--color-danger:#df5050;--color-danger-subtle:#fdeeee;
@@ -34,9 +35,9 @@
 @media (prefers-color-scheme:light){
   :root:not([data-theme]){
     color-scheme:light;
-    --color-canvas:#f4f6f9;--color-surface:#ffffff;--color-surface-raised:#ffffff;--color-surface-hover:color-mix(in oklab, var(--color-text) 4%, transparent);--color-surface-selected:color-mix(in oklab, var(--color-text) 7%, transparent);--color-fill-card:color-mix(in oklab, var(--color-text) 3%, transparent);--color-fill-well:color-mix(in oklab, var(--color-text) 7%, transparent);--color-surface-inset:#f4f6f9;
+    --color-canvas:#f4f6f9;--color-surface:#ffffff;--color-surface-raised:#ffffff;--color-surface-hover:color-mix(in oklab, var(--color-text) 3.5%, transparent);--color-surface-selected:color-mix(in oklab, var(--color-text) 7%, transparent);
     --color-border:#dfe3ec;--color-border-subtle:rgb(22 30 50 / 0.07);--color-border-strong:#cdd2de;
-    --color-text:#161a24;--color-text-secondary:#596075;--color-text-tertiary:#676e82;--color-text-disabled:#a4aab9;--color-icon:#7a8195;
+    --color-text:#161a24;--color-text-secondary:#454f62;--color-text-tertiary:#677083;--color-text-disabled:#a4aab9;
     --color-primary:#161a24;--color-on-primary:#ffffff;
     --color-accent:#3a7ef0;--color-accent-text:#2361d4;--color-accent-subtle:#ecf2fe;
     --color-success:#23955a;--color-warning:#c06e00;--color-danger:#df5050;--color-danger-subtle:#fdeeee;
@@ -84,11 +85,9 @@ button{font:inherit;color:inherit;background:none;border:0;padding:0;cursor:poin
 /* the framed panel a mocked screen sits in; inside it, use the project's own styling */
 .screen{border:1px solid var(--color-border);border-radius:var(--radius-lg);overflow:hidden;background:var(--color-surface);position:relative}
 
-/* a screen designed in design mode: a name, one line, and a button that opens it in the app's design panel */
+/* a screen designed in design mode: a title, one line, the states its switcher holds, and the component file and design page it names (no button) */
 .designed{display:grid;gap:6px;justify-items:start;padding:12px 14px;border:1px solid var(--color-border);border-left:2px solid var(--color-accent);border-radius:var(--radius-md);background:var(--color-surface-raised)}
 .designed p{color:var(--color-text-secondary)}
-.designed button[data-open-design]{height:28px;padding:0 12px;border-radius:var(--radius-md);background:var(--color-accent-subtle);color:var(--color-accent-text);font-weight:500}
-.designed button[data-open-design]:hover{background:var(--color-accent);color:#fff}
 
 /* decided / left out / under the hood */
 .dlist{border-top:1px solid var(--color-border-subtle);margin-top:12px}
@@ -134,6 +133,7 @@ button{font:inherit;color:inherit;background:none;border:0;padding:0;cursor:poin
 
 <!-- 1 · what this is -->
 <header id="what">
+  <!-- FILL:what -->
   <h1>[Feature title]</h1>
   <p class="lede">[One or two sentences: what this feature is, in the human's words.]</p>
   <div class="meta"><span><span data-dcount></span> decisions</span><span class="mono">docs/features/[slug]/preview.html</span></div>
@@ -145,6 +145,7 @@ button{font:inherit;color:inherit;background:none;border:0;padding:0;cursor:poin
 <!-- 2 · the show -->
 <section id="show">
   <h2>The show</h2>
+  <!-- FILL:show -->
   <!-- THE SHOW IS FREE-FORM. Replace this comment with whatever explains how the
        feature will work: screens, clickable prototypes, skeletons, flows, before
        and after, scenarios. There is no template. Pin a decision's number where
@@ -154,10 +155,12 @@ button{font:inherit;color:inherit;background:none;border:0;padding:0;cursor:poin
 
        Example screen block (copy it, rename it in kebab case, uncomment the
        panel; delete it if the show has no screen). A screen designed in design
-       mode gets a designed-screen entry instead of a mock; see preview.md:
-       <div class="designed"><h3>Name</h3><p>What is real, what is sample.</p>
-       <button data-open-design="/preview/path">Open in design</button></div>
+       mode gets a designed-screen entry instead of a mock, with no button; see preview.md:
+       <div class="designed"><h3>Title</h3><p>What is real, what is sample.</p>
+       <p>States: empty · loading · full · error.</p>
+       <p class="mono">src/components/File.tsx · design page /preview/path</p></div>
   -->
+<!-- FILL:screen -->
 <!-- screen:example-name -->
 <!--
     <div class="screen">
@@ -178,9 +181,11 @@ button{font:inherit;color:inherit;background:none;border:0;padding:0;cursor:poin
 <section id="left-out">
   <h2>What is left out</h2>
   <div class="out2">
+    <!-- FILL:later -->
     <div><h3>Later</h3><ul>
       <li><i class="dot"></i>[Deferred to a backlog feature]</li>
     </ul></div>
+    <!-- FILL:not-this -->
     <div><h3>Not this feature</h3><ul>
       <li><i class="dot"></i>[Out of scope]</li>
     </ul></div>
@@ -192,6 +197,7 @@ button{font:inherit;color:inherit;background:none;border:0;padding:0;cursor:poin
   <details class="hood" id="hood">
     <summary><svg class="i"><use href="#i-chev"/></svg><h2>Under the hood</h2></summary>
     <div class="sub">
+      <!-- FILL:hood -->
       <!-- [The technical shape, for a reader who wants it. Draw it where you can.] -->
     </div>
   </details>
@@ -204,11 +210,13 @@ button{font:inherit;color:inherit;background:none;border:0;padding:0;cursor:poin
   var $ = function (s, r) { return (r || document).querySelector(s) }
   var $$ = function (s, r) { return Array.prototype.slice.call((r || document).querySelectorAll(s)) }
 
+  // <!-- FILL:D -->
   // every decision in decisions.md, by number and title, in order: [title, reason, mark?]
   // mark is 'assumed' for a decision made without the human; a grilled feature has none
   var D = [
     ['[Decision 1 title]', '[Why, in a sentence]']
   ]
+  // <!-- FILL:C -->
   // check first, a self-planned feature only (at most five): [decisionNumber, alternative, whyUnsure, tag?]
   // leave it empty for a grilled feature, and no group is drawn
   var C = []
@@ -256,12 +264,6 @@ button{font:inherit;color:inherit;background:none;border:0;padding:0;cursor:poin
   // navigation is unreliable inside the app's sandboxed frame
   function reveal(el) { el.scrollIntoView({ behavior: 'smooth', block: 'center' }) }
   document.addEventListener('click', function (e) {
-    // Open in design: the app listens for exactly this message and opens the design panel
-    var od = e.target.closest('[data-open-design]')
-    if (od) {
-      parent.postMessage({ type: 'runcastle:open-design', path: od.dataset.openDesign }, '*')
-      return
-    }
     var pin = e.target.closest('a.pin[data-d]')
     if (pin) {
       e.preventDefault()

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

@@ -1,27 +1,28 @@
-# The plan preview — the page the human looks at
+# The Plan — the page the human looks at
 
 Load this when the decisions are settled and you are about to show the human
-the plan, or when a decision edit means the preview has to be redrawn.
+the plan, or when a decision edit means the Plan has to be redrawn.
 Otherwise it costs this conversation nothing.
 
-The preview is the one page the human reads the feature by. They confirm the
+The Plan (`preview.html`) is the one page the human reads the feature by. They confirm the
 plan by looking at it, and when tired it is the only thing they read before
-they say yes to the first round. Draw it for that reader.
+they say yes to the work. Draw it for that reader.
 
 ## Show it, then get the yes
 
 1. **Draw it** from `./preview-starter.html`, following the rules below.
 2. **Check it against `decisions.md`** (the self-check at the end). Fix the
    preview before anyone sees it.
-3. **Show it**: `show_panel({ view: 'plan' })` opens it beside the chat. Tell
-   the human what you propose — tickets and rounds, or work you will do
-   yourself — and ask for their explicit yes. Then wait for the answer.
+3. **Show it**: `show_plan()` posts the Plan card in the chat and opens the
+   Plan tab beside it. Tell the human what you propose — the workers, the work you
+   will do yourself, the Review worker at the end — and ask for their explicit yes. Then wait for the answer.
 4. **A correction is a decision edit plus a redraw.** Edit the decision in
-   `decisions.md` and redraw the preview in the same move, then ask them to
-   look again.
+   `decisions.md` and redraw the preview in the same move, call `show_plan()`
+   again, then ask them to look again.
 
-With no human present, steps 1 and 2 are the whole of this; `./planning-alone.md`
-says how that run asks for the yes.
+With no human present, steps 1 and 2 are the whole of this, plus one
+`show_plan()` before the closing message; `./planning-alone.md` says how that
+run asks for the yes.
 
 **Never skip the preview on your own judgement** — not because the feature is
 small, not because the grill went quickly. A small feature gets a small
@@ -37,9 +38,22 @@ built.
 - **Exactly one file, `preview.html`, at the root of the feature's docs dir**:
   `docs/features/<slug>/preview.html`. Several screens or flows are sections of
   that one page, never more files.
-- **Start from `./preview-starter.html`.** Copy it to that path and fill it in.
-  It carries runcastle's theme tokens for both themes and the styles and markup
-  for the fixed parts; do not restyle them.
+- **Start from `./preview-starter.html`.** Copy it to that path with a shell
+  copy (`cp`), find its slots with `grep -n 'FILL:'` on the copy, and fill each
+  by editing; **never read the starter whole**. It carries runcastle's theme
+  tokens for both themes and the styles and markup for the fixed parts; do not
+  restyle them.
+- **The slots**, each a `<!-- FILL:<name> -->` line just above what to replace:
+  - `title`: the feature title in `<title>`.
+  - `what`: the `<h1>` title, the one- or two-sentence lede, `[slug]` in the meta line.
+  - `show`: replace the free-form comment below it with the show.
+  - `screen`: the example screen block; copy and rename it per screen, or delete it.
+  - `D`: one entry per decision, in order: `['Title', 'Why, in a sentence']`, or
+    `['Title', 'Why', 'assumed']` for a decision made without the human.
+  - `C`: Check first, a self-planned feature only, at most five:
+    `[decisionNumber, 'Alternative', 'Why unsure', 'tag'?]`; leave `[]` for a grilled feature.
+  - `later` / `not-this`: one `<li><i class="dot"></i>…</li>` per item left out.
+  - `hood`: the technical shape, inside the collapsed **Under the hood**.
 - **Throwaway explorations** may go under `docs/features/<slug>/prototypes/`.
   They are never shown; the app shows only `preview.html`.
 
@@ -50,6 +64,9 @@ built.
    no template**: screens, clickable prototypes, skeletons, flows, before and
    after, scenarios. Choose the form that explains *this* feature — work with no
    screen gets flows, use cases, before and after, or a clickable skeleton.
+   **It ends with who builds what**: each worker you offer by its label, one-line
+   purpose and kind ("with you" or "on its own"), what you build yourself, and
+   the Review worker at the end. The human's yes starts those workers.
 3. **What was decided.** Every decision in `decisions.md` by its number and
    title, with the reason available on demand (the starter's `D` list builds
    this). Where a decision is visible in the show, pin its number on that spot:
@@ -89,8 +106,8 @@ Each screen in the show is a **screen block**: the lines between two markers,
 <!-- /screen:<name> -->
 ```
 
-with `<name>` in kebab case and unique in the file. A ticket that builds that
-screen names the block, and its worker reads only those lines — so put
+with `<name>` in kebab case and unique in the file. A worker that builds that
+screen is pointed at the block and reads only those lines — so put
 everything the screen needs to be understood between the markers, and nothing
 else. Delete the starter's `example-name` block if the show has no screen.
 
@@ -99,15 +116,15 @@ else. Delete the starter's `example-name` block if the show has no screen.
 A screen designed in design mode (`./design.md`) is **not mocked
 again**. Its place in the show is a **designed-screen entry**:
 
-- its name;
+- its name, the same title you gave `show_design`;
 - one line saying what is real and what is sample data;
-- an **Open in design** button: `<button data-open-design="/preview/path">Open in design</button>`,
-  where the value is the preview page's path on the design server. The starter
-  wires it; the app answers by opening the design panel at that path, starting
-  the server first if needed.
+- the states its switcher holds, so the plan says what the human will find.
+
+The entry has **no button**: the human reaches a design from its card in the chat
+and from the Design tab, which lists every design you showed with `show_design`.
 
 Wrap the entry in a screen block, but put no markup in it. The block names the
-**committed component file and the preview page path**, so the ticket that
+**committed component file and the design page path**, so the worker that
 connects the screen has something to point at. Use the starter's `.designed`
 entry:
 
@@ -116,8 +133,8 @@ entry:
 <div class="designed">
   <h3>Invoice list</h3>
   <p>Layout and states are real components; the rows are sample data.</p>
-  <p class="mono">src/components/InvoiceList.tsx · preview /preview/invoice-list</p>
-  <button data-open-design="/preview/invoice-list">Open in design</button>
+  <p>States: empty · loading · full · error.</p>
+  <p class="mono">src/components/InvoiceList.tsx · design page /preview/invoice-list</p>
 </div>
 <!-- /screen:invoice-list -->
 ```
@@ -133,8 +150,7 @@ or inline SVG. This is enforced, not a preference: the app renders the preview
 in a sandboxed frame that runs scripts and refuses every fetch, external image
 and font, form post and popup. Anything hosted elsewhere simply does not load.
 In-page links scroll by script (the starter does this), because hash navigation
-is unreliable inside that frame. The Open in design button posts a message to
-the app, which is not a request, so it stays within this rule.
+is unreliable inside that frame.
 
 ## Sizing
 
@@ -152,6 +168,8 @@ minute for a small feature, a few minutes for a large one.**
   For a grilled feature, `C` is empty and no decision is marked.
 - Every pin points at the decision the spot actually shows.
 - The five parts are in order; **Under the hood** is closed.
+- The show ends with who builds what: every worker by label, purpose and kind,
+  and the Review worker unless the human declined it.
 - Every screen designed in design mode is a designed-screen entry that names its
-  committed component and preview page, not a redrawn mock.
+  states, its committed component and design page, not a redrawn mock.
 - The file is still fully inline.

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

@@ -20,7 +20,7 @@ settled.
    Prefer *existing* seams to new ones; use the *highest* seam possible; the
    fewer across the codebase, the better — the ideal is one. If new seams are
    needed, propose them at the highest point you can. They flow straight into
-   the tickets and the tests, so get them right here.
+   the workers' assignments and the tests, so get them right here.
 
 3. **Write `docs/features/<slug>/spec.md`** with exactly these sections:
 

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

@@ -0,0 +1,144 @@
+# Workers
+
+Load this when you are about to start, message, land or send back a worker, or
+you have just been woken by one. Which work gets a worker is SKILL.md's rule
+("Build it the cheapest good way").
+
+A worker is an agent in its own sandbox, on its own copy of the feature branch.
+The human can step into any worker and talk to it. It cannot see this chat. It
+can read the feature's docs, its designs and your latest turns. Its only way to
+change the feature is its handback. `get_feature_context` lists the feature's
+workers and their statuses.
+
+## Start one
+
+Start workers on the human's yes to the plan, or to an offer in chat. Nothing
+else starts them, and they need no approval each.
+
+`start_worker({ label, purpose, kind, goal, doneWhen, model? })`:
+
+- **label** — the short name the human sees in the sidebar ("Thread list").
+- **purpose** — one line on what it is for.
+- **kind** — `"with-you"` for taste work, `"on-its-own"` for build work.
+- **goal** and **doneWhen** — the assignment, below.
+- **model** — only an id from `get_feature_context`'s `annotatedModels`, where
+  the human's note plainly fits the job. Otherwise omit it. Never invent an id.
+
+A "with you" worker makes a first pass, then waits for the human. It hands back
+only when the human says they are happy or presses **Hand back**. An "on its
+own" worker hands back when its done-when is met, and stops only for a real
+question.
+
+Where one piece must wait for another, start the second after you land the
+first. Pieces that run side by side should touch different files: two on the
+same files conflict when you land them. Workers share the machine's limit of
+agents working at once; past it they queue and start by themselves.
+
+Without Docker or Podman, `start_worker` says so. Tell the human in plain words
+and point them at the setup check (doctor).
+
+## Write the assignment
+
+The worker cannot ask you where things live, so the goal and done-when are
+concrete:
+
+- **Name what it needs**: the files to touch, the patterns to copy, the shapes,
+  the gotchas, the decisions and spec sections that bind it.
+- **State the check.** A worker with no stated check reports success on its own
+  terms. Say what is built and what proves it: a test worth writing, a command
+  that passes, the screen that shows it. Name the tests that cover the change,
+  never the whole suite: you run the project's checks after landing.
+- **UI work names its design references**: the project's design docs and this
+  feature's designs. Ask it to plan the screen, build it, then critique it
+  against those docs with screenshots.
+- **A screen in `preview.html`**: point it at one named screen block, never the
+  file. It reads only the lines between `<!-- screen:<name> -->` and
+  `<!-- /screen:<name> -->`. The block shows the approved look, not the
+  implementation: it builds with the project's real components.
+- **A designed screen** (committed in design mode): name the component and its
+  design page, and say the look is approved. Its job is to connect, never
+  restyle: real data in place of the sample, the behaviour the design left out,
+  markup changed only where the wiring needs it. The states on the design
+  page's switcher are the states it must reach.
+- **Hard-to-reach state**: when `scenarios.setUp` is true, the done-when ships
+  the scenario (see **Ship a scenario**, below).
+- **One area each.** A worker's cost grows with the square of its context, so a
+  job across several packages is two workers, one after the other.
+
+## Ship a scenario
+
+**Ship a scenario when the state is hard to reach.** A scenario is a project
+command under `.runcastle/scenarios/` that seeds a state and prints the URL to
+land on, so a test drive starts where the feature is instead of on a blank app.
+Read `get_feature_context`'s `scenarios` field — `{ setUp, runnerConfigured,
+scenarios, fixtures }` — before you decide anything.
+
+**When `setUp` is true**, ask of each piece of work: will the person driving
+this have to build state by hand to see it — an account, a cart with an expired
+coupon?
+
+- If yes, the work that builds that state ships `.runcastle/scenarios/<group>/<name>.<ext>`, which seeds the state (reusing `_fixtures`) and prints `ENTRY_URL=<where>`: a line in that worker's done-when, or yours to write. Name the fixtures it should reuse. When the change is an API call, it also ships a sibling `.http` file at the same path with the request, and the scenario prints `TOKEN=` when the call is authenticated.
+- Use that scenario as the `scenario` you declare ready with; the Review worker replays it rather than improvising the setup.
+- Copy changes and settings toggles get none. A scenario earns its place only where reaching the state is the chore.
+- A worker writes and typechecks the scenario but cannot run it — a sandbox has no drive.
+
+**When `setUp` is false**, card nothing about scenarios. Tell the human once
+that ＋ New scenario in a test drive sets scenarios up for this project.
+
+## Talk to it
+
+`message_worker({ workerId, text })` reaches any worker at any time. One sent
+mid-turn waits for the turn's end. The human may be talking to it too.
+
+Never ask a worker for its transcript or its work in detail. This chat gains
+only handbacks, and that is the point.
+
+## A handback
+
+You are woken once, with a handback card: the worker's summary, which carries
+any direction the human gave it, plus its commits and changed files. Trust the
+commits over the summary. Then do one of three things:
+
+- **Land it**: `land_worker({ workerId })` lands its branch on the feature
+  branch through the landing queue, like your own commits. Resolve any conflict.
+  Then run the project's checks yourself, and fix small slips yourself rather
+  than sending it back.
+- **Send it back**: `send_back_worker({ workerId, note })`, saying concretely
+  what is wrong. It returns to working.
+- **Drop it**: `drop_worker({ workerId })` removes its sandbox and branch.
+
+Where the human's direction to a worker changes a decision, amend
+`decisions.md` and `spec.md` when you land it.
+
+A worker the human started with the "+" has no assignment. It hands back the
+same way, and you land, send back or drop it the same way.
+
+A worker that hands back after you declared ready: land it, then declare ready
+again.
+
+## The review
+
+The review at the end is a worker labelled **Review**. Start it when the work
+is done, every build worker landed or dropped: `start_review({})`. It writes no
+code and lands nothing. It runs the project's checks itself, reports each
+finding as it goes, and hands back.
+
+- **Its mode is set at start.** Left unset, it drives the app when this
+  machine can: on the human's machine, in their checkout, while it holds
+  the one drive slot. It waits as queued while the human drives. Otherwise, or
+  with `mode: "gates"` (a change with nothing to drive), it reads the diff in
+  its own sandbox.
+- **Its handback is the Review Package** in your chat: its account,
+  screenshots, walkthrough, calls and findings, with the findings listed for
+  you. Close each finding with `resolve_finding` (`addressed` or `dismissed`,
+  with a note). Fix the defects you judge real, yourself or with workers.
+- **Then verify.** Once you fixed some, start a fresh one:
+  `start_review({ verify: { findingIds, commits } })`, with only those findings
+  and the commits that fixed them. It checks each fix holds and nothing else.
+- `send_back_worker` asks a review for more; `drop_worker` closes it. Never
+  `land_worker` it.
+
+## A failed worker
+
+When a worker's sandbox dies, its setup fails or its agent crashes, you get one
+short message saying what failed. Retry it, drop it, or do the job yourself.