| name | shape-board |
| description | Serve a keyboard-driven data board that lets a human dispose of LLM output outside the console — a Q&A board (multiple-choice over a doc) or a path-board (N candidate paths/plans/options as side-by-side columns, strike losers). Blocks until the human submits, returns their dispositions as JSON. Use instead of AskUserQuestion whenever there are ≥3 items to compare or answer in parallel — an interrogation/convergence loop, comparing candidate plans, sorting options to make a decision. Triggers on "shape-board", "path-board", "serve the board", "board these options/paths", "compare these side by side", "interrogation board". |
shape-board — keyboard data boards for disposing of LLM output
The board is the non-isolated alternative to AskUserQuestion: it holds a whole
batch of items in spatial context beside the source, and the human drives it
entirely by keyboard. The calling loop owns convergence; this skill owns one
round — present, collect, return.
One engine (serve.mjs), three board patterns. serve.mjs is payload+render-agnostic:
it injects the payload into a template, serves it, blocks on one POST, echoes the
result to stdout. WK_BOARD_TEMPLATE selects the template:
board.html (default) — Q&A board: multiple-choice cards over a doc.path-board.html — path-board: N candidate paths/plans/options as side-by-side
columns; strike losers (whole path or per-milestone), customize, escalate. Use when
comparing ≥3 whole routes the human narrows by ELIMINATION, not selection.matrix-board.html — comparison matrix: options (rows) × criteria (columns) grid,
2D cell navigation. Strike an option (row), drop a criterion (column), flag a dealbreaker
cell, note a cell, elevate an option. Use for compare-across decisions over a shared
criteria set. Payload: {docText:"", head:{title,frontier,criteria:[...]}, batch:[{label, cells:[...]}]}
(batch = option-rows; criteria in head). Returns {dispositions:[{option,struck,struck_cells,notes,escalate}], dropped_criteria, invalidated, escalated}.exec-board.html — command-approval HITL: captured commands/code blocks; approve (a) the
ones to run, reject (x), note, escalate. Default PENDING — nothing runs from the page; the AGENT
executes only approved[] out-of-band (offer≠commit). Payload: {docText:"", head:{title,frontier}, batch:[{cmd, lang?, note?, danger?}]}. Returns {dispositions, approved, rejected, escalated}.quad-board.html — 2×2 quadrant: place items into four quadrants across two axes (1-4 assign,
0 unplace). Positioning is the gesture. Payload: {docText:"", head:{title,frontier,axes:{x,y},quadrants?:[4]}, batch:[{label,note?}]}. Returns {dispositions:[{label,quadrant,note}], by_quadrant, escalated}.venn-board.html — Venn (2 sets): assign each item to a region — A-only (a), B-only (b),
both (i), neither (n). Payload: {docText:"", head:{title,frontier,sets:{a,b}}, batch:[{label,note?}]}. Returns {dispositions:[{label,region,note}], by_region, escalated}.transcript-board.html — transcript review: display turns (role+text); mark (space/m) the
keepers, note, escalate. Review-and-extract, not editing. Payload: {docText:"", head:{title,frontier}, batch:[{role, text}]}. Returns {dispositions, marked:[{i,role,text}], escalated}.
Q&A board — contract
in { docText, batch:[ { q, choices:[ { label, what_changes } ], anchor? } ] }
out { dispositions:[ ... ], escalated:[q_text] }
docText — the current (in-memory) shape doc, inlined. Never a path; the loop
holds the live doc and need not flush to disk.batch[].anchor — OPTIONAL. The doc element a question probes, e.g.
"inviolate:2". Display-only: it labels the card so the human sees which element
is under the knife. No cross-card behavior.
dispositions[] entries, one per card:
{ q, picks, pick_indices } choices picked — arrays (multi-select; a single pick is a 1-element array)
{ q, custom } free-text answer
{ q, skip:true } skipped (also the default for untouched active cards)
{ q, escalate:true } human hit escalate — route this q to a Workshop transform
Cards are multi-select: 1-5 toggle choices on/off, so a card can carry several
picks. picks[] holds the chosen labels, pick_indices[] the 0-based indices (sorted).
s/c/e are exclusive — they clear any picks.
escalated[] — the q of every escalate; the caller routes each to a Workshop
transform (fork into framings / adjudicate A vs B / lens), the board does not.
path-board — contract
in { docText:"", head:{ title, frontier, forks:[{id,text}] },
batch:[ { id, archetype, grade, thesis, milestones:[{m,note}],
leans, risks, trades, forkFrom } ] }
out { dispositions:[ { id, archetype, struck, struck_milestones:[m], custom, escalate } ],
invalidated:[id], // whole paths struck
escalated:[id] } // paths sent to a Workshop transform
Polarity is elimination, not selection: the human strikes LOSERS with territory
knowledge; whatever survives un-struck carries forward. Do not ask it to pick a winner.
(docText must be "" — the header context rides in head; the engine still validates
docText as a string.)
Invoke
Both boards run through the same engine; WK_BOARD_TEMPLATE picks the board. Paths
below use $SKILL = this skill's directory (where this SKILL.md lives, e.g.
~/.claude/skills/shape-board).
node "$SKILL/serve.mjs" /tmp/qa.json > /tmp/qa.result.json
WK_BOARD_TEMPLATE=path-board.html node "$SKILL/serve.mjs" /tmp/paths.json > /tmp/paths.result.json
Run serve.mjs in the background so the agent is not locked while the human works —
you are notified when they submit. The server opens the browser (open; set
WK_BOARD_NO_OPEN=1 for headless) and blocks on a single POST /submit fired by
Enter; diagnostics go to stderr, the {dispositions, …} object to stdout.
Port defaults to 3335 (override with WK_BOARD_PORT). node may be shadowed by a
broken nvm shell function — use an absolute node path (e.g. /opt/homebrew/bin/node)
if it loops on _load_nvm.
Keyboard reference
Q&A board:
1-5 toggle choice N (multi-select) s skip
c custom (free-text) e escalate → Workshop transform
↑ ↓ move between cards ⏎ submit the round
path-board:
← → move between paths (columns) space strike a milestone (invalidate step)
↑ ↓ move between milestones x strike the whole path (invalidate route)
c customize (steer note) e escalate → Workshop
⏎ submit
Async loop — many one-shot boards, agent off the console (seed β)
The engine is one-shot by design (serve → block → submit → exit 0). "Async" is NOT a
persistent server — it is the AGENT running async around a sequence of one-shot boards.
This keeps the engine host-agnostic (no standing state) and makes the offer≠commit invariant
hold for free: each board is an offer, and between boards the agent only composes the next
offer — it never commits on the human's behalf.
The loop (the human never returns to the chat console between rounds):
1. write payload-N.json
2. serve it in the BACKGROUND: node "$SKILL/serve.mjs" payload-N.json > result-N.json
(the submit → exit 0 IS the wake signal — you are notified when the human hits Enter)
3. on notification, read result-N.json (the structured disposition)
4. COMPOSE payload-(N+1).json from it — a fresh OFFER (never a commit)
5. go to 2, until the human's disposition ends the loop
Use the harness's background-run + wake-on-exit (or Monitor watching result-N.json). Hard
invariant: step 4 is re-offer only. An agent that acts on a disposition instead of
re-boarding it violates inviolate #1 (the human's Enter is the only commit).
Same-tab vs new-tab: reuse WK_BOARD_PORT across rounds so the browser refreshes in place
rather than opening a fresh tab each round — new-tab churn can feel like "returning to a new
surface" even though the console is never touched.
Context-follow — the doc pane tracks focus (seed α, Q&A board)
On the Q&A board, batch[].anchor is no longer display-only: if the anchor text appears in
docText, focusing that card scrolls the left doc pane to the matching section and flashes it.
Author anchors as substrings of docText to light them up; anchors absent from the doc are a
graceful no-op. Keyboard-driven (rides the existing ↑↓ focus), commits nothing.
Health
- Blank cards / "docText must be a string" — payload malformed; the server
prints the reason to stderr and exits 1 before serving.
- Browser did not open — visit the URL printed on stderr manually.
- Nothing returns — the human has not hit Enter yet; the process blocks by
design until one submit arrives.
