Visual companion workflow skill

Visual Companion Workflow

Core Rule

Open the browser first, then push content. During discussion, prefer an append-only requirement waterfall over replacing the visible story every turn.

The correct experience is:

1. Start a local visual companion server.
2. Immediately give and open the local URL while it still shows the waiting screen.
3. Then write the first small screen into the watched content directory.
4. Keep the same URL for the whole discussion.
5. On each user reply, read browser events, append the user's input, the agent's understanding, and the new design delta into the page, then continue.

Do not first build a full polished HTML page and only then tell the user to open it. That is a final artifact flow, not visual companionship.

Append-First Waterfall

For requirements, architecture, product design, and ontology discussions, the companion page should read from top to bottom as a growing decision trace:

1. User input, preferably preserving the user's original wording.
2. Agent understanding and analysis, including assumptions and architecture challenge points.
3. The design delta produced by that round.
4. Open questions, selectable options, or the next decision.

Do not make each update look like a brand-new standalone report. A new screen file may still be written for technical reasons, but its visible content should keep prior decisions and append the latest block below them. This makes the final durable artifact easier to derive without losing process requirements.

Trigger Examples

Use this skill for prompts like:

• "进入可视化伴随模式"
• "启动一个静态 HTML 页面，我们边看边改"
• "先给我一个 localhost URL"
• "打开我的本地浏览器，页面里等待推送"
• "用可视化伴随讨论这个需求/架构/流程/本体"
• "不要先落正式文档，先用页面讨论"

Required Sequence

1. Start the companion server

Prefer the Superpowers brainstorming visual companion server when available:

<superpowers>/skills/brainstorming/scripts/start-server.sh

Use a temporary session unless the user explicitly asks to persist companion files in the project. The returned JSON contains:

• url
• screen_dir
• state_dir

Save those paths in the conversation context.

2. Open the browser before content is ready

Immediately open the returned URL in the user's local browser:

open "$url"

If open is unavailable or the environment is not macOS, use the best available browser-opening mechanism. If no browser-opening mechanism is available, clearly say so and give the URL.

The browser should initially show the companion waiting screen, such as "Waiting for the agent to push a screen...".

3. Push a minimal first screen

Write a small content fragment to screen_dir, not a full polished final page.

Use fragments by default, because the companion server wraps them with its frame, styling, selection handling, and live update helper:

<h2>本轮要确认什么？</h2>
<p class="subtitle">先校准边界，再逐步细化。</p>

Only use a full HTML document when complete control is necessary.

4. Iterate on the same URL

For every visual update:

• Check state_dir/server-info exists and state_dir/server-stopped does not.
• Read state_dir/events if present and merge browser clicks with the user's chat feedback.
• Write a new semantic filename into screen_dir; never overwrite an old screen.
• Preserve the previous decision trace in the visible page and append the new round below it.
• Include the user's latest requirement text, the agent's understanding, and the new content/change block.
• Keep the same URL.
• Tell the user what changed and ask them to respond in chat or click on the page.

5. Separate companion content from durable artifacts

The companion page is a temporary thinking surface.

Do not treat companion HTML as the final requirement document. After the user confirms the design, then produce durable artifacts such as:

• Markdown requirements
• HTML design document
• implementation plan
• code changes

For project repositories with commit rules, only commit durable artifacts after confirmation.

Recommended Companion Page Shape

For architecture and product design topics, use a light whiteboard structure:

• A top-level requirement waterfall / decision trace
• Current question or decision after the accumulated trace
• A central diagram or mockup
• Left side: concepts, scope, or object list
• Right side: clickable options or decision checklist
• Bottom: examples, open risks, and next step

Companion Navigation Layout

When the companion page becomes longer than one screen, add version navigation without blocking the canvas:

• Prefer a right-edge collapsed navigation tab instead of a permanently open side panel.
• In the collapsed state, show only a small half-pill or half-circle handle attached to the right viewport edge, such as "目录".
• Expand the navigation panel on hover or keyboard focus; collapse it automatically when the pointer leaves.
• Keep the expanded panel narrow and scrollable, and hide it on small screens if it would cover content.
• Generate entries from the visible round/section headings so the navigation stays append-friendly.
• Do not let navigation obscure the main discussion content in its resting state.

For ontology or knowledge graph design, useful screens include:

• Ontology layer / instance graph / business fact graph boundary map
• Object type tree
• Relationship map
• Instance calibration example, e.g. business domain -> data product -> physical source
• Product workspace wireframe
• Decision checklist

Common Mistakes

Mistake	Correct behavior
Building a full HTML report before opening the browser	Start URL first, show waiting page, then push content
Changing URLs every iteration	Keep the same URL and push newer files
Replacing the whole story each turn	Preserve prior inputs and decisions, then append the new requirement, analysis, and design delta
Writing formal docs during brainstorming	Use temporary companion pages until design is confirmed
Ignoring browser clicks	Read state_dir/events before updating
Over-polishing the first screen	Start minimal and enrich as the discussion develops
Using only text for spatial decisions	Use diagrams, mockups, or wireframes in the browser

Fallback Without Companion Server

If the Superpowers visual companion server is unavailable:

1. Create a temporary directory.

2. Write a minimal index.html waiting page.

3. Start a local static server, for example:

   python3 -m http.server 0 --directory "$tmp_dir"
   

4. Open the printed localhost URL.

5. Rewrite index.html as the discussion progresses.

This fallback lacks click event capture and automatic newest-file serving, so prefer the companion server whenever possible.