mirror of
https://github.com/obra/superpowers.git
synced 2026-04-25 02:59:05 +08:00
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.
This commit is contained in:
Jesse Vincent
@@ -5,8 +5,6 @@ description: "You MUST use this before any creative work - creating features, bu
|
||||
|
||||
# Brainstorming Ideas Into Designs
|
||||
|
||||
## Overview
|
||||
|
||||
Help turn ideas into fully formed designs and specs through natural collaborative dialogue.
|
||||
|
||||
Start by understanding the current project context, then ask questions one at a time to refine the idea. Once you understand what you're building, present the design in small sections (200-300 words), checking after each section whether it looks right so far.
|
||||
@@ -43,16 +41,8 @@ Start by understanding the current project context, then ask questions one at a
|
||||
**Spec Review Loop:**
|
||||
After writing the spec document:
|
||||
1. Dispatch spec-document-reviewer subagent (see spec-document-reviewer-prompt.md)
|
||||
2. If ❌ Issues Found:
|
||||
- Fix the issues in the spec document
|
||||
- Re-dispatch reviewer
|
||||
- Repeat until ✅ Approved
|
||||
3. If ✅ Approved: proceed to implementation setup
|
||||
|
||||
**Review loop guidance:**
|
||||
- Same agent that wrote the spec fixes it (preserves context)
|
||||
- If loop exceeds 5 iterations, surface to human for guidance
|
||||
- Reviewers are advisory - explain disagreements if you believe feedback is incorrect
|
||||
2. If Issues Found: fix, re-dispatch, repeat until Approved
|
||||
3. If loop exceeds 5 iterations, surface to human for guidance
|
||||
|
||||
**Implementation (if continuing):**
|
||||
- Ask: "Ready to set up for implementation?"
|
||||
@@ -72,83 +62,10 @@ After writing the spec document:
|
||||
|
||||
## Visual Companion (Claude Code Only)
|
||||
|
||||
A browser-based visual companion for showing mockups, diagrams, and options. Use it whenever visual representation makes feedback easier. **Only works in Claude Code.**
|
||||
A browser-based visual companion for showing mockups, diagrams, and options during brainstorming. Use it whenever visual representation would make feedback easier than text descriptions alone.
|
||||
|
||||
### When to Use
|
||||
**When the topic involves visual decisions, ask:**
|
||||
> "This involves some visual decisions. I can show mockups in a browser window so you can see options and give feedback visually. This feature is still new — it can be token-intensive and a bit slow, but it works well for layout, design, and architecture questions. Want to try it? (Requires opening a local URL)"
|
||||
|
||||
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
|
||||
|
||||
**Always ask first:**
|
||||
> "This involves some visual decisions. Would you like me to show mockups in a browser window? (Requires opening a local URL)"
|
||||
|
||||
Only proceed if they agree. Otherwise, describe options in text.
|
||||
|
||||
### How to Use Effectively
|
||||
|
||||
**Scale fidelity to the question.** If you're asking about layout structure, simple wireframes suffice. If you're asking about visual polish, show polish. Match the mockup's detail level to what you're trying to learn.
|
||||
|
||||
**Explain the question on each page.** Don't just show options—state what decision you're seeking. "Which layout feels more professional?" not just "Pick one."
|
||||
|
||||
**Iterate before moving on.** If feedback changes the current screen, update it and show again. Validate that your changes address their feedback before proceeding to the next question.
|
||||
|
||||
**Limit choices to 2-4 options.** More gets overwhelming. If you have more alternatives, narrow them down first or group them.
|
||||
|
||||
**Use real content when it matters.** For a photography portfolio, use actual images (Unsplash). For a blog, use realistic text. Placeholder content obscures design issues.
|
||||
|
||||
### Starting a Session
|
||||
|
||||
```bash
|
||||
# Start server (creates unique 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"}
|
||||
```
|
||||
|
||||
Save `screen_dir` from the response. Tell user to open the URL.
|
||||
|
||||
### The Loop
|
||||
|
||||
1. **Start watcher first** (background bash) - avoids race condition:
|
||||
```bash
|
||||
${CLAUDE_PLUGIN_ROOT}/lib/brainstorm-server/wait-for-feedback.sh $SCREEN_DIR
|
||||
```
|
||||
|
||||
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
|
||||
|
||||
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")
|
||||
- This lets them know what to look for before switching to browser
|
||||
|
||||
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 next question when current step is validated.
|
||||
|
||||
7. Repeat until done.
|
||||
|
||||
### Cleaning Up
|
||||
|
||||
```bash
|
||||
${CLAUDE_PLUGIN_ROOT}/lib/brainstorm-server/stop-server.sh $SCREEN_DIR
|
||||
```
|
||||
|
||||
### Resources
|
||||
|
||||
- Frame template: `${CLAUDE_PLUGIN_ROOT}/lib/brainstorm-server/frame-template.html`
|
||||
- CSS classes: `.options`, `.cards`, `.mockup`, `.split`, `.pros-cons`
|
||||
- Detailed examples: `${CLAUDE_PLUGIN_ROOT}/lib/brainstorm-server/CLAUDE-INSTRUCTIONS.md`
|
||||
- Quick reference: `${CLAUDE_PLUGIN_ROOT}/skills/brainstorming/visual-companion.md`
|
||||
If they agree, read the detailed guide before proceeding:
|
||||
`${CLAUDE_PLUGIN_ROOT}/skills/brainstorming/visual-companion.md`
|
||||
|
||||
Reference in New Issue
Block a user