docs: restructure brainstorming skill with progressive disclosure

SKILL.md is now minimal: process, principles, and a prompt that notes the visual companion is new/token-intensive/slow. All visual companion details move to visual-companion.md as a progressive disclosure document read only when the user opts in. Delete CLAUDE-INSTRUCTIONS.md (content folded into visual-companion.md). Document fragment vs full-document behavior and --project-dir persistence.
2026-04-26 03:29:06 +08:00 · 2026-02-06 18:02:51 -08:00
parent b52af8427c
commit 2716e12781
3 changed files with 142 additions and 364 deletions
--- a/skills/brainstorming/visual-companion.md
+++ b/skills/brainstorming/visual-companion.md
@@ -1,62 +1,97 @@
-# Visual Companion Reference
+# Visual Companion Guide

-Quick reference for the browser-based visual brainstorming companion.
+Browser-based visual brainstorming companion for showing mockups, diagrams, and options.

-## Files
+## When to Use

-| File | Purpose |
-|------|---------|
-| `lib/brainstorm-server/start-server.sh` | Start server, outputs JSON with URL and session paths |
-| `lib/brainstorm-server/stop-server.sh` | Stop server and clean up session directory |
-| `lib/brainstorm-server/wait-for-feedback.sh` | Wait for user feedback (polling-based) |
-| `lib/brainstorm-server/frame-template.html` | Base HTML template with CSS |
-| `lib/brainstorm-server/CLAUDE-INSTRUCTIONS.md` | Detailed usage guide |
+Use the visual companion when seeing beats describing:
+- **UI mockups** — layouts, navigation, component designs
+- **Architecture diagrams** — system components, data flow, relationships
+- **Complex choices** — multi-option decisions with visual trade-offs
+- **Design polish** — when the question is about look and feel
+- **Spatial relationships** — file structures, database schemas, state machines

-## Quick Start
+Don't use it for simple text questions, code review, or when the user prefers terminal-only interaction.
+
+## How It Works
+
+The server watches a directory for HTML files and serves the newest one to the browser. You write HTML content, the user sees it in their browser, clicks options or types feedback, and you receive their response as JSON.
+
+**Content fragments vs full documents:** If your HTML file starts with `<!DOCTYPE` or `<html`, the server serves it as-is (just injects the helper script). Otherwise, the server automatically wraps your content in the frame template — adding the header, CSS theme, feedback footer, and all interactive infrastructure. **Write content fragments by default.** Only write full documents when you need complete control over the page.
+
+## Starting a Session

 ```bash
-# 1. Start server
-${CLAUDE_PLUGIN_ROOT}/lib/brainstorm-server/start-server.sh
-# Returns: {"screen_dir":"/tmp/brainstorm-xxx","url":"http://localhost:PORT"}
+# Start server with persistence (mockups saved to project)
+${CLAUDE_PLUGIN_ROOT}/lib/brainstorm-server/start-server.sh --project-dir /path/to/project

-# 2. Start watcher FIRST (background bash) - avoids race condition
-${CLAUDE_PLUGIN_ROOT}/lib/brainstorm-server/wait-for-feedback.sh $SCREEN_DIR
-
-# 3. Write HTML to a NEW file in screen_dir (e.g., platform.html, style.html)
-#    Never reuse filenames - server serves newest file automatically
-
-# 4. Call TaskOutput(task_id, block=true, timeout=600000)
-#    If timeout, call again. After 3 timeouts (30 min), prompt user.
-# Returns: {"choice":"a","feedback":"user notes"}
-
-# 5. Iterate or advance - write new file if feedback changes it (e.g., style-v2.html)
-
-# 6. Clean up when done
-${CLAUDE_PLUGIN_ROOT}/lib/brainstorm-server/stop-server.sh $SCREEN_DIR
+# Returns: {"type":"server-started","port":52341,"url":"http://localhost:52341",
+#           "screen_dir":"/path/to/project/.superpowers/brainstorm/12345-1706000000"}
 ```

-## Key Principles
+Save `screen_dir` from the response. Tell user to open the URL.

- **Always ask first** before starting visual companion
- **Scale fidelity to the question** - wireframes for layout, polish for polish questions
- **Explain the question** on each page - what decision are you seeking?
- **Iterate before advancing** - if feedback changes current screen, write new version
- **2-4 options max** per screen
+**Note:** Pass the project root as `--project-dir` so mockups persist in `.superpowers/brainstorm/` and survive server restarts. Without it, files go to `/tmp` and get cleaned up. Remind the user to add `.superpowers/` to `.gitignore` if it's not already there.

-## File Naming
+## The Loop

- **Use semantic names**: `platform.html`, `visual-style.html`, `layout.html`, `controls.html`
- **Never reuse filenames** - each screen is a new file
- **For iterations**: append version suffix like `layout-v2.html`, `layout-v3.html`
- Server automatically serves the newest file by modification time
+1. **Start watcher first** (background bash) — avoids race condition:
+   ```bash
+   ${CLAUDE_PLUGIN_ROOT}/lib/brainstorm-server/wait-for-feedback.sh $SCREEN_DIR
+   ```

-## Terminal UX
+2. **Write HTML** to a new file in `screen_dir`:
+   - Use semantic filenames: `platform.html`, `visual-style.html`, `layout.html`
+   - **Never reuse filenames** — each screen gets a fresh file
+   - Use Write tool — **never use cat/heredoc** (dumps noise into terminal)
+   - Server automatically serves the newest file

- **Never use cat/heredoc for HTML** - dumps noise into terminal. Use Write tool instead.
- **Remind user of URL** on every step, not just the first
- **Give text summary** of what's on screen before they look (e.g., "Showing 3 API structure options")
+3. **Tell user what to expect:**
+   - Remind them of the URL (every step, not just first)
+   - Give a brief text summary of what's on screen (e.g., "Showing 3 layout options for the homepage")

-## CSS Classes
+4. **Wait for feedback** — call `TaskOutput(task_id, block=true, timeout=600000)`
+   - If timeout, call TaskOutput again (watcher still running)
+   - After 3 timeouts (30 min), say "Let me know when you want to continue"
+
+5. **Process feedback** — returns JSON like `{"choice": "a", "feedback": "make header smaller"}`
+
+6. **Iterate or advance** — if feedback changes current screen, write a new file (e.g., `layout-v2.html`). Only move to the next question when the current step is validated.
+
+7. Repeat until done.
+
+## Writing Content Fragments
+
+Write just the content that goes inside the page. The server wraps it in the frame template automatically (header, theme CSS, feedback footer, interactive JS).
+
+**Minimal example:**
+```html
+<h2>Which layout works better?</h2>
+<p class="subtitle">Consider readability and visual hierarchy</p>
+
+<div class="options">
+  <div class="option" data-choice="a" onclick="toggleSelect(this)">
+    <div class="letter">A</div>
+    <div class="content">
+      <h3>Single Column</h3>
+      <p>Clean, focused reading experience</p>
+    </div>
+  </div>
+  <div class="option" data-choice="b" onclick="toggleSelect(this)">
+    <div class="letter">B</div>
+    <div class="content">
+      <h3>Two Column</h3>
+      <p>Sidebar navigation with main content</p>
+    </div>
+  </div>
+</div>
+```
+
+That's it. No `<html>`, no CSS, no `<script>` tags needed. The server provides all of that.
+
+## CSS Classes Available
+
+The frame template provides these CSS classes for your content:

 ### Options (A/B/C choices)
 ```html
@@ -74,8 +109,8 @@ ${CLAUDE_PLUGIN_ROOT}/lib/brainstorm-server/stop-server.sh $SCREEN_DIR
 ### Cards (visual designs)
 ```html
 <div class="cards">
-  <div class="card" data-choice="x" onclick="toggleSelect(this)">
-    <div class="card-image"><!-- mockup --></div>
+  <div class="card" data-choice="design1" onclick="toggleSelect(this)">
+    <div class="card-image"><!-- mockup content --></div>
    <div class="card-body">
      <h3>Name</h3>
      <p>Description</p>
@@ -87,44 +122,82 @@ ${CLAUDE_PLUGIN_ROOT}/lib/brainstorm-server/stop-server.sh $SCREEN_DIR
 ### Mockup container
 ```html
 <div class="mockup">
-  <div class="mockup-header">Label</div>
-  <div class="mockup-body"><!-- content --></div>
+  <div class="mockup-header">Preview: Dashboard Layout</div>
+  <div class="mockup-body"><!-- your mockup HTML --></div>
 </div>
 ```

-### Split view
+### Split view (side-by-side)
 ```html
 <div class="split">
-  <div><!-- left --></div>
-  <div><!-- right --></div>
+  <div class="mockup"><!-- left --></div>
+  <div class="mockup"><!-- right --></div>
 </div>
 ```

 ### Pros/Cons
 ```html
 <div class="pros-cons">
-  <div class="pros"><h4>Pros</h4><ul><li>...</li></ul></div>
-  <div class="cons"><h4>Cons</h4><ul><li>...</li></ul></div>
+  <div class="pros"><h4>Pros</h4><ul><li>Benefit</li></ul></div>
+  <div class="cons"><h4>Cons</h4><ul><li>Drawback</li></ul></div>
 </div>
 ```

-### Mock elements
+### Mock elements (wireframe building blocks)
 ```html
-<div class="mock-nav">Nav items</div>
-<div class="mock-sidebar">Sidebar</div>
-<div class="mock-content">Content</div>
-<button class="mock-button">Button</button>
-<input class="mock-input" placeholder="Input">
+<div class="mock-nav">Logo | Home | About | Contact</div>
+<div style="display: flex;">
+  <div class="mock-sidebar">Navigation</div>
+  <div class="mock-content">Main content area</div>
+</div>
+<button class="mock-button">Action Button</button>
+<input class="mock-input" placeholder="Input field">
 <div class="placeholder">Placeholder area</div>
 ```

+### Typography and sections
+- `h2` — page title
+- `h3` — section heading
+- `.subtitle` — secondary text below title
+- `.section` — content block with bottom margin
+- `.label` — small uppercase label text
+
 ## User Feedback Format

 ```json
 {
-  "choice": "option-id",    // from data-choice attribute
-  "feedback": "user notes"  // from feedback textarea
+  "choice": "option-id",
+  "feedback": "user notes"
 }
 ```

-Both fields are optional - user may select without notes, or send notes without selection.
+Both fields are optional — user may select without notes, or send notes without a selection.
+
+## Design Tips
+
+- **Scale fidelity to the question** — wireframes for layout, polish for polish questions
+- **Explain the question on each page** — "Which layout feels more professional?" not just "Pick one"
+- **Iterate before advancing** — if feedback changes current screen, write a new version
+- **2-4 options max** per screen
+- **Use real content when it matters** — for a photography portfolio, use actual images (Unsplash). Placeholder content obscures design issues.
+- **Keep mockups simple** — focus on layout and structure, not pixel-perfect design
+
+## File Naming
+
+- Use semantic names: `platform.html`, `visual-style.html`, `layout.html`
+- Never reuse filenames — each screen must be a new file
+- For iterations: append version suffix like `layout-v2.html`, `layout-v3.html`
+- Server serves newest file by modification time
+
+## Cleaning Up
+
+```bash
+${CLAUDE_PLUGIN_ROOT}/lib/brainstorm-server/stop-server.sh $SCREEN_DIR
+```
+
+If the session used `--project-dir`, mockup files persist in `.superpowers/brainstorm/` for later reference. Only `/tmp` sessions get deleted on stop.
+
+## Reference
+
+- Frame template (CSS reference): `${CLAUDE_PLUGIN_ROOT}/lib/brainstorm-server/frame-template.html`
+- Helper script (JS API): `${CLAUDE_PLUGIN_ROOT}/lib/brainstorm-server/helper.js`