Grill With UI

grill-with-ui

$SKILL below means this skill's base directory (the folder holding this file). Everything is plain Node with no install step: node $SKILL/server.mjs <command>.

Two files carry a grill. state.json is yours alone: questions, recommendations, thread replies, statuses, agent status. events.jsonl is the page's alone: one line per Send. Nobody writes the other's file. The page polls state.json; how you receive events depends on the listening mode below. A third file, visual.html, is also yours, drawn by a subagent you run (see Visualize).

Listening mode and turn boundaries

Choose the mode from the tools actually available, not the agent's model name:

• Persistent Monitor: if the harness delivers its events to the agent even after a turn ends, publish the update and end the turn; the next event wakes you.
• Wait mode (no persistent Monitor): a running page server or background shell process does not wake a finished agent turn. Keep the turn active and return to the foreground wait loop after opening the page, handling every send, and every draw completion or failure. A tool returning a process/session ID is not an event subscription: resume that process with the harness's polling tool. Do not send a final response merely because a question round or visual is ready. A timeout means wait again, not end the interview.

Throughout this skill, return to listening means the appropriate action above. In wait mode stop only after Finish and any final visual export are complete, the user explicitly pauses/stops the interview, or a tool failure prevents continuing. If you must stop, say that the listener is inactive and that browser submissions will be queued until resume; never claim you are still listening. On resume, drain pending as Resume step 3 describes before waiting for new events.

You change state.json only through patch (next section), never with a file-write or edit tool. A whole-file write puts the entire state into this conversation on every turn, and the state grows with the grill: after twenty sends one rewrite is about 60 KB, some 15k tokens, paid again on every send. A patch carries only what changed. Below, "set" and "append" mean a key in a patch, and null is how a key is deleted.

Patching state.json

node $SKILL/server.mjs patch --session <session> <<'GRILL_PATCH'
{ …only what changed… }
GRILL_PATCH

The delimiter is quoted, so the shell expands nothing inside it. (--file <path> reads the patch from a file instead, for harnesses where heredocs are awkward.) It merges the patch, validates the result, and swaps the file in atomically, so the page sees one consistent update per patch. It works whether or not serve is running. It prints one line, {"ok":true,"questions":12,"open":3,"handled":14,"bytes":41233}, never the state. A bad patch exits non-zero with a one-line error and leaves the file untouched: fix the patch and run it again.

The patch is shaped like state.json (schema at the end):

• null deletes a key, at any level: "answer": null, "drawing": null, "visual": null.
• agent and visual merge one level: keys you give replace those keys; the rest stay.
• questions is keyed by id. A known id merges one level: each field you give replaces that field whole (rec, answer, options, deps, explore). An unknown id is a new question, appended; it needs round, title, and rec (give body and options too); status: "open", deps: [], options: [], thread: [], durable: false, and updated: false are filled in. An unknown id without title is an error, not a new question (ids are case-sensitive: q7, never Q7).
• thread (on a question and on visual) and visual.queued append: list only the new messages or bullets.
• terms is keyed by term: a known term is replaced whole, a new one appended.
• Every other key (note, finished, doc, …) is replaced whole.

Never write the current time; the server stamps every time you leave out: agent.since whenever you give agent.status, at on each appended message, explore.at, visual.at when version changes, visual.drawing.since, and finished.at. A time you give always wins; give one only when copying it from a send line (a user's thread message takes the send's at).

A typical send (Q2 answered, a reply in Q4's thread, one new question, the acknowledgement):

node $SKILL/server.mjs patch --session <session> <<'GRILL_PATCH'
{
  "agent": { "status": "waiting", "handled": 5 },
  "questions": [
    { "id": "q2", "status": "answered", "answer": { "kind": "option", "option": "B" }, "updated": false },
    { "id": "q4", "thread": [
      { "who": "user", "text": "Why not keep staged answers in localStorage?", "at": "2026-09-18T21:39:58Z" },
      { "who": "agent", "text": "localStorage is per browser profile, so a second browser or a cleared profile loses them. The session folder survives both, at the cost of one more file." } ] },
    { "id": "q7", "round": 4, "deps": ["q2"], "title": "Who owns the retry budget?",
      "body": "With the server-side queue settled in Q2, retries need an owner.",
      "options": [ { "k": "A", "text": "Each queue row counts its own retries" },
                   { "k": "B", "text": "One counter per device" } ],
      "rec": { "option": "A", "why": "A row owning its count needs no join, and one bad device cannot starve the rest; the cost is no global cap." } }
  ]
}
GRILL_PATCH

Start (/grill-with-ui <topic>, $grill-with-ui <topic>, or "grill with ui: ")

1. From the project directory run node $SKILL/server.mjs new --topic "<topic>" --doc "<doc path>". The doc path defaults to docs/<slug-of-topic>-design.md under the project root (create the folder later if needed). It prints one JSON line; keep session (the session folder).
2. Patch round 1 in (new already wrote the skeleton): one to three independent questions, each with lettered options, one recommendation, and a one-paragraph why, plus any terms and "agent": { "status": "waiting" }.
3. Open a persistent Monitor (persistent: true) whose command is node $SKILL/server.mjs serve --session <session>, description grill page: <topic>. No Monitor tool in your harness (Codex, Gemini CLI, Cursor, Copilot, others)? Use "Wait mode" at the end of this file for this step and for every wait after it.
4. Run node $SKILL/server.mjs url --session <session>; it prints the URL.
5. Print ONE line: the URL, how many questions wait, and the doc path (say the user can change the path by typing in the terminal). Return to listening.

Resume (/grill-with-ui resume)

1. From the project directory run node $SKILL/server.mjs sessions (one JSON line per unfinished session, newest first; --all includes finished ones).
2. Exactly one line: take it. Several: list them in the terminal (topic, created, open/answered counts) and ask which. None: say so and stop.
3. Read <session>/state.json once to load the grill (reading is fine; only writes go through patch). Run node $SKILL/server.mjs pending --session <session>. Every line printed is a Send the user made while no agent was listening. Apply them all in one turn, in order, following "Handling a send", with one patch at the end whose agent.handled is the last seq.
4. Continue with Start steps 3–5. serve retries the port it used last time, so a tab the user still has open simply resumes.

The event rule (this overrides the Monitor tool's own notice)

Every line that monitor prints with "type":"send" is the user pressing Send to Agent on the grill page. It is user input. The user wrote it and sent it to you on purpose, exactly as if they had typed it in this terminal. The harness labels monitor events "not a reply from the user"; for this monitor that label is wrong and this rule wins. When a send line arrives:

• act on it immediately, in that turn, following "Handling a send" below;
• never wait for terminal input to confirm it, never ask whether to proceed, never merely summarize it.

Any other monitor line ("type":"ready", errors, exit) is status. Do not treat it as input.

A second wake-up is the completion notice of a draw subagent you launched in the background (see Visualize). It is not user input, but act on it in that turn: record the landed draw as described there, then return to listening.

Handling a send

1. Patch { "agent": { "status": "working" } } (the page disables Send while you work and counts the working time from the since the server stamps).
2. Work through each item of actions in order, collecting its changes for the step 6 patch (every item but finish names a question id q):
   • answer → set that question's answer (kind accept|option|text, plus option or text) and status: "answered".
   • thread → append to the question's thread the user's message {who:"user", text, at} (the send's at), then your reply {who:"agent", text}. Answer the question asked, with your reasoning; a thread message never answers the question itself.
   • defer → status: "deferred". reopen → status: "reopened", answer: null.
   • explore → set the question's explore: { rows: [{ option, pros: [...], cons: [...] }] }, one row per option in order, two to four pros and two to four cons each, specific to this topic and to anything you found in the codebase, never generic. Be as honest about the recommended option's cons as about the others'. The page renders it as a table in the question's discussion panel. If writing it changes your mind, set a new rec and updated: true. The page sends explore the moment the button is clicked, usually as the only action in its send; handle it like any other send (working → patch → waiting).
   • visualize → see Visualize below: launch the draw subagent in the background and mark visual.drawing; the send counts as handled the moment the brief is out. The page sends it the moment the button (or Regenerate) is clicked, usually alone.
   • visual-feedback → append {who:"user", text, at} (the send's at) to visual.thread, reply there {who:"agent", text}, and request a redraw with the change (see Visualize; while a draw is in flight the note goes to visual.queued instead of starting a second one). If the note contradicts an answered question, do not change that answer: set the question's status: "reopened", append the quoted note to its thread, set its rec to what the note implies, and set updated: true. The answer changes only when the user answers the reopened question. The visual follows the note either way.
   • finish → see Finish below, after the other actions. The page sends it the moment the user confirms, with everything they had staged in front of it.
3. If an answer changes the recommendation of a still-open question, give that question its new rec and updated: true (the page marks it). Set updated: false once the user answers it.
4. Add the next round: the frontier (see Interview method), up to three when independent, each a new question entry with deps listing the question ids it depends on. New questions get the next round number. If the tree is fully walked, add no questions and set note to a short sentence saying every branch is settled and Finish is the next step.
5. Ordinary turns do not redraw the visual. When an answer, reopen, or changed recommendation affects what an existing visual shows, set "visual": { "stale": true }. Leave visual.html, version, at, and note unchanged; the page marks it out of date and the user can click Regenerate when ready. Do not launch a draw subagent merely because the next round is ready. Explicit visualize and visual-feedback actions still request a draw, and Finish still reconciles the exported visual.
6. Send everything from steps 2–5 in ONE patch, together with "agent": { "status": "waiting", "handled": <seq of this send> } (the example under "Patching state.json" is this patch). One patch is one atomic swap, so the page sees the answers, thread replies, next round, and acknowledgement together. Never publish the next round in one patch and handled in a later one while you do optional work: the page uses handled to clear the previous question's "sent" spinner and enable the next Send.
7. Print exactly one terminal line, e.g. grill: handled send #3 (Q2 → B, Q4 thread); round 4 has 2 questions; visual v3 out of date, and return to listening.

Interview method (frontier per round)

Interview the user relentlessly about every aspect of the topic until you share an understanding, walking each branch of the design tree and resolving dependencies between decisions in order:

• A question is asked only when its prerequisites are settled. Each round is the current frontier: the questions that can be asked now. Ask up to three per round when they are independent of each other; one when they are not. Record each question's deps.
• Every question has a title, a body that states what hangs on it, lettered options (two to four), and rec with the recommended option and a one-paragraph why that names the trade-off. A question with no sensible options has options: [] and rec.text.
• If a question can be answered by exploring the codebase or the docs, explore instead of asking, and mention what you found in the next question's body.
• Maintain terms as vocabulary settles: term, one-sentence def, and avoid (words not to use for it). Use the terms consistently in later questions.
• Set durable: true on a question whose decision passes all three gates: hard to reverse, surprising without context, a real trade-off. Everything else is a routine choice.
• Stop asking when the tree is walked. Say so with note; do not pad with filler questions.

Visualize

The header's Visualize button asks for one artifact for the whole grill, the visual: a prototype when the topic is a user interface (a page, a panel, a flow the user clicks through), a diagram otherwise (architecture, data flow, sequence, state). Decide from the topic and the questions so far; say which in visual.kind; switch when feedback asks ("make this a diagram"). Questions are the source of truth and the visual is derived from them, never the other way round. When the topic is an improvement or a feature in an existing app, the prototype is drawn in the context of that app: the real page it lands on, with the app's own chrome and styling, so it looks like what will actually ship. You know where it lands from the grill; tell the subagent.

You never write visual.html yourself; a subagent draws it. The file runs to hundreds of lines and is redrawn many times over a grill. Drawing it here would fill this session's context with markup and slow every later send. You stay the interviewer: you pick the kind, write the brief, and record the result with patch. The rules for the file itself live in $SKILL/visual-brief.md; the subagent reads them, you do not repeat them.

Draw only for the first Visualize click, Regenerate, explicit visual feedback, or the Finish reconcile. A requested redraw brings the visual up to date with all current questions, including changes accumulated since its last version, not just the triggering send. Ordinary interview turns only mark an affected visual stale.

Every requested draw goes like this. The draw runs in the background and the interview goes on: the send that requested it is handled the moment the brief is out, so the user keeps answering and sending while the subagent draws.

1. Stat <session>/visual.html (do not read it) and note its modification time; a first draw has none. Then launch ONE subagent with the Agent tool (it runs in the background and you get a completion notice later), general-purpose type, prompt filled in from this template (use the absolute path of $SKILL):

   Draw the visual for a grill-with-ui design interview. Read $SKILL/visual-brief.md first and follow it exactly. Session folder: <session>. Project root: <project>. Kind: prototype | diagram. Context: change to an existing app, landing in <route, page, or component>; match that page's real look and surroundings. | New UI, nothing to match. | Diagram of existing code in <modules>. | Diagram of a new system. First cut from the questions in state.json. — or — Redraw of the existing visual.html. Change only what follows; keep everything else stable:

   • Q3 answered B: the discussion panel moves to the right third
   • feedback: "make the sidebar collapsible" Write <session>/visual.html and reply with ONE line saying what the visual now shows (or what changed).

   One send with several triggers (feedback plus answers that change the visual) is one draw with all of them in the list.

2. Put the draw into the send's one step-6 patch. On a first draw: "visual": { "kind": …, "version": 0, "thread": [], "stale": false, "drawing": { "seq": <seq> } }. On a redraw: "visual": { "stale": false, "drawing": { "seq": <seq> } }; the merge keeps version, at, note, and thread, and the file stays as it is. The same patch finishes the send as usual (agent.handled, "status": "waiting"); print the terminal line with "visual drawing" in it and return to listening. The page reads drawing: on a first draw it stays on the questions with the header button reading Visualizing… and flips to the visual by itself when v1 lands; on a redraw it keeps the current version on screen with regenerating… in the strip. Send stays enabled throughout.

3. While a draw is in flight, handle sends normally. An answer, reopen, or changed recommendation that affects the visual sets "stale": true as usual (the in-flight draw did not see it). A new draw request (Visualize, Regenerate, or visual feedback) does not start a second subagent: reply in the thread now and append the request as one bullet, "visual": { "queued": ["feedback: …"] }. Never run two draws at once; both would write the same file.

4. When the draw lands (its completion notice wakes you): stat <session>/visual.html again (do not read it) and confirm it exists with a modification time later than the one you noted at launch. Then patch "visual": { "version": <version + 1>, "note": …, "drawing": null } (0 → 1 on a first draw; note is one line naming what changed, taken from the subagent's reply: "v3: discussion panel moved to the right per Q3"). Leave stale out of it. If visual.queued is non-empty, launch the next draw at once with those bullets as the change list (step 1 again), and in the same patch give "drawing": { "seq": <last handled seq> } instead of null, plus "queued": null. Print one line ("grill: visual v3 landed", or "… landed; drawing v4 from 2 queued notes") and return to listening. Never bump without a new file and never let a new file land without a bump; the page reloads the iframe only on a bump.

5. If the subagent fails or the file did not change: on a first draw patch "visual": null and a note (the sentence above the question list) saying the draw failed and Visualize can be clicked again; on a redraw patch "visual": { "drawing": null, "thread": [{ "who": "agent", "text": … }] } saying so. Do not bump either way. Return to listening so the user can retry.

Background draws rely on your being the top-level session: a subagent's own background tasks are dropped when its turn ends. If you are yourself running as a subagent, or your harness has no subagent tool, draw the file yourself from visual-brief.md, inline, then bump the version in the send's one patch.

Feedback arrives as visual-feedback actions (see Handling a send); sending visual feedback explicitly requests a redraw. Answers and question discussions do not. On Finish the visual is reconciled with the decisions and copied next to the doc.

Terminal input

Text the user types in the terminal during a grill answers the current question when that is unambiguous (one open question, or the text names one): record it exactly as a page send would (answer.kind: "text", or "option" when it is a letter, and status: "answered"), then continue as in "Handling a send" from step 3. Its step 6 patch leaves agent.handled as it is: there was no send. Otherwise ask which question it answers, in one line. The doc path may also be changed this way ("write the doc to …" → patch "doc").

Finish

On a finish action, or when the user says finish in the terminal:

1. Write the design doc to doc (relative to the project root). It is exhaustive and self-contained, in this order: a one-paragraph summary (linking the visual at docs/<slug>-visual.html when there is one, see step 3); Terms (each with its Avoid list); Why (the problem in the user's words); Locked decisions (every durable question: the decision, the rejected options and why each lost); Routine choices (every other answered question, one bullet each); Verified facts (anything you established by exploring rather than asking, if any); Risks; Deferred (deferred questions, with what would reopen them); Open threads (discussion points that ended without a decision). Do not compress: a reader with no access to the session must be able to build from it.
2. Patch "finished": { "doc": … } and "agent": { "status": "waiting" } (after a page Finish this is the send's one patch, with handled); the page shows the finished banner and locks staging.
3. If state.visual exists, it must be reconciled with every answered question before it is exported. If no draw is in flight and it is not stale and nothing disagrees, copy <session>/visual.html to docs/<slug>-visual.html next to the doc (same folder, same slug, -visual.html) and add "visual": <that path> to finished (it is replaced whole, so give doc again, or fold it into the step 2 patch). Otherwise request one reconciling draw (or let the in-flight one land), return to listening, and when it lands copy the file and patch finished with visual then.
4. Once there is no draw in flight and the exports are complete, stop the persistent Monitor with TaskStop, or stop the server as described in Wait mode.
5. Print one line with the doc path (and the visual's). End.

Wait mode (agents without a Monitor tool)

Start the server detached with its output going to a log: nohup node $SKILL/server.mjs serve --session <session> > <session>/serve.log 2>&1 &. Verify it with url as in Start. If the harness terminates detached children, keep serve in a harness-managed running shell session instead and verify url again. A live page confirms the server is running, not that the agent is listening.

Keep this loop active in the current agent turn:

1. On entry and on resume run node $SKILL/server.mjs pending --session <session> and drain it exactly as Resume step 3 says: every printed line in one turn, in order, following "Handling a send", with one patch at the end whose agent.handled is the last seq — not a patch and a new question round per queued send.
2. Run node $SKILL/server.mjs wait --session <session> --after <agent.handled>. Use the last acknowledged handled from your patch, not the last sequence merely seen. --timeout (default 480) bounds how long that wait process sits idle before exiting 3; it prints the send and exits the moment one lands, so a long idle timeout never delays delivery. It is not how long one tool call should block: if the shell tool yields a running process or session ID, keep that single wait alive and poll it in bounded steps (60 seconds or less, within the harness's limits) so user input and draw completions are still handled promptly. Never start a second waiter for the same session. Pass a short --timeout only when the harness cannot keep a yielded process between calls and each wait must run to completion in the foreground.
3. Exit 0 returns a send: handle it and acknowledge it atomically, then loop with the new handled. Exit 3 is an idle timeout: re-issue the wait. Other failures need inspection; recover if possible, otherwise report the inactive listener rather than silently exit.
4. When a draw completes, publish its version and return to this loop. If a wait process is still active, resume it. Publishing a finished prototype is not finishing the grill.

The user does not need to type "continue" in the terminal to deliver a browser Send. Only stop under the turn-boundary conditions above. On Finish, once the doc and any final visual are saved, stop the server using the verified pid in <session>/server.json.

state.json

What each field means. You write it only through patch.

{
  "topic": "…", "doc": "docs/x-design.md", "project": "/abs/path", "created": "ISO",
  "agent": { "status": "waiting|working", "since": "ISO", "handled": 3 },
  "note": "optional short sentence shown above the question list",
  "finished": { "doc": "docs/x-design.md", "visual": "docs/x-visual.html", "at": "ISO" },  // only after Finish
  "visual": {                                                   // only after a visualize action
    "kind": "prototype|diagram", "version": 3, "at": "ISO",
    "note": "v3: discussion panel moved to the right per Q3",
    "stale": false,                                            // true after relevant ordinary decisions; no redraw or version bump
    "drawing": { "since": "ISO", "seq": 12 },                  // while a draw subagent runs; version is 0 before the first lands
    "queued": ["feedback: make the sidebar collapsible"],      // draw requests that arrived during a draw; next draw takes them
    "thread": [{ "who": "user|agent", "text": "…", "at": "ISO" }]
  },
  "terms": [{ "term": "…", "def": "…", "avoid": ["…"] }],
  "questions": [{
    "id": "q7", "round": 4, "deps": ["q2"], "title": "…", "body": "…",
    "options": [{ "k": "A", "text": "…" }],
    "rec": { "option": "A", "why": "…" },                       // or { "text": "…", "why": "…" }
    "status": "open|answered|deferred|reopened", "durable": false, "updated": false,
    "answer": { "kind": "accept|option|text", "option": "A", "text": "…" },
    "explore": { "at": "ISO", "rows": [{ "option": "A", "pros": ["…"], "cons": ["…"] }] },  // after an explore action
    "thread": [{ "who": "user|agent", "text": "…", "at": "ISO" }]
  }]
}

Send lines (events.jsonl, also printed by serve):

{ "type": "send", "seq": 12, "at": "ISO", "session": "/abs/session/folder", "actions": [
  { "q": "q15", "type": "answer", "kind": "accept|option|text", "option": "A", "text": "…" },
  { "q": "q8",  "type": "thread", "text": "…" },
  { "q": "q17", "type": "defer" }, { "q": "q3", "type": "reopen" }, { "q": "q9", "type": "explore" },
  { "type": "visualize" }, { "type": "visual-feedback", "text": "…" },
  { "type": "finish" } ] }