mirror of https://github.com/obra/superpowers.git synced 2026-04-23 01:49:04 +08:00

Files

Jesse Vincent d494f5a483 fix: session isolation and blocking wait for visual companion

- Each session gets unique temp directory (/tmp/brainstorm-{pid}-{timestamp})
- Server outputs screen_dir and screen_file in startup JSON
- stop-server.sh takes screen_dir arg and cleans up session directory
- Document blocking TaskOutput pattern: 10-min timeouts, retry up to 3x,
  then prompt user "let me know when you want to continue"

2026-02-19 09:35:44 -08:00

3.0 KiB

Raw Blame History

Visual Companion Reference

Quick reference for using the visual brainstorming companion.

Files

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-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

Quick Start

# 1. 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-1234567890",
#           "screen_file":"/tmp/brainstorm-12345-1234567890/screen.html"}

# 2. Write screen to the session's screen_file
# Use Bash with heredoc to write HTML

# 3. Wait for feedback using TaskOutput with block=true
# Start watcher in background:
${CLAUDE_PLUGIN_ROOT}/lib/brainstorm-server/wait-for-event.sh $SCREEN_DIR/.server.log
# Then call TaskOutput(task_id, block=true, timeout=600000) to wait
# If timeout, call TaskOutput again (watcher still running)
# After 3 timeouts (30 min), say "Let me know when you want to continue"
# Returns: {"choice":"a","feedback":"user notes"}

# 4. Clean up when done (pass screen_dir as argument)
${CLAUDE_PLUGIN_ROOT}/lib/brainstorm-server/stop-server.sh $SCREEN_DIR

CSS Classes

Options (A/B/C choices)

<div class="options">
  <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>

Cards (visual designs)

<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

<div class="mockup">
  <div class="mockup-header">Label</div>
  <div class="mockup-body"><!-- content --></div>
</div>

Split view

<div class="split">
  <div><!-- left --></div>
  <div><!-- right --></div>
</div>

Pros/Cons

<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

<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

{
  "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.

3.0 KiB Raw Blame History