rogee/superpowers
1
0
Fork 0
mirror of https://github.com/obra/superpowers.git synced 2026-04-23 09:59:05 +08:00
Code Issues Packages Projects Releases Wiki Activity

feat: add visual companion for brainstorming skill

Browse Source 
Adds browser-based mockup display to replace ASCII art during
brainstorming sessions. Key components:

- Frame template with OS-aware light/dark theming
- CSS helpers for options, cards, mockups, split views
- Server lifecycle scripts (start/stop with random high port)
- Event watcher using tail+grep for feedback loop
- Claude instructions for using the visual companion

The skill now asks users if they want browser mockups and only
runs in Claude Code environments.
This commit is contained in:
Jesse Vincent
2026-01-17 16:47:03 -08:00
parent 94d5f4a817
commit 2a61167b02
7 changed files with 665 additions and 64 deletions
Download Patch File Download Diff File Expand all files Collapse all files

78
skills/brainstorming/SKILL.md
View File

@@ -53,22 +53,72 @@ Start by understanding the current project context, then ask questions one at a
- **Incremental validation** - Present design in sections, validate each
- **Be flexible** - Go back and clarify when something doesn't make sense
## Visual Companion (Optional)
## Visual Companion (Claude Code Only)
When brainstorming involves visual elements - UI mockups, wireframes, interactive prototypes - use the browser-based visual companion.
When brainstorming involves visual elements - UI mockups, layouts, design comparisons - you can use a browser-based visual companion instead of ASCII art. **This only works in Claude Code.**
**When to use:**
- Presenting UI/UX options that benefit from visual comparison
- Showing wireframes or layout options
- Gathering structured feedback (ratings, forms)
- Prototyping click interactions
### When to Offer
**How it works:**
1. Start the server as a background job
2. Tell user to open http://localhost:3333
3. Write HTML to `/tmp/brainstorm/screen.html` (auto-refreshes)
4. Check background task output for user interactions
If the brainstorm involves visual decisions (UI layouts, design choices, mockups), ask the user:
The terminal remains the primary conversation interface. The browser is a visual aid.
> "This involves some visual decisions. Would you like me to show mockups in a browser window? (Requires opening a local URL)"
**Reference:** See `visual-companion.md` in this skill directory for HTML patterns and API details.
Only proceed with visual companion if they agree. Otherwise, describe options in text.
### Starting the Visual Companion
```bash
# Start server (outputs JSON with URL)
${CLAUDE_PLUGIN_ROOT}/lib/brainstorm-server/start-server.sh
# Output looks like: {"type":"server-started","port":52341,"url":"http://localhost:52341"}
```
Tell the user to open the URL in their browser.
### Showing Content
Write complete HTML to `/tmp/brainstorm/screen.html`. The browser auto-refreshes.
Use the frame template structure from `${CLAUDE_PLUGIN_ROOT}/lib/brainstorm-server/frame-template.html`:
- Keep the header and feedback-footer intact
- Replace `#claude-content` with your content
- Use the CSS helper classes (`.options`, `.cards`, `.mockup`, `.split`, `.pros-cons`)
See `${CLAUDE_PLUGIN_ROOT}/lib/brainstorm-server/CLAUDE-INSTRUCTIONS.md` for detailed examples.
### Waiting for User Feedback
Run the watcher as a background bash command:
```bash
${CLAUDE_PLUGIN_ROOT}/lib/brainstorm-server/wait-for-event.sh /tmp/brainstorm/.server.log
```
When the user clicks Send in the browser, the watcher exits and you receive their feedback as JSON:
```json
{"choice": "a", "feedback": "I like this but make the header smaller"}
```
### The Loop
1. Write screen HTML
2. Start watcher (background bash)
3. Watcher completes when user sends feedback
4. Read feedback, respond with new screen
5. Repeat until done
### Cleaning Up
When the visual brainstorming session is complete:
```bash
${CLAUDE_PLUGIN_ROOT}/lib/brainstorm-server/stop-server.sh
```
### Tips
- **Keep mockups simple** - Focus on layout and structure, not pixel-perfect design
- **Limit choices** - 2-4 options is ideal
- **Regenerate fully** - Write complete HTML each turn; the screen is stateless
- **Terminal is primary** - The browser shows things; conversation happens in terminal

133
skills/brainstorming/visual-companion.md
View File

@@ -1,73 +1,108 @@
# Visual Companion Reference
## Starting the Server
Quick reference for using the visual brainstorming companion.
Run as a background job:
## Files
| File | Purpose |
|------|---------|
| `lib/brainstorm-server/start-server.sh` | Start server, outputs JSON with URL |
| `lib/brainstorm-server/stop-server.sh` | Stop server and clean up |
| `lib/brainstorm-server/wait-for-event.sh` | Wait for user feedback |
| `lib/brainstorm-server/frame-template.html` | Base HTML template with CSS |
| `lib/brainstorm-server/CLAUDE-INSTRUCTIONS.md` | Detailed usage guide |
| `/tmp/brainstorm/screen.html` | Write your screens here |
| `/tmp/brainstorm/.server.log` | Server output (for watcher) |
## Quick Start
```bash
node ${CLAUDE_PLUGIN_ROOT}/lib/brainstorm-server/index.js
# 1. Start server
${CLAUDE_PLUGIN_ROOT}/lib/brainstorm-server/start-server.sh
# Returns: {"type":"server-started","port":52341,"url":"http://localhost:52341"}
# 2. Write screen
# Write HTML to /tmp/brainstorm/screen.html
# 3. Wait for feedback (background)
${CLAUDE_PLUGIN_ROOT}/lib/brainstorm-server/wait-for-event.sh /tmp/brainstorm/.server.log
# 4. Read watcher output when it completes
# Returns: {"choice":"a","feedback":"user notes"}
# 5. Clean up when done
${CLAUDE_PLUGIN_ROOT}/lib/brainstorm-server/stop-server.sh
```
Tell the user: "I've started a visual companion at http://localhost:3333 - open it in a browser."
## Pushing Screens
Write HTML to `/tmp/brainstorm/screen.html`. The server watches this file and auto-refreshes the browser.
## Reading User Responses
Check the background task output for JSON events:
```json
{"source":"user-event","type":"click","text":"Option A","choice":"optionA","timestamp":1234567890}
{"source":"user-event","type":"submit","data":{"notes":"My feedback"},"timestamp":1234567891}
```
Event types:
- **click**: User clicked button or `data-choice` element
- **submit**: User submitted form (includes all form data)
- **input**: User typed in field (debounced 500ms)
- **choice**: Explicit choice via `brainstorm.choice()` call
## HTML Patterns
### Choice Cards
## CSS Classes
### Options (A/B/C choices)
```html
<div class="options">
<button data-choice="optionA">
<h3>Option A</h3>
<p>Description</p>
</button>
<button data-choice="optionB">
<h3>Option B</h3>
<p>Description</p>
</button>
<div class="option" data-choice="a" onclick="toggleSelect(this)">
<div class="letter">A</div>
<div class="content">
<h3>Title</h3>
<p>Description</p>
</div>
</div>
</div>
```
### Interactive Mockup
### 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-body">
<h3>Name</h3>
<p>Description</p>
</div>
</div>
</div>
```
### Mockup container
```html
<div class="mockup">
<header data-choice="header">App Header</header>
<nav data-choice="nav">Navigation</nav>
<main data-choice="main">Content</main>
<div class="mockup-header">Label</div>
<div class="mockup-body"><!-- content --></div>
</div>
```
### Form with Notes
### Split view
```html
<form>
<label>Priority: <input type="range" name="priority" min="1" max="5"></label>
<textarea name="notes" placeholder="Additional thoughts..."></textarea>
<button type="submit">Submit</button>
</form>
<div class="split">
<div><!-- left --></div>
<div><!-- right --></div>
</div>
```
### Explicit JavaScript
### Pros/Cons
```html
<button onclick="brainstorm.choice('custom', {extra: 'data'})">Custom</button>
<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>
```
### Mock elements
```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="placeholder">Placeholder area</div>
```
## User Feedback Format
```json
{
"choice": "option-id", // from data-choice attribute
"feedback": "user notes" // from feedback textarea
}
```
Both fields are optional - user may select without notes, or send notes without selection.