visual-companion

Visual Companion

A browser-based companion for displaying mockups, wireframes, architecture diagrams, and side-by-side visual comparisons during brainstorm sessions.

1. When to Use

Decide per question whether to show content in the browser or keep it in the terminal.

Use the browser for:

• UI mockups and wireframes
• Architecture diagrams and system maps
• Side-by-side visual comparisons (layout A vs. layout B)
• Spatial relationships (grid layouts, navigation flows, screen transitions)
• Color palettes, typography samples, component galleries

Use the terminal for:

• Requirements questions and conceptual choices
• Tradeoff lists and technical decisions
• Clarifying questions about scope or constraints
• API design, data models, algorithm selection

A question about a UI topic is not automatically a visual question. "Should we use tabs or accordion?" is a terminal question. "Here are two tab layouts -- which one?" is a browser question.

2. Starting a Session

1. Create a temporary directory for HTML files:

   mktemp -d /tmp/visual-companion-XXXXXX
   

2. Start the visual companion server in the background:

   python3 <skill-dir>/server.py --dir <temp-dir> --owner-pid $$ &
   

   <skill-dir> is resolved by the invoking agent to the absolute path of skills/visual-companion/.

3. Wait for the server to become ready before announcing its URL. The & in step 2 returns immediately; the Python process still needs to import modules, bind the port, and write server-info.json. Announcing the URL before this finishes is the #1 cause of "localhost opened but link unreachable" failures. Probe until both server-info.json exists and the port accepts TCP connections:

   for i in $(seq 1 30); do
     [ -f <temp-dir>/.vc-meta/server-info.json ] && \
       python3 -c "import json,socket; info=json.load(open('<temp-dir>/.vc-meta/server-info.json')); s=socket.socket(); s.settimeout(0.5); s.connect(('127.0.0.1', info['port'])); s.close(); print(info['url'])" 2>/dev/null && break
     sleep 0.2
   done
   

   • If the loop prints a URL, the server is ready. Use that URL.
   • If the loop completes with no output, the server failed to launch. Do NOT announce a URL. Inspect <temp-dir>/.vc-meta/ and the background-process output, fix the underlying issue, and retry step 2.

4. Tell the user (only after step 3 prints a URL):

   Visual companion running at {url}. It auto-refreshes when I update content.

3. The Loop

For each visual step in the brainstorm:

1. Write an HTML fragment to <temp-dir> with a semantic filename (e.g., layout-options.html). Write body content only -- the server wraps fragments automatically.
2. Never reuse filenames. Each screen gets a fresh file. For iterations, append a version suffix: layout-options-v2.html.
3. Browser auto-reloads via SSE when a new or changed .html file is detected. No manual refresh needed.

Pick ONE input mode per step

A step is either browser-answered or terminal-answered. Do not do both in the same step. Mixing them produces the common failure: agent renders clickable cards, user clicks them, agent is actually blocked on AskUserQuestion -- clicks land in events.jsonl that the agent never reads, and the user sees their clicks "do nothing."

Mode A -- Browser-answered (the cards ARE the question):

Use when the whole point is "pick one of these visual options."

1. Clear stale selections first so old clicks do not leak into the new question:

   python3 -c "import urllib.request; req=urllib.request.Request('http://localhost:{port}/events', method='DELETE'); urllib.request.urlopen(req)"
   

2. Write HTML with [data-choice] elements. The client JS highlights the clicked element and POSTs to /event, which appends a line to .vc-meta/events.jsonl.
3. Tell the user explicitly: > Click one of the cards in the browser to select your choice.
4. Poll events.jsonl until a new line arrives (up to ~60s):

   for i in $(seq 1 300); do
     line=$(tail -n 1 <temp-dir>/.vc-meta/events.jsonl 2>/dev/null)
     [ -n "$line" ] && echo "$line" && break
     sleep 0.2
   done
   

5. Parse the JSON line and use the choice field as the answer.
6. If the poll times out with no click, fall back to AskUserQuestion and treat the step as Mode B from this point on.

Mode B -- Terminal-answered (browser is visual aid only):

Use when the browser shows a diagram, mockup, or reference and the real answer is a conceptual choice or free text.

1. Write the HTML WITHOUT [data-choice] attributes. Clickable styling with no listener on the agent side is the bug that bit us before -- if you are not going to poll events.jsonl, do not ship clickable targets.
2. Ask the question with AskUserQuestion. The browser is decoration; the button click is the answer.

Terminal-only steps (no browser): No HTML update needed. Optionally push a placeholder page:

<div style="display:flex;align-items:center;justify-content:center;height:100vh;font-family:system-ui;color:#666">
  <p>Continuing in terminal...</p>
</div>

4. HTML Content Guide

Write body content only. The server wraps fragments with DOCTYPE, CSS, and client JS automatically.

A file is treated as a fragment if its first 256 bytes (stripped, case-insensitive) do not start with <!DOCTYPE or <html>. Full HTML documents are served as-is, with client JS injected before </body>.

Layout Patterns

• Options grid: Use .options + .option for comparing 2-3 approaches visually. Mark the recommended option with .recommended.
• Cards: Use .cards + .card for component galleries or feature inventories.
• Mockup: Use .mockup with .mock-nav, .mock-sidebar, .mock-content for wireframes.
• Split view: Use .split for before/after or A/B comparisons.
• Pros/cons: Use .pros-cons for tradeoff visualization.
• Mock UI: .mock-button, .mock-input for wireframe form elements.

Clickable Options with data-choice

Add data-choice attributes to elements that users can click to make selections:

<div class="options">
  <div class="option" data-choice="grid">
    <h3>Grid Layout</h3>
    <p>Content arranged in a responsive grid</p>
  </div>
  <div class="option" data-choice="list">
    <h3>List Layout</h3>
    <p>Content in a vertical list</p>
  </div>
</div>

When a user clicks a [data-choice] element:

• The .selected class is added (blue border + light blue background)
• Previous selections within the same parent are deselected
• A JSON event is appended to .vc-meta/events.jsonl:

  {"type":"choice","choice":"grid","text":"Grid Layout Content arranged in a responsive grid","timestamp":"2026-04-09T14:30:00.000Z"}
  

events.jsonl Format

Each line is a JSON object appended by the server. The agent reads this file to see what the user clicked:

{"type":"choice","choice":"option-a","text":"Option A","timestamp":"..."}
{"type":"choice","choice":"option-b","text":"Option B","timestamp":"..."}

5. Cleaning Up

The server self-terminates in two cases:

• Idle timeout: No HTTP requests for 30 minutes.
• Owner PID death: The --owner-pid process no longer exists (checked every 0.5s).

To stop manually:

kill $(cat <temp-dir>/.vc-meta/server-info.json | python3 -c "import sys,json; print(json.load(sys.stdin)['pid'])") 2>/dev/null

HTML files remain in the temp directory for reference. Optionally copy key mockups to docs/brainstorms/ alongside the spec:

cp <temp-dir>/final-layout.html docs/brainstorms/YYYY-MM-DD-<name>-mockups/

---

Test Plan

Trigger: Used by /brainstorm Step 1.5 when the user opts into the visual companion. Not directly slash-invoked.

Setup:

• Python 3 available on PATH.
• A brainstorm session in progress where the user has accepted the "Open visual companion" prompt.

Expected behavior:

1. /brainstorm reads this skill, starts the companion server (server.py) in a temp directory, and points the user to the local URL.
2. For each visual question, the orchestrator writes HTML to the companion temp dir; for non-visual questions, it stays in the terminal.
3. On session end (or manual cleanup), the server process is stopped using the PID recorded in <temp-dir>/.vc-meta/server-info.json.
4. Any mockups the user wants to keep are copied alongside the spec in docs/brainstorms/.

Verification checklist:

• /brainstorm only offers the companion when the topic is visual (UI/UX, layout, architecture diagrams).
• Companion server boots from server.py, prints a local URL, and serves written HTML files.
• PID is captured in <temp-dir>/.vc-meta/server-info.json and used for clean shutdown.
• Refusal path (user says "No, continue with text") leaves the companion stopped and falls back to terminal-only flow.

Known gotchas:

• This is the only Quiver skill that ships a runtime executable (server.py); never assume skill dirs are prompt-only.
• Stopping the server depends on the PID file; if the temp dir is deleted before the kill, manual pkill -f server.py is needed.