33 KiB
Plan2Code Web Console: design proposal
Status: implemented in v2.4.0. Kept as the design record, because it explains
why the thing is shaped the way it is. For how to use it, see
web-console.md; for where the code lives, see
AGENTS-architecture.md.
Date: 2026-09-20
Scope: an optional local browser UI that plan2code-0-pathfinder and plan2code-1-plan can offer at startup, built as a shared component other workflow steps can adopt later.
1. Why this is smaller than it looks
Pathfinder is already written against a delivery-channel abstraction. Its rules say:
AskUserQuestion when available; prose Q blocks only as fallback.
and grilling.md specifies the question object in full: a plain two-or-three-word header, the probe with its why-it-matters, two to four genuine options each described by its trade-off with exactly one named as the recommendation, plus an automatic Other escape hatch.
That is a form. The console is not a new workflow, it is a third delivery channel alongside the structured tool and prose. The methodology, the file formats, the gates and the rules are untouched.
Plan is the opposite: pure prose Q and A with seven phases and four named approval gates. But every one of its gates already resolves to a literal typed token (approved, needs changes, approve / refine / abort). That gives us the second half of the idea.
The keystone: answers map back to the literal token
Every console request carries two extra fields:
| Field | Purpose |
|---|---|
fallbackText |
the exact terminal phrasing the prompt would have printed |
token |
what each button resolves to: approved, H, A, S 1,3,5, yes, skip |
Clicking Approve in the browser is then byte-identical to typing approved in the terminal. No prompt logic ever forks. If the console is absent, refused, or times out, the agent prints fallbackText and the session continues in the terminal with nothing lost. Mid-session switching in either direction is free, because the markdown files under specs/ remain the only source of truth.
This one decision is what keeps the integration from metastasising across twelve prompt files.
2. Hard constraints found during research
These are verified, not assumed. They shape everything below.
2.1 The character limit is the binding constraint
scripts/validate-char-count.js caps every flat src/plan2code-*.md at 11,000 characters, enforced by a husky pre-commit hook. Measured today:
10995 5 plan2code-0-pathfinder.md <- 5 characters of headroom
10676 324 plan2code-1-plan.md
10835 165 plan2code-2-document.md
Neither target prompt can absorb the integration inline. Trimming pathfinder by roughly 250 characters is a prerequisite task, not a nice-to-have. Reference files are exempt from the limit, so all of the console contract lives in one.
2.2 Packaging needs zero installer code changes
computeExpectedSkills() in install.js copies additionalReferences directories verbatim through listFilesRecursive(), which has no extension filter. The initial implementation fanned one shared source directory into two skills; the current installer fans it into every skill.
Current packaging constraints:
- Reference files are copied as
Buffers, so binary assets are supported; the shipped MP3 chimes exercise this path. Browser-served assets must also be added to the server'sSERVABLEallow-list and covered by a test. skills/is generated build output (committed, and checked for drift bynpm test) andbuildSkills()prunes files it doesn't expect. Assets must originate insrc/and never be hand-placed.
2.3 specs/ is gitignored, which is an argument for the server
Three prompts repeat the warning that Glob silently fails on specs/ and only a shell listing works. A Node server enumerating candidate spec directories server-side and handing the page a list is strictly better than either a terminal listing or a browser file input.
2.4 Formats that must round-trip byte for byte
<!-- METRICS_JSON {...} -->comments- the
## User Feedbacktable (exact field namesRating,Reason,Went Well,Went Poorly, pipes escaped as\|) - the five-state checkbox alphabet
[ ][/][x][?][!], with the invariant "never reset[/]to[ ]" - the handoff string
**Status:** Phase 3 Complete - Resume at Phase 4, plain ASCII hyphen, single spaces
The console carries all of these as opaque strings and never reformats them.
2.5 Two regex landmines
plan2code-metricsscrapes confidence with patterns like/[Rr]equirements?[:\s|]+(\d{1,2})/that do not require a percent sign. Nothing the console writes underspecs/may contain bareRequirements/Feasibility/Integration/Riskfollowed by a number.- The loop parses
TASK_COMPLETE,PHASE_COMPLETEand friends. Pathfinder already forbids these tokens underspecs/.
Both are cheap to enforce mechanically in the server's write path.
3. Architecture
3.1 Placement
src/web-console/
console.mjs CLI: open | post | wait | status | stop
server.mjs the HTTP server (spawned detached by `open`)
lib.mjs paths, atomic writes, patch merge, validate()
console.md the agent-facing contract
public/index.html markup shell only
public/app.js the client (no inline script, see CSP below)
public/app.css
public/render.js markdown tokens to DOM nodes
public/vendor/marked.esm.js pinned 15.0.7, MIT, lexer only
Wired in with one data entry per consumer:
{
source: 'plan2code-0-pathfinder.md',
// ...
additionalReferences: [{ source: 'web-console', target: 'web-console' }]
}
Lands at ~/.agents/skills/<skill>/references/web-console/ on all ~28 target agents. The server finds its own siblings via path.dirname(fileURLToPath(import.meta.url)).
The agent needs an absolute path to invoke it. ai-assist-git-pr already establishes the convention, proven on Windows, and we reuse its wording:
<SKILL_ROOT>= the directory containing thisSKILL.md(its install location). Use the absolute path you loaded it from.
3.2 The transport, which is the genuinely hard part
A turn-based agent must wait up to twenty minutes for a human. Claude Code's Bash tool caps at 600s and harness-managed background tasks are not a safe place to wait: there are open issues documenting them being killed at 5 to 20 minutes, killed on compaction, killed when a new prompt arrives, and leaked with no handle when spawned by subagents. Detached processes are explicitly immune.
So: split into two processes with deliberately different lifetimes.
# once, at handoff
node <SKILL_ROOT>/references/web-console/console.mjs open --file request.json
-> spawns server.mjs DETACHED, prints URL + session id, exits in under 300ms
# repeatedly, until done
node ... console.mjs wait --seconds 240
exit 0 -> stdout is the result JSON. Done.
exit 10 -> {"status":"waiting","elapsed":"6m12s","answered":3,"total":7,...}
Agent relays one line to the user and calls wait again.
exit 20 -> server is dead. Agent restarts it, re-reports the URL.
exit 30 -> human hit Cancel.
Why bounded rather than a single long block:
- The deadline lives in our code, not the harness's.
--seconds 240covers a 20-minute session in five turns. Drop to--seconds 90for harnesses with a 120s default (Cursor auto-backgrounds and cannot be told not to). - Every return is a free heartbeat: "still waiting, 3 of 7 answered, 6 minutes in" beats silence.
- Interruption is survivable. Ctrl-C the agent, compact the context, restart: the next
waitre-attaches, because state is on disk.
The waiter uses fs.watch on the session directory (watching a file breaks on Windows when the file is replaced by rename) with a 500ms stat fallback as the authority, and pings /health every 5s for liveness. The result is delivered through the filesystem, not HTTP, which decouples the waiter from the server and is also the resumability story.
Optional push accelerator, Claude Code only: at start, also fire a backgrounded until [ -f <dir>/result.json ]; do sleep 2; done. If it survives, submit-to-agent latency drops to near zero. If it gets killed, nothing breaks, because the poll loop is the source of truth.
3.3 Port, lifecycle, security
| Concern | Decision |
|---|---|
| Port | listen(0, '127.0.0.1'), handle file in os.tmpdir()/<tool>/<sha1(cwd).slice(0,8)>/. This is Jupyter's jpserver-<pid>.json pattern and RFC 8252 §7.3. A fixed port is fatal here: you run git worktrees, so two agents in two checkouts of one repo is routine, and a fixed port makes that silently wrong. |
| Bind | the literal 127.0.0.1, never 0.0.0.0, never the string localhost (which may resolve to ::1 and produce the classic "server is up but the browser gets ECONNREFUSED" bug on Windows). |
| Auto-open | best-effort, never fatal. Skip when DISPLAY and WAYLAND_DISPLAY are both unset, or SSH_CONNECTION / REMOTE_CONTAINERS is set. Honour BROWSER= and --no-open. |
| Orphan prevention | a server-side idle deadline (30 min, bumped by any authenticated request) is the mechanism, not a nicety. Windows has no real SIGTERM, and a detached server with no console never sees SIGINT, so signal handlers cannot be relied on. Plus a 4h absolute cap, a pagehide beacon, an explicit stop, and a reap sweep on every start. |
| Liveness test | process.kill(pid, 0) and a /health check whose returned session id matches the handle. PID reuse is real; the sid match is what disambiguates. |
Security, six controls, about 60 lines:
- Bind
127.0.0.1. Hostheader allowlist. This is the DNS-rebinding defence and the highest-value line in the server. Vite shipped GHSA-vg6x-rcgg-rjx6 for exactly this omission.- 128-bit token in the URL path, not the query string. Path placement also kills the Windows
cmd /c start&-injection hazard, because the URL then contains no&. - First
GET /s/<token>/setsHttpOnly; SameSite=Strictcookie and 302s to/. Token leaves the address bar, history and pasted screenshots; CSRF protection comes free. Origincheck on every mutating request.- Strict CSP with no
unsafe-inline, which is why JS and CSS are separate files rather than one inlined HTML.
On whether XSS matters here. The tempting argument is "it is the user's own machine and the model would not write <script>". That misses the real risk. The page is same-origin with a server that reads and writes the user's files and holds the session token, so script in that page can post arbitrary answers back to the agent, which then acts on them with the agent's full tool permissions. And the markdown is only nominally agent-authored: in practice the agent is summarising a dependency README, a scraped page, a PR description, a log. Treat it as attacker-controlled.
The structural fix, rather than a filter: vendor marked for lexer() only and render tokens to the DOM with createElement and textContent. No HTML string is ever produced, so there is nothing for a sanitiser bypass to bypass, and the strict CSP holds. Roughly 120 lines of renderer. Hand-rolling the parser instead is a trap: hand-rolled markdown fails exactly where agent-authored technical documents live (a table inside a list item, a fenced block containing backticks) and its failure mode is usually an injection hole.
3.4 Browser transport
SSE primary (about fifteen lines on Node's built-in http), with automatic fallback to 3s interval polling after three consecutive errors. Exactly one EventSource per page, ever: browsers cap HTTP/1.1 at ~6 connections per origin, and a second stream per tab across three tabs wedges the origin with no error and no timeout. Multiplex everything through one stream with a type field.
The page shows the agent's liveness, not the server's. If the agent's turn crashed, the server is still happily up and a naive spinner lies forever. Stamp agentLastSeen on every waiter ping; when stale past two minutes the page says so plainly: "The agent has not checked in for 4 minutes. Your answers are saved. Check your terminal."
3.5 State on disk
The filesystem is the database and the result transport.
~/.plan2code/console/sessions/<sid>/
session.json sid, cwd, workflow, title, phase
request-<rev>.json the agent's payload, immutable per revision
draft.json in-progress answers, debounced ~500ms write
result.json written ATOMICALLY on submit (temp + fsync + rename)
events.ndjson append-only, doubles as SSE Last-Event-ID replay
Deliberately not under specs/: that keeps the console clear of the metrics scraper and the loop's marker parser, and survives a git clean.
Draft persistence is the highest-value feature in the tool and among the cheapest. Twenty minutes of a product manager's structured answers must never be lost to a closed tab. Server-side debounced write plus a localStorage mirror keyed by sid + rev.
Recovery matrix:
| Failure | Recovery |
|---|---|
| Tab closed or browser crashed | Reopen the URL, draft restored, agent never notices |
| Server died, agent alive | wait returns exit 20, agent runs start --resume <sid>, new port, same session dir |
| Agent session died, human still working | Human submits, result.json lands on disk. A fresh session runs status, finds the unconsumed result, picks up where it left off |
| Machine rebooted | Handle file is gone (correct), session dir survives, --resume works |
4. The interaction contract
4.1 Item envelope
{
"id": "i7", "topic": "t2", "kind": "choice",
"title": "Export format", // PLAIN 2-4 words, never internal jargon
"body": "markdown: the probe plus its why-it-matters",
"options": [ { "k": "A", "text": "CSV", "detail": "trade-off", "recommended": true } ],
"allowOther": true,
"required": true,
"status": "open",
"answer": null,
"thread": [],
"fallbackText": "the exact terminal phrasing",
"token": { "A": "a", "B": "b" } // maps a click back to the literal reply
}
Note recommended is optional per option. Handoff explicitly wants its inferred task offered as the recommendation; the .gitignore question in handoff explicitly does not ("present it, don't force it").
4.2 Primitives
Tier 1, needed for pathfinder and plan, build now:
| Kind | Covers |
|---|---|
choice |
Step 0 intent gate, all six destination probes, the 14 frontier axes, plan's coverage and scope questions |
multi |
plan's testing types (Unit / Integration / E2E / None) |
text |
sacrificial boundary, the embarrassment question, kebab-case feature name with live pattern validation the terminal cannot do |
confirm |
the Tier-2 sketch gate, the lock offer, abort confirmations |
recap |
the recap-and-confirm turn. Non-skippable by design |
review |
plan's four approval gates, 1b's spec-update gate, paper-sketch reactions |
checklist |
legwork · HITL: numbered steps plus Done / Blocked / Need help / Defer plus a values field |
menu |
the fork menu: up to three takeable questions plus Start fresh, one recommended, with the resume command as copy-to-clipboard |
list |
orderable and editable rows, for plan Phase 6's implementation phases |
Tier 2, design the schema to admit them but do not build yet: findings-triage, table-review, form, path-picker, command-handoff, notice, progress.
4.3 Rules the server enforces mechanically
Several prose rules become checks, which is the quiet advantage of routing through a server at all:
- Reject a patch leaving more than three open required items. Grilling says "the cap is three regardless of what the environment allows. The ceiling is the human's attention, not the tool's schema." A web UI tempts you to show ten. Make the rule mechanical.
- Reject internal jargon in
title:grill,frontier,fog,HITL,Locked:,Blocked by:. There is an explicit do-not-say list ingrilling.md; this is where to enforce it. - One authoritative gate per session.
plan2code-3-implement-reviewproves several prompts each carry an approval gate while only one may fire when composed. Agate: { id, authoritative }field plus a server guard. - Defer is a third verb, distinct from reject.
- Reject forbidden tokens and bare confidence-word-plus-number patterns in anything written under
specs/. - Stamp every timestamp server-side. Models do not reliably know the time.
5. The UI
Three panes, plus view tabs, closer to pathfinder's own vocabulary than to a grilling UI.
┌──────────────────────────────────────────────────────────────────────┐
│ 🧭 audit-export · Pathfinder · Working 4 of 9 cleared ▓▓▓▓░░░░░ │
│ ● Waiting on you · 3 questions [Questions] [Map] [Draft] │
├───────────────┬──────────────────────────────┬───────────────────────┤
│ THE MAP │ What you end up with │ DISCUSSION │
│ │ │ │
│ ✓ Destination │ Why this matters: ... │ thread on this item │
│ ✓ Codebase │ │ │
│ ● Export fmt │ ○ A CSV, ... │ │
│ ○ Size cap │ ◉ B Parquet RECOMMENDED │ │
│ ⊘ Retention │ ○ C Both, ... │ │
│ │ ○ Something else ______ │ │
│ NOT YET CLEAR │ │ │
│ · fog item │ Not sure, skip for now │ │
├───────────────┴──────────────────────────────┴───────────────────────┤
│ 2 staged · Export format → B · +1 comment ⌘↩ [Send to Agent] │
└──────────────────────────────────────────────────────────────────────┘
What to take from grill-with-ui
- Batch staging with one explicit Send. Everything is local and reversible until one deliberate press. For a non-technical user this removes the terror of "did I just commit to that?"
- The three-tier commitment vocabulary: staged (amber, removable) → sent and pending (dashed, spinner) → recorded (green check). Honoured consistently on every surface.
- The whole stuck-agent apparatus: live elapsed counter, disabled Send while working, a five-minute grace that re-enables Send with an explanation, server-gone detection with self-reconnect. About 40 lines, and more honest about agent latency than most commercial agent UIs.
- Assumed regions. The best idea in that repo: the generated artifact marks regions that depend on still-open questions with a dashed outline and "assumed, pending Q3". This transplants directly onto a plan taking shape.
- Versioned artifacts with a staleness flag and a one-line change note.
withInputs()focus preservation, raw-string diffing before re-render, and theprefers-reduced-motionhandling that keeps progress indicators legible rather than freezing them.
What to change
- Topics, not rounds. Grill groups the nav by round, which is a temporal artifact: "questions the agent happened to ask on turn 4". Its own sample data has one round containing three unrelated subjects. Product people cannot use that. Group by topic, stable and nameable.
- Show real progress. Grill has no "N of M" counter at all. Pathfinder's trail footer already computes
4/9 clearedand a plain-English confidence line. Put both in the header. In a 45-minute session with a PM, "how much longer is this" is the first question asked. - Recommendations become optional. Grill always leads with one, which is right when the agent has an opinion and you are pushing on it. In discovery the agent frequently should not have an opinion, and pre-filling one anchors a PM into rubber-stamping. Neutral mode: no
rec, or reframed as "what similar products do". - Real, accessible form controls. Grill's options are
<li>withonclick, so they are unreachable by keyboard and invisible to screen readers. Non-negotiable to fix if non-technical stakeholders are in scope. - Markdown actually renders. Grill escapes everything and sets
white-space: pre-line; there is no markdown at all. A plan document cannot be shown that way. - Rename everything. "Grill", "durable", "Defer", "Reopen", "Why A." is a vocabulary for interrogating an engineer who already has a plan.
- Do not dim rejected options to 45%. In discovery the rejected options are often the most valuable thing in the room, and an engineer joining late needs to see why B lost.
Two things the console unlocks that the terminal cannot
- Tier-2 UI sketches.
resolve.mdalready sanctions building 3 to 5 structurally different UI variants switched by "a URL search param plus a small floating bar". The console can host them in a sandboxed iframe with a proper variant switcher. This is already in the methodology and currently awkward. - Anchored reactions.
resolve.mdinsists every sketch probe "names its row or element". Withanchors: { "row5": "b3" }, clicking the probe highlights the row. That is the inline-commenting capability, scoped to something the methodology already demands.
Room-screen polish (v2.4.0)
Built for a mixed product and engineering room reading one screen together.
- One width variable.
--card-widthon:rootinapp.csssets the column the card, the pager and the document tabs share (max-width: min(var(--card-width), 100%), so a narrow window still wins); no fixed720pxcolumn rule is left outside a media query. Three presets, picked under Card width in the looks panel and saved aslooks.width:narrow720px,comfortable880px (the default, and the variable's own value),wide1080px, applied as:root[data-width="…"].CARD_WIDTHSinpalette.jsis the same list for the page's validation and the server's first-paintdata-width;palette.jsandapp.cssmust agree, which is the one place the number is written twice. The dashboard keeps its own 860px layout. Inside the card the62ch/68chmeasure caps come off (.card .md, .card .prompt { max-width: none; }) so a wider card is not a narrow column in a wide frame; documents keep.md's 68ch. - One box grows. On the primary card, the answer box that is being typed in — a
textquestion's box, a choice's Something else box once picked, or the note under a verdict / confirm / recap once shown — istextarea.grow, and the card takes the column's full height above the pager (.card.is-primary.has-grow { flex: 1 1 auto; }).fitGrowBox()inapp.jswrites the card's free height as the box'smin-height, never under 160px; aResizeObserverwatches the main column rather than the box, so the box growing can never retrigger it, and it writes only on a change over 1px.resize: verticalwith that moving floor makes the handle taller-only; past the fill the card scrolls. Every other box keeps its ordinary size, and the notes panel is untouched. - A switch per sound. Every cue is an event in
SOUND_EVENTS(palette.js), each naming its file and rank:startSkill(start-skill.mp3, played once the dashboard's Start is accepted) 5,bootup4,sessionStart/sessionEnd(start-stop.mp3) 3,question/skillReady/chatReply(next.mp3) 2,newTab(insert.mp3) 1,snore(sleeping.mp3, looped by the wake-up outside the queue) 0. The queue, the held slot and the one-at-a-time rule inapp.jswork on events, oneAudioper file shared by the events that use it. User Preferences shows a Play sounds master (looks.sound) over one box per event, saved flat assound<Event>(soundStartSkill, …) becauselooks.jsononly holds flat values;soundPrefs()turns any missing or non-boolean switch on, so a file from before the switches keeps every sound. A cue plays only while the master and its own switch are both on; the master off greys the boxes but keeps their ticks, and ticking a box plays it. - Send breathes.
#btn-send:not(:disabled)runssend-pulse, a soft accent ring that spreads and fades every 2.4s; a disabled Send is still, and reduced motion switches it off. - Per-tab scroll memory. An in-memory
Mapkeyed by view id holds the scroller's position (the main column on a document or the Overview, the card on the questions view, with the item it belonged to), restored when the tab comes back. Page-local, never persisted, cleared when the session turns into or out of the dashboard. - The Overview tab. Appears only while
GET /overviewreturns a file for the session's spec (on the dashboard: the picker's spec; gone for start from scratch), fetched withno-storeon load, on a spec change and on every tab click, so it always shows the file as it is on disk. Rendered through the same DOM-only markdown path as every doc, captioned read-only. It never becomes a doc: the page is not the record. - The footer slot. The workspace label sits centred in the footer's middle track, 12px and muted:
footerLabel()inpublic/workspace.jsbuildsfolder · branch(from the workspace's original folder andstate.branch), orfolder + N folders · branchonce folders are added, andrenderWhere()steps down through its narrower tiers (FOOTER_TIERS) until the text fits. A warning dot marks a missing or unreadable folder. A click opens the Workspace dialog (#workspace-modal), where each folder has its own Copy path. The notification pill is fixed over the same spot and covers it while it shows, on purpose: nothing there needs pressing while the pill is up. The dashboard keeps the footer for this label alone:renderFooter()putsis-dashon it, which hides the summary and Send (and on a narrow screen keeps the label, the one thing left in the bar); the footer only disappears there when there is no label to show. - The wake-up. A fresh dashboard (
state.wake, plus a per-sidsessionStorageguard) plays Planny powering on centre stage, as proven inpathfinder/sketch-01. The wake layer hides the dashboard behind a solidvar(--bg)backdrop (.wake::before, so it follows the theme) whose opacity fades out over the same 0.6s as the glide, revealing the menu as he lands; the notification pill (.banner, z-index 46) stays above the layer (45). Before the first click or key he sleeps there on loop under a "Click to wake Planny" hint (.wake.dormant): Z's rising, slow breathing, slack arms swaying out of step, his feet pulsing like a standby light. While he sleeps the page tries to loopsleeping.mp3(browsers usually refuse until the first click, so this is normally silent). That click fades the hint and nudges him (.wake.stirring): he rocks gently about his feet (wake-nudge) while exactly one snore plays from the top, via thestir()callbackplayWake()awaits — timed by the snore'sended, capped at 6s, or a 2.6s timer when sounds are off or refused. Then the boot starts tobootup.mp3(in place of the opening chime; outranked only by the Start-skill cue, which cannot coincide with it because the wake layer swallows every click and key until the run ends), which fades out over 0.5s the moment the run ends or is aborted. The boot pops the Z's outward: 0.4s power-on and his feet blink · 1.35s feet plant · 1.5s / 1.9s arms lift off his sides · 2.5s the star opens lit, with a scan · 2.85s he glances left, right, then ahead · 3.2s smile · 3.6s hop and a cheer, star back to ink · 4.3s a 0.6s glide into the rail, measured once byboot.jsand handed to CSS as--wake-glide· the menu groups rise in 60ms apart as he lands, and the note types in. Done by 5s (a fallback timer covers a hidden tab whose transition never fires). The beats are CSS keyframes on delays under.wake.booting, all inside@media (prefers-reduced-motion: no-preference); there is no skip: from the waking click on, clicks and plain keys (no Ctrl/Meta/Alt) are swallowed so the nudge, boot and sound always play out; only a launch mid-run aborts it (snore stopped, boot-up faded), and under reduced motionplayWake()resolves at once and the awake dashboard is simply there.
6. The startup question
Both prompts open with one ask. Pathfinder already uses AskUserQuestion, so this costs almost nothing:
Run this session in the web console (a local page in your browser, better for walking through decisions with someone) or here in the terminal?
Recommended default is an open decision (see §8). Because the markdown files stay the source of truth, the user can switch either way mid-session at no cost, and the prompt should say so.
7. Work plan
| # | Task | Notes |
|---|---|---|
| 0 | Trim plan2code-0-pathfinder.md by ~250 characters |
Hard prerequisite. 5 characters of headroom today. Candidates: the grilling.md fallback blockquote, the Rules list. |
| 1 | src/web-console/ skeleton: console.mjs start/wait/status/stop, detached spawn, handle file, reap sweep |
The transport is the risky part, build and prove it first |
| 2 | server.mjs: the six security controls, SSE, atomic result write with Windows EPERM retry |
|
| 3 | index.html + app.js + app.css + vendored marked lexer, token-to-DOM renderer |
|
| 4 | Tier 1 primitives, staging, drafts, Send | |
| 5 | console.md: the agent contract |
The only file the prompts point at |
| 6 | SOURCE_PROMPTS entries + npm run build:skills + commit skills/ |
Zero installer code changes |
| 7 | Pathfinder integration: startup ask, channel rule, Read line |
~250 chars, funded by task 0 |
| 8 | Plan integration | 324 chars headroom, fits, trim ~150 for margin |
| 9 | CHANGELOG + version.json + package.json in lockstep |
plan2code-publish refuses to release on mismatch |
Three things most likely to bite during implementation
- Forgetting
windowsHide: trueon the detached spawn. It defaults tofalse, anddetachedon Windows forces a console window that "once enabled, cannot be disabled". Every handoff flashes a black box at the user. fs.renameEPERMfrom antivirus and search indexers on Windows. Intermittent, unreproducible on demand, looks exactly like a logic bug. Retry three times with backoff from day one.- Relying on
SIGTERMfor cleanup on Windows. It does not arrive. Build the idle deadline first, not last, and comment why.
Non-obvious portability notes
- grill-with-ui's heredoc idiom (
patch <<'EOF') is not portable to PowerShell, which is the default shell for Claude Code on Windows. Use a--file <path>form as the primary documented interface. nohup ... &is bash-only. Backgrounding happens insideconsole.mjs start, never in the shell command the agent writes.- Always emit
node "<abs>/console.mjs"quoted. Install paths contain spaces.
8. Open decisions
- Default channel. Terminal (lower ceremony for an engineer working solo) or console (better for the cross-functional sessions that motivated this)? Recommendation: console marked as recommended in the ask, terminal as the low-ceremony alternative.
- Vendoring
marked. It is MIT and dependency-free, but it is the first vendored third-party code in the repo, against a house style of "Node built-ins only". The alternative, a hand-rolled parser, is materially worse on both correctness and security. Recommendation: vendor it, pin the version, record the SHA-256. - Single-driver or multi-user. Everything above assumes one browser, one driver, no identity or attribution. A facilitated workshop with one person at the keyboard works fine. Two people answering independently is a different product and reaches into the state model. Recommendation: single-driver for v1, say so explicitly.
- Third consumer. After pathfinder and plan,
/plan2code-reviewis the strongest case: two of its rules exist only because output goes to a terminal ("for 15+ findings, present top 10", "output tables as direct markdown, NOT inside code blocks") and a browser deletes both. ItsS 1,3,5fix selection is literally a checkbox list compressed into a CLI token, and one findings UI serves both/plan2code-reviewand/plan2code-3-implement-review.
9. Honest assessment of size
This is not a weekend. Rough shape: console.mjs plus server.mjs around 700 to 900 lines, the client around 900 to 1,200, the contract file 300 to 400 lines of prose, plus the prompt trims and build wiring. The transport and lifecycle work (tasks 1 and 2) is where the risk concentrates, and it is worth proving end to end on one primitive before building the other eight.
A smaller first cut that still tests the whole idea: pathfinder only, choice and text and recap only, no artifact pane. That exercises the transport, the token mapping, the fallback path and the three-probe cap, which are the parts most likely to be wrong.
Credits
The architecture owes a large debt to grill-with-ui, whose file-ownership model, staged-then-send interaction, commitment tiers and assumed-region idea are all borrowed here. The implementation is independent.