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 (see Visualize for drawing).

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, intent, 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: <topic>")

1. From the project directory run node $SKILL/server.mjs new --topic "<topic>" --intent "<why this grill exists, 1-2 sentences>" --doc "<doc path>". The doc path defaults to docs/<slug-of-topic>-design.md under the project root (create the folder later if needed). Pass --intent with the user's goal in their words (1-2 sentences), taken from the topic message that started this grill. The topic is the title; the intent is the why. Omit it only when the topic arrived as a bare phrase with no goal attached. The page shows it under the topic so several open grills stay distinguishable. 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, intent, 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, options, or text, copied as the send gives them) and status: "answered". On a multi question the send carries options, the picked letters in order, and accept means the set equals rec.options.
   • 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 → request a draw using Subagent or inline below. 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.
• When the options do not exclude each other and the user may want any mix of them (which channels to support, which checks to run, which roles get access), set multi: true and recommend a set: rec.options: ["A","C"] instead of rec.option. The page lets the user toggle any number of options. Keep single choice whenever picking one rules out the others; never use multi to dodge a real trade-off, and never offer an "all of the above" option on a multi question.
• 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.