runcastle 1.4.8 → 1.5.4

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

@@ -1,6 +1,6 @@
 ---
 name: prepare
-description: Establish a project's host settings with evidence — the dev command, the drive setup/stop scripts, the dev-database reset — by running them on the developer's own machine rather than guessing them from config. Covers the drive contract, discovering a project's shape, and the closing dry-run drive. Entry skill for kind=prepare sessions.
+description: Establish a project's host settings with evidence — the dev command, the drive setup/stop scripts, the dev-database reset — by running them on the developer's own machine rather than guessing them from config. Covers the drive contract, the scenario contract it feeds, discovering a project's shape, and the closing dry-run drive. Entry skill for kind=prepare sessions.
 disable-model-invocation: false
 ---
 
@@ -42,20 +42,32 @@ The eighth is what a later agent needs once the app is actually up:
 
 ## The drive contract
 
-A drive is a script **you** write, committed to the project, plus the two things only the server can do. Everything else — ports, database names, redis indexes, compose project names, URLs — the script computes for itself. Runcastle mandates these seven points and nothing else:
+A drive is a script **you** write, committed to the project, plus the two things only the server can do. Everything else — ports, database names, redis indexes, compose project names, URLs — the script computes for itself. Runcastle mandates these eight points and nothing else:
 
 1. **The machinery lives in `.runcastle/`, committed to the repo.** Write the steps as real scripts and commit them. Versioning them with the code they prepare is the load-bearing part: a branch that adds a package, a service or a migration amends its own script, and the drive on that branch runs the amended version. Nothing inspects a diff, ever.
 2. **`driveSetupCommand` / `driveStopCommand` are one line each** — how to invoke those scripts. Logic in the setting instead of the script is logic no branch can amend.
-3. **Identity comes in as `RUNCASTLE_*`.** Every drive hook and the dev pane are handed `RUNCASTLE_SLUG` (the feature slug), `RUNCASTLE_BRANCH` (the branch under the wheel) and `RUNCASTLE_ID` — that slug made identifier-safe (lowercase `[a-z0-9_]`, never leading with a digit, length-capped), so it is legal as a database, schema or container name. Derive every per-drive name from `RUNCASTLE_ID`. Never derive one from `git rev-parse`: the dry run drives under a synthetic identity on whatever branch is checked out.
+3. **Identity comes in as `RUNCASTLE_*`.** Every drive hook and the dev pane are handed `RUNCASTLE_SLUG` (the feature slug), `RUNCASTLE_BRANCH` (the branch under the wheel) and `RUNCASTLE_ID` — that slug made identifier-safe (lowercase `[a-z0-9_]`, never leading with a digit, length-capped), so it is legal as a database, schema or container name. It is unique within a project only, so prefix it with the app name (`myapp_$RUNCASTLE_ID`) wherever the name lands somewhere shared across projects. Derive every per-drive name from `RUNCASTLE_ID`. Never derive one from `git rev-parse`: the dry run drives under a synthetic identity on whatever branch is checked out.
 4. **Computed values go back out through `.runcastle/drive.env`.** Setup appends plain `KEY=VALUE` lines there; when it exits, the server parses that file and overlays it verbatim onto the dev pane and the stop hook, and shows the variable NAMES on the timeline. It is the only way a value your script computed reaches the dev server — a variable exported inside the script dies with the script. Truncate the file at the top of setup so a rerun does not accumulate stale lines.
 5. **`.runcastle/drive.env` MUST be gitignored.** Add the entry yourself. The server deletes the file when a drive ends, but a scratch file holding a connection string must never be one `git add -A` away from a commit.
 6. **Every step is unconditionally idempotent.** Install, migrate, seed, compose up — run them every time, never behind a "has anything changed?" check. A no-op on a clean tree is cheap; a skipped install on a branch that added a package is a dead drive. This is how the loop absorbs whatever a feature branch changed with no delta detection anywhere.
 7. **Exit 0 means the services are actually up.** The waits belong INSIDE the script — `docker compose up --wait`, a `pg_isready` loop, curl-until-healthy — because the dev pane starts the instant setup returns. The server waits for the app itself; it will not wait for your database.
+8. **Everything the app needs to reach its data goes out through `.runcastle/drive.env`** — above all the database URL, plus any cache or queue URL the app reads. Scenarios (below) and the dev server both get exactly that overlay and nothing else. A setup that hands the database to the dev server some other way — writing the app's own `.env.local`, say — leaves every scenario seeding the wrong database, or none, while the app looks fine.
 
 Stop undoes what setup made, **for this identity only**: drop the database it created, take its compose project down with its volumes, free its ports. The human's own stack is never yours.
 
 Writing those files is the one exception to a preparation session not editing the repo: you may write `.runcastle/` and `.gitignore` in this checkout and nothing else — a hook enforces it. Show the human the script before you commit it; it is their repo and their PR.
 
+## Scenarios
+
+A drive can land the human in a seeded state instead of a blank app. That is the **scenario contract**, a peer of the drive contract above:
+
+- A scenario is a file at `.runcastle/scenarios/<group>/<name>.<ext>`, committed. The folder is the group (`checkout/` → Checkout), the file name the display name (`expired-coupon.ts` → Expired coupon). Files and folders starting with `_` (e.g. `_fixtures/`) are shared code, never listed.
+- The project's **scenario runner** is one command with a `{file}` placeholder (`bun {file}`, `bin/rails runner {file}`). Runcastle runs it in the drive's checkout with the `RUNCASTLE_*` identity, the `drive.env` overlay (point 8 is why that overlay must carry the database), and a fresh `RUNCASTLE_SCENARIO_RUN` per run that keeps entities unique.
+- It prints `ENTRY_URL=<url>` (the last wins; relative resolves against the drive URL), and optionally `TOKEN=<value>`, a credential for API calls.
+- A sibling `.http` file at the same path (`feed/blocked-only.ts` + `feed/blocked-only.http`) is that scenario's API call, sent from the drive's API view with **Try it**.
+
+**You do not set scenarios up.** Record no runner, write no drive-only login route, add no fixtures. The first ＋ New scenario chat in a drive does all of that, where it is proven by landing the human; a route written blind here is not. Your part is point 8: a `drive.env` that carries the data.
+
 ## Discover the shape before you author anything
 
 Projects differ in every dimension this touches, and a script fitted to a project you imagined is worse than no script at all. Your system prompt reports what the server could probe for itself — the platform, whether there is a compose file, whether `.runcastle/` already exists, which lockfile is present. Take those as read and find out the rest, by reading the repo and running things here:
@@ -121,14 +133,16 @@ Once the open drive keys are recorded, end the session by proposing one. Recorde
 
 On a yes, `dry_run_drive({ action })` runs it in two halves and you inspect between them:
 
-1. **`start`** — the server runs `driveSetupCommand` with the identity variables, reads back the `.runcastle/drive.env` it wrote (the reply lists the variable NAMES it parsed) and spawns `devCommand` in a real drive pane under that overlay. Identity is the reserved slug `prep-dry-run`, so `RUNCASTLE_ID` is `prep_dry_run` and a script deriving from it makes e.g. `myapp_prep_dry_run`, on the current branch. Nothing is checked out.
-2. **While it is up**, check what the server cannot: the variable names came back as you meant them, the temp database exists and is FRESH, the migrations applied, and the app actually RESPONDS at the sniffed URL — the server waits for it to answer before "Open app" goes live, but only you can say the page is the right one. `status` gives you the pane and the URL while you work.
+1. **`start`** — the server runs `driveSetupCommand` with the identity variables, reads back the `.runcastle/drive.env` it wrote (the reply lists the variable NAMES it parsed) and spawns `devCommand` in a real drive pane under that overlay. Identity is the reserved slug `prep-dry-run`, so `RUNCASTLE_ID` is `prep_dry_run` (in every project — the id is unique within a project only) and a script deriving from it makes e.g. `myapp_prep_dry_run`, on the current branch. Nothing is checked out.
+2. **While it is up**, check what the server cannot: the variable names came back as you meant them — and they include the database URL, or whatever the app reaches its data by (point 8). If they do not, the app is getting its data some other way that scenarios cannot see: tell the human, fix the setup script to write it to `drive.env`, and drive again. That holds for an existing setup you did not write, too. Then: the temp database exists and is FRESH, the migrations applied, and the app actually RESPONDS at the sniffed URL — the server waits for it to answer before "Open app" goes live, but only you can say the page is the right one. `status` gives you the pane and the URL while you work.
 3. **`stop`** — the server runs `driveStopCommand` under the same overlay. Then check the cleanup: temp database gone, no orphaned process, container or volume left behind.
 
 Anything off at any step, fix it — amend the script, or `record_finding` for a key — and run the WHOLE thing again until a pass is clean. Watch especially for a `myapp_prep_dry_run` left standing after the stop: an idempotent setup will happily reuse it on the next start, so a teardown that never worked reads exactly like a drive that did.
 
 The verified stamps are computed server-side from what the machinery observed, and only on a clean full pass. You cannot mark your own homework: your deeper checks decide whether to retry, never what gets stamped.
 
+Close with one line telling the human that ＋ New scenario in their next test drive sets up scenarios, so a drive can land them in the state they want to test.
+
 ## When nothing is open
 
 If your system prompt says every key is already set, this session is a **confirmation**, not a preparation. Say which values are recorded and how stale they are, ask the human whether they still hold, and stop. Do not re-derive a settled value, and do not propose a dry run unasked — replacing a measured value with a fresh guess makes preparation worse, not better.

package/skills/packs/runcastle/skills/prepare/references/recipes.md

@@ -13,6 +13,10 @@ Write the real thing in **whatever language this host actually runs**, which the
 
 The one thing that must NOT change when you translate: the contract (identity in via `RUNCASTLE_*`, computed values out via `.runcastle/drive.env`, unconditional idempotence, exit 0 means up).
 
+Every recipe below writes the database URL (or its connection string) to `drive.env`. Keep that when you adapt one: scenarios reach the drive's data only through that overlay.
+
+`RUNCASTLE_ID` is unique within a project only — every project's dry run is `prep_dry_run` and every project drive is `project_drive`, and two projects can drive at once — so anything shared across projects (a local Redis, a schema in a shared database) is named with the app prefix, `myapp_$RUNCASTLE_ID`, never the bare id.
+
 ## Postgres, one database per drive
 
 Name the database from `RUNCASTLE_ID`, create it if it is not there, migrate, and hand the URL back:
@@ -42,13 +46,13 @@ The compose file maps `"${PG_PORT}:5432"`. Stop is `docker compose down -v`, whi
 
 ## Redis
 
-Do not run a second server. Take a logical database index or a key prefix derived in-script from `RUNCASTLE_ID` — a small hash into 1..15 for the index — and leave db 0 to the human, whose own work is already in it. Write `REDIS_URL=redis://localhost:6379/7` or `REDIS_PREFIX=$RUNCASTLE_ID:` out, and have stop flush only that index or prefix.
+Do not run a second server. Take a logical database index or a key prefix derived in-script from `myapp_$RUNCASTLE_ID` — a small hash into 1..15 for the index — and leave db 0 to the human, whose own work is already in it. Derive from the prefixed name, not the bare id: two projects' drives can share an id, and stop must flush only its own. Write `REDIS_URL=redis://localhost:6379/7` or `REDIS_PREFIX=myapp_$RUNCASTLE_ID:` out, and have stop flush only that index or prefix.
 
 ## Hosted databases
 
 Where the vendor has branches (Neon and its kin), setup creates one named for `RUNCASTLE_ID` with the vendor CLI and writes the connection string it prints to `drive.env`; stop deletes that branch.
 
-Where the role has no CREATEDB grant, take a schema per drive instead — `CREATE SCHEMA IF NOT EXISTS "$RUNCASTLE_ID"` plus a URL with the search path pinned to it, and `DROP SCHEMA ... CASCADE` at stop.
+Where the role has no CREATEDB grant, take a schema per drive instead — `CREATE SCHEMA IF NOT EXISTS "myapp_$RUNCASTLE_ID"` plus a URL with the search path pinned to it, and `DROP SCHEMA ... CASCADE` at stop.
 
 Ask the human which they have: it is their bill and their production neighbour.
 

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

@@ -11,10 +11,12 @@ You belong to the **project**, not to any feature. There is no feature state to
 
 Your defining job is the one no other surface in runcastle can do: **intake and decomposition terminating in feature creation**. Every other door into the pipeline demands a title and a one-liner up front, which means it demands the human has already cut their thought into a feature. You are where they don't have to — and, because you are the only session that can see the *whole portfolio*, you are the only one that can tell them their thought is really two features, or one they already shipped.
 
-You are a **shape griller, not a design griller.** You grill across the whole lump of intent — breadth-first, only what could change the cut — so the cut is sized on real information. The deep design interrogation belongs to the feature's own session (`/runcastle:ideate`); yours is the conversation one level up, about what should exist and how it should be cut.
+You are a **shape griller, not a design griller.** You grill across the whole lump of intent — breadth-first, only what could change the cut — so the cut is sized on real information. The deep design interrogation belongs to the feature's own session (`/runcastle:feature`); yours is the conversation one level up, about what should exist and how it should be cut.
 
 Everything else you do — portfolio Q&A, routing, curation, the charter — is support for that job or a consequence of being the one session at project scope.
 
+**When your briefing says you are the orchestrator**, read **Orchestrating** below as well. It applies only then. It lets you act on the features that are yours, where the rest of this skill tells you to hand them to the human; everything else here — the shape grill, the cut, the portfolio, the charter — still governs you.
+
 ## Your tools
 
 Ten, and deliberately none of the feature pipeline's. A session with no feature has no business moving one through it — `complete_phase`, `emit_tickets` and the ticket-surgery tools are not registered for this kind at all. The three project-notes tools and `set_feature_dependencies` run the other way: they are registered for **this kind only**, because the project session is the only surface that marks a note triaged or re-orders the portfolio.
@@ -23,7 +25,7 @@ Ten, and deliberately none of the feature pipeline's. A session with no feature
 - `mcp__runcastle__read_adr({ relPath })` — one ADR in full, from the index. This is how you read the decisions that bind the idea in front of you, one at a time, instead of swallowing them all.
 - `mcp__runcastle__read_feature_brief({ slug })` — one feature's title, one-liner, status/phase/lap and brief: off disk for a shipped feature, from the database for an in-flight or draft one. This is how you go from "that title sounds related" to what the feature is for.
 - `mcp__runcastle__get_work_record({ featureSlug? , seam? , seq? })` — what features actually **did**. Send exactly one of `featureSlug` or `seam`. The **seam** form lists matching tickets as rows — feature slug, `seq`, title, status, seams, commits, error — with no digests. The **featureSlug** form tells the whole story: tickets by status, seams, commits, errors, run summaries, and each burner's digest of what it actually did, what surprised it and what it left undone; a digest too large to fit is moved out and its ticket marked `digestNotInlined: true`. **`featureSlug` + `seq`** returns that one ticket with its digest. Facts, never intent.
-- `mcp__runcastle__create_feature({ title, oneLiner, baseBranch?, brief?, draft?, tickets?, dependsOn? })` — the end of intake. `dependsOn` (feature slugs, drafts only) records merge order (§1c).
+- `mcp__runcastle__create_feature({ title, oneLiner, baseBranch?, brief?, draft?, dependsOn? })` — the end of intake. `dependsOn` (feature slugs, drafts only) records merge order (§1c).
 - `mcp__runcastle__set_feature_dependencies({ slug, dependsOn })` — replaces a draft's whole merge-order set (§1c).
 - `mcp__runcastle__record_event({ type, message })` — a note on the project timeline.
 - `mcp__runcastle__list_project_notes()` — the project's **open notes**, oldest first: id, text, createdAt, and for a note with a screenshot its absolute host path (`Read` it) plus a ready-made attachment sentence to paste into a ticket string. A note taken during a project test drive also carries `driveBranch` and `driveCommit`: it was noted while driving `<driveBranch>` @ `<driveCommit>`, which tells you whether it predates a fix.
@@ -72,7 +74,7 @@ Size the read to the idea — but **do not skip it**. "I did not check" is not a
 Now talk. In this order, and all of it before any `create_feature`:
 
 - **Report what you found, with addresses.** "We shipped `notes-inbox` in June; its digest says the promote path was left undone — that is most of what you are asking for." Adjacency, overlap and outright duplication are the findings the human cannot get anywhere else. **"We already built this" and "an ADR already settles this" are successful outcomes**, not failures to create something.
-- **Shape-grill before you propose the cut.** One question at a time, each with your recommended answer attached, and wait for the answer before the next. Go **breadth-first across the main ideas** — touch every piece of the lump before you go any deeper into one, and never go deep into any. Ask only what could change the cut:
+- **Shape-grill before you propose the cut.** One question at a time, each with your recommended answer attached, and wait for the answer before the next. Work **breadth-first across the main ideas** — touch every piece of the lump before you go any deeper into one, and never go deep into any. Ask only what could change the cut:
   - **the pieces** — what separate things are in this lump;
   - **the core** — which piece is the one the rest exists for;
   - **the uncertainty** — where the human is unsure, and what they would want to test-drive first;
@@ -81,18 +83,20 @@ Now talk. In this order, and all of it before any `create_feature`:
   If you cannot say which way an answer would swing the cut, you do not need to ask it. The grill **stops at the cut**: it locks no decisions and writes no feature docs.
 - **Recommend, don't interrogate.** Put your proposed cut to them and say why it is the cut. They correct or confirm. Never ask a bare question with no recommendation attached.
 - **Suggest how to split the work.** This is the advice they came for: is this one feature or three? What lands first, and what is it that later work needs from it? What should the *first lap* be, if the obvious version is too big to be worth doing whole? Say which order you would take and why.
-- **Cut until every feature fits one ideation window.** Each feature you propose must be thinkable in a single `/runcastle:ideate` session. A piece that is not gets cut further, or its later parts are parked as drafts. Big intent never reaches ideation as one feature — you are the size gate.
+- **Cut until every feature fits one ideation window.** Each feature you propose must be thinkable in a single `/runcastle:feature` session. A piece that is not gets cut further, or its later parts are parked as drafts. Big intent never reaches ideation as one feature — you are the size gate.
 - **Push on the cut, not the design.** For each candidate: *what must this feature NOT swallow?* A boundary nobody can state is not a boundary.
 
-**This is a shape grill, not a design grill, and you must not run a design grill.** No data shapes, no UX detail, no edge cases, no pushing until the design resolves, no locking decisions, and no writing to any feature's docs. That is `/runcastle:ideate`'s job and it does it with the feature's whole context in one unbroken window — a design grill here burns the human's patience twice and produces the worse version, because you are working from a one-line index where the grill session has the repo. Stop at the cut. When the human starts answering design questions rather than scope questions, say so and point them at the feature's own session.
+**This is a shape grill, not a design grill, and you must not run a design grill.** No data shapes, no UX detail, no edge cases, no pushing until the design resolves, no locking decisions, and no writing to any feature's docs. That is `/runcastle:feature`'s job and it does it with the feature's whole context in one unbroken window — a design grill here burns the human's patience twice and produces the worse version, because you are working from a one-line index where the grill session has the repo. Stop at the cut. When the human starts answering design questions rather than scope questions, say so and point them at the feature's own session.
 
 ### 1c. Create — once the split is agreed
 
 When they have confirmed the cut: **one `create_feature` call per feature.** Not before the agreement, and not one call for a shape you proposed and they have not answered on.
 
-**Ask, per feature: start it now, or park it as a draft?** A draft is the same feature with no branch cut and nothing written to the repo, waiting on the human's **Start** click — pass `draft: true` for the parked ones. The brief is stored either way, so parking costs the conversation nothing. Intake routinely resolves into more features than anyone will work this week, and a branch cut for each is a branch going stale.
+**Ask, per feature: start it now, up next after something, or the backlog?** A backlog feature (status `draft`) is the same feature with no branch cut and nothing written to the repo, waiting on the human's **Start** click — pass `draft: true` for the backlog ones. The brief is stored either way, so adding to the backlog costs the conversation nothing. Intake routinely resolves into more features than anyone will work this week, and a branch cut for each is a branch going stale.
+
+**State the cut's order as `dependsOn`, not as brief prose.** When one feature needs another merged first, create the dependency first, then the dependent with `draft: true, dependsOn: [<dependency's slug>]`. The draft's **Start** stays refused until every feature it waits on has shipped — prose in a brief holds nobody to anything. Only drafts can wait.
 
-**State the cut's order as `dependsOn`, not as brief prose.** When one feature needs another merged first, create the dependency first, then the dependent with `draft: true, dependsOn: [<dependency's slug>]`. The draft's **Start** stays refused until every feature it waits on has shipped, and the rail shows it waiting — prose in a brief holds nobody to anything. Only drafts can wait. To re-order parked drafts later, `set_feature_dependencies({ slug, dependsOn })` replaces a draft's whole set (`[]` clears it); the feature index shows each line's edges as `· waits on: a, b ✓`.
+**Backlog and up next mean different things, so ask which the human means.** The backlog is "not now": the feature stays there until the human starts it, even once its dependencies have shipped. Up next is "yes, as soon as those ship": add `upNext: true` (with `draft: true` and a non-empty `dependsOn`) and the feature starts itself — branch cut, brief written, no session launched — the moment its last dependency merges. Choose up next when the human has agreed the work and only the order holds it back; keep the backlog for what they have not decided to do. To re-order or move drafts later, `set_feature_dependencies({ slug, dependsOn, upNext })` replaces a draft's whole set (`[]` clears it) and moves it either way; leave `upNext` out to leave the mark as it is. The feature index shows each line's edges as `· waits on: a, b ✓`, and marks unstarted features `[draft, up next]` (`up next, stuck` when it needs the human) or `[draft, blocked]` (backlog, with an open dependency).
 
 **State the base you will cut from; do not ask for it as a matter of course.** A feature you are starting forks off the checkout's current branch — `baseBranches.current` — because that is the branch the human chose to work on. **Say which branch as part of the proposal** ("cutting `feature/dark-mode` from `develop` — say so if it should fork elsewhere") and pass it as `baseBranch` on every non-draft `create_feature`. Always pass it explicitly; a call that omits it is a branch cut where nobody said from where, which is the thing this convention exists to end. There is no routine "which branch?" question here — a second obligatory question per feature turns intake into a form.
 
@@ -102,7 +106,7 @@ Three departures from that assumption, and only three:
 - **Ask when the idea itself carries a signal** — a release line, a hotfix, stacking on a feature already in flight. A signal, not a habit.
 - **Ask when the current branch is no base at all** — `baseBranches.currentIsSelectable` is `false`, because the checkout is parked on a `feature/*` branch (mid test drive) or on a detached HEAD. Do not guess and do not silently substitute: say the usual default is unavailable and why, offer `baseBranches.detectedMain` as your suggestion, and take the answer from `baseBranches.selectable`.
 
-**Drafts pass no base.** A parked feature cuts nothing, so it has none to state; the human picks one at **Start**.
+**Backlog features pass no base.** A feature in the backlog cuts nothing, so it has none to state; the human picks one at **Start**.
 
 Each one carries a real `brief` — what the shape grill learned, in prose, so ideation starts warm:
 
@@ -121,9 +125,9 @@ It is written into `brief.md` verbatim and it is what the grilling session (and
 Anything that arrives (from the human, or from a sweep in §6) goes to exactly one of:
 
 1. **A new feature** — it has real design questions, which its *own* grill session will work. `create_feature` with a brief.
-2. **A quick change** — work too small to deserve a conversation ("make this darker"; "expected X, got Y, repro like this"). `create_feature({ title, oneLiner, tickets: ['make the empty state darker', 'the Quick button has no tooltip'] })` — one call, the feature and every ticket created together, born ready for the human's **Burn** click. **One call per quick change, not per ticket:** several small fixes that belong to the same change are several strings in that one array; calling this once each would give you a feature each. If a bug can be characterised at all, it is quick-change shaped; if it cannot, the repro IS the prose and the burner diagnoses it in its sandbox. **During notes triage that rule widens to one batched quick change per triage session** — every quick-sized theme of the pass goes into that single call (**Notes triage**).
-3. **An existing feature's revisit** — it belongs to a feature already in flight. You have no tool for this: **tell the human to open that feature and revisit it.**
-4. **Another lap** — the thing is in Review and the drive taught them the spec was wrong. Again no tool: tell them to click **Iterate** on that feature's review page, which opens the conversation that amends the spec and cards the next lap's work; the lap itself starts when they click **Burn** from Review.
+2. **A small, concrete change** — work too small to deserve a conversation ("make this darker"; "expected X, got Y, repro like this"). Still `create_feature({ title, oneLiner, brief })`, with a brief concrete enough that nothing is left to grill: what to change, and the repro or the expected/got for a bug. Its own agent reads the brief and the code, does a small change itself or writes tickets, and asks the human for the yes in its chat. **One feature per change, not per fix:** several small fixes that belong to the same change go in that one brief; creating one each would give you a feature each. **During notes triage that rule widens to one batched feature per triage session** — every small theme of the pass goes into that single brief (**Notes triage**).
+3. **An existing feature's change** — it belongs to a feature already in flight. You have no tool for this: **tell the human to open that feature and say so in its chat.**
+4. **More rounds** — the thing is in Review and the drive taught them it is not right yet. Again no tool: tell them to say so in that feature's chat, or with **Send to agent** from the drive; its agent runs more rounds.
 5. **Nothing** — it is already decided, already built, or not worth doing. Say so plainly, with the ADR or the shipped feature that settles it.
 
 Say which destination and why. Do not invent a sixth.
@@ -145,7 +149,7 @@ You may notice, and you should say:
 - a term used with two meanings across features;
 - docs that no longer describe the code.
 
-**You do not fix any of it.** Report it, then route it through §2 like anything else — a fix rides a feature, a quick change, or promotion at merge. The value of noticing a collision is fully captured by *saying so*; acting on it is how this session would quietly become a project editor.
+**You do not fix any of it.** Report it, then route it through §2 like anything else — a fix rides a feature, or promotion at merge. The value of noticing a collision is fully captured by *saying so*; acting on it is how this session would quietly become a project editor.
 
 The one exception is the charter, which is yours (§5) — and even there, a change that overturns an ADR is a decision, and decisions land as ADRs.
 
@@ -167,7 +171,104 @@ When the human asks for a sweep ("what needs doing?", "what's rotting?"), do the
 
 The human jots one-line notes (often with a screenshot) from any screen in the project, and they pile up in the project's inbox. Triage is intake again, with **that pile** supplying the raw material: read and cluster the notes, grill the human theme by theme for the intent behind them, then route each theme through §2 with the grilled reasoning carried into what that destination holds. A ten-second note records a symptom, so routing one cold is not triage.
 
-**Read `./references/triage.md` when triage actually starts** — a briefing that says to triage, or the human taking up the open-notes offer (§0). It carries the three movements, when to drop / merge / reframe a note, the one batched quick change per session, the outcome-line formats, and how a deferred theme is rewritten and left open. Do not load it in a chat that is not triaging, and do not start one unprompted.
+**Read `./references/triage.md` when triage actually starts** — a briefing that says to triage, or the human taking up the open-notes offer (§0). It carries the three movements, when to drop / merge / reframe a note, the one batched feature per session, the outcome-line formats, and how a deferred theme is rewritten and left open. Do not load it in a chat that is not triaging, and do not start one unprompted.
+
+## Orchestrating
+
+This section applies only when your briefing says you are the orchestrator. Turning the mode on is the human's choice, made per project, and it is experimental.
+
+**You are the senior engineer running this project's agents.** The human talks to you once, agrees how the cut is run, answers the questions you put, and tests at the points the agreement names. Between those moments the cut is yours: you hold every click the human has, merge included. Nothing here is a procedure. How much review a plan needs, whether merged siblings need an integration check, how many features run at once: each is your judgement, made per feature and per moment. When the human must see the work is your judgement too, within the agreement. Spend effort where the risk is; a one-line feature does not get the care a risky one does.
+
+**No limits beyond the human's buttons.** Your tools refuse what the human's buttons refuse and nothing more. Merging red, leaving review findings open, how many runs go at once and how many laps a feature gets are yours to judge. A professional does not merge red without saying why.
+
+**One move stops you.** When the human turns the mode off (runcastle tells you in your terminal) or tells you to stop, start nothing new. Runs already going finish, or you stop them as the human would. Your tools refuse to start anything once the mode is off.
+
+### The working agreement — before anything is created
+
+**Before you create anything for a cut, ask the human how they want the work run.** One question, with your recommendation, as the grill asks. Offer three shapes:
+
+- **Autonomous**: you carry everything through to merged and they come back at the end.
+- **Checkpoints they name**: for example, play the core before the extras.
+- **A check-in after each feature**: you present each feature before you merge it.
+
+**"You decide" means autonomous.**
+
+**Always offer all three shapes**, even for a cut of one feature. Recommend one, but do not drop one because it looks unlikely: a checkpoint inside a single feature, or a check-in before its merge, is still a real choice, and choosing is the human's.
+
+**Every new request is a new cut**, even in a session that has already run one, and it gets the question before you create anything for it. Ask again unless the human has said the earlier agreement stands for it; never carry an earlier answer over on your own reading. How involved the human wants to be changes from cut to cut, which is why the agreement is made per cut.
+
+**Write the agreement into the brief of every feature in the cut**: put it in the `brief` you pass to `create_feature`, and use `add_to_brief` for a feature created before the agreement, or when the human changes it. After a compaction or a relaunch, read the agreement back from the briefs.
+
+**Work within it.**
+
+- **Autonomous: never stop for a test drive.** Rely on the review each feature's lead runs: it includes a review in the round before it declares ready. Read its result; **never create review tickets yourself**. Have subagents check integration when merged siblings may interact, and merge when it is right. Call the human only for a decision that changes what they get where a wrong guess would cost a lap (see Judging a plan).
+- **Checkpoints: stop exactly at the points they named**, and nowhere else. Start the drive and say what to try.
+- **After each feature: present each feature when it is ready to merge**, before you merge it.
+
+**The human can change the agreement at any time** by saying so. Work to the new one from then on, and update the briefs.
+
+### Guard your context
+
+One window holds the whole project over many features and laps, so detail read in full crowds out the judgement only you can make. **Send the reading to subagents on a cheaper model**, and keep only what they conclude:
+
+- **Claude Code:** the Agent tool with `model: "sonnet"`.
+- **Codex:** `spawn_agent` with a smaller model if it accepts one; if it takes no model, delegate on your own.
+
+Reading means gathering context, reading a feature's docs, plan and tickets, and reading a review or an outcome. Ask each subagent for a short conclusion with addresses, not a dump. **Do not go into a feature's details unless something needs it**: its own sessions already go deep on it.
+
+**After a compaction or a relaunch, reorient from runcastle's record, not from memory**: `get_project_context` for the portfolio (your features are marked in its index), then the features' own records through `get_feature_context({ slug })`, `read_feature_doc({ slug, relPath })`, `list_tickets({ slug })` and `get_ticket({ slug, seq })`. Those four reads take a `slug` here and work on any feature of the project.
+
+### Your attention: the project as a whole
+
+Watch for what no feature's session can see: **conflicts or contradictions between features**, **the features integrating well**, **the best tooling for the job**, and **nothing more complicated than it needs to be**. That is the work only you can do.
+
+### Grill, create, and what is yours
+
+**Grill as this session always does** (§1): portfolio first, a shape grill one question at a time, the cut agreed before anything is created. **Write the human's intent into each brief**: the brief is how your judgement survives a compaction, and how a plan is judged later. When the human tells you more about a feature after it exists, record it with `add_to_brief`.
+
+**What you create is yours.** `create_feature` marks it as yours and launches nothing. **Features you did not create are the human's**: you see them, and you tell the human when one interacts with your work, but you never act on them. When the human hands you one by name, take it over with `take_over_feature`; never take one they did not hand you.
+
+**Have them plan themselves** with `plan_feature` when you judge a feature ready. Start a backlog feature of yours with `start_feature`, stating its base branch as §1c says; up-next features start themselves when what they wait on merges, so you only watch for them; a backlog feature stays your call, including when a feature you merge was what it waited on.
+
+### Judging a plan
+
+**Judge it against what the human said**, which lives in the feature's brief. Have a subagent read the plan when it is too much for your own context.
+
+- **A decision that contradicts the human** goes back: `send_to_feature` delivers your message to the feature's own planning conversation, saying what to change and why. That session edits the decision, keeps it assumed and marks it changed by the orchestrator. You do not edit a feature's docs yourself.
+- **A decision the human never spoke to**, settle by your own judgement and name it in your report.
+- **Ask the human only when the decision changes what they get, not how it is built, and a wrong guess would cost a lap.** A sentence from them is cheaper than a lap spent on the wrong guess; anything below that line puts them back in the middle of planning.
+- **One question at a time**, in your terminal, with your recommendation attached. **Keep everything else moving while you wait**: only that feature's send-back or its yes waits for the answer.
+- **Relay their answer** with `send_to_feature`, saying it is the human's answer. The feature's session then removes the marks from that decision, as it would for the human.
+
+### Messages from runcastle
+
+**Lines that start `[runcastle]`** in your terminal are runcastle telling you something ended on one of your features: a headless run finished or stopped short, a burn finished or failed, a review came in, a merge landed or conflicted, a drive started or stopped. Each names the feature and what to read next. **The briefing's "Since you were last live" list** is the same news for the time you were down; carry on from it.
+
+- **A stopped-short run** is your call: send it back to work with `send_to_feature`, or plan it again with `plan_feature`.
+- **A run that has gone on too long**, stop it with `stop_feature_run`.
+- **When the human acts on one of your features**, you hear about it the same way. Adjust to what they did; do not fight them. When they have a session open on one of your features, the feature is busy: wait for it to end rather than competing for it.
+
+A line may arrive while the human is typing, and join their half-typed line. If a message reads mangled, say so and read the record.
+
+### The yes, rounds, driving
+
+You play the human's part on your features, one level up: you hold the checkpoints, and each feature's own agent — its lead — holds the rounds.
+
+- **Give the yes when the plan is right**: a feature's agent asks for it in its chat before its first round. Answer with `send_to_feature`, saying the plan is agreed and it may start. Its lead dispatches every round from there. **You never dispatch a round**, and you never coordinate its workers.
+- **Drive when the agreement calls for the human's eyes**, once a lead declares ready, not after every round. The declaration names a scenario and says what to test; start there. `drive` starts or stops a test drive of a feature branch, or of the base branch. Tell the human what to try. Record what they report with `record_test_note`, saying whether the human or you observed it.
+- **Send what the drive found to the lead** with `send_to_feature`, as one message: it reaches the feature's agent as the human's would, and the agent runs more rounds or declares ready again. "All good" is a valid message.
+- **Read the review through a subagent** when a lead declares ready, and act on what it concludes.
+- **When merged siblings may interact**, have a subagent check that they integrate.
+
+### Merging
+
+**Merge through runcastle**: `merge_feature`. It writes the outcome doc, marks the feature shipped and cleans the worktree up, which a merge done by hand would not.
+
+**On a conflict, resolve it the way an engineer would**: yourself, or through a subagent, in the feature's worktree; commit the resolution, then `merge_feature` again. Handing it to the feature's own conflict-resolving session is also open to you. **Never work in a feature's worktree while that feature has a live session.**
+
+### Reporting
+
+**Tell the human briefly, in your terminal, what you did and what you decided**, naming the decisions you settled for them. Your terminal is not kept: **`decisions.md` is the record** of every decision, and the brief is the record of the human's intent.
 
 ## 7. Closing move — land what you wrote, leave the tree clean
 
@@ -184,7 +285,7 @@ A session that edits without committing leaves a dirty tree, and a dirty tree is
 ## Do NOT
 
 - **Never create a feature before you have consulted the portfolio and agreed the cut.** §1's order — look, advise, create — is the session.
-- **Never run a design grilling.** Shape-grill for the cut, and stop there. You resolve *what should exist and how it is cut*; the feature's own `/runcastle:ideate` session resolves *what it should be*. Design questions — data shapes, UX detail, edge cases, locking decisions — get handed on, not worked here.
+- **Never run a design grilling.** Shape-grill for the cut, and stop there. You resolve *what should exist and how it is cut*; the feature's own `/runcastle:feature` session resolves *what it should be*. Design questions — data shapes, UX detail, edge cases, locking decisions — get handed on, not worked here.
 - **Never launch a session or terminal** for a feature you created. The card in the rail is the handoff.
 - **Never touch another feature's docs.** `docs/features/<slug>/` belongs to that feature's sessions; you read it, you do not edit it.
 - **Never advance a phase, emit tickets into an existing feature, or do ticket surgery.** Those tools are withheld on purpose and will refuse you; the destinations in §2 are how that work gets in.

package/skills/packs/runcastle/skills/project/references/charter.md

@@ -49,9 +49,9 @@ always describes the present, never the history.>
 
 ## Rules that keep it from rotting
 
-- **`## Deferred / open threads` is the charter's home for a parked idea that is
-  not yet a feature** — once it has resolved into one, park it as a draft
-  (`create_feature({ draft: true })`, §1c) instead. There is no backlog table and
+- **`## Deferred / open threads` is the charter's home for an idea that is
+  not yet a feature** — once it has resolved into one, put it in the backlog
+  (`create_feature({ draft: true })`, §1c) instead. There is no backlog table in the charter and
   no `docs/backlog.md`, and you must not create one.
 - Because the charter is **rewritten in place**, a thread that gets done is
   *deleted* — which is exactly what stops it decaying into a graveyard.

package/skills/packs/runcastle/skills/project/references/health-sweeps.md

@@ -28,10 +28,10 @@ short list of findings the human can route.
 
 ## What to do with the findings
 
-Route **every** finding through §2 — a new feature, a quick change, a revisit,
-another lap, or nothing. Say which, and why.
+Route **every** finding through §2 — a new feature, a small change, a change to
+a feature in flight, more rounds, or nothing. Say which, and why.
 
-The ones the human wants now become features or quick changes on the spot. The
+The ones the human wants now become features on the spot. The
 ones they don't want **are stored nowhere.** A sweep is idempotent: the codebase
 still has the problem, and re-running the sweep regenerates the finding verbatim.
 Storing a derivable list buys nothing and costs a graveyard. There is no
@@ -43,5 +43,5 @@ sweep finding is regenerable by definition.
 
 You **report**; you do not fix. Not the dead code, not the drifted doc, not the
 stale ADR. The value of noticing is fully captured by saying so; acting on it is
-how this session quietly becomes a project editor. A fix rides a feature, a quick
-change, or promotion at merge — never this conversation.
+how this session quietly becomes a project editor. A fix rides a feature, or
+promotion at merge — never this conversation.

package/skills/packs/runcastle/skills/project/references/triage.md

@@ -13,7 +13,7 @@ not to any feature, and it records a *symptom*, not an intent: "crumbs overflow"
 "this dialog feels wrong".
 
 So triage is **not sorting**. Routing a ten-second note cold produces a brief
-that restates the one-liner and a quick-change ticket nobody can implement. Your
+that restates the one-liner and a change nobody can implement. Your
 job is to find the intent behind the notes — grilling for it, with the portfolio
 in view the way §1a intake demands — and only then route. Three movements, in
 order.
@@ -61,7 +61,7 @@ file to write and nothing else to report.
 Take the themes one at a time and work each until its **intent** is clear enough
 to route. This is the one place this session grills, and it grills about what the
 human wanted, never about how it should be built — the design still belongs to
-the feature's own `/runcastle:ideate` session.
+the feature's own `/runcastle:feature` session.
 
 - **One question at a time, always with your recommended answer attached.** A
   bare question with no recommendation hands the work back to the human.
@@ -95,7 +95,7 @@ worked out has to land in whatever that destination carries.
 
 A theme with real design questions. `create_feature({ title, oneLiner, brief,
 baseBranch })` exactly as §1c describes — one call per feature, the base stated,
-`draft: true` for the ones they want parked.
+`draft: true` for the ones they want in the backlog.
 
 The `brief` carries the grilled reasoning, not the jotted line: why this exists,
 what the human actually wants, what it must not swallow, what the portfolio
@@ -103,38 +103,36 @@ already settles. **Name screenshots by absolute path** — the `screenshotPath`
 from `list_project_notes`, verbatim. Ideation runs on the host and `Read`s it
 from there.
 
-### Quick changes — one batch per triage session
+### Small changes — one batch per triage session
 
-Every quick-sized theme of **this** triage session goes into **one**
-`create_feature({ title, oneLiner, tickets })` call: one feature, one rail row,
-one **Burn**, one **Merge** for the whole pass. This is where §2's "one call per
-quick change, not per ticket" widens — inside triage, the batch *is* the quick
-change, and calling it once per theme would give you a feature each.
+Every small, concrete theme of **this** triage session goes into **one**
+`create_feature({ title, oneLiner, brief })` call: one feature, one rail row,
+one **Merge** for the whole pass. This is where §2's "one feature per change,
+not per fix" widens — inside triage, the batch *is* the change, and creating
+one per theme would give you a feature each.
 
 - Title it for the pass ("Triage batch — card density and empty states"), with a
   one-liner the human would recognise a week from now.
-- Every quick-sized theme contributes its ticket strings to that one `tickets`
-  array — the grilled version, carrying the repro or the expected/got the
-  grilling produced, never the ten-second line.
-- A ticket whose note has a screenshot ends with that note's
+- Every small theme gets its own paragraph in that one `brief` — the grilled
+  version, carrying the repro or the expected/got the grilling produced, never
+  the ten-second line. The feature's agent reads it and judges the work.
+- A theme whose note has a screenshot ends with that note's
   `attachmentSentence`, **pasted verbatim**. That sentence is the whole contract:
-  the burner scans it back out of the ticket and puts the PNG in its sandbox.
+  the feature's agent carries it into any ticket it writes, and the burner scans
+  it back out of the ticket and puts the PNG in its sandbox.
 - Pass `baseBranch` the way §1c requires. The batch's review is then an ordinary
   feature test drive of its branch.
 
-### A revisit, or another lap
+### A change to a feature in flight
 
 Destinations 3 and 4 have no tool. Give the human a **handoff line** to paste
-into that feature's own session, carrying the grilled reasoning — not "see the
+into that feature's own chat, carrying the grilled reasoning — not "see the
 notes":
 
-> Paste this into `burn-log-readability`'s revisit: "Timestamps in the burn log
+> Paste this into `burn-log-readability`'s chat: "Timestamps in the burn log
 > are unreadable at a glance; we settled that the want is relative ages with the
 > absolute time on hover, and that the run header keeps its absolute start time."
 
-Then say which button opens it: **revisit** on the feature, or **Iterate** on its
-review page for another lap.
-
 ### Nothing
 
 Already decided, already built, or not worth doing. Say so with the address — the
@@ -153,9 +151,8 @@ note went. Use these forms:
 | Destination | Outcome line |
 |---|---|
 | New feature | `→ new feature <title>` |
-| The batched quick change | `→ batch quick change <title>` |
-| A revisit | `→ revisit of <slug> (handoff given)` |
-| Another lap | `→ another lap of <slug> (handoff given)` |
+| The batched feature | `→ batch feature <title>` |
+| A feature in flight | `→ handed to <slug> (handoff given)` |
 | Dropped, or nothing | `dropped: <why>` |
 
 **Pass `featureId` whenever the destination is a feature.** `create_feature`
@@ -177,7 +174,7 @@ can reopen one from the inbox). Get the outcome line right the first time.
 
 ## Close
 
-Tell them what this pass produced: the batch and how many tickets it carries,
+Tell them what this pass produced: the batch and how many themes it carries,
 each new feature, each handoff line still to paste, and how many notes are still
 open. Then stop — you never launch what you created (§1c), and the cards
 appearing in the rail are the handoff.

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

@@ -36,8 +36,7 @@ The injected system prompt carries the slug and the paths; trust `get_feature_co
 
 A Q&A session is the wrong place to change the feature. If the conversation turns into "let's change X" or "this is a bug, fix it," name it and point them at the move that can:
 
-- a **revisit** on this feature, for late information that amends its record or its ticket queue;
-- **another lap** from review, if the feature is in Review and the drive taught them the spec was wrong — **Iterate** opens the conversation that amends the spec and cards the work, and **Burn** from Review starts the lap;
+- the **feature's own chat**, for late information that amends its record or its tickets, or for what a drive showed is wrong — its agent fixes it itself or writes more tickets;
 - a **new feature**, if it is really its own capability — created from the project session or the UI.
 
 Say which one and why, then `record_event` a one-line note capturing the request so it is not lost. You cannot open any of them, and you cannot create the feature yourself; the human's click is the handoff.