Wip/brainstorm handoff fix#1
Open
gabehak wants to merge 44 commits into
Open
Conversation
Create the initial server for the visual brainstorming companion: - Express server with WebSocket support for browser communication - File watcher (chokidar) to detect screen.html changes - Auto-injects helper.js into served HTML for event capture - Binds to localhost only (127.0.0.1) for security - Outputs JSON events to stdout for Claude consumption
The spread operator order was causing incoming event types to overwrite the user-event type marker.
- Add sendToClaude() function to browser helper that shows confirmation - Add wait-for-event.sh script for watching server output (tail -f | grep -m 1) - Enables clean event-driven loop: background bash waits for event, completion triggers Claude's turn
Adds browser-based mockup display to replace ASCII art during brainstorming sessions. Key components: - Frame template with OS-aware light/dark theming - CSS helpers for options, cards, mockups, split views - Server lifecycle scripts (start/stop with random high port) - Event watcher using tail+grep for feedback loop - Claude instructions for using the visual companion The skill now asks users if they want browser mockups and only runs in Claude Code environments.
- 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"
- New show-and-wait.sh combines write + wait into one command - Uses polling instead of tail -f (which hangs on macOS) - Docs updated: start watcher BEFORE writing screen to avoid race - Reduces terminal noise by consolidating operations
Scripts: - Rename show-and-wait.sh -> wait-for-feedback.sh (just waits, no HTML piping) - Remove wait-for-event.sh (used hanging tail -f) - Workflow now: Write tool for HTML, wait-for-feedback.sh to block Documentation rewrite: - Broader "when to use" (UI, architecture, complex choices, spatial) - Always ask user first before starting - Scale fidelity to the question being asked - Explain the question on each page - Iterate before moving on - validate changes address feedback - Use real content (Unsplash images) when it matters
- Never use cat/heredoc for HTML (dumps noise into terminal) - Read screen_file first before Write tool to avoid errors - Remind user of URL on every step, not just first - Give text summary of what's on screen before they look
Server now watches directory for new .html files instead of a single screen file. Claude writes to semantically named files like platform.html, style.html, layout.html - each screen is a new file. Benefits: - No need to read before write (files are always new) - Semantic filenames describe what's on screen - History preserved in directory for debugging - Server serves newest file by mtime automatically Updated: index.js, start-server.sh, and all documentation.
Clarifies that user instructions (CLAUDE.md, direct requests) always take precedence over Superpowers skills, which in turn override default system prompt behavior. Ensures users remain in control. Also updates RELEASE-NOTES.md with unreleased changes including the visual companion feature.
* fix use_skill agent context (#290) * fix: respect OPENCODE_CONFIG_DIR for personal skills lookup (#297) * fix: respect OPENCODE_CONFIG_DIR for personal skills lookup The plugin was hardcoded to look for personal skills in ~/.config/opencode/skills, ignoring users who set OPENCODE_CONFIG_DIR to a custom path (e.g., for dotfiles management). Now uses OPENCODE_CONFIG_DIR if set, falling back to the default path. * fix: update help text to use dynamic paths Use configDir and personalSkillsDir variables in help text so paths are accurate when OPENCODE_CONFIG_DIR is set. * fix: normalize OPENCODE_CONFIG_DIR before use Handle edge cases where the env var might be: - Empty or whitespace-only - Using ~ for home directory (common in .env files) - A relative path Now trims, expands ~, and resolves to absolute path. * feat(opencode): use native skills and fix agent reset bug (#226) - Replace custom use_skill/find_skills tools with OpenCode's native skill tool - Use experimental.chat.system.transform hook instead of session.prompt (fixes #226 agent reset on first message) - Symlink skills directory into ~/.config/opencode/skills/superpowers/ - Update installation docs with comprehensive Windows support: - Command Prompt, PowerShell, and Git Bash instructions - Proper symlink vs junction handling - Reinstall safety with cleanup steps - Verification commands for each shell * Add OpenCode native skills changes to release notes Documents: - Breaking change: switch to native skill tool - Fix for agent reset bug (#226) - Fix for Windows installation (#232) --------- Co-authored-by: Vinicius da Motta <[email protected]> Co-authored-by: oribi <[email protected]>
* fix: convert shell scripts from CRLF to LF line endings Add .gitattributes to enforce LF line endings for shell scripts, preventing bash errors like "/usr/bin/bash: line 1: : command not found" when scripts are checked out on Windows with CRLF. Fixes #317 (SessionStart hook fails due to CRLF line endings) Files converted: - hooks/session-start.sh - lib/brainstorm-server/start-server.sh - lib/brainstorm-server/stop-server.sh - lib/brainstorm-server/wait-for-feedback.sh - skills/systematic-debugging/find-polluter.sh Co-Authored-By: Claude Opus 4.5 <[email protected]> * fix: update Windows hook execution for Claude Code 2.1.x Claude Code 2.1.x changed the Windows execution model: it now auto-detects .sh files in hook commands and prepends "bash " automatically. This broke the polyglot wrapper because: Before: "run-hook.cmd" session-start.sh (wrapper executes) After: bash "run-hook.cmd" session-start.sh (bash can't run .cmd) Changes: - hooks.json now calls session-start.sh directly (Claude Code handles bash) - Added deprecation comment to run-hook.cmd explaining the change - Updated RELEASE-NOTES.md Fixes #317, #313, #275, #292 Co-Authored-By: Claude Opus 4.5 <[email protected]> --------- Co-authored-by: Claude Opus 4.5 <[email protected]>
- Specs (brainstorming output) now go to docs/superpowers/specs/ - Plans (writing-plans output) now go to docs/superpowers/plans/ - User preferences for locations override these defaults - Update all skill references and test files Co-Authored-By: Claude Opus 4.5 <[email protected]>
- Make writing-plans REQUIRED after design approval - Explicitly forbid platform planning features (EnterPlanMode, etc.) - Forbid direct implementation without writing-plans skill Co-Authored-By: Claude Opus 4.5 <[email protected]>
- Subagent-driven-development is now mandatory when harness supports it - No longer offer choice between subagent-driven and executing-plans - Executing-plans reserved for harnesses without subagent capability - Update plan header to reference both execution paths Co-Authored-By: Claude Opus 4.5 <[email protected]>
Co-Authored-By: Claude Opus 4.5 <[email protected]>
Co-Authored-By: Claude Opus 4.5 <[email protected]>
Co-Authored-By: Claude Opus 4.5 <[email protected]>
Co-Authored-By: Claude Opus 4.5 <[email protected]>
Co-Authored-By: Claude Opus 4.5 <[email protected]>
- Spec: docs/superpowers/specs/2026-01-22-document-review-system-design.md - Plan: docs/superpowers/plans/2026-01-22-document-review-system.md Co-Authored-By: Claude Opus 4.5 <[email protected]>
The `- [ ] ### Task N:` syntax was unusual and might not render correctly in all markdown parsers. Now only steps have checkboxes. Co-Authored-By: Claude Opus 4.5 <[email protected]>
Tests verify: - Spec document reviewer checks (completeness, TODOs) - Plan document reviewer checks (spec alignment, task decomposition) - Review loops exist in brainstorming and writing-plans skills - Chunk-by-chunk review for plans with 1000-line limit - Iteration guidance (5 iterations, escalate to human) - Checkbox syntax on steps only (not task headings) - Correct directories (docs/superpowers/specs, docs/superpowers/plans) - Reviewers are advisory - Same agent fixes issues (preserves context) Co-Authored-By: Claude Opus 4.5 <[email protected]>
- Creates test project with spec containing intentional errors - Runs Claude to actually review using spec-document-reviewer template - Verifies reviewer catches TODO and "specified later" deferrals - Checks review format and verdict Co-Authored-By: Claude Opus 4.5 <[email protected]>
Move toggleSelect/send/selectedChoice from frame-template.html inline script to helper.js so they're auto-injected. Server now detects bare HTML fragments (no DOCTYPE/html tag) and wraps them in the frame template automatically. Full documents pass through as before. Fix dark mode in sendToClaude confirmation (was using hardcoded colors). Fix test env var bug (BRAINSTORM_SCREEN -> BRAINSTORM_DIR). Add tests for fragment wrapping, full doc passthrough, and helper.js.
start-server.sh now accepts --project-dir to store session files under .superpowers/brainstorm/ instead of /tmp. stop-server.sh only deletes ephemeral /tmp sessions, keeping persistent ones for later review. Fix test race condition with polling-based server startup wait.
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.
…ills Brainstorming: design-for-isolation guidance and brownfield codebase awareness Writing-plans: file structure section requiring decomposition before task definition Implementer prompt: code organization awareness, structured escalation protocol (DONE/DONE_WITH_CONCERNS/BLOCKED/NEEDS_CONTEXT), explicit permission to stop Subagent-driven-development: provider-agnostic model selection tiers, escalation handling
- Define DONE_WITH_CONCERNS handling in SDD controller flow - Make implementer action explicit when file grows beyond plan intent - Reword writing-plans file size reasoning (avoid tooling-artifact language) - Add decomposition awareness to code quality reviewer prompt
Focus on whether this implementation grew or created large files, not pre-existing file sizes in brownfield codebases.
Spec reviewer now checks for unit decomposition with clear boundaries. Plan reviewer now checks file structure and whether files will grow too large to reason about.
Brainstorming now assesses whether a project is too large for a single spec and helps decompose into sub-projects. Spec reviewer checks scope. Writing-plans has a backstop if brainstorming missed it.
Testing showed the model skipped scope assessment when it was a separate step after "Understanding the idea." Inlining it as the first thing in understanding ensures it fires before detailed questions.
…writing-plans EnterPlanMode's system prompt guidance fires every turn while skill content loaded early in conversation fades in context. Three fixes: - Add EnterPlanMode to using-superpowers red flags table (refreshed every turn) - Make brainstorming handoff imperative: invoke Skill tool, not EnterPlanMode - Update writing-plans description to explicitly say "not EnterPlanMode" - Reorder: plan first (while context is fresh), worktree second (for implementation)
Tests that Claude invokes writing-plans skill (not EnterPlanMode) after brainstorming. Includes --without-fix mode that strips the fix from a plugin copy to attempt failure reproduction.
8-turn brainstorming flow that tests whether Claude invokes writing-plans (correct) or EnterPlanMode (bug) after design approval. Includes --without-fix mode for failure reproduction attempts.
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 03360d1a21
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
|
|
||
| # Start server, capturing output to log file | ||
| cd "$SCRIPT_DIR" | ||
| BRAINSTORM_DIR="$SCREEN_DIR" node index.js > "$LOG_FILE" 2>&1 & |
There was a problem hiding this comment.
In a fresh checkout/plugin install there is no node_modules/ for lib/brainstorm-server, and the visual companion guide tells users to run this script directly without any npm install step. This node index.js therefore exits before the server starts because index.js requires express, chokidar, and ws; I confirmed start-server.sh --project-dir <tmp> currently times out with Error: Cannot find module 'express'. Unless the script installs/locates bundled dependencies or the plugin install path guarantees them, the new visual companion is unusable for users who have not manually installed this package.
Useful? React with 👍 / 👎.
Merge activity
|
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What problem are you trying to solve?
What does this PR change?
Is this change appropriate for the core library?
What alternatives did you consider?
Does this PR contain multiple unrelated changes?
Existing PRs
Environment tested
New harness support (required if this PR adds a new harness)
Clean-session transcript for "Let's make a react todo list"
Evaluation
the session that led to this change?
Rigor
superpowers:writing-skillsandcompleted adversarial pressure testing (paste results below)
rationalizations, "human partner" language) without extensive evals
showing the change is an improvement
Human review