Relationships
↔ sibling #4659#4936 stagecraft skill: gate summaries at the decision point, systemPrompt on workflow and behavior stages, claim's key, in-flight definition changes
Opened by skunk-ape · 11/20/2026· Shipped 11/20/2026
Also fixes #4659 (a DESIGN.md wording bug in the same docs). Carry both through one lifecycle (link_issue).
Problem
Factory sessions from Nov 4–18 hit several places where the stagecraft skill (SKILL.md, references/driving.md) leaves the driver to guess, or presents a gate in a way the person has to dig for:
- Gate presentation. At a human gate, the driver's summary had often scrolled out of view by the time the person decided ("your earlier message has scrolled by, don't make me find it"). One session confused the "review" and "revise" exits.
onBehalfOfwas spelled "seth" in some approvals and "Seth" in others, and two early approvals carried none. systemPrompton workflow and behavior stages.dispatchputs the stage's renderedsystemPromptin the packet'spromptfor every work mode, but the workflow or behavior it runs receives only literal inputs pluspassAsInputs. The driving reference's workflow and behavior section doesn't say the prompt is for the driver, or what to do with it.claim's key. The skill should tell the driver to use the keyclaimprints for every later command, and what the "no work item" and "claimed, not started" refusals (#4922) mean.- Changing a factory definition while work items are running. A work item pins the definition it started with. The skill doesn't say what a definition change does to work items already in flight, or how to move one onto the new definition.
- #4659. DESIGN.md's "stored as received" bullet reads as a general guard against expression evaluation. It only catches a redacted secret;
--literal-inputsis what stops evaluation.
What to change
- Gates: the skill says how to present a human gate. Restate the decision in the message that asks for it: the exits, what each does, and what was produced, so the person never has to scroll back. It names each exit as the definition does, and says to record
onBehalfOfas the person's handle exactly as given. systemPrompt: the driving reference says that for workflow and behavior stages the packet'spromptis guidance for the driver, and how to use it. The definition-authoring docs say the same.claim: one rule and the refusal meanings, in the driving reference and the quick reference.- In-flight changes: what happens to running work items when a definition changes, and the supported way to move one, if there is one. If none exists, say so. Don't design one in this issue.
- #4659: the sentence the issue asks for, in DESIGN.md and REFERENCE.md.
Done when
All five are covered in SKILL.md, driving.md, REFERENCE.md or DESIGN.md as fits. The skill's own tests (skill_test) still pass, and any quoted command or output matches the shipped engine (2026.11.19.3 or later).
Out of scope
Engine or studio changes. If a docs fix shows that the engine needs to change (for example, normalising onBehalfOf), report it rather than doing it here.
Shipped
Click a lifecycle step above to view its details.