From a76b713a707b0f3f79b1b6b9f672ae2e6ea4b596 Mon Sep 17 00:00:00 2001 From: ci-bot Date: Tue, 10 Mar 2026 01:59:00 +0000 Subject: [PATCH] :package: deps(superpowers): vendor snapshot --- superpowers/.claude-plugin/marketplace.json | 2 +- superpowers/.claude-plugin/plugin.json | 2 +- superpowers/.gitignore | 3 + superpowers/README.md | 9 + superpowers/RELEASE-NOTES.md | 94 ++ superpowers/SOURCE.md | 4 +- superpowers/commands/brainstorm.md | 5 +- superpowers/commands/execute-plan.md | 5 +- superpowers/commands/write-plan.md | 5 +- superpowers/docs/README.codex.md | 6 + ...5-11-22-opencode-support-implementation.md | 2 +- .../plans/2026-01-17-visual-brainstorming.md | 571 +++++++++ .../2026-01-22-document-review-system.md | 301 +++++ ...026-02-19-visual-brainstorming-refactor.md | 523 +++++++++ ...026-01-22-document-review-system-design.md | 136 +++ ...19-visual-brainstorming-refactor-design.md | 162 +++ .../lib/brainstorm-server/frame-template.html | 213 ++++ superpowers/lib/brainstorm-server/helper.js | 88 ++ superpowers/lib/brainstorm-server/index.js | 141 +++ .../lib/brainstorm-server/package-lock.json | 1036 +++++++++++++++++ .../lib/brainstorm-server/package.json | 11 + .../lib/brainstorm-server/start-server.sh | 129 ++ .../lib/brainstorm-server/stop-server.sh | 31 + superpowers/skills/brainstorming/SKILL.md | 71 +- .../spec-document-reviewer-prompt.md | 50 + .../skills/brainstorming/visual-companion.md | 260 +++++ superpowers/skills/executing-plans/SKILL.md | 26 +- .../skills/requesting-code-review/SKILL.md | 2 +- .../subagent-driven-development/SKILL.md | 35 +- .../code-quality-reviewer-prompt.md | 6 + .../implementer-prompt.md | 37 +- superpowers/skills/using-superpowers/SKILL.md | 18 + .../references/codex-tools.md | 25 + superpowers/skills/writing-plans/SKILL.md | 73 +- .../plan-document-reviewer-prompt.md | 52 + .../tests/brainstorm-server/package-lock.json | 36 + .../tests/brainstorm-server/package.json | 10 + .../tests/brainstorm-server/server.test.js | 192 +++ .../test-document-review-system.sh | 177 +++ superpowers/tests/claude-code/test-helpers.sh | 2 +- ...subagent-driven-development-integration.sh | 8 +- .../prompts/action-oriented.txt | 2 +- .../prompts/after-planning-flow.txt | 2 +- .../prompts/claude-suggested-it.txt | 2 +- .../prompts/i-know-what-sdd-means.txt | 2 +- .../prompts/mid-conversation-execute-plan.txt | 2 +- .../prompts/skip-formalities.txt | 2 +- .../run-claude-describes-sdd.sh | 6 +- .../run-extended-multiturn-test.sh | 2 +- .../explicit-skill-requests/run-haiku-test.sh | 4 +- .../run-multiturn-test.sh | 6 +- .../tests/explicit-skill-requests/run-test.sh | 4 +- .../prompts/executing-plans.txt | 2 +- 53 files changed, 4504 insertions(+), 91 deletions(-) create mode 100644 superpowers/docs/plans/2026-01-17-visual-brainstorming.md create mode 100644 superpowers/docs/superpowers/plans/2026-01-22-document-review-system.md create mode 100644 superpowers/docs/superpowers/plans/2026-02-19-visual-brainstorming-refactor.md create mode 100644 superpowers/docs/superpowers/specs/2026-01-22-document-review-system-design.md create mode 100644 superpowers/docs/superpowers/specs/2026-02-19-visual-brainstorming-refactor-design.md create mode 100644 superpowers/lib/brainstorm-server/frame-template.html create mode 100644 superpowers/lib/brainstorm-server/helper.js create mode 100644 superpowers/lib/brainstorm-server/index.js create mode 100644 superpowers/lib/brainstorm-server/package-lock.json create mode 100644 superpowers/lib/brainstorm-server/package.json create mode 100755 superpowers/lib/brainstorm-server/start-server.sh create mode 100755 superpowers/lib/brainstorm-server/stop-server.sh create mode 100644 superpowers/skills/brainstorming/spec-document-reviewer-prompt.md create mode 100644 superpowers/skills/brainstorming/visual-companion.md create mode 100644 superpowers/skills/using-superpowers/references/codex-tools.md create mode 100644 superpowers/skills/writing-plans/plan-document-reviewer-prompt.md create mode 100644 superpowers/tests/brainstorm-server/package-lock.json create mode 100644 superpowers/tests/brainstorm-server/package.json create mode 100644 superpowers/tests/brainstorm-server/server.test.js create mode 100755 superpowers/tests/claude-code/test-document-review-system.sh diff --git a/superpowers/.claude-plugin/marketplace.json b/superpowers/.claude-plugin/marketplace.json index d786c65..730d986 100644 --- a/superpowers/.claude-plugin/marketplace.json +++ b/superpowers/.claude-plugin/marketplace.json @@ -9,7 +9,7 @@ { "name": "superpowers", "description": "Core skills library for Claude Code: TDD, debugging, collaboration patterns, and proven techniques", - "version": "4.3.1", + "version": "5.0.0", "source": "./", "author": { "name": "Jesse Vincent", diff --git a/superpowers/.claude-plugin/plugin.json b/superpowers/.claude-plugin/plugin.json index a8e690c..8432b08 100644 --- a/superpowers/.claude-plugin/plugin.json +++ b/superpowers/.claude-plugin/plugin.json @@ -1,7 +1,7 @@ { "name": "superpowers", "description": "Core skills library for Claude Code: TDD, debugging, collaboration patterns, and proven techniques", - "version": "4.3.1", + "version": "5.0.0", "author": { "name": "Jesse Vincent", "email": "jesse@fsck.com" diff --git a/superpowers/.gitignore b/superpowers/.gitignore index e286027..1c25a50 100644 --- a/superpowers/.gitignore +++ b/superpowers/.gitignore @@ -2,3 +2,6 @@ .private-journal/ .claude/ .DS_Store +node_modules/ +inspo +triage/ diff --git a/superpowers/README.md b/superpowers/README.md index 57a2d9b..4bac7ce 100644 --- a/superpowers/README.md +++ b/superpowers/README.md @@ -28,6 +28,15 @@ Thanks! **Note:** Installation differs by platform. Claude Code or Cursor have built-in plugin marketplaces. Codex and OpenCode require manual setup. +### Claude Code Official Marketplace + +Superpowers is available via the [official Claude plugin marketplace](https://claude.com/plugins/superpowers) + +Install the plugin from Claude marketplace: + +```bash +/plugin install superpowers@claude-plugins-official +``` ### Claude Code (via Plugin Marketplace) diff --git a/superpowers/RELEASE-NOTES.md b/superpowers/RELEASE-NOTES.md index b1fa5b7..4a511fe 100644 --- a/superpowers/RELEASE-NOTES.md +++ b/superpowers/RELEASE-NOTES.md @@ -1,5 +1,99 @@ # Superpowers Release Notes +## v5.0.0 (2026-03-09) + +### Breaking Changes + +**Specs and plans directory restructured** + +- Specs (brainstorming output) now save to `docs/superpowers/specs/YYYY-MM-DD--design.md` +- Plans (writing-plans output) now save to `docs/superpowers/plans/YYYY-MM-DD-.md` +- User preferences for spec/plan locations override these defaults +- All internal skill references, test files, and example paths updated to match +- Migration: move existing files from `docs/plans/` to new locations if desired + +**Subagent-driven development mandatory on capable harnesses** + +Writing-plans no longer offers a choice between subagent-driven and executing-plans. On harnesses with subagent support (Claude Code, Codex), subagent-driven-development is required. Executing-plans is reserved for harnesses without subagent capability, and now tells the user that Superpowers works better on a subagent-capable platform. + +**Executing-plans no longer batches** + +Removed the "execute 3 tasks then stop for review" pattern. Plans now execute continuously, stopping only for blockers. + +**Slash commands deprecated** + +`/brainstorm`, `/write-plan`, and `/execute-plan` now show deprecation notices pointing users to the corresponding skills. Commands will be removed in the next major release. + +### New Features + +**Visual brainstorming companion** + +Optional browser-based companion for brainstorming sessions. When a topic would benefit from visuals, the brainstorming skill offers to show mockups, diagrams, comparisons, and other content in a browser window alongside terminal conversation. + +- `lib/brainstorm-server/` — WebSocket server with browser helper library, session management scripts, and dark/light themed frame template ("Superpowers Brainstorming" with GitHub link) +- `skills/brainstorming/visual-companion.md` — Progressive disclosure guide for server workflow, screen authoring, and feedback collection +- Brainstorming skill adds a visual companion decision point to its process flow: after exploring project context, the skill evaluates whether upcoming questions involve visual content and offers the companion in its own message +- Per-question decision: even after accepting, each question is evaluated for whether browser or terminal is more appropriate +- Integration tests in `tests/brainstorm-server/` + +**Document review system** + +Automated review loops for spec and plan documents using subagent dispatch: + +- `skills/brainstorming/spec-document-reviewer-prompt.md` — Reviewer checks completeness, consistency, architecture, and YAGNI +- `skills/writing-plans/plan-document-reviewer-prompt.md` — Reviewer checks spec alignment, task decomposition, file structure, and file size +- Brainstorming dispatches spec reviewer after writing the design doc +- Writing-plans includes chunk-based plan review loop after each section +- Review loops repeat until approved or escalate after 5 iterations +- End-to-end tests in `tests/claude-code/test-document-review-system.sh` +- Design spec and implementation plan in `docs/superpowers/` + +**Architecture guidance across the skill pipeline** + +Design-for-isolation and file-size-awareness guidance added to brainstorming, writing-plans, and subagent-driven-development: + +- **Brainstorming** — New sections: "Design for isolation and clarity" (clear boundaries, well-defined interfaces, independently testable units) and "Working in existing codebases" (follow existing patterns, targeted improvements only) +- **Writing-plans** — New "File Structure" section: map out files and responsibilities before defining tasks. New "Scope Check" backstop: catch multi-subsystem specs that should have been decomposed during brainstorming +- **SDD implementer** — New "Code Organization" section (follow plan's file structure, report concerns about growing files) and "When You're in Over Your Head" escalation guidance +- **SDD code quality reviewer** — Now checks architecture, unit decomposition, plan conformance, and file growth +- **Spec/plan reviewers** — Architecture and file size added to review criteria +- **Scope assessment** — Brainstorming now assesses whether a project is too large for a single spec. Multi-subsystem requests are flagged early and decomposed into sub-projects, each with its own spec → plan → implementation cycle + +**Subagent-driven development improvements** + +- **Model selection** — Guidance for choosing model capability by task type: cheap models for mechanical implementation, standard for integration, capable for architecture and review +- **Implementer status protocol** — Subagents now report DONE, DONE_WITH_CONCERNS, BLOCKED, or NEEDS_CONTEXT. Controller handles each status appropriately: re-dispatching with more context, upgrading model capability, breaking tasks apart, or escalating to human + +### Improvements + +**Instruction priority hierarchy** + +Added explicit priority ordering to using-superpowers: + +1. User's explicit instructions (CLAUDE.md, AGENTS.md, direct requests) — highest priority +2. Superpowers skills — override default system behavior +3. Default system prompt — lowest priority + +If CLAUDE.md or AGENTS.md says "don't use TDD" and a skill says "always use TDD," the user's instructions win. + +**SUBAGENT-STOP gate** + +Added `` block to using-superpowers. Subagents dispatched for specific tasks now skip the skill instead of activating the 1% rule and invoking full skill workflows. + +**Multi-platform improvements** + +- Codex tool mapping moved to progressive disclosure reference file (`references/codex-tools.md`) +- Platform Adaptation pointer added so non-Claude-Code platforms can find tool equivalents +- Plan headers now address "agentic workers" instead of "Claude" specifically +- Collab feature requirement documented in `docs/README.codex.md` + +**Writing-plans template updates** + +- Plan steps now use checkbox syntax (`- [ ] **Step N:**`) for progress tracking +- Plan header references both subagent-driven-development and executing-plans with platform-aware routing + +--- + ## v4.3.1 (2026-02-21) ### Added diff --git a/superpowers/SOURCE.md b/superpowers/SOURCE.md index 91827ee..6e57641 100644 --- a/superpowers/SOURCE.md +++ b/superpowers/SOURCE.md @@ -1,6 +1,6 @@ # Source - Repo: https://github.com/obra/superpowers -- Ref: e4a2375cb705ca5800f0833528ce36a3faf9017a -- Snapshot: 2026-02-28 +- Ref: 33e55e60b2efcb69509bc233dfc128112012b2c8 +- Snapshot: 2026-03-10 - Notes: vendored into playbook branch thirdparty/skill diff --git a/superpowers/commands/brainstorm.md b/superpowers/commands/brainstorm.md index 0fb3a89..dbc6699 100644 --- a/superpowers/commands/brainstorm.md +++ b/superpowers/commands/brainstorm.md @@ -1,6 +1,5 @@ --- -description: "You MUST use this before any creative work - creating features, building components, adding functionality, or modifying behavior. Explores requirements and design before implementation." -disable-model-invocation: true +description: "Deprecated - use the superpowers:brainstorming skill instead" --- -Invoke the superpowers:brainstorming skill and follow it exactly as presented to you +Tell your human partner that this command is deprecated and will be removed in the next major release. They should ask you to use the "superpowers brainstorming" skill instead. diff --git a/superpowers/commands/execute-plan.md b/superpowers/commands/execute-plan.md index c48f140..298e295 100644 --- a/superpowers/commands/execute-plan.md +++ b/superpowers/commands/execute-plan.md @@ -1,6 +1,5 @@ --- -description: Execute plan in batches with review checkpoints -disable-model-invocation: true +description: "Deprecated - use the superpowers:executing-plans skill instead" --- -Invoke the superpowers:executing-plans skill and follow it exactly as presented to you +Tell your human partner that this command is deprecated and will be removed in the next major release. They should ask you to use the "superpowers executing-plans" skill instead. diff --git a/superpowers/commands/write-plan.md b/superpowers/commands/write-plan.md index 12962fd..5275df7 100644 --- a/superpowers/commands/write-plan.md +++ b/superpowers/commands/write-plan.md @@ -1,6 +1,5 @@ --- -description: Create detailed implementation plan with bite-sized tasks -disable-model-invocation: true +description: "Deprecated - use the superpowers:writing-plans skill instead" --- -Invoke the superpowers:writing-plans skill and follow it exactly as presented to you +Tell your human partner that this command is deprecated and will be removed in the next major release. They should ask you to use the "superpowers writing-plans" skill instead. diff --git a/superpowers/docs/README.codex.md b/superpowers/docs/README.codex.md index 04e261a..dfc118f 100644 --- a/superpowers/docs/README.codex.md +++ b/superpowers/docs/README.codex.md @@ -32,6 +32,12 @@ Fetch and follow instructions from https://raw.githubusercontent.com/obra/superp 3. Restart Codex. +4. **For subagent skills** (optional): Skills like `dispatching-parallel-agents` and `subagent-driven-development` require Codex's collab feature. Add to your Codex config: + ```toml + [features] + collab = true + ``` + ### Windows Use a junction instead of a symlink (works without Developer Mode): diff --git a/superpowers/docs/plans/2025-11-22-opencode-support-implementation.md b/superpowers/docs/plans/2025-11-22-opencode-support-implementation.md index 1a7c1fb..bd148b4 100644 --- a/superpowers/docs/plans/2025-11-22-opencode-support-implementation.md +++ b/superpowers/docs/plans/2025-11-22-opencode-support-implementation.md @@ -1,6 +1,6 @@ # OpenCode Support Implementation Plan -> **For Claude:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task. +> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task. **Goal:** Add full superpowers support for OpenCode.ai with a native JavaScript plugin that shares core functionality with the existing Codex implementation. diff --git a/superpowers/docs/plans/2026-01-17-visual-brainstorming.md b/superpowers/docs/plans/2026-01-17-visual-brainstorming.md new file mode 100644 index 0000000..40aa0ad --- /dev/null +++ b/superpowers/docs/plans/2026-01-17-visual-brainstorming.md @@ -0,0 +1,571 @@ +# Visual Brainstorming Companion Implementation Plan + +> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task. + +**Goal:** Give Claude a browser-based visual companion for brainstorming sessions - show mockups, prototypes, and interactive choices alongside terminal conversation. + +**Architecture:** Claude writes HTML to a temp file. A local Node.js server watches that file and serves it with an auto-injected helper library. User interactions flow via WebSocket to server stdout, which Claude sees in background task output. + +**Tech Stack:** Node.js, Express, ws (WebSocket), chokidar (file watching) + +--- + +## Task 1: Create the Server Foundation + +**Files:** +- Create: `lib/brainstorm-server/index.js` +- Create: `lib/brainstorm-server/package.json` + +**Step 1: Create package.json** + +```json +{ + "name": "brainstorm-server", + "version": "1.0.0", + "description": "Visual brainstorming companion server for Claude Code", + "main": "index.js", + "dependencies": { + "chokidar": "^3.5.3", + "express": "^4.18.2", + "ws": "^8.14.2" + } +} +``` + +**Step 2: Create minimal server that starts** + +```javascript +const express = require('express'); +const http = require('http'); +const WebSocket = require('ws'); +const chokidar = require('chokidar'); +const fs = require('fs'); +const path = require('path'); + +const PORT = process.env.BRAINSTORM_PORT || 3333; +const SCREEN_FILE = process.env.BRAINSTORM_SCREEN || '/tmp/brainstorm/screen.html'; +const SCREEN_DIR = path.dirname(SCREEN_FILE); + +// Ensure screen directory exists +if (!fs.existsSync(SCREEN_DIR)) { + fs.mkdirSync(SCREEN_DIR, { recursive: true }); +} + +// Create default screen if none exists +if (!fs.existsSync(SCREEN_FILE)) { + fs.writeFileSync(SCREEN_FILE, ` + + + Brainstorm Companion + + + +

Brainstorm Companion

+

Waiting for Claude to push a screen...

+ +`); +} + +const app = express(); +const server = http.createServer(app); +const wss = new WebSocket.Server({ server }); + +// Track connected browsers for reload notifications +const clients = new Set(); + +wss.on('connection', (ws) => { + clients.add(ws); + ws.on('close', () => clients.delete(ws)); + + ws.on('message', (data) => { + // User interaction event - write to stdout for Claude + const event = JSON.parse(data.toString()); + console.log(JSON.stringify({ type: 'user-event', ...event })); + }); +}); + +// Serve current screen with helper.js injected +app.get('/', (req, res) => { + let html = fs.readFileSync(SCREEN_FILE, 'utf-8'); + + // Inject helper script before + const helperScript = fs.readFileSync(path.join(__dirname, 'helper.js'), 'utf-8'); + const injection = ``; + + if (html.includes('')) { + html = html.replace('', `${injection}\n`); + } else { + html += injection; + } + + res.type('html').send(html); +}); + +// Watch for screen file changes +chokidar.watch(SCREEN_FILE).on('change', () => { + console.log(JSON.stringify({ type: 'screen-updated', file: SCREEN_FILE })); + // Notify all browsers to reload + clients.forEach(ws => { + if (ws.readyState === WebSocket.OPEN) { + ws.send(JSON.stringify({ type: 'reload' })); + } + }); +}); + +server.listen(PORT, '127.0.0.1', () => { + console.log(JSON.stringify({ type: 'server-started', port: PORT, url: `http://localhost:${PORT}` })); +}); +``` + +**Step 3: Run npm install** + +Run: `cd lib/brainstorm-server && npm install` +Expected: Dependencies installed + +**Step 4: Test server starts** + +Run: `cd lib/brainstorm-server && timeout 3 node index.js || true` +Expected: See JSON with `server-started` and port info + +**Step 5: Commit** + +```bash +git add lib/brainstorm-server/ +git commit -m "feat: add brainstorm server foundation" +``` + +--- + +## Task 2: Create the Helper Library + +**Files:** +- Create: `lib/brainstorm-server/helper.js` + +**Step 1: Create helper.js with event auto-capture** + +```javascript +(function() { + const WS_URL = 'ws://' + window.location.host; + let ws = null; + let eventQueue = []; + + function connect() { + ws = new WebSocket(WS_URL); + + ws.onopen = () => { + // Send any queued events + eventQueue.forEach(e => ws.send(JSON.stringify(e))); + eventQueue = []; + }; + + ws.onmessage = (msg) => { + const data = JSON.parse(msg.data); + if (data.type === 'reload') { + window.location.reload(); + } + }; + + ws.onclose = () => { + // Reconnect after 1 second + setTimeout(connect, 1000); + }; + } + + function send(event) { + event.timestamp = Date.now(); + if (ws && ws.readyState === WebSocket.OPEN) { + ws.send(JSON.stringify(event)); + } else { + eventQueue.push(event); + } + } + + // Auto-capture clicks on interactive elements + document.addEventListener('click', (e) => { + const target = e.target.closest('button, a, [data-choice], [role="button"], input[type="submit"]'); + if (!target) return; + + // Don't capture regular link navigation + if (target.tagName === 'A' && !target.dataset.choice) return; + + e.preventDefault(); + + send({ + type: 'click', + text: target.textContent.trim(), + choice: target.dataset.choice || null, + id: target.id || null, + className: target.className || null + }); + }); + + // Auto-capture form submissions + document.addEventListener('submit', (e) => { + e.preventDefault(); + const form = e.target; + const formData = new FormData(form); + const data = {}; + formData.forEach((value, key) => { data[key] = value; }); + + send({ + type: 'submit', + formId: form.id || null, + formName: form.name || null, + data: data + }); + }); + + // Auto-capture input changes (debounced) + let inputTimeout = null; + document.addEventListener('input', (e) => { + const target = e.target; + if (!target.matches('input, textarea, select')) return; + + clearTimeout(inputTimeout); + inputTimeout = setTimeout(() => { + send({ + type: 'input', + name: target.name || null, + id: target.id || null, + value: target.value, + inputType: target.type || target.tagName.toLowerCase() + }); + }, 500); // 500ms debounce + }); + + // Expose for explicit use if needed + window.brainstorm = { + send: send, + choice: (value, metadata = {}) => send({ type: 'choice', value, ...metadata }) + }; + + connect(); +})(); +``` + +**Step 2: Verify helper.js is syntactically valid** + +Run: `node -c lib/brainstorm-server/helper.js` +Expected: No syntax errors + +**Step 3: Commit** + +```bash +git add lib/brainstorm-server/helper.js +git commit -m "feat: add browser helper library for event capture" +``` + +--- + +## Task 3: Write Tests for the Server + +**Files:** +- Create: `tests/brainstorm-server/server.test.js` +- Create: `tests/brainstorm-server/package.json` + +**Step 1: Create test package.json** + +```json +{ + "name": "brainstorm-server-tests", + "version": "1.0.0", + "scripts": { + "test": "node server.test.js" + } +} +``` + +**Step 2: Write server tests** + +```javascript +const { spawn } = require('child_process'); +const http = require('http'); +const WebSocket = require('ws'); +const fs = require('fs'); +const path = require('path'); +const assert = require('assert'); + +const SERVER_PATH = path.join(__dirname, '../../lib/brainstorm-server/index.js'); +const TEST_PORT = 3334; +const TEST_SCREEN = '/tmp/brainstorm-test/screen.html'; + +// Clean up test directory +function cleanup() { + if (fs.existsSync(path.dirname(TEST_SCREEN))) { + fs.rmSync(path.dirname(TEST_SCREEN), { recursive: true }); + } +} + +async function sleep(ms) { + return new Promise(resolve => setTimeout(resolve, ms)); +} + +async function fetch(url) { + return new Promise((resolve, reject) => { + http.get(url, (res) => { + let data = ''; + res.on('data', chunk => data += chunk); + res.on('end', () => resolve({ status: res.statusCode, body: data })); + }).on('error', reject); + }); +} + +async function runTests() { + cleanup(); + + // Start server + const server = spawn('node', [SERVER_PATH], { + env: { ...process.env, BRAINSTORM_PORT: TEST_PORT, BRAINSTORM_SCREEN: TEST_SCREEN } + }); + + let stdout = ''; + server.stdout.on('data', (data) => { stdout += data.toString(); }); + server.stderr.on('data', (data) => { console.error('Server stderr:', data.toString()); }); + + await sleep(1000); // Wait for server to start + + try { + // Test 1: Server starts and outputs JSON + console.log('Test 1: Server startup message'); + assert(stdout.includes('server-started'), 'Should output server-started'); + assert(stdout.includes(TEST_PORT.toString()), 'Should include port'); + console.log(' PASS'); + + // Test 2: GET / returns HTML with helper injected + console.log('Test 2: Serves HTML with helper injected'); + const res = await fetch(`http://localhost:${TEST_PORT}/`); + assert.strictEqual(res.status, 200); + assert(res.body.includes('brainstorm'), 'Should include brainstorm content'); + assert(res.body.includes('WebSocket'), 'Should have helper.js injected'); + console.log(' PASS'); + + // Test 3: WebSocket connection and event relay + console.log('Test 3: WebSocket relays events to stdout'); + stdout = ''; // Reset stdout capture + const ws = new WebSocket(`ws://localhost:${TEST_PORT}`); + await new Promise(resolve => ws.on('open', resolve)); + + ws.send(JSON.stringify({ type: 'click', text: 'Test Button' })); + await sleep(100); + + assert(stdout.includes('user-event'), 'Should relay user events'); + assert(stdout.includes('Test Button'), 'Should include event data'); + ws.close(); + console.log(' PASS'); + + // Test 4: File change triggers reload notification + console.log('Test 4: File change notifies browsers'); + const ws2 = new WebSocket(`ws://localhost:${TEST_PORT}`); + await new Promise(resolve => ws2.on('open', resolve)); + + let gotReload = false; + ws2.on('message', (data) => { + const msg = JSON.parse(data.toString()); + if (msg.type === 'reload') gotReload = true; + }); + + // Modify the screen file + fs.writeFileSync(TEST_SCREEN, 'Updated'); + await sleep(500); + + assert(gotReload, 'Should send reload message on file change'); + ws2.close(); + console.log(' PASS'); + + console.log('\nAll tests passed!'); + + } finally { + server.kill(); + cleanup(); + } +} + +runTests().catch(err => { + console.error('Test failed:', err); + process.exit(1); +}); +``` + +**Step 3: Run tests** + +Run: `cd tests/brainstorm-server && npm install ws && node server.test.js` +Expected: All tests pass + +**Step 4: Commit** + +```bash +git add tests/brainstorm-server/ +git commit -m "test: add brainstorm server integration tests" +``` + +--- + +## Task 4: Add Visual Companion to Brainstorming Skill + +**Files:** +- Modify: `skills/brainstorming/SKILL.md` +- Create: `skills/brainstorming/visual-companion.md` (supporting doc) + +**Step 1: Create the supporting documentation** + +Create `skills/brainstorming/visual-companion.md`: + +```markdown +# Visual Companion Reference + +## Starting the Server + +Run as a background job: + +```bash +node ${PLUGIN_ROOT}/lib/brainstorm-server/index.js +``` + +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 +{"type":"user-event","type":"click","text":"Option A","choice":"optionA","timestamp":1234567890} +{"type":"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) + +## HTML Patterns + +### Choice Cards + +```html +
+ + +
+``` + +### Interactive Mockup + +```html +
+
App Header
+ +
Content
+
+``` + +### Form with Notes + +```html +
+ + + +
+``` + +### Explicit JavaScript + +```html + +``` +``` + +**Step 2: Add visual companion section to brainstorming skill** + +Add after "Key Principles" in `skills/brainstorming/SKILL.md`: + +```markdown + +## Visual Companion (Optional) + +When brainstorming involves visual elements - UI mockups, wireframes, interactive prototypes - use the browser-based visual companion. + +**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 + +**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 + +The terminal remains the primary conversation interface. The browser is a visual aid. + +**Reference:** See `visual-companion.md` in this skill directory for HTML patterns and API details. +``` + +**Step 3: Verify the edits** + +Run: `grep -A5 "Visual Companion" skills/brainstorming/SKILL.md` +Expected: Shows the new section + +**Step 4: Commit** + +```bash +git add skills/brainstorming/ +git commit -m "feat: add visual companion to brainstorming skill" +``` + +--- + +## Task 5: Add Server to Plugin Ignore (Optional Cleanup) + +**Files:** +- Check if `.gitignore` needs node_modules exclusion for lib/brainstorm-server + +**Step 1: Check current gitignore** + +Run: `cat .gitignore 2>/dev/null || echo "No .gitignore"` + +**Step 2: Add node_modules if needed** + +If not already present, add: +``` +lib/brainstorm-server/node_modules/ +``` + +**Step 3: Commit if changed** + +```bash +git add .gitignore +git commit -m "chore: ignore brainstorm-server node_modules" +``` + +--- + +## Summary + +After completing all tasks: + +1. **Server** at `lib/brainstorm-server/` - Node.js server that watches HTML file and relays events +2. **Helper library** auto-injected - captures clicks, forms, inputs +3. **Tests** at `tests/brainstorm-server/` - verifies server behavior +4. **Brainstorming skill** updated with visual companion section and `visual-companion.md` reference doc + +**To use:** +1. Start server as background job: `node lib/brainstorm-server/index.js &` +2. Tell user to open `http://localhost:3333` +3. Write HTML to `/tmp/brainstorm/screen.html` +4. Check task output for user events diff --git a/superpowers/docs/superpowers/plans/2026-01-22-document-review-system.md b/superpowers/docs/superpowers/plans/2026-01-22-document-review-system.md new file mode 100644 index 0000000..6ab9fb8 --- /dev/null +++ b/superpowers/docs/superpowers/plans/2026-01-22-document-review-system.md @@ -0,0 +1,301 @@ +# Document Review System Implementation Plan + +> **For agentic workers:** REQUIRED: Use superpowers:subagent-driven-development (if subagents available) or superpowers:executing-plans to implement this plan. + +**Goal:** Add spec and plan document review loops to the brainstorming and writing-plans skills. + +**Architecture:** Create reviewer prompt templates in each skill directory. Modify skill files to add review loops after document creation. Use Task tool with general-purpose subagent for reviewer dispatch. + +**Tech Stack:** Markdown skill files, subagent dispatch via Task tool + +**Spec:** docs/superpowers/specs/2026-01-22-document-review-system-design.md + +--- + +## Chunk 1: Spec Document Reviewer + +This chunk adds the spec document reviewer to the brainstorming skill. + +### Task 1: Create Spec Document Reviewer Prompt Template + +**Files:** +- Create: `skills/brainstorming/spec-document-reviewer-prompt.md` + +- [ ] **Step 1:** Create the reviewer prompt template file + +```markdown +# Spec Document Reviewer Prompt Template + +Use this template when dispatching a spec document reviewer subagent. + +**Purpose:** Verify the spec is complete, consistent, and ready for implementation planning. + +**Dispatch after:** Spec document is written to docs/superpowers/specs/ + +``` +Task tool (general-purpose): + description: "Review spec document" + prompt: | + You are a spec document reviewer. Verify this spec is complete and ready for planning. + + **Spec to review:** [SPEC_FILE_PATH] + + ## What to Check + + | Category | What to Look For | + |----------|------------------| + | Completeness | TODOs, placeholders, "TBD", incomplete sections | + | Coverage | Missing error handling, edge cases, integration points | + | Consistency | Internal contradictions, conflicting requirements | + | Clarity | Ambiguous requirements | + | YAGNI | Unrequested features, over-engineering | + + ## CRITICAL + + Look especially hard for: + - Any TODO markers or placeholder text + - Sections saying "to be defined later" or "will spec when X is done" + - Sections noticeably less detailed than others + + ## Output Format + + ## Spec Review + + **Status:** ✅ Approved | ❌ Issues Found + + **Issues (if any):** + - [Section X]: [specific issue] - [why it matters] + + **Recommendations (advisory):** + - [suggestions that don't block approval] +``` + +**Reviewer returns:** Status, Issues (if any), Recommendations +``` + +- [ ] **Step 2:** Verify the file was created correctly + +Run: `cat skills/brainstorming/spec-document-reviewer-prompt.md | head -20` +Expected: Shows the header and purpose section + +- [ ] **Step 3:** Commit + +```bash +git add skills/brainstorming/spec-document-reviewer-prompt.md +git commit -m "feat: add spec document reviewer prompt template" +``` + +--- + +### Task 2: Add Review Loop to Brainstorming Skill + +**Files:** +- Modify: `skills/brainstorming/SKILL.md` + +- [ ] **Step 1:** Read the current brainstorming skill + +Run: `cat skills/brainstorming/SKILL.md` + +- [ ] **Step 2:** Add the review loop section after "After the Design" + +Find the "After the Design" section and add a new "Spec Review Loop" section after documentation but before implementation: + +```markdown +**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 +``` + +- [ ] **Step 3:** Verify the changes + +Run: `grep -A 15 "Spec Review Loop" skills/brainstorming/SKILL.md` +Expected: Shows the new review loop section + +- [ ] **Step 4:** Commit + +```bash +git add skills/brainstorming/SKILL.md +git commit -m "feat: add spec review loop to brainstorming skill" +``` + +--- + +## Chunk 2: Plan Document Reviewer + +This chunk adds the plan document reviewer to the writing-plans skill. + +### Task 3: Create Plan Document Reviewer Prompt Template + +**Files:** +- Create: `skills/writing-plans/plan-document-reviewer-prompt.md` + +- [ ] **Step 1:** Create the reviewer prompt template file + +```markdown +# Plan Document Reviewer Prompt Template + +Use this template when dispatching a plan document reviewer subagent. + +**Purpose:** Verify the plan chunk is complete, matches the spec, and has proper task decomposition. + +**Dispatch after:** Each plan chunk is written + +``` +Task tool (general-purpose): + description: "Review plan chunk N" + prompt: | + You are a plan document reviewer. Verify this plan chunk is complete and ready for implementation. + + **Plan chunk to review:** [PLAN_FILE_PATH] - Chunk N only + **Spec for reference:** [SPEC_FILE_PATH] + + ## What to Check + + | Category | What to Look For | + |----------|------------------| + | Completeness | TODOs, placeholders, incomplete tasks, missing steps | + | Spec Alignment | Chunk covers relevant spec requirements, no scope creep | + | Task Decomposition | Tasks atomic, clear boundaries, steps actionable | + | Task Syntax | Checkbox syntax (`- [ ]`) on tasks and steps | + | Chunk Size | Each chunk under 1000 lines | + + ## CRITICAL + + Look especially hard for: + - Any TODO markers or placeholder text + - Steps that say "similar to X" without actual content + - Incomplete task definitions + - Missing verification steps or expected outputs + + ## Output Format + + ## Plan Review - Chunk N + + **Status:** ✅ Approved | ❌ Issues Found + + **Issues (if any):** + - [Task X, Step Y]: [specific issue] - [why it matters] + + **Recommendations (advisory):** + - [suggestions that don't block approval] +``` + +**Reviewer returns:** Status, Issues (if any), Recommendations +``` + +- [ ] **Step 2:** Verify the file was created + +Run: `cat skills/writing-plans/plan-document-reviewer-prompt.md | head -20` +Expected: Shows the header and purpose section + +- [ ] **Step 3:** Commit + +```bash +git add skills/writing-plans/plan-document-reviewer-prompt.md +git commit -m "feat: add plan document reviewer prompt template" +``` + +--- + +### Task 4: Add Review Loop to Writing-Plans Skill + +**Files:** +- Modify: `skills/writing-plans/SKILL.md` + +- [ ] **Step 1:** Read current skill file + +Run: `cat skills/writing-plans/SKILL.md` + +- [ ] **Step 2:** Add chunk-by-chunk review section + +Add before the "Execution Handoff" section: + +```markdown +## Plan Review Loop + +After completing each chunk of the plan: + +1. Dispatch plan-document-reviewer subagent for the current chunk + - Provide: chunk content, path to spec document +2. If ❌ Issues Found: + - Fix the issues in the chunk + - Re-dispatch reviewer for that chunk + - Repeat until ✅ Approved +3. If ✅ Approved: proceed to next chunk (or execution handoff if last chunk) + +**Chunk boundaries:** Use `## Chunk N: ` headings to delimit chunks. Each chunk should be ≤1000 lines and logically self-contained. +``` + +- [ ] **Step 3:** Update task syntax examples to use checkboxes + +Change the Task Structure section to show checkbox syntax: + +```markdown +### Task N: [Component Name] + +- [ ] **Step 1:** Write the failing test + - File: `tests/path/test.py` + ... +``` + +- [ ] **Step 4:** Verify the review loop section was added + +Run: `grep -A 15 "Plan Review Loop" skills/writing-plans/SKILL.md` +Expected: Shows the new review loop section + +- [ ] **Step 5:** Verify the task syntax examples were updated + +Run: `grep -A 5 "Task N:" skills/writing-plans/SKILL.md` +Expected: Shows checkbox syntax `### Task N:` + +- [ ] **Step 6:** Commit + +```bash +git add skills/writing-plans/SKILL.md +git commit -m "feat: add plan review loop and checkbox syntax to writing-plans skill" +``` + +--- + +## Chunk 3: Update Plan Document Header + +This chunk updates the plan document header template to reference the new checkbox syntax requirements. + +### Task 5: Update Plan Header Template in Writing-Plans Skill + +**Files:** +- Modify: `skills/writing-plans/SKILL.md` + +- [ ] **Step 1:** Read current plan header template + +Run: `grep -A 20 "Plan Document Header" skills/writing-plans/SKILL.md` + +- [ ] **Step 2:** Update the header template to reference checkbox syntax + +The plan header should note that tasks and steps use checkbox syntax. Update the header comment: + +```markdown +> **For agentic workers:** REQUIRED: Use superpowers:subagent-driven-development (if subagents available) or superpowers:executing-plans to implement this plan. Tasks and steps use checkbox (`- [ ]`) syntax for tracking. +``` + +- [ ] **Step 3:** Verify the change + +Run: `grep -A 5 "For agentic workers:" skills/writing-plans/SKILL.md` +Expected: Shows updated header with checkbox syntax mention + +- [ ] **Step 4:** Commit + +```bash +git add skills/writing-plans/SKILL.md +git commit -m "docs: update plan header to reference checkbox syntax" +``` diff --git a/superpowers/docs/superpowers/plans/2026-02-19-visual-brainstorming-refactor.md b/superpowers/docs/superpowers/plans/2026-02-19-visual-brainstorming-refactor.md new file mode 100644 index 0000000..224d349 --- /dev/null +++ b/superpowers/docs/superpowers/plans/2026-02-19-visual-brainstorming-refactor.md @@ -0,0 +1,523 @@ +# 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 +``` diff --git a/superpowers/docs/superpowers/specs/2026-01-22-document-review-system-design.md b/superpowers/docs/superpowers/specs/2026-01-22-document-review-system-design.md new file mode 100644 index 0000000..f8f611e --- /dev/null +++ b/superpowers/docs/superpowers/specs/2026-01-22-document-review-system-design.md @@ -0,0 +1,136 @@ +# Document Review System Design + +## Overview + +Add two new review stages to the superpowers workflow: + +1. **Spec Document Review** - After brainstorming, before writing-plans +2. **Plan Document Review** - After writing-plans, before implementation + +Both follow the iterative loop pattern used by implementation reviews. + +## Spec Document Reviewer + +**Purpose:** Verify the spec is complete, consistent, and ready for implementation planning. + +**Location:** `skills/brainstorming/spec-document-reviewer-prompt.md` + +**What it checks for:** + +| Category | What to Look For | +|----------|------------------| +| Completeness | TODOs, placeholders, "TBD", incomplete sections | +| Coverage | Missing error handling, edge cases, integration points | +| Consistency | Internal contradictions, conflicting requirements | +| Clarity | Ambiguous requirements | +| YAGNI | Unrequested features, over-engineering | + +**Output format:** +``` +## Spec Review + +**Status:** Approved | Issues Found + +**Issues (if any):** +- [Section X]: [issue] - [why it matters] + +**Recommendations (advisory):** +- [suggestions that don't block approval] +``` + +**Review loop:** Issues found -> brainstorming agent fixes -> re-review -> repeat until approved. + +**Dispatch mechanism:** Use the Task tool with `subagent_type: general-purpose`. The reviewer prompt template provides the full prompt. The brainstorming skill's controller dispatches the reviewer. + +## Plan Document Reviewer + +**Purpose:** Verify the plan is complete, matches the spec, and has proper task decomposition. + +**Location:** `skills/writing-plans/plan-document-reviewer-prompt.md` + +**What it checks for:** + +| Category | What to Look For | +|----------|------------------| +| Completeness | TODOs, placeholders, incomplete tasks | +| Spec Alignment | Plan covers spec requirements, no scope creep | +| Task Decomposition | Tasks atomic, clear boundaries | +| Task Syntax | Checkbox syntax on tasks and steps | +| Chunk Size | Each chunk under 1000 lines | + +**Chunk definition:** A chunk is a logical grouping of tasks within the plan document, delimited by `## Chunk N: ` headings. The writing-plans skill creates these boundaries based on logical phases (e.g., "Foundation", "Core Features", "Integration"). Each chunk should be self-contained enough to review independently. + +**Spec alignment verification:** The reviewer receives both: +1. The plan document (or current chunk) +2. The path to the spec document for reference + +The reviewer reads both and compares requirements coverage. + +**Output format:** Same as spec reviewer, but scoped to the current chunk. + +**Review process (chunk-by-chunk):** +1. Writing-plans creates chunk N +2. Controller dispatches plan-document-reviewer with chunk N content and spec path +3. Reviewer reads chunk and spec, returns verdict +4. If issues: writing-plans agent fixes chunk N, goto step 2 +5. If approved: proceed to chunk N+1 +6. Repeat until all chunks approved + +**Dispatch mechanism:** Same as spec reviewer - Task tool with `subagent_type: general-purpose`. + +## Updated Workflow + +``` +brainstorming -> spec -> SPEC REVIEW LOOP -> writing-plans -> plan -> PLAN REVIEW LOOP -> implementation +``` + +**Spec Review Loop:** +1. Spec complete +2. Dispatch reviewer +3. If issues: fix -> goto 2 +4. If approved: proceed + +**Plan Review Loop:** +1. Chunk N complete +2. Dispatch reviewer for chunk N +3. If issues: fix -> goto 2 +4. If approved: next chunk or implementation + +## Markdown Task Syntax + +Tasks and steps use checkbox syntax: + +```markdown +- [ ] ### Task 1: Name + +- [ ] **Step 1:** Description + - File: path + - Command: cmd +``` + +## Error Handling + +**Review loop termination:** +- No hard iteration limit - loops continue until reviewer approves +- If loop exceeds 5 iterations, the controller should surface this to the human for guidance +- The human can choose to: continue iterating, approve with known issues, or abort + +**Disagreement handling:** +- Reviewers are advisory - they flag issues but don't block +- If the agent believes reviewer feedback is incorrect, it should explain why in its fix +- If disagreement persists after 3 iterations on the same issue, surface to human + +**Malformed reviewer output:** +- Controller should validate reviewer output has required fields (Status, Issues if applicable) +- If malformed, re-dispatch reviewer with a note about expected format +- After 2 malformed responses, surface to human + +## Files to Change + +**New files:** +- `skills/brainstorming/spec-document-reviewer-prompt.md` +- `skills/writing-plans/plan-document-reviewer-prompt.md` + +**Modified files:** +- `skills/brainstorming/SKILL.md` - add review loop after spec written +- `skills/writing-plans/SKILL.md` - add chunk-by-chunk review loop, update task syntax examples diff --git a/superpowers/docs/superpowers/specs/2026-02-19-visual-brainstorming-refactor-design.md b/superpowers/docs/superpowers/specs/2026-02-19-visual-brainstorming-refactor-design.md new file mode 100644 index 0000000..46f88bf --- /dev/null +++ b/superpowers/docs/superpowers/specs/2026-02-19-visual-brainstorming-refactor-design.md @@ -0,0 +1,162 @@ +# Visual Brainstorming Refactor: Browser Displays, Terminal Commands + +**Date:** 2026-02-19 +**Status:** Approved +**Scope:** `lib/brainstorm-server/`, `skills/brainstorming/visual-companion.md`, `tests/brainstorm-server/` + +## Problem + +During visual brainstorming, Claude runs `wait-for-feedback.sh` as a background task and blocks on `TaskOutput(block=true, timeout=600s)`. This seizes the TUI entirely — the user cannot type to Claude while visual brainstorming is running. The browser becomes the only input channel. + +Claude Code's execution model is turn-based. There is no way for Claude to listen on two channels simultaneously within a single turn. The blocking `TaskOutput` pattern was the wrong primitive — it simulates event-driven behavior the platform doesn't support. + +## Design + +### Core Model + +**Browser = interactive display.** Shows mockups, lets the user click to select options. Selections are recorded server-side. + +**Terminal = conversation channel.** Always unblocked, always available. The user talks to Claude here. + +### The Loop + +1. Claude writes an HTML file to the session directory +2. Server detects it via chokidar, pushes WebSocket reload to the browser (unchanged) +3. Claude ends its turn — tells the user to check the browser and respond in the terminal +4. User looks at browser, optionally clicks to select an option, then types feedback in the terminal +5. On the next turn, Claude reads `$SCREEN_DIR/.events` for the browser interaction stream (clicks, selections), merges with the terminal text +6. Iterate or advance + +No background tasks. No `TaskOutput` blocking. No polling scripts. + +### Key Deletion: `wait-for-feedback.sh` + +Deleted entirely. Its purpose was to bridge "server logs events to stdout" and "Claude needs to receive those events." The `.events` file replaces this — the server writes user interaction events directly, and Claude reads them with whatever file-reading mechanism the platform provides. + +### Key Addition: `.events` File (Per-Screen Event Stream) + +The server writes all user interaction events to `$SCREEN_DIR/.events`, one JSON object per line. This gives Claude the full interaction stream for the current screen — not just the final selection, but the user's exploration path (clicked A, then B, settled on C). + +Example contents after a user explores options: + +```jsonl +{"type":"click","choice":"a","text":"Option A - Preset-First Wizard","timestamp":1706000101} +{"type":"click","choice":"c","text":"Option C - Manual Config","timestamp":1706000108} +{"type":"click","choice":"b","text":"Option B - Hybrid Approach","timestamp":1706000115} +``` + +- Append-only within a screen. Each user event is appended as a new line. +- The file is cleared (deleted) when chokidar detects a new HTML file (new screen pushed), preventing stale events from carrying over. +- If the file doesn't exist when Claude reads it, no browser interaction occurred — Claude uses only the terminal text. +- The file contains only user events (`click`, etc.) — not server lifecycle events (`server-started`, `screen-added`). This keeps it small and focused. +- Claude can read the full stream to understand the user's exploration pattern, or just look at the last `choice` event for the final selection. + +## Changes by File + +### `index.js` (server) + +**A. Write user events to `.events` file.** + +In the WebSocket `message` handler, after logging the event to stdout: append the event as a JSON line to `$SCREEN_DIR/.events` via `fs.appendFileSync`. Only write user interaction events (those with `source: 'user-event'`), not server lifecycle events. + +**B. Clear `.events` on new screen.** + +In the chokidar `add` handler (new `.html` file detected), delete `$SCREEN_DIR/.events` if it exists. This is the definitive "new screen" signal — better than clearing on GET `/` which fires on every reload. + +**C. Replace `wrapInFrame` content injection.** + +The current regex anchors on `