# Visual Brainstorming Refactor Implementation Plan > **For agentic workers:** REQUIRED: Use superpowers:subagent-driven-development (if subagents available) or superpowers:executing-plans to implement this plan. Steps use checkbox (`- [ ]`) syntax for tracking. **Goal:** Refactor visual brainstorming from blocking TUI feedback model to non-blocking "Browser Displays, Terminal Commands" architecture. **Architecture:** Browser becomes an interactive display; terminal stays the conversation channel. Server writes user events to a per-screen `.events` file that Claude reads on its next turn. Eliminates `wait-for-feedback.sh` and all `TaskOutput` blocking. **Tech Stack:** Node.js (Express, ws, chokidar), vanilla HTML/CSS/JS **Spec:** `docs/superpowers/specs/2026-02-19-visual-brainstorming-refactor-design.md` --- ## File Map | File | Action | Responsibility | |------|--------|---------------| | `lib/brainstorm-server/index.js` | Modify | Server: add `.events` file writing, clear on new screen, replace `wrapInFrame` | | `lib/brainstorm-server/frame-template.html` | Modify | Template: remove feedback footer, add content placeholder + selection indicator | | `lib/brainstorm-server/helper.js` | Modify | Client JS: remove send/feedback functions, narrow to click capture + indicator updates | | `lib/brainstorm-server/wait-for-feedback.sh` | Delete | No longer needed | | `skills/brainstorming/visual-companion.md` | Modify | Skill instructions: rewrite loop to non-blocking flow | | `tests/brainstorm-server/server.test.js` | Modify | Tests: update for new template structure and helper.js API | --- ## Chunk 1: Server, Template, Client, Tests, Skill ### Task 1: Update `frame-template.html` **Files:** - Modify: `lib/brainstorm-server/frame-template.html` - [ ] **Step 1: Remove the feedback footer HTML** Replace the feedback-footer div (lines 227-233) with a selection indicator bar: ```html

Click an option above, then return to the terminal

``` Also replace the default content inside `#claude-content` (lines 220-223) with the content placeholder: ```html

``` - [ ] **Step 2: Replace feedback footer CSS with indicator bar CSS** Remove the `.feedback-footer`, `.feedback-footer label`, `.feedback-row`, and the textarea/button styles within `.feedback-footer` (lines 82-112). Add indicator bar CSS: ```css .indicator-bar { background: var(--bg-secondary); border-top: 1px solid var(--border); padding: 0.5rem 1.5rem; flex-shrink: 0; text-align: center; } .indicator-bar span { font-size: 0.75rem; color: var(--text-secondary); } .indicator-bar .selected-text { color: var(--accent); font-weight: 500; } ``` - [ ] **Step 3: Verify template renders** Run the test suite to check the template still loads: ```bash cd /Users/drewritter/prime-rad/superpowers && node tests/brainstorm-server/server.test.js ``` Expected: Tests 1-5 should still pass. Tests 6-8 may fail (expected — they assert old structure). - [ ] **Step 4: Commit** ```bash git add lib/brainstorm-server/frame-template.html git commit -m "Replace feedback footer with selection indicator bar in brainstorm template" ``` --- ### Task 2: Update `index.js` — content injection and `.events` file **Files:** - Modify: `lib/brainstorm-server/index.js` - [ ] **Step 1: Write failing test for `.events` file writing** Add to `tests/brainstorm-server/server.test.js` after Test 4 area — a new test that sends a WebSocket event with a `choice` field and verifies `.events` file is written: ```javascript // Test: Choice events written to .events file console.log('Test: Choice events written to .events file'); const ws3 = new WebSocket(`ws://localhost:${TEST_PORT}`); await new Promise(resolve => ws3.on('open', resolve)); ws3.send(JSON.stringify({ type: 'click', choice: 'a', text: 'Option A' })); await sleep(300); const eventsFile = path.join(TEST_DIR, '.events'); assert(fs.existsSync(eventsFile), '.events file should exist after choice click'); const lines = fs.readFileSync(eventsFile, 'utf-8').trim().split('\n'); const event = JSON.parse(lines[lines.length - 1]); assert.strictEqual(event.choice, 'a', 'Event should contain choice'); assert.strictEqual(event.text, 'Option A', 'Event should contain text'); ws3.close(); console.log(' PASS'); ``` - [ ] **Step 2: Run test to verify it fails** ```bash cd /Users/drewritter/prime-rad/superpowers && node tests/brainstorm-server/server.test.js ``` Expected: New test FAILS — `.events` file doesn't exist yet. - [ ] **Step 3: Write failing test for `.events` file clearing on new screen** Add another test: ```javascript // Test: .events cleared on new screen console.log('Test: .events cleared on new screen'); // .events file should still exist from previous test assert(fs.existsSync(path.join(TEST_DIR, '.events')), '.events should exist before new screen'); fs.writeFileSync(path.join(TEST_DIR, 'new-screen.html'), '

New screen

'); await sleep(500); assert(!fs.existsSync(path.join(TEST_DIR, '.events')), '.events should be cleared after new screen'); console.log(' PASS'); ``` - [ ] **Step 4: Run test to verify it fails** ```bash cd /Users/drewritter/prime-rad/superpowers && node tests/brainstorm-server/server.test.js ``` Expected: New test FAILS — `.events` not cleared on screen push. - [ ] **Step 5: Implement `.events` file writing in `index.js`** In the WebSocket `message` handler (line 74-77 of `index.js`), after the `console.log`, add: ```javascript // Write user events to .events file for Claude to read if (event.choice) { const eventsFile = path.join(SCREEN_DIR, '.events'); fs.appendFileSync(eventsFile, JSON.stringify(event) + '\n'); } ``` In the chokidar `add` handler (line 104-111), add `.events` clearing: ```javascript if (filePath.endsWith('.html')) { // Clear events from previous screen const eventsFile = path.join(SCREEN_DIR, '.events'); if (fs.existsSync(eventsFile)) fs.unlinkSync(eventsFile); console.log(JSON.stringify({ type: 'screen-added', file: filePath })); // ... existing reload broadcast } ``` - [ ] **Step 6: Replace `wrapInFrame` with comment placeholder injection** Replace the `wrapInFrame` function (lines 27-32 of `index.js`): ```javascript function wrapInFrame(content) { return frameTemplate.replace('', content); } ``` - [ ] **Step 7: Run all tests** ```bash cd /Users/drewritter/prime-rad/superpowers && node tests/brainstorm-server/server.test.js ``` Expected: New `.events` tests PASS. Existing tests may still have failures from old assertions (fixed in Task 4). - [ ] **Step 8: Commit** ```bash git add lib/brainstorm-server/index.js tests/brainstorm-server/server.test.js git commit -m "Add .events file writing and comment-based content injection to brainstorm server" ``` --- ### Task 3: Simplify `helper.js` **Files:** - Modify: `lib/brainstorm-server/helper.js` - [ ] **Step 1: Remove `sendToClaude` function** Delete the `sendToClaude` function (lines 92-106) — the function body and the page takeover HTML. - [ ] **Step 2: Remove `window.send` function** Delete the `window.send` function (lines 120-129) — was tied to the removed Send button. - [ ] **Step 3: Remove form submission and input change handlers** Delete the form submission handler (lines 57-71) and the input change handler (lines 73-89) including the `inputTimeout` variable. - [ ] **Step 4: Remove `pageshow` event listener** Delete the `pageshow` listener we added earlier (no textarea to clear anymore). - [ ] **Step 5: Narrow click handler to `[data-choice]` only** Replace the click handler (lines 36-55) with a narrower version: ```javascript // Capture clicks on choice elements document.addEventListener('click', (e) => { const target = e.target.closest('[data-choice]'); if (!target) return; sendEvent({ type: 'click', text: target.textContent.trim(), choice: target.dataset.choice, id: target.id || null }); }); ``` - [ ] **Step 6: Add indicator bar update on choice click** After the `sendEvent` call in the click handler, add: ```javascript // Update indicator bar const indicator = document.getElementById('indicator-text'); if (indicator) { const label = target.querySelector('h3, .content h3, .card-body h3')?.textContent?.trim() || target.dataset.choice; indicator.innerHTML = '' + label + ' selected — return to terminal to continue'; } ``` - [ ] **Step 7: Remove `sendToClaude` from `window.brainstorm` API** Update the `window.brainstorm` object (lines 132-136) to remove `sendToClaude`: ```javascript window.brainstorm = { send: sendEvent, choice: (value, metadata = {}) => sendEvent({ type: 'choice', value, ...metadata }) }; ``` - [ ] **Step 8: Run tests** ```bash cd /Users/drewritter/prime-rad/superpowers && node tests/brainstorm-server/server.test.js ``` - [ ] **Step 9: Commit** ```bash git add lib/brainstorm-server/helper.js git commit -m "Simplify helper.js: remove feedback functions, narrow to choice capture + indicator" ``` --- ### Task 4: Update tests for new structure **Files:** - Modify: `tests/brainstorm-server/server.test.js` **Note:** Line references below are from the _original_ file. Task 2 inserted new tests earlier in the file, so actual line numbers will be shifted. Find tests by their `console.log` labels (e.g., "Test 5:", "Test 6:"). - [ ] **Step 1: Update Test 5 (full document assertion)** Find the Test 5 assertion `!fullRes.body.includes('feedback-footer')`. Change it to: Full documents should NOT have the indicator bar either (they're served as-is): ```javascript assert(!fullRes.body.includes('indicator-bar') || fullDoc.includes('indicator-bar'), 'Should not wrap full documents in frame template'); ``` - [ ] **Step 2: Update Test 6 (fragment wrapping)** Line 125: Replace `feedback-footer` assertion with indicator bar assertion: ```javascript assert(fragRes.body.includes('indicator-bar'), 'Fragment should get indicator bar from frame'); ``` Also verify content placeholder was replaced (fragment content appears, placeholder comment doesn't): ```javascript assert(!fragRes.body.includes(''), 'Content placeholder should be replaced'); ``` - [ ] **Step 3: Update Test 7 (helper.js API)** Lines 140-142: Update assertions to reflect the new API surface: ```javascript assert(helperContent.includes('toggleSelect'), 'helper.js should define toggleSelect'); assert(helperContent.includes('sendEvent'), 'helper.js should define sendEvent'); assert(helperContent.includes('selectedChoice'), 'helper.js should track selectedChoice'); assert(helperContent.includes('brainstorm'), 'helper.js should expose brainstorm API'); assert(!helperContent.includes('sendToClaude'), 'helper.js should not contain sendToClaude'); ``` - [ ] **Step 4: Replace Test 8 (sendToClaude theming) with indicator bar test** Replace Test 8 (lines 145-149) — `sendToClaude` no longer exists. Test the indicator bar instead: ```javascript // Test 8: Indicator bar uses CSS variables (theme support) console.log('Test 8: Indicator bar uses CSS variables'); const templateContent = fs.readFileSync( path.join(__dirname, '../../lib/brainstorm-server/frame-template.html'), 'utf-8' ); assert(templateContent.includes('indicator-bar'), 'Template should have indicator bar'); assert(templateContent.includes('indicator-text'), 'Template should have indicator text element'); console.log(' PASS'); ``` - [ ] **Step 5: Run full test suite** ```bash cd /Users/drewritter/prime-rad/superpowers && node tests/brainstorm-server/server.test.js ``` Expected: ALL tests PASS. - [ ] **Step 6: Commit** ```bash git add tests/brainstorm-server/server.test.js git commit -m "Update brainstorm server tests for new template structure and helper.js API" ``` --- ### Task 5: Delete `wait-for-feedback.sh` **Files:** - Delete: `lib/brainstorm-server/wait-for-feedback.sh` - [ ] **Step 1: Verify no other files import or reference `wait-for-feedback.sh`** Search the codebase: ```bash grep -r "wait-for-feedback" /Users/drewritter/prime-rad/superpowers/ --include="*.js" --include="*.md" --include="*.sh" --include="*.json" ``` Expected references: only `visual-companion.md` (rewritten in Task 6) and possibly release notes (historical, leave as-is). - [ ] **Step 2: Delete the file** ```bash rm lib/brainstorm-server/wait-for-feedback.sh ``` - [ ] **Step 3: Run tests to confirm nothing breaks** ```bash cd /Users/drewritter/prime-rad/superpowers && node tests/brainstorm-server/server.test.js ``` Expected: All tests PASS (no test referenced this file). - [ ] **Step 4: Commit** ```bash git add -u lib/brainstorm-server/wait-for-feedback.sh git commit -m "Delete wait-for-feedback.sh: replaced by .events file" ``` --- ### Task 6: Rewrite `visual-companion.md` **Files:** - Modify: `skills/brainstorming/visual-companion.md` - [ ] **Step 1: Update "How It Works" description (line 18)** Replace the sentence about receiving feedback "as JSON" with: ```markdown 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 and can click to select options. Selections are recorded to a `.events` file that you read on your next turn. ``` - [ ] **Step 2: Update fragment description (line 20)** Remove "feedback footer" from the description of what the frame template provides: ```markdown **Content fragments vs full documents:** If your HTML file starts with ` ``` - [ ] **Step 3: Verify no stale references remain** ```bash grep -r "wait-for-feedback\|sendToClaude\|feedback-footer\|send-to-claude\|TaskOutput.*block.*true" /Users/drewritter/prime-rad/superpowers/ --include="*.js" --include="*.md" --include="*.sh" --include="*.html" | grep -v node_modules | grep -v RELEASE-NOTES | grep -v "\.md:.*spec\|plan" ``` Expected: No hits outside of release notes and the spec/plan docs (which are historical). - [ ] **Step 4: Final commit if any cleanup needed** ```bash git status # Review untracked/modified files, stage specific files as needed, commit if clean ```