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

docs: restructure brainstorming skill with progressive disclosure

Browse Source 
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.
This commit is contained in:
Jesse Vincent
2026-02-06 18:02:51 -08:00
parent b10a3c0995
commit 3ed92079c2
3 changed files with 142 additions and 364 deletions
Download Patch File Download Diff File Expand all files Collapse all files

212
lib/brainstorm-server/CLAUDE-INSTRUCTIONS.md
View File

@@ -1,212 +0,0 @@
# Visual Companion Instructions for Claude
This document explains how to use the brainstorm visual companion to show mockups, designs, and options to users without resorting to ASCII art.
## When to Use
Use the visual companion when you need to show:
- **UI mockups** - layouts, navigation patterns, component designs
- **Design comparisons** - "Which of these 3 approaches works better?"
- **Interactive prototypes** - clickable wireframes
- **Visual choices** - anything where seeing beats describing
**Don't use it for:** simple text questions, code review, or when the user prefers terminal-only interaction.
## Lifecycle
```bash
# Start server (returns JSON with URL and session directory)
${CLAUDE_PLUGIN_ROOT}/lib/brainstorm-server/start-server.sh
# Returns: {"type":"server-started","port":52341,"url":"http://localhost:52341",
# "screen_dir":"/tmp/brainstorm-12345-1234567890"}
# Save screen_dir from response!
# Tell user to open the URL in their browser
# For each screen:
# 1. Start watcher in background FIRST (avoids race condition)
${CLAUDE_PLUGIN_ROOT}/lib/brainstorm-server/wait-for-feedback.sh $SCREEN_DIR
# 2. Write HTML to a NEW file in screen_dir (e.g., platform.html, style.html)
# Server automatically serves the newest file by modification time
# 3. Call TaskOutput(task_id, block=true, timeout=600000) to wait for feedback
# When done, stop server (pass screen_dir)
${CLAUDE_PLUGIN_ROOT}/lib/brainstorm-server/stop-server.sh $SCREEN_DIR
```
## File Naming
- **Use semantic names**: `platform.html`, `visual-style.html`, `layout.html`, `controls.html`
- **Never reuse filenames** - each screen must be a new file
- **For iterations**: append version suffix like `layout-v2.html`, `layout-v3.html`
- Server automatically serves the newest `.html` file by modification time
## Writing Screens
Copy the frame template structure but replace `#claude-content` with your content:
```html
<div id="claude-content">
<h2>Your Question</h2>
<p class="subtitle">Brief context</p>
<!-- Your content here -->
</div>
```
The frame template (`frame-template.html`) includes CSS for:
- OS-aware light/dark theming
- Fixed header and feedback footer
- Common UI patterns (see below)
## CSS Helper Classes
### Options (A/B/C choices)
```html
<div class="options">
<div class="option" data-choice="a" onclick="toggleSelect(this)">
<div class="letter">A</div>
<div class="content">
<h3>Option Title</h3>
<p>Description of this option</p>
</div>
</div>
<!-- More options... -->
</div>
```
### Cards (visual designs)
```html
<div class="cards">
<div class="card" data-choice="design1" onclick="toggleSelect(this)">
<div class="card-image">
<!-- Put mockup content here -->
</div>
<div class="card-body">
<h3>Design Name</h3>
<p>Brief description</p>
</div>
</div>
</div>
```
### Mockup Container
```html
<div class="mockup">
<div class="mockup-header">Preview: Dashboard Layout</div>
<div class="mockup-body">
<!-- Your mockup HTML -->
</div>
</div>
```
### Split View (side-by-side)
```html
<div class="split">
<div class="mockup"><!-- Left side --></div>
<div class="mockup"><!-- Right side --></div>
</div>
```
### Pros/Cons
```html
<div class="pros-cons">
<div class="pros">
<h4>Pros</h4>
<ul>
<li>Benefit one</li>
<li>Benefit two</li>
</ul>
</div>
<div class="cons">
<h4>Cons</h4>
<ul>
<li>Drawback one</li>
<li>Drawback two</li>
</ul>
</div>
</div>
```
### Inline Mockup Elements
```html
<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">
```
## User Feedback
When the user clicks Send, you receive JSON like:
```json
{"choice": "a", "feedback": "I like this but make the header smaller"}
```
- `choice` - which option/card they selected (from `data-choice` attribute)
- `feedback` - any notes they typed
## Example: Design Comparison
```html
<div id="claude-content">
<h2>Which blog layout works better?</h2>
<p class="subtitle">Consider readability and visual hierarchy</p>
<div class="cards">
<div class="card" data-choice="classic" onclick="toggleSelect(this)">
<div class="card-image">
<div style="padding: 1rem;">
<div class="mock-nav">Blog Title</div>
<div style="padding: 1rem;">
<h3 style="margin-bottom: 0.5rem;">Post Title</h3>
<p style="color: var(--text-secondary); font-size: 0.9rem;">
Content preview text goes here...
</p>
</div>
</div>
</div>
<div class="card-body">
<h3>Classic Layout</h3>
<p>Traditional blog with posts in a single column</p>
</div>
</div>
<div class="card" data-choice="magazine" onclick="toggleSelect(this)">
<div class="card-image">
<div style="padding: 1rem;">
<div class="mock-nav">Blog Title</div>
<div style="display: grid; grid-template-columns: 1fr 1fr; gap: 0.5rem; padding: 0.5rem;">
<div class="placeholder" style="padding: 1rem;">Featured</div>
<div class="placeholder" style="padding: 0.5rem;">Post</div>
</div>
</div>
</div>
<div class="card-body">
<h3>Magazine Layout</h3>
<p>Grid-based with featured posts</p>
</div>
</div>
</div>
</div>
```
## Tips
1. **Keep mockups simple** - Focus on layout and structure, not pixel-perfect design
2. **Use placeholders** - The `.placeholder` class works great for content areas
3. **Label clearly** - Use `.mockup-header` to explain what each mockup shows
4. **Limit choices** - 2-4 options is ideal; more gets overwhelming
5. **Provide context** - Use `.subtitle` to explain what you're asking
6. **Regenerate fully** - Write the complete HTML each turn; don't try to patch