runcastle 1.5.3 → 1.5.5

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "runcastle",
-  "version": "1.5.3",
+  "version": "1.5.5",
   "description": "Burn tickets into shipped features with Claude Code.",
   "license": "FSL-1.1-ALv2",
   "type": "module",

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; `revisit` and `prepare` are 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. 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.
 
 ## The `runcastle` pack
 
@@ -8,13 +8,10 @@ Scope-specific skills, each namespaced `/runcastle:<skill>`:
 
 | Skill | Invoked | Does |
 |---|---|---|
-| `/runcastle:ideate` | entry for `kind=ideation` | grills the human, locks decisions incrementally, drives spec + tickets out of one unbroken window |
-| `/runcastle:spec` | by ideate | synthesizes `spec.md`, completes the `spec` phase |
-| `/runcastle:tickets` | by ideate | emits session-sized vertical-slice tickets via MCP, completes the `tickets` phase |
-| `/runcastle:qa` | entry for `kind=qa` | read-only Q&A over an existing feature; never advances phases |
+| `/runcastle:feature` | entry for `kind=chat` | the feature's lead from its first message to merge: grills when the intent is unclear, 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: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:revisit` | entry for `kind=revisit` | *original* — folds late information into a finished feature; on an Iterate from review, runs the whole front half of a lap |
-| `/runcastle:design` | by the feature chat's entry skills | *original* — live UI design beside the chat: preview pages, the design server and panel, Tweaks, `design:` commits; not an entry skill |
+| `/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):
@@ -26,16 +23,17 @@ packs/
     ├── .claude-plugin/
     │   └── plugin.json        # name: "runcastle" → sets the /runcastle: namespace
     └── skills/
-        ├── ideate/SKILL.md
-        ├── spec/SKILL.md
-        ├── tickets/SKILL.md
+        ├── feature/
+        │   ├── SKILL.md
+        │   └── references/         # grilling, spec, tickets, rounds, 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
-        ├── revisit/SKILL.md
+        │       ├── health-sweeps.md
+        │       └── triage.md
+        ├── prepare/SKILL.md
         └── code-review/SKILL.md
 ```
 
@@ -68,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:ideate` and friends. The injected system prompt tells each session which entry skill to invoke for its kind (`/runcastle:ideate` for ideation, `/runcastle:qa` for Q&A).
+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).
 
 ### Entry-skill isolation — settings deny rules, not `disable-model-invocation`
 
@@ -76,11 +74,11 @@ Every skill's `description` is loaded into every session in the pack, whether or
 not that session can use it. That is cheap for a skill the model might genuinely
 need and risky for one it must not run: a session carrying the descriptions of
 every other kind's entry skill is one description-match away from running
-another session's procedure — `project/SKILL.md` says "**Never run an ideation
-grilling**" while `ideate`'s description sits in the same list offering exactly
+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 five **session-entry** skills — `ideate`, `qa`, `revisit`, `project`,
+The **session-entry** skills — today `feature`, `qa`, `project` and
 `prepare` — 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
@@ -98,13 +96,11 @@ live: **per-session settings**. The launcher launches each session with
 — for every entry skill that is not that kind's own (`entrySkillsFor` /
 `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` keeps both of its openings
-(`ideate` + `revisit`); `qa` — whose session kind was retired — is denied
-everywhere; `drive-fix` has no entry skill and denies all five.
+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.
 
-The chained/reached skills — `spec` and `tickets` (invoked by name from inside
-`ideate`) and `code-review` (reached by description) — are in no
-deny list.
+The reached skill — `code-review` (reached by description) — is in no deny list.
 
 The rule, for anything added later: **a session-entry skill goes into
 `ENTRY_SKILLS` and the per-kind table in
@@ -129,14 +125,13 @@ The standing convention across this pack:
   rule lives there, backed by `launcher/edit-guard.ts`, and is *not* restated in
   any skill).
 - **Procedures belong to the skill.** One skill owns each procedure in full;
-  `revisit/SKILL.md` §Lap mode is the whole lap procedure, `ideate/SKILL.md` §1
-  is the whole grilling procedure.
+  `feature/references/grilling.md` is the whole grilling procedure.
 - **Where a skill names a fact the prompt also names, it points instead of
-  restating** — the shape is `ideate/SKILL.md`'s "The injected system prompt
-  carries the slug and paths; trust `get_feature_context` for the live state."
+  restating** — "the injected system prompt carries the slug and paths; trust
+  `get_feature_context` for the live state."
 - **Where two skills need the same procedure, the second delegates by
-  reference** — "grill the way `/runcastle:ideate` §1 does" rather than a
-  second copy that ages differently.
+  reference** — "grill the way `feature/references/grilling.md` does" rather
+  than a second copy that ages differently.
 - **A rule the hook enforces is stated once, as enforced, not as advice.** The
   `qa` kind's write refusals are server-side; `qa/SKILL.md` says so rather than
   asking nicely.
@@ -150,7 +145,7 @@ 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`, `complete_phase`).
+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`).
 4. Pass another `--plugin-dir` for it at launch.
 
 ## Not a pack: `../burner/`

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

@@ -1,6 +1,6 @@
 {
   "name": "runcastle",
-  "description": "Runcastle phase-scoped skills for the MCP feature pipeline: ideate, spec, tickets, qa, project, code-review (forks of Matt Pocock's grilling, to-spec, to-tickets and code-review, adapted) plus revisit, prepare and lead (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), qa, project and code-review (forks, adapted), plus prepare (original).",
   "version": "0.1.0",
   "author": { "name": "runcastle" }
 }

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

@@ -0,0 +1,72 @@
+---
+name: feature
+description: The runcastle feature lead's entry skill — the whole guidance for a feature's agent from its first message to merge, with the detail in reference files read when needed.
+disable-model-invocation: false
+---
+<!-- Folds in runcastle's former ideate, lead, spec, tickets, revisit and design skills (themselves forked from Matt Pocock's grilling, to-spec and to-tickets skills), 2026-10-24 -->
+
+# 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.
+
+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.
+
+## 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.
+
+## Understand before you build
+
+When the intent is unclear, grill: one question at a time, each with your recommended answer and why. Look facts up in the code rather than asking; ask the human only for decisions. Record each settled decision in `docs/features/<slug>/decisions.md` the moment it settles. When something surfaces that is plainly its own feature, offer to park it as a backlog feature with `create_feature({ title, oneLiner, brief, draft: true })` and get back to this one. When the brief is already concrete, skip the grilling. How: `./references/grilling.md`.
+
+Write `spec.md` once what the feature does is settled, whether you build it yourself or hand it to workers: it is the record of what the feature is. How: `./references/spec.md`.
+
+## Build it the cheapest good way
+
+Small work you do yourself: a few files, a change that would not split into tickets, a fix a round left behind. Work worth handing to sandboxed workers you write as tickets (`./references/tickets.md`); `emit_tickets` opens the **Work** view beside the chat for you. If a "small" change keeps growing, make it tickets.
+
+When the feature changes how a screen looks, offer to show it live before you talk layout in words: `./references/design.md`.
+
+## The human's yes
+
+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).
+
+Then run rounds: `./references/rounds.md`.
+
+## Review is your call
+
+Run a review ticket when the change is worth an independent look: it spans several areas, it has a surface a human operates, or you are not sure of it. Skip it when it is not, and say why. No rule requires one.
+
+## 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:
+
+- **what to test**: what changed, where to look, what would count as broken;
+- **how you checked it**: for example "typecheck and tests green; no review agent, since it's a one-file style change".
+
+Pass on any warning `declare_ready` returns.
+
+## 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.
+
+## Commit your own work
+
+Commit what you write, docs included, with conventional subjects (`feat(scope): …`, `fix(scope): …`, `docs(scope): …`), and only once the project's checks are green for code. **Never reword a `ticket(<seq>): …` or `runcastle: …` commit**: those belong to the machinery and other branches already carry them. While the human drives, your commits wait until the drive stops.
+
+## 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.
+- 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>" })`.
+
+## Situations
+
+- **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 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.

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

@@ -0,0 +1,158 @@
+# Design — iterate on the real screen, beside the chat
+
+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).
+
+## 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).
+
+## 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.
+
+## 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>`
+
+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.
+
+## 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.
+
+## 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.
+
+## 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.
+
+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.
+
+## 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:
+
+- **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).

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

@@ -0,0 +1,101 @@
+# Grilling, and recording what was decided
+
+Load this when the human's intent is unclear and you are about to interview
+them, 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.
+
+## Grill relentlessly
+
+Interview the human about every aspect of the feature until you reach a
+genuinely shared understanding. Walk each branch of the design tree, resolving
+dependencies between decisions one at a time.
+
+- **One question at a time.** Wait for the answer before the next. Asking
+  several at once is bewildering.
+- **Always recommend an answer.** Never ask a bare question — put your
+  recommended answer and say why. The human corrects or confirms.
+- **Look up facts; ask only for decisions.** If a fact is discoverable in the
+  codebase — how something works now, what a type looks like, whether a pattern
+  exists — read the repo and find it. Never make the human be your grep.
+  *Decisions* are theirs: put each one to them and wait.
+- **Model the domain as you go**: challenge terms that conflict with existing
+  usage, sharpen fuzzy words to one canonical meaning ("you said 'account' —
+  Customer or User?"), invent concrete edge cases that force precision, and
+  cross-check claims against the code ("your code cancels whole Orders, but you
+  just said partial — which is right?").
+- **Offer to cut deferred scope.** When the feature turns out larger than it
+  first looked, or the human is unsure of part of it, say so plainly with your
+  recommendation: build the part they are sure of, and put the rest in the
+  backlog as its own feature. It is an offer; the human decides.
+- **Put scope creep in the backlog instead of swallowing it.** When something
+  plainly its own feature surfaces, offer
+  `mcp__runcastle__create_feature({ title, oneLiner, brief, draft: true })`: a
+  backlog feature, no branch, nothing written, with the `brief` carrying why you
+  deferred it and what it must not swallow. When it builds on this feature, pass
+  `dependsOn: [<this feature's slug>]` so it cannot start before this one
+  merges. If the human wants it started by itself once this one ships, they can
+  mark it up next on its page. Then get back to this feature. Backlog features
+  are the only kind you create.
+
+Grilling is done when the human agrees you share the picture. That agreement
+is made on the plan preview (`./preview.md`), not in chat alone.
+
+## Record each decision at once
+
+The moment a decision settles, append it to `docs/features/<slug>/decisions.md`
+— **immediately, one at a time, never batched at the end.** If this session
+dies mid-grill, what was settled must already be on disk.
+
+```markdown
+## <n>. <short decision title>
+**Decision:** <the choice, in the project's domain vocabulary>
+**Why:** <the reason / the trade-off chosen over the alternatives>
+```
+
+A decision made without the human (see `./planning-alone.md`) keeps that shape
+and adds a line naming the main alternative it was chosen over. A decision the
+challenger disagreed with adds a further line with its reason:
+
+```markdown
+## <n>. <short decision title>
+**Decision:** <the choice>
+**Why:** <the reason>
+**Assumed.** Alternative: <the main alternative>.
+**Challenged:** <the challenger's reason>.
+```
+
+For example:
+
+```markdown
+## 4. Tags and dates are left out of the PDF
+**Decision:** The PDF carries the title and body only.
+**Why:** The brief asks for the note, not its filing.
+**Assumed.** Alternative: a small footer with tags and the last-edited date.
+```
+
+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 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
+`**Assumed.**` line, or gains one, and adds
+`**Changed by the orchestrator:** <why>`. The human has not seen it, and the
+record must say who decided. A message whose opening line says instead that it
+relays the human's own answer is the human confirming: remove the marks, that
+line included.
+
+**Later information supersedes, it does not rewrite.** When the human comes
+back with something new after decisions were written — a constraint they
+remembered, a change of mind — append it as a new decision that names the one it
+replaces ("Supersedes: 4"), and amend `spec.md` where it is affected.
+
+Keep `decisions.md` free of implementation minutiae: it records what was
+decided and why. Whenever it changes and a `preview.html` exists, redraw the
+preview in the same move (`./preview.md`). Commit it like any other doc.

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

@@ -0,0 +1,120 @@
+# Planning with no human present
+
+Load this when your briefing says no human is present: a headless run that
+plans the feature while the human is away. With a human in the chat, grill them
+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.
+
+**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
+is designing its screens (**Designing alone**, below): for that, and only that,
+you may install dependencies and write components, preview 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
+  question or to report progress: nobody will reply, and ending the turn ends
+  the run.
+- **Frontier rounds.** Work in question rounds. A question round is every open
+  question that does not depend on an unanswered one. Write each as you would
+  put it to the human, with your recommended answer and the main alternative,
+  then accept your own recommendations and record them. Then ask what those
+  answers opened: that is the next question round. Write each to
+  `decisions.md` as it is decided (`./grilling.md`, the `**Assumed.**` shape),
+  not at the end, so a run that dies keeps what it had.
+- **Depth rule.** Record a decision only if it changes what the feature is or
+  does for its users, or the human might reasonably overturn it. Anything an
+  engineer would settle while building (wording, internal formats, test
+  coverage) is not a question; it goes to the spec as detail.
+- **Exactly one challenger.** When a question round would be empty, run one
+  separate agent: the Agent tool in Claude Code, `spawn_agent` in Codex. Give it
+  only the brief and `decisions.md`. Ask it for (a) design branches never asked,
+  within the depth rule, and (b) decisions it would have made differently, with
+  its reason. Do not tell it what you expect to hear. Ask its branches as one
+  more question round and decide them, with whatever they open. A decision it
+  disagrees with gets a `**Challenged:**` line with its reason, and your own
+  answer stands. There is no second pass. If you have no tool that runs a
+  separate agent, challenge your own plan as a separate pass and write in
+  `decisions.md` that the challenge was not independent.
+- **A refused tool is not a wait.** If a tool is refused, do not retry it and do
+  not wait: decide on what you know, and treat that decision as one to check
+  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
+  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.
+
+## Designing alone
+
+Design when the feature **adds a screen or changes a screen's layout**. A small
+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.
+- **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,
+  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
+  (`./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.
+- **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
+  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.
+- **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,
+  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.
+
+## Straight through, then ask
+
+1. Write `spec.md` (`./spec.md`) once the decisions are recorded.
+2. Write the tickets if the work is worth handing to workers (`./tickets.md`);
+   otherwise the plan says you will build it yourself.
+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
+   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
+   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
+   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
+   are back; their yes is what starts the work, in a later turn.