docs: use OPENCODE_CONFIG_DIR in install docs

Set the variable once at the top of each shell block with a default
fallback, then use it cleanly throughout. Supports custom config
directories without repeating the alternation on every line.

Based on cavanaug's work in PR #704.

Co-Authored-By: John Cavanaugh <cavanaug@users.noreply.github.com>
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

.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.0",
+      "version": "5.0.2",
       "source": "./",
       "author": {
         "name": "Jesse Vincent",

.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.0",
+  "version": "5.0.2",
   "author": {
     "name": "Jesse Vincent",
     "email": "jesse@fsck.com"

.cursor-plugin/plugin.json

@@ -2,7 +2,7 @@
   "name": "superpowers",
   "displayName": "Superpowers",
   "description": "Core skills library: TDD, debugging, collaboration patterns, and proven techniques",
-  "version": "4.3.0",
+  "version": "5.0.2",
   "author": {
     "name": "Jesse Vincent",
     "email": "jesse@fsck.com"

.gitignore

@@ -1,6 +1,7 @@
 .worktrees/
 .private-journal/
 .claude/
+.DS_Store
 node_modules/
 inspo
 triage/

.opencode/INSTALL.md

@@ -7,10 +7,13 @@
 
 ## Installation Steps
 
+> **Custom config directory:** If you've set `OPENCODE_CONFIG_DIR`, the commands below will use it automatically. Otherwise they default to `~/.config/opencode`.
+
 ### 1. Clone Superpowers
 
 ```bash
-git clone https://github.com/obra/superpowers.git ~/.config/opencode/superpowers
+OPENCODE_CONFIG_DIR="${OPENCODE_CONFIG_DIR:-$HOME/.config/opencode}"
+git clone https://github.com/obra/superpowers.git "$OPENCODE_CONFIG_DIR/superpowers"
 ```
 
 ### 2. Register the Plugin
@@ -18,9 +21,10 @@ git clone https://github.com/obra/superpowers.git ~/.config/opencode/superpowers
 Create a symlink so OpenCode discovers the plugin:
 
 ```bash
-mkdir -p ~/.config/opencode/plugins
-rm -f ~/.config/opencode/plugins/superpowers.js
-ln -s ~/.config/opencode/superpowers/.opencode/plugins/superpowers.js ~/.config/opencode/plugins/superpowers.js
+OPENCODE_CONFIG_DIR="${OPENCODE_CONFIG_DIR:-$HOME/.config/opencode}"
+mkdir -p "$OPENCODE_CONFIG_DIR/plugins"
+rm -f "$OPENCODE_CONFIG_DIR/plugins/superpowers.js"
+ln -s "$OPENCODE_CONFIG_DIR/superpowers/.opencode/plugins/superpowers.js" "$OPENCODE_CONFIG_DIR/plugins/superpowers.js"
 ```
 
 ### 3. Symlink Skills
@@ -28,9 +32,10 @@ ln -s ~/.config/opencode/superpowers/.opencode/plugins/superpowers.js ~/.config/
 Create a symlink so OpenCode's native skill tool discovers superpowers skills:
 
 ```bash
-mkdir -p ~/.config/opencode/skills
-rm -rf ~/.config/opencode/skills/superpowers
-ln -s ~/.config/opencode/superpowers/skills ~/.config/opencode/skills/superpowers
+OPENCODE_CONFIG_DIR="${OPENCODE_CONFIG_DIR:-$HOME/.config/opencode}"
+mkdir -p "$OPENCODE_CONFIG_DIR/skills"
+rm -rf "$OPENCODE_CONFIG_DIR/skills/superpowers"
+ln -s "$OPENCODE_CONFIG_DIR/superpowers/skills" "$OPENCODE_CONFIG_DIR/skills/superpowers"
 ```
 
 ### 4. Restart OpenCode
@@ -59,13 +64,14 @@ use skill tool to load superpowers/brainstorming
 
 ### Personal Skills
 
-Create your own skills in `~/.config/opencode/skills/`:
+Create your own skills in your OpenCode skills directory:
 
 ```bash
-mkdir -p ~/.config/opencode/skills/my-skill
+OPENCODE_CONFIG_DIR="${OPENCODE_CONFIG_DIR:-$HOME/.config/opencode}"
+mkdir -p "$OPENCODE_CONFIG_DIR/skills/my-skill"
 ```
 
-Create `~/.config/opencode/skills/my-skill/SKILL.md`:
+Create a `SKILL.md` in that directory:
 
 ```markdown
 ---
@@ -87,7 +93,8 @@ Create project-specific skills in `.opencode/skills/` within your project.
 ## Updating
 
 ```bash
-cd ~/.config/opencode/superpowers
+OPENCODE_CONFIG_DIR="${OPENCODE_CONFIG_DIR:-$HOME/.config/opencode}"
+cd "$OPENCODE_CONFIG_DIR/superpowers"
 git pull
 ```
 
@@ -95,20 +102,25 @@ git pull
 
 ### Plugin not loading
 
-1. Check plugin symlink: `ls -l ~/.config/opencode/plugins/superpowers.js`
-2. Check source exists: `ls ~/.config/opencode/superpowers/.opencode/plugins/superpowers.js`
-3. Check OpenCode logs for errors
+```bash
+OPENCODE_CONFIG_DIR="${OPENCODE_CONFIG_DIR:-$HOME/.config/opencode}"
+ls -l "$OPENCODE_CONFIG_DIR/plugins/superpowers.js"
+ls "$OPENCODE_CONFIG_DIR/superpowers/.opencode/plugins/superpowers.js"
+```
 
 ### Skills not found
 
-1. Check skills symlink: `ls -l ~/.config/opencode/skills/superpowers`
-2. Verify it points to: `~/.config/opencode/superpowers/skills`
-3. Use `skill` tool to list what's discovered
+```bash
+OPENCODE_CONFIG_DIR="${OPENCODE_CONFIG_DIR:-$HOME/.config/opencode}"
+ls -l "$OPENCODE_CONFIG_DIR/skills/superpowers"
+```
+
+Verify the symlink points to `$OPENCODE_CONFIG_DIR/superpowers/skills`. Use `skill` tool to list what's discovered.
 
 ### Tool mapping
 
 When skills reference Claude Code tools:
-- `TodoWrite` → `update_plan`
+- `TodoWrite` → `todowrite`
 - `Task` with subagents → `@mention` syntax
 - `Skill` tool → OpenCode's native `skill` tool
 - File operations → your native tools

.opencode/plugins/superpowers.js

@@ -63,7 +63,7 @@ export const SuperpowersPlugin = async ({ client, directory }) => {
 
     const toolMapping = `**Tool Mapping for OpenCode:**
 When skills reference tools you don't have, substitute OpenCode equivalents:
-- \`TodoWrite\` → \`update_plan\`
+- \`TodoWrite\` → \`todowrite\`
 - \`Task\` tool with subagents → Use OpenCode's subagent system (@mention)
 - \`Skill\` tool → OpenCode's native \`skill\` tool
 - \`Read\`, \`Write\`, \`Edit\`, \`Bash\` → Your native tools

GEMINI.md

@@ -0,0 +1,2 @@
+@./skills/using-superpowers/SKILL.md
+@./skills/using-superpowers/references/gemini-tools.md

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)
 
@@ -48,9 +57,11 @@ Then install the plugin from this marketplace:
 In Cursor Agent chat, install from marketplace:
 
 ```text
-/plugin-add superpowers
+/add-plugin superpowers
 ```
 
+or search for "superpowers" in the plugin marketplace.
+
 ### Codex
 
 Tell Codex:
@@ -71,6 +82,18 @@ Fetch and follow instructions from https://raw.githubusercontent.com/obra/superp
 
 **Detailed docs:** [docs/README.opencode.md](docs/README.opencode.md)
 
+### Gemini CLI
+
+```bash
+gemini extensions install https://github.com/obra/superpowers
+```
+
+To update:
+
+```bash
+gemini extensions update superpowers
+```
+
 ### Verify Installation
 
 Start a new session in your chosen platform and ask for something that should trigger a skill (for example, "help me plan this feature" or "let's debug this issue"). The agent should automatically invoke the relevant superpowers skill.

RELEASE-NOTES.md

@@ -1,93 +1,239 @@
 # Superpowers Release Notes
 
-## Unreleased
+## v5.0.3 (2026-03-15)
+
+### Bug Fixes
+
+- **Stop firing SessionStart hook on `--resume`** — the startup hook was re-injecting context on resumed sessions, which already have the context in their conversation history. The hook now fires only on `startup`, `clear`, and `compact`.
+
+## v5.0.2 (2026-03-11)
+
+### Zero-Dependency Brainstorm Server
+
+**Removed all vendored node_modules — server.js is now fully self-contained**
+
+- Replaced Express/Chokidar/WebSocket dependencies with zero-dependency Node.js server using built-in `http`, `fs`, and `crypto` modules
+- Removed ~1,200 lines of vendored `node_modules/`, `package.json`, and `package-lock.json`
+- Custom WebSocket protocol implementation (RFC 6455 framing, ping/pong, proper close handshake)
+- Native `fs.watch()` file watching replaces Chokidar
+- Full test suite: HTTP serving, WebSocket protocol, file watching, and integration tests
+
+### Brainstorm Server Reliability
+
+- **Auto-exit after 30 minutes idle** — server shuts down when no clients are connected, preventing orphaned processes
+- **Owner process tracking** — server monitors the parent harness PID and exits when the owning session dies
+- **Liveness check** — skill verifies server is responsive before reusing an existing instance
+- **Encoding fix** — proper `<meta charset="utf-8">` on served HTML pages
+
+### Subagent Context Isolation
+
+- All delegation skills (brainstorming, dispatching-parallel-agents, requesting-code-review, subagent-driven-development, writing-plans) now include context isolation principle
+- Subagents receive only the context they need, preventing context window pollution
+
+## v5.0.1 (2026-03-10)
+
+### Agentskills Compliance
+
+**Brainstorm-server moved into skill directory**
+
+- Moved `lib/brainstorm-server/` → `skills/brainstorming/scripts/` per the [agentskills.io](https://agentskills.io) specification
+- All `${CLAUDE_PLUGIN_ROOT}/lib/brainstorm-server/` references replaced with relative `scripts/` paths
+- Skills are now fully portable across platforms — no platform-specific env vars needed to locate scripts
+- `lib/` directory removed (was the last remaining content)
+
+### New Features
+
+**Gemini CLI extension**
+
+- Native Gemini CLI extension support via `gemini-extension.json` and `GEMINI.md` at repo root
+- `GEMINI.md` @imports `using-superpowers` skill and tool mapping table at session start
+- Gemini CLI tool mapping reference (`skills/using-superpowers/references/gemini-tools.md`) — translates Claude Code tool names (Read, Write, Edit, Bash, etc.) to Gemini CLI equivalents (read_file, write_file, replace, etc.)
+- Documents Gemini CLI limitations: no subagent support, skills fall back to `executing-plans`
+- Extension root at repo root for cross-platform compatibility (avoids Windows symlink issues)
+- Install instructions added to README
+
+### Improvements
+
+**Multi-platform brainstorm server launch**
+
+- Per-platform launch instructions in visual-companion.md: Claude Code (default mode), Codex (auto-foreground via `CODEX_CI`), Gemini CLI (`--foreground` with `is_background`), and fallback for other environments
+- Server now writes startup JSON to `$SCREEN_DIR/.server-info` so agents can find the URL and port even when stdout is hidden by background execution
+
+**Brainstorm server dependencies bundled**
+
+- `node_modules` vendored into the repo so the brainstorm server works immediately on fresh plugin installs without requiring `npm` at runtime
+- Removed `fsevents` from bundled deps (macOS-only native binary; chokidar falls back gracefully without it)
+- Fallback auto-install via `npm install` if `node_modules` is missing
+
+**OpenCode tool mapping fix**
+
+- `TodoWrite` → `todowrite` (was incorrectly mapped to `update_plan`); verified against OpenCode source
+
+### Bug Fixes
+
+**Windows/Linux: single quotes break SessionStart hook** (#577, #529, #644, PR #585)
+
+- Single quotes around `${CLAUDE_PLUGIN_ROOT}` in hooks.json fail on Windows (cmd.exe doesn't recognize single quotes as path delimiters) and on Linux (single quotes prevent variable expansion)
+- Fix: replaced single quotes with escaped double quotes — works across macOS bash, Windows cmd.exe, Windows Git Bash, and Linux, with and without spaces in paths
+- Verified on Windows 11 (NT 10.0.26200.0) with Claude Code 2.1.72 and Git for Windows
+
+**Brainstorming spec review loop skipped** (#677)
+
+- The spec review loop (dispatch spec-document-reviewer subagent, iterate until approved) existed in the prose "After the Design" section but was missing from the checklist and process flow diagram
+- Since agents follow the diagram and checklist more reliably than prose, the spec review step was being skipped entirely
+- Added step 7 (spec review loop) to the checklist and corresponding nodes to the dot graph
+- Tested with `claude --plugin-dir` and `claude-session-driver`: worker now correctly dispatches the reviewer
+
+**Cursor install command** (PR #676)
+
+- Fixed Cursor install command in README: `/plugin-add` → `/add-plugin` (confirmed via Cursor 2.5 release announcement)
+
+**User review gate in brainstorming** (#565)
+
+- Added explicit user review step between spec completion and writing-plans handoff
+- User must approve the spec before implementation planning begins
+- Checklist, process flow, and prose updated with the new gate
+
+**Session-start hook emits context only once per platform**
+
+- Hook now detects whether it's running in Claude Code or another platform
+- Emits `hookSpecificOutput` for Claude Code, `additional_context` for others — prevents double context injection
+
+**Linting fix in token analysis script**
+
+- `except:` → `except Exception:` in `tests/claude-code/analyze-token-usage.py`
+
+### Maintenance
+
+**Removed dead code**
+
+- Deleted `lib/skills-core.js` and its test (`tests/opencode/test-skills-core.js`) — unused since February 2026
+- Removed skills-core existence check from `tests/opencode/test-plugin-loading.sh`
+
+### Community
+
+- @karuturi — Claude Code official marketplace install instructions (PR #610)
+- @mvanhorn — session-start hook dual-emit fix, OpenCode tool mapping fix
+- @daniel-graham — linting fix for bare except
+- PR #585 author — Windows/Linux hooks quoting fix
+
+---
+
+## v5.0.0 (2026-03-09)
 
 ### Breaking Changes
 
 **Specs and plans directory restructured**
 
-- Specs (brainstorming output) now go to `docs/superpowers/specs/YYYY-MM-DD-<topic>-design.md`
-- Plans (writing-plans output) now go to `docs/superpowers/plans/YYYY-MM-DD-<feature-name>.md`
+- Specs (brainstorming output) now save to `docs/superpowers/specs/YYYY-MM-DD-<topic>-design.md`
+- Plans (writing-plans output) now save to `docs/superpowers/plans/YYYY-MM-DD-<feature-name>.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
 
-**Brainstorming → writing-plans transition enforced**
+**Subagent-driven development mandatory on capable harnesses**
 
-- After design approval, brainstorming now requires using writing-plans skill
-- Platform planning features (e.g., EnterPlanMode) should not be used
-- Direct implementation without writing-plans is not allowed
+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.
 
-**Subagent-driven development now mandatory on capable harnesses**
+**Executing-plans no longer batches**
 
-- On harnesses with subagent support (Claude Code), subagent-driven-development is now required after plan approval
-- No longer offers a choice between subagent-driven and executing-plans
-- Executing-plans is only used on harnesses without subagent capability
+Removed the "execute 3 tasks then stop for review" pattern. Plans now execute continuously, stopping only for blockers.
 
-**OpenCode: Switched to native skills system**
+**Slash commands deprecated**
 
-Superpowers for OpenCode now uses OpenCode's native `skill` tool instead of custom `use_skill`/`find_skills` tools. This is a cleaner integration that works with OpenCode's built-in skill discovery.
-
-**Migration required:** Skills must be symlinked to `~/.config/opencode/skills/superpowers/` (see updated installation docs).
-
-### Fixes
-
-**OpenCode: Fixed agent reset on session start (#226)**
-
-The previous bootstrap injection method using `session.prompt({ noReply: true })` caused OpenCode to reset the selected agent to "build" on first message. Now uses `experimental.chat.system.transform` hook which modifies the system prompt directly without side effects.
-
-**OpenCode: Fixed Windows installation (#232)**
-
-- Removed dependency on `skills-core.js` (eliminates broken relative imports when file is copied instead of symlinked)
-- Added comprehensive Windows installation docs for cmd.exe, PowerShell, and Git Bash
-- Documented proper symlink vs junction usage for each platform
+`/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 companion for brainstorming skill**
+**Visual brainstorming companion**
 
-Added optional browser-based visual companion for brainstorming sessions. When users have a browser available, brainstorming can display interactive screens showing current phase, questions, and design decisions in a more readable format than terminal output.
+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.
 
-Components:
-- `lib/brainstorm-server/` - WebSocket server for real-time updates
-- `skills/brainstorming/visual-companion.md` - Integration guide
-- Helper scripts for session management with proper isolation
-- Browser helper library for event capture
+- `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/`
 
-The visual companion is opt-in and falls back gracefully to terminal-only operation.
+**Document review system**
 
-### Bug Fixes
+Automated review loops for spec and plan documents using subagent dispatch:
 
-**Fixed Windows hook execution for Claude Code 2.1.x**
+- `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/`
 
-Claude Code 2.1.x changed how hooks execute on Windows: it now auto-detects `.sh` files in commands and prepends `bash `. This broke the polyglot wrapper pattern because `bash "run-hook.cmd" session-start.sh` tries to execute the .cmd file as a bash script.
+**Architecture guidance across the skill pipeline**
 
-Fix: hooks.json now calls session-start.sh directly. Claude Code 2.1.x handles the bash invocation automatically. Also added .gitattributes to enforce LF line endings for shell scripts (fixes CRLF issues on Windows checkout).
+Design-for-isolation and file-size-awareness guidance added to brainstorming, writing-plans, and subagent-driven-development:
 
-**Brainstorming visual companion: reduced token cost and improved persistence**
+- **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
 
-The visual companion now generates much smaller HTML per screen. The server automatically wraps bare content fragments in the frame template (header, CSS theme, feedback footer, interactive JS), so Claude writes only the content portion (~30 lines instead of ~260). Full HTML documents are still served as-is when Claude needs complete control.
+**Subagent-driven development improvements**
 
-Other improvements:
-- `toggleSelect`/`send`/`selectedChoice` moved from inline template script to `helper.js` (auto-injected)
-- `start-server.sh --project-dir` persists mockups under `.superpowers/brainstorm/` instead of `/tmp`
-- `stop-server.sh` only deletes ephemeral `/tmp` sessions, preserving persistent ones
-- Dark mode fix: `sendToClaude` confirmation page now uses CSS variables instead of hardcoded colors
-- Skill restructured: SKILL.md is minimal (prompt + pointer); all visual companion details in progressive disclosure doc (`visual-companion.md`)
-- Prompt to user now notes the feature is new, token-intensive, and can be slow
-- Deleted redundant `CLAUDE-INSTRUCTIONS.md` (content folded into `visual-companion.md`)
-- Test fixes: correct env var (`BRAINSTORM_DIR`), polling-based startup wait, new tests for frame wrapping
+- **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 clarified in using-superpowers**
+**Instruction priority hierarchy**
 
-Added explicit instruction priority hierarchy to prevent conflicts with user preferences:
+Added explicit priority ordering to using-superpowers:
 
-1. User's explicit instructions (CLAUDE.md, direct requests) — highest priority
-2. Superpowers skills — override default system behavior where they conflict
+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
 
-This ensures users remain in control. If CLAUDE.md says "don't use TDD" and a skill says "always use TDD," CLAUDE.md wins.
+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 `<SUBAGENT-STOP>` 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
+
+**Cursor support**
+
+Superpowers now works with Cursor's plugin system. Includes a `.cursor-plugin/plugin.json` manifest and Cursor-specific installation instructions in the README. The SessionStart hook output now includes an `additional_context` field alongside the existing `hookSpecificOutput.additionalContext` for Cursor hook compatibility.
+
+### Fixed
+
+**Windows: Restored polyglot wrapper for reliable hook execution (#518, #504, #491, #487, #466, #440)**
+
+Claude Code's `.sh` auto-detection on Windows was prepending `bash` to the hook command, breaking execution. The fix:
+
+- Renamed `session-start.sh` to `session-start` (extensionless) so auto-detection doesn't interfere
+- Restored `run-hook.cmd` polyglot wrapper with multi-location bash discovery (standard Git for Windows paths, then PATH fallback)
+- Exits silently if no bash is found rather than erroring
+- On Unix, the wrapper runs the script directly via `exec bash`
+- Uses POSIX-safe `dirname "$0"` path resolution (works on dash/sh, not just bash)
+
+This fixes SessionStart failures on Windows with spaces in paths, missing WSL, `set -euo pipefail` fragility on MSYS, and backslash mangling.
 
 ## v4.3.0 (2026-02-12)
 

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.

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.

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.

docs/README.opencode.md

@@ -7,7 +7,7 @@ Complete guide for using Superpowers with [OpenCode.ai](https://opencode.ai).
 Tell OpenCode:
 
 ```
-Clone https://github.com/obra/superpowers to ~/.config/opencode/superpowers, then create directory ~/.config/opencode/plugins, then symlink ~/.config/opencode/superpowers/.opencode/plugins/superpowers.js to ~/.config/opencode/plugins/superpowers.js, then symlink ~/.config/opencode/superpowers/skills to ~/.config/opencode/skills/superpowers, then restart opencode.
+Clone https://github.com/obra/superpowers to my OpenCode config directory under superpowers/, then create a plugins/ directory there, then symlink superpowers/.opencode/plugins/superpowers.js to plugins/superpowers.js, then symlink superpowers/skills to skills/superpowers, then restart opencode.
 ```
 
 ## Manual Installation
@@ -17,26 +17,30 @@ Clone https://github.com/obra/superpowers to ~/.config/opencode/superpowers, the
 - [OpenCode.ai](https://opencode.ai) installed
 - Git installed
 
+> **Custom config directory:** If you've set `OPENCODE_CONFIG_DIR`, the commands below will use it automatically. Otherwise they default to `~/.config/opencode` (macOS/Linux) or `%USERPROFILE%\.config\opencode` (Windows).
+
 ### macOS / Linux
 
 ```bash
+OPENCODE_CONFIG_DIR="${OPENCODE_CONFIG_DIR:-$HOME/.config/opencode}"
+
 # 1. Install Superpowers (or update existing)
-if [ -d ~/.config/opencode/superpowers ]; then
-  cd ~/.config/opencode/superpowers && git pull
+if [ -d "$OPENCODE_CONFIG_DIR/superpowers" ]; then
+  cd "$OPENCODE_CONFIG_DIR/superpowers" && git pull
 else
-  git clone https://github.com/obra/superpowers.git ~/.config/opencode/superpowers
+  git clone https://github.com/obra/superpowers.git "$OPENCODE_CONFIG_DIR/superpowers"
 fi
 
 # 2. Create directories
-mkdir -p ~/.config/opencode/plugins ~/.config/opencode/skills
+mkdir -p "$OPENCODE_CONFIG_DIR/plugins" "$OPENCODE_CONFIG_DIR/skills"
 
 # 3. Remove old symlinks/directories if they exist
-rm -f ~/.config/opencode/plugins/superpowers.js
-rm -rf ~/.config/opencode/skills/superpowers
+rm -f "$OPENCODE_CONFIG_DIR/plugins/superpowers.js"
+rm -rf "$OPENCODE_CONFIG_DIR/skills/superpowers"
 
 # 4. Create symlinks
-ln -s ~/.config/opencode/superpowers/.opencode/plugins/superpowers.js ~/.config/opencode/plugins/superpowers.js
-ln -s ~/.config/opencode/superpowers/skills ~/.config/opencode/skills/superpowers
+ln -s "$OPENCODE_CONFIG_DIR/superpowers/.opencode/plugins/superpowers.js" "$OPENCODE_CONFIG_DIR/plugins/superpowers.js"
+ln -s "$OPENCODE_CONFIG_DIR/superpowers/skills" "$OPENCODE_CONFIG_DIR/skills/superpowers"
 
 # 5. Restart OpenCode
 ```
@@ -44,8 +48,9 @@ ln -s ~/.config/opencode/superpowers/skills ~/.config/opencode/skills/superpower
 #### Verify Installation
 
 ```bash
-ls -l ~/.config/opencode/plugins/superpowers.js
-ls -l ~/.config/opencode/skills/superpowers
+OPENCODE_CONFIG_DIR="${OPENCODE_CONFIG_DIR:-$HOME/.config/opencode}"
+ls -l "$OPENCODE_CONFIG_DIR/plugins/superpowers.js"
+ls -l "$OPENCODE_CONFIG_DIR/skills/superpowers"
 ```
 
 Both should show symlinks pointing to the superpowers directory.
@@ -65,22 +70,24 @@ Pick your shell below: [Command Prompt](#command-prompt) | [PowerShell](#powersh
 Run as Administrator, or with Developer Mode enabled:
 
 ```cmd
+if not defined OPENCODE_CONFIG_DIR set OPENCODE_CONFIG_DIR=%USERPROFILE%\.config\opencode
+
 :: 1. Install Superpowers
-git clone https://github.com/obra/superpowers.git "%USERPROFILE%\.config\opencode\superpowers"
+git clone https://github.com/obra/superpowers.git "%OPENCODE_CONFIG_DIR%\superpowers"
 
 :: 2. Create directories
-mkdir "%USERPROFILE%\.config\opencode\plugins" 2>nul
-mkdir "%USERPROFILE%\.config\opencode\skills" 2>nul
+mkdir "%OPENCODE_CONFIG_DIR%\plugins" 2>nul
+mkdir "%OPENCODE_CONFIG_DIR%\skills" 2>nul
 
 :: 3. Remove existing links (safe for reinstalls)
-del "%USERPROFILE%\.config\opencode\plugins\superpowers.js" 2>nul
-rmdir "%USERPROFILE%\.config\opencode\skills\superpowers" 2>nul
+del "%OPENCODE_CONFIG_DIR%\plugins\superpowers.js" 2>nul
+rmdir "%OPENCODE_CONFIG_DIR%\skills\superpowers" 2>nul
 
 :: 4. Create plugin symlink (requires Developer Mode or Admin)
-mklink "%USERPROFILE%\.config\opencode\plugins\superpowers.js" "%USERPROFILE%\.config\opencode\superpowers\.opencode\plugins\superpowers.js"
+mklink "%OPENCODE_CONFIG_DIR%\plugins\superpowers.js" "%OPENCODE_CONFIG_DIR%\superpowers\.opencode\plugins\superpowers.js"
 
 :: 5. Create skills junction (works without special privileges)
-mklink /J "%USERPROFILE%\.config\opencode\skills\superpowers" "%USERPROFILE%\.config\opencode\superpowers\skills"
+mklink /J "%OPENCODE_CONFIG_DIR%\skills\superpowers" "%OPENCODE_CONFIG_DIR%\superpowers\skills"
 
 :: 6. Restart OpenCode
 ```
@@ -90,22 +97,24 @@ mklink /J "%USERPROFILE%\.config\opencode\skills\superpowers" "%USERPROFILE%\.co
 Run as Administrator, or with Developer Mode enabled:
 
 ```powershell
+if (-not $env:OPENCODE_CONFIG_DIR) { $env:OPENCODE_CONFIG_DIR = "$env:USERPROFILE\.config\opencode" }
+
 # 1. Install Superpowers
-git clone https://github.com/obra/superpowers.git "$env:USERPROFILE\.config\opencode\superpowers"
+git clone https://github.com/obra/superpowers.git "$env:OPENCODE_CONFIG_DIR\superpowers"
 
 # 2. Create directories
-New-Item -ItemType Directory -Force -Path "$env:USERPROFILE\.config\opencode\plugins"
-New-Item -ItemType Directory -Force -Path "$env:USERPROFILE\.config\opencode\skills"
+New-Item -ItemType Directory -Force -Path "$env:OPENCODE_CONFIG_DIR\plugins"
+New-Item -ItemType Directory -Force -Path "$env:OPENCODE_CONFIG_DIR\skills"
 
 # 3. Remove existing links (safe for reinstalls)
-Remove-Item "$env:USERPROFILE\.config\opencode\plugins\superpowers.js" -Force -ErrorAction SilentlyContinue
-Remove-Item "$env:USERPROFILE\.config\opencode\skills\superpowers" -Force -ErrorAction SilentlyContinue
+Remove-Item "$env:OPENCODE_CONFIG_DIR\plugins\superpowers.js" -Force -ErrorAction SilentlyContinue
+Remove-Item "$env:OPENCODE_CONFIG_DIR\skills\superpowers" -Force -ErrorAction SilentlyContinue
 
 # 4. Create plugin symlink (requires Developer Mode or Admin)
-New-Item -ItemType SymbolicLink -Path "$env:USERPROFILE\.config\opencode\plugins\superpowers.js" -Target "$env:USERPROFILE\.config\opencode\superpowers\.opencode\plugins\superpowers.js"
+New-Item -ItemType SymbolicLink -Path "$env:OPENCODE_CONFIG_DIR\plugins\superpowers.js" -Target "$env:OPENCODE_CONFIG_DIR\superpowers\.opencode\plugins\superpowers.js"
 
 # 5. Create skills junction (works without special privileges)
-New-Item -ItemType Junction -Path "$env:USERPROFILE\.config\opencode\skills\superpowers" -Target "$env:USERPROFILE\.config\opencode\superpowers\skills"
+New-Item -ItemType Junction -Path "$env:OPENCODE_CONFIG_DIR\skills\superpowers" -Target "$env:OPENCODE_CONFIG_DIR\superpowers\skills"
 
 # 6. Restart OpenCode
 ```
@@ -115,21 +124,23 @@ New-Item -ItemType Junction -Path "$env:USERPROFILE\.config\opencode\skills\supe
 Note: Git Bash's native `ln` command copies files instead of creating symlinks. Use `cmd //c mklink` instead (the `//c` is Git Bash syntax for `/c`).
 
 ```bash
+OPENCODE_CONFIG_DIR="${OPENCODE_CONFIG_DIR:-$HOME/.config/opencode}"
+
 # 1. Install Superpowers
-git clone https://github.com/obra/superpowers.git ~/.config/opencode/superpowers
+git clone https://github.com/obra/superpowers.git "$OPENCODE_CONFIG_DIR/superpowers"
 
 # 2. Create directories
-mkdir -p ~/.config/opencode/plugins ~/.config/opencode/skills
+mkdir -p "$OPENCODE_CONFIG_DIR/plugins" "$OPENCODE_CONFIG_DIR/skills"
 
 # 3. Remove existing links (safe for reinstalls)
-rm -f ~/.config/opencode/plugins/superpowers.js 2>/dev/null
-rm -rf ~/.config/opencode/skills/superpowers 2>/dev/null
+rm -f "$OPENCODE_CONFIG_DIR/plugins/superpowers.js" 2>/dev/null
+rm -rf "$OPENCODE_CONFIG_DIR/skills/superpowers" 2>/dev/null
 
 # 4. Create plugin symlink (requires Developer Mode or Admin)
-cmd //c "mklink \"$(cygpath -w ~/.config/opencode/plugins/superpowers.js)\" \"$(cygpath -w ~/.config/opencode/superpowers/.opencode/plugins/superpowers.js)\""
+cmd //c "mklink \"$(cygpath -w "$OPENCODE_CONFIG_DIR/plugins/superpowers.js")\" \"$(cygpath -w "$OPENCODE_CONFIG_DIR/superpowers/.opencode/plugins/superpowers.js")\""
 
 # 5. Create skills junction (works without special privileges)
-cmd //c "mklink /J \"$(cygpath -w ~/.config/opencode/skills/superpowers)\" \"$(cygpath -w ~/.config/opencode/superpowers/skills)\""
+cmd //c "mklink /J \"$(cygpath -w "$OPENCODE_CONFIG_DIR/skills/superpowers")\" \"$(cygpath -w "$OPENCODE_CONFIG_DIR/superpowers/skills")\""
 
 # 6. Restart OpenCode
 ```
@@ -142,14 +153,16 @@ If running OpenCode inside WSL, use the [macOS / Linux](#macos--linux) instructi
 
 **Command Prompt:**
 ```cmd
-dir /AL "%USERPROFILE%\.config\opencode\plugins"
-dir /AL "%USERPROFILE%\.config\opencode\skills"
+if not defined OPENCODE_CONFIG_DIR set OPENCODE_CONFIG_DIR=%USERPROFILE%\.config\opencode
+dir /AL "%OPENCODE_CONFIG_DIR%\plugins"
+dir /AL "%OPENCODE_CONFIG_DIR%\skills"
 ```
 
 **PowerShell:**
 ```powershell
-Get-ChildItem "$env:USERPROFILE\.config\opencode\plugins" | Where-Object { $_.LinkType }
-Get-ChildItem "$env:USERPROFILE\.config\opencode\skills" | Where-Object { $_.LinkType }
+if (-not $env:OPENCODE_CONFIG_DIR) { $env:OPENCODE_CONFIG_DIR = "$env:USERPROFILE\.config\opencode" }
+Get-ChildItem "$env:OPENCODE_CONFIG_DIR\plugins" | Where-Object { $_.LinkType }
+Get-ChildItem "$env:OPENCODE_CONFIG_DIR\skills" | Where-Object { $_.LinkType }
 ```
 
 Look for `<SYMLINK>` or `<JUNCTION>` in the output.
@@ -186,13 +199,14 @@ use skill tool to load superpowers/brainstorming
 
 ### Personal Skills
 
-Create your own skills in `~/.config/opencode/skills/`:
+Create your own skills in your OpenCode skills directory:
 
 ```bash
-mkdir -p ~/.config/opencode/skills/my-skill
+OPENCODE_CONFIG_DIR="${OPENCODE_CONFIG_DIR:-$HOME/.config/opencode}"
+mkdir -p "$OPENCODE_CONFIG_DIR/skills/my-skill"
 ```
 
-Create `~/.config/opencode/skills/my-skill/SKILL.md`:
+Create a `SKILL.md` in that directory:
 
 ```markdown
 ---
@@ -243,13 +257,13 @@ The plugin automatically injects superpowers context via the `experimental.chat.
 
 ### Native Skills Integration
 
-Superpowers uses OpenCode's native `skill` tool for skill discovery and loading. Skills are symlinked into `~/.config/opencode/skills/superpowers/` so they appear alongside your personal and project skills.
+Superpowers uses OpenCode's native `skill` tool for skill discovery and loading. Skills are symlinked into the skills directory so they appear alongside your personal and project skills.
 
 ### Tool Mapping
 
 Skills written for Claude Code are automatically adapted for OpenCode. The bootstrap provides mapping instructions:
 
-- `TodoWrite` → `update_plan`
+- `TodoWrite` → `todowrite`
 - `Task` with subagents → OpenCode's `@mention` system
 - `Skill` tool → OpenCode's native `skill` tool
 - File operations → Native OpenCode tools
@@ -258,7 +272,7 @@ Skills written for Claude Code are automatically adapted for OpenCode. The boots
 
 ### Plugin Structure
 
-**Location:** `~/.config/opencode/superpowers/.opencode/plugins/superpowers.js`
+**Location:** `$OPENCODE_CONFIG_DIR/superpowers/.opencode/plugins/superpowers.js`
 
 **Components:**
 - `experimental.chat.system.transform` hook for bootstrap injection
@@ -266,14 +280,15 @@ Skills written for Claude Code are automatically adapted for OpenCode. The boots
 
 ### Skills
 
-**Location:** `~/.config/opencode/skills/superpowers/` (symlink to `~/.config/opencode/superpowers/skills/`)
+**Location:** `$OPENCODE_CONFIG_DIR/skills/superpowers/` (symlink to `$OPENCODE_CONFIG_DIR/superpowers/skills/`)
 
 Skills are discovered by OpenCode's native skill system. Each skill has a `SKILL.md` file with YAML frontmatter.
 
 ## Updating
 
 ```bash
-cd ~/.config/opencode/superpowers
+OPENCODE_CONFIG_DIR="${OPENCODE_CONFIG_DIR:-$HOME/.config/opencode}"
+cd "$OPENCODE_CONFIG_DIR/superpowers"
 git pull
 ```
 
@@ -283,14 +298,14 @@ Restart OpenCode to load the updates.
 
 ### Plugin not loading
 
-1. Check plugin exists: `ls ~/.config/opencode/superpowers/.opencode/plugins/superpowers.js`
-2. Check symlink/junction: `ls -l ~/.config/opencode/plugins/` (macOS/Linux) or `dir /AL %USERPROFILE%\.config\opencode\plugins` (Windows)
+1. Check plugin exists: `ls $OPENCODE_CONFIG_DIR/superpowers/.opencode/plugins/superpowers.js`
+2. Check symlink/junction: `ls -l $OPENCODE_CONFIG_DIR/plugins/` (macOS/Linux) or `dir /AL "%OPENCODE_CONFIG_DIR%\plugins"` (Windows)
 3. Check OpenCode logs: `opencode run "test" --print-logs --log-level DEBUG`
 4. Look for plugin loading message in logs
 
 ### Skills not found
 
-1. Verify skills symlink: `ls -l ~/.config/opencode/skills/superpowers` (should point to superpowers/skills/)
+1. Verify skills symlink: `ls -l $OPENCODE_CONFIG_DIR/skills/superpowers` (should point to superpowers/skills/)
 2. Use OpenCode's `skill` tool to list available skills
 3. Check skill structure: each skill needs a `SKILL.md` file with valid frontmatter
 
@@ -302,7 +317,7 @@ If you see `Cannot find module` errors on Windows:
 
 ### Bootstrap not appearing
 
-1. Verify using-superpowers skill exists: `ls ~/.config/opencode/superpowers/skills/using-superpowers/SKILL.md`
+1. Verify using-superpowers skill exists: `ls $OPENCODE_CONFIG_DIR/superpowers/skills/using-superpowers/SKILL.md`
 2. Check OpenCode version supports `experimental.chat.system.transform` hook
 3. Restart OpenCode after plugin changes
 

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.
 

docs/plans/2026-01-17-visual-brainstorming.md

@@ -1,6 +1,6 @@
 # Visual Brainstorming Companion 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:** Give Claude a browser-based visual companion for brainstorming sessions - show mockups, prototypes, and interactive choices alongside terminal conversation.
 

docs/superpowers/plans/2026-01-22-document-review-system.md

@@ -1,6 +1,6 @@
 # Document Review System Implementation Plan
 
-> **For Claude:** REQUIRED: Use superpowers:subagent-driven-development (if subagents available) or superpowers:executing-plans to implement this 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.
 
@@ -285,12 +285,12 @@ Run: `grep -A 20 "Plan Document Header" skills/writing-plans/SKILL.md`
 The plan header should note that tasks and steps use checkbox syntax. Update the header comment:
 
 ```markdown
-> **For Claude:** 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.
+> **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 Claude:" skills/writing-plans/SKILL.md`
+Run: `grep -A 5 "For agentic workers:" skills/writing-plans/SKILL.md`
 Expected: Shows updated header with checkbox syntax mention
 
 - [ ] **Step 4:** Commit

docs/superpowers/plans/2026-02-19-visual-brainstorming-refactor.md

@@ -1,6 +1,6 @@
 # Visual Brainstorming Refactor Implementation Plan
 
-> **For Claude:** REQUIRED: Use superpowers:subagent-driven-development (if subagents available) or superpowers:executing-plans to implement this plan. Steps use checkbox (`- [ ]`) syntax for tracking.
+> **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.
 

docs/superpowers/plans/2026-03-11-zero-dep-brainstorm-server.md

@@ -0,0 +1,479 @@
+# Zero-Dependency Brainstorm Server 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:** Replace the brainstorm server's vendored node_modules with a single zero-dependency `server.js` using Node built-ins.
+
+**Architecture:** Single file with WebSocket protocol (RFC 6455 text frames), HTTP server (`http` module), and file watching (`fs.watch`). Exports protocol functions for unit testing when required as a module.
+
+**Tech Stack:** Node.js built-ins only: `http`, `crypto`, `fs`, `path`
+
+**Spec:** `docs/superpowers/specs/2026-03-11-zero-dep-brainstorm-server-design.md`
+
+**Existing tests:** `tests/brainstorm-server/ws-protocol.test.js` (unit), `tests/brainstorm-server/server.test.js` (integration)
+
+---
+
+## File Map
+
+- **Create:** `skills/brainstorming/scripts/server.js` — the zero-dep replacement
+- **Modify:** `skills/brainstorming/scripts/start-server.sh:94,100` — change `index.js` to `server.js`
+- **Modify:** `.gitignore:6` — remove the `!skills/brainstorming/scripts/node_modules/` exception
+- **Delete:** `skills/brainstorming/scripts/index.js`
+- **Delete:** `skills/brainstorming/scripts/package.json`
+- **Delete:** `skills/brainstorming/scripts/package-lock.json`
+- **Delete:** `skills/brainstorming/scripts/node_modules/` (714 files)
+- **No changes:** `skills/brainstorming/scripts/helper.js`, `skills/brainstorming/scripts/frame-template.html`, `skills/brainstorming/scripts/stop-server.sh`
+
+---
+
+## Chunk 1: WebSocket Protocol Layer
+
+### Task 1: Implement WebSocket protocol exports
+
+**Files:**
+- Create: `skills/brainstorming/scripts/server.js`
+- Test: `tests/brainstorm-server/ws-protocol.test.js` (already exists)
+
+- [ ] **Step 1: Create server.js with OPCODES constant and computeAcceptKey**
+
+```js
+const crypto = require('crypto');
+
+const OPCODES = { TEXT: 0x01, CLOSE: 0x08, PING: 0x09, PONG: 0x0A };
+const WS_MAGIC = '258EAFA5-E914-47DA-95CA-C5AB0DC85B11';
+
+function computeAcceptKey(clientKey) {
+  return crypto.createHash('sha1').update(clientKey + WS_MAGIC).digest('base64');
+}
+```
+
+- [ ] **Step 2: Implement encodeFrame**
+
+Server frames are never masked. Three length encodings:
+- payload < 126: 2-byte header (FIN+opcode, length)
+- 126-65535: 4-byte header (FIN+opcode, 126, 16-bit length)
+- &gt; 65535: 10-byte header (FIN+opcode, 127, 64-bit length)
+
+```js
+function encodeFrame(opcode, payload) {
+  const fin = 0x80;
+  const len = payload.length;
+  let header;
+
+  if (len < 126) {
+    header = Buffer.alloc(2);
+    header[0] = fin | opcode;
+    header[1] = len;
+  } else if (len < 65536) {
+    header = Buffer.alloc(4);
+    header[0] = fin | opcode;
+    header[1] = 126;
+    header.writeUInt16BE(len, 2);
+  } else {
+    header = Buffer.alloc(10);
+    header[0] = fin | opcode;
+    header[1] = 127;
+    header.writeBigUInt64BE(BigInt(len), 2);
+  }
+
+  return Buffer.concat([header, payload]);
+}
+```
+
+- [ ] **Step 3: Implement decodeFrame**
+
+Client frames are always masked. Returns `{ opcode, payload, bytesConsumed }` or `null` for incomplete. Throws on unmasked frames.
+
+```js
+function decodeFrame(buffer) {
+  if (buffer.length < 2) return null;
+
+  const firstByte = buffer[0];
+  const secondByte = buffer[1];
+  const opcode = firstByte & 0x0F;
+  const masked = (secondByte & 0x80) !== 0;
+  let payloadLen = secondByte & 0x7F;
+  let offset = 2;
+
+  if (!masked) throw new Error('Client frames must be masked');
+
+  if (payloadLen === 126) {
+    if (buffer.length < 4) return null;
+    payloadLen = buffer.readUInt16BE(2);
+    offset = 4;
+  } else if (payloadLen === 127) {
+    if (buffer.length < 10) return null;
+    payloadLen = Number(buffer.readBigUInt64BE(2));
+    offset = 10;
+  }
+
+  const maskOffset = offset;
+  const dataOffset = offset + 4;
+  const totalLen = dataOffset + payloadLen;
+  if (buffer.length < totalLen) return null;
+
+  const mask = buffer.slice(maskOffset, dataOffset);
+  const data = Buffer.alloc(payloadLen);
+  for (let i = 0; i < payloadLen; i++) {
+    data[i] = buffer[dataOffset + i] ^ mask[i % 4];
+  }
+
+  return { opcode, payload: data, bytesConsumed: totalLen };
+}
+```
+
+- [ ] **Step 4: Add module exports at the bottom of the file**
+
+```js
+module.exports = { computeAcceptKey, encodeFrame, decodeFrame, OPCODES };
+```
+
+- [ ] **Step 5: Run unit tests**
+
+Run: `cd tests/brainstorm-server && node ws-protocol.test.js`
+Expected: All tests pass (handshake, encoding, decoding, boundaries, edge cases)
+
+- [ ] **Step 6: Commit**
+
+```bash
+git add skills/brainstorming/scripts/server.js
+git commit -m "Add WebSocket protocol layer for zero-dep brainstorm server"
+```
+
+---
+
+## Chunk 2: HTTP Server and Application Logic
+
+### Task 2: Add HTTP server, file watching, and WebSocket connection handling
+
+**Files:**
+- Modify: `skills/brainstorming/scripts/server.js`
+- Test: `tests/brainstorm-server/server.test.js` (already exists)
+
+- [ ] **Step 1: Add configuration and constants at top of server.js (after requires)**
+
+```js
+const http = require('http');
+const fs = require('fs');
+const path = require('path');
+
+const PORT = process.env.BRAINSTORM_PORT || (49152 + Math.floor(Math.random() * 16383));
+const HOST = process.env.BRAINSTORM_HOST || '127.0.0.1';
+const URL_HOST = process.env.BRAINSTORM_URL_HOST || (HOST === '127.0.0.1' ? 'localhost' : HOST);
+const SCREEN_DIR = process.env.BRAINSTORM_DIR || '/tmp/brainstorm';
+
+const MIME_TYPES = {
+  '.html': 'text/html', '.css': 'text/css', '.js': 'application/javascript',
+  '.json': 'application/json', '.png': 'image/png', '.jpg': 'image/jpeg',
+  '.jpeg': 'image/jpeg', '.gif': 'image/gif', '.svg': 'image/svg+xml'
+};
+```
+
+- [ ] **Step 2: Add WAITING_PAGE, template loading at module scope, and helper functions**
+
+Load `frameTemplate` and `helperInjection` at module scope so they're accessible to `wrapInFrame` and `handleRequest`. They only read files from `__dirname` (the scripts directory), which is valid whether the module is required or run directly.
+
+```js
+const WAITING_PAGE = `<!DOCTYPE html>
+<html>
+<head><title>Brainstorm Companion</title>
+<style>body { font-family: system-ui, sans-serif; padding: 2rem; max-width: 800px; margin: 0 auto; }
+h1 { color: #333; } p { color: #666; }</style>
+</head>
+<body><h1>Brainstorm Companion</h1>
+<p>Waiting for Claude to push a screen...</p></body></html>`;
+
+const frameTemplate = fs.readFileSync(path.join(__dirname, 'frame-template.html'), 'utf-8');
+const helperScript = fs.readFileSync(path.join(__dirname, 'helper.js'), 'utf-8');
+const helperInjection = '<script>\n' + helperScript + '\n</script>';
+
+function isFullDocument(html) {
+  const trimmed = html.trimStart().toLowerCase();
+  return trimmed.startsWith('<!doctype') || trimmed.startsWith('<html');
+}
+
+function wrapInFrame(content) {
+  return frameTemplate.replace('<!-- CONTENT -->', content);
+}
+
+function getNewestScreen() {
+  const files = fs.readdirSync(SCREEN_DIR)
+    .filter(f => f.endsWith('.html'))
+    .map(f => {
+      const fp = path.join(SCREEN_DIR, f);
+      return { path: fp, mtime: fs.statSync(fp).mtime.getTime() };
+    })
+    .sort((a, b) => b.mtime - a.mtime);
+  return files.length > 0 ? files[0].path : null;
+}
+```
+
+- [ ] **Step 3: Add HTTP request handler**
+
+```js
+function handleRequest(req, res) {
+  if (req.method === 'GET' && req.url === '/') {
+    const screenFile = getNewestScreen();
+    let html = screenFile
+      ? (raw => isFullDocument(raw) ? raw : wrapInFrame(raw))(fs.readFileSync(screenFile, 'utf-8'))
+      : WAITING_PAGE;
+
+    if (html.includes('</body>')) {
+      html = html.replace('</body>', helperInjection + '\n</body>');
+    } else {
+      html += helperInjection;
+    }
+
+    res.writeHead(200, { 'Content-Type': 'text/html' });
+    res.end(html);
+  } else if (req.method === 'GET' && req.url.startsWith('/files/')) {
+    const fileName = req.url.slice(7); // strip '/files/'
+    const filePath = path.join(SCREEN_DIR, path.basename(fileName));
+    if (!fs.existsSync(filePath)) {
+      res.writeHead(404);
+      res.end('Not found');
+      return;
+    }
+    const ext = path.extname(filePath).toLowerCase();
+    const contentType = MIME_TYPES[ext] || 'application/octet-stream';
+    res.writeHead(200, { 'Content-Type': contentType });
+    res.end(fs.readFileSync(filePath));
+  } else {
+    res.writeHead(404);
+    res.end('Not found');
+  }
+}
+```
+
+- [ ] **Step 4: Add WebSocket connection handling**
+
+```js
+const clients = new Set();
+
+function handleUpgrade(req, socket) {
+  const key = req.headers['sec-websocket-key'];
+  if (!key) { socket.destroy(); return; }
+
+  const accept = computeAcceptKey(key);
+  socket.write(
+    'HTTP/1.1 101 Switching Protocols\r\n' +
+    'Upgrade: websocket\r\n' +
+    'Connection: Upgrade\r\n' +
+    'Sec-WebSocket-Accept: ' + accept + '\r\n\r\n'
+  );
+
+  let buffer = Buffer.alloc(0);
+  clients.add(socket);
+
+  socket.on('data', (chunk) => {
+    buffer = Buffer.concat([buffer, chunk]);
+    while (buffer.length > 0) {
+      let result;
+      try {
+        result = decodeFrame(buffer);
+      } catch (e) {
+        socket.end(encodeFrame(OPCODES.CLOSE, Buffer.alloc(0)));
+        clients.delete(socket);
+        return;
+      }
+      if (!result) break;
+      buffer = buffer.slice(result.bytesConsumed);
+
+      switch (result.opcode) {
+        case OPCODES.TEXT:
+          handleMessage(result.payload.toString());
+          break;
+        case OPCODES.CLOSE:
+          socket.end(encodeFrame(OPCODES.CLOSE, Buffer.alloc(0)));
+          clients.delete(socket);
+          return;
+        case OPCODES.PING:
+          socket.write(encodeFrame(OPCODES.PONG, result.payload));
+          break;
+        case OPCODES.PONG:
+          break;
+        default:
+          // Unsupported opcode — close with 1003
+          const closeBuf = Buffer.alloc(2);
+          closeBuf.writeUInt16BE(1003);
+          socket.end(encodeFrame(OPCODES.CLOSE, closeBuf));
+          clients.delete(socket);
+          return;
+      }
+    }
+  });
+
+  socket.on('close', () => clients.delete(socket));
+  socket.on('error', () => clients.delete(socket));
+}
+
+function handleMessage(text) {
+  let event;
+  try {
+    event = JSON.parse(text);
+  } catch (e) {
+    console.error('Failed to parse WebSocket message:', e.message);
+    return;
+  }
+  console.log(JSON.stringify({ source: 'user-event', ...event }));
+  if (event.choice) {
+    const eventsFile = path.join(SCREEN_DIR, '.events');
+    fs.appendFileSync(eventsFile, JSON.stringify(event) + '\n');
+  }
+}
+
+function broadcast(msg) {
+  const frame = encodeFrame(OPCODES.TEXT, Buffer.from(JSON.stringify(msg)));
+  for (const socket of clients) {
+    try { socket.write(frame); } catch (e) { clients.delete(socket); }
+  }
+}
+```
+
+- [ ] **Step 5: Add debounce timer map**
+
+```js
+const debounceTimers = new Map();
+```
+
+File watching logic is inlined in `startServer` (Step 6) to keep watcher lifecycle together with server lifecycle and include an `error` handler per spec.
+
+- [ ] **Step 6: Add startServer function and conditional main**
+
+`frameTemplate` and `helperInjection` are already at module scope (Step 2). `startServer` just creates the screen dir, starts the HTTP server, watcher, and logs startup info.
+
+```js
+function startServer() {
+  if (!fs.existsSync(SCREEN_DIR)) fs.mkdirSync(SCREEN_DIR, { recursive: true });
+
+  const server = http.createServer(handleRequest);
+  server.on('upgrade', handleUpgrade);
+
+  const watcher = fs.watch(SCREEN_DIR, (eventType, filename) => {
+    if (!filename || !filename.endsWith('.html')) return;
+    if (debounceTimers.has(filename)) clearTimeout(debounceTimers.get(filename));
+    debounceTimers.set(filename, setTimeout(() => {
+      debounceTimers.delete(filename);
+      const filePath = path.join(SCREEN_DIR, filename);
+      if (eventType === 'rename' && fs.existsSync(filePath)) {
+        const eventsFile = path.join(SCREEN_DIR, '.events');
+        if (fs.existsSync(eventsFile)) fs.unlinkSync(eventsFile);
+        console.log(JSON.stringify({ type: 'screen-added', file: filePath }));
+      } else if (eventType === 'change') {
+        console.log(JSON.stringify({ type: 'screen-updated', file: filePath }));
+      }
+      broadcast({ type: 'reload' });
+    }, 100));
+  });
+  watcher.on('error', (err) => console.error('fs.watch error:', err.message));
+
+  server.listen(PORT, HOST, () => {
+    const info = JSON.stringify({
+      type: 'server-started', port: Number(PORT), host: HOST,
+      url_host: URL_HOST, url: 'http://' + URL_HOST + ':' + PORT,
+      screen_dir: SCREEN_DIR
+    });
+    console.log(info);
+    fs.writeFileSync(path.join(SCREEN_DIR, '.server-info'), info + '\n');
+  });
+}
+
+if (require.main === module) {
+  startServer();
+}
+```
+
+- [ ] **Step 7: Run integration tests**
+
+The test directory already has a `package.json` with `ws` as a dependency. Install it if needed, then run tests.
+
+Run: `cd tests/brainstorm-server && npm install && node server.test.js`
+Expected: All tests pass
+
+- [ ] **Step 8: Commit**
+
+```bash
+git add skills/brainstorming/scripts/server.js
+git commit -m "Add HTTP server, WebSocket handling, and file watching to server.js"
+```
+
+---
+
+## Chunk 3: Swap and Cleanup
+
+### Task 3: Update start-server.sh and remove old files
+
+**Files:**
+- Modify: `skills/brainstorming/scripts/start-server.sh:94,100`
+- Modify: `.gitignore:6`
+- Delete: `skills/brainstorming/scripts/index.js`
+- Delete: `skills/brainstorming/scripts/package.json`
+- Delete: `skills/brainstorming/scripts/package-lock.json`
+- Delete: `skills/brainstorming/scripts/node_modules/` (entire directory)
+
+- [ ] **Step 1: Update start-server.sh — change `index.js` to `server.js`**
+
+Two lines to change:
+
+Line 94: `env BRAINSTORM_DIR="$SCREEN_DIR" BRAINSTORM_HOST="$BIND_HOST" BRAINSTORM_URL_HOST="$URL_HOST" node server.js`
+
+Line 100: `nohup env BRAINSTORM_DIR="$SCREEN_DIR" BRAINSTORM_HOST="$BIND_HOST" BRAINSTORM_URL_HOST="$URL_HOST" node server.js > "$LOG_FILE" 2>&1 &`
+
+- [ ] **Step 2: Remove the gitignore exception for node_modules**
+
+In `.gitignore`, delete line 6: `!skills/brainstorming/scripts/node_modules/`
+
+- [ ] **Step 3: Delete old files**
+
+```bash
+git rm skills/brainstorming/scripts/index.js
+git rm skills/brainstorming/scripts/package.json
+git rm skills/brainstorming/scripts/package-lock.json
+git rm -r skills/brainstorming/scripts/node_modules/
+```
+
+- [ ] **Step 4: Run both test suites**
+
+Run: `cd tests/brainstorm-server && node ws-protocol.test.js && node server.test.js`
+Expected: All tests pass
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add skills/brainstorming/scripts/ .gitignore
+git commit -m "Remove vendored node_modules, swap to zero-dep server.js"
+```
+
+### Task 4: Manual smoke test
+
+- [ ] **Step 1: Start the server manually**
+
+```bash
+cd skills/brainstorming/scripts
+BRAINSTORM_DIR=/tmp/brainstorm-smoke BRAINSTORM_PORT=9876 node server.js
+```
+
+Expected: `server-started` JSON printed with port 9876
+
+- [ ] **Step 2: Open browser to http://localhost:9876**
+
+Expected: Waiting page with "Waiting for Claude to push a screen..."
+
+- [ ] **Step 3: Write an HTML file to the screen directory**
+
+```bash
+echo '<h2>Hello from smoke test</h2>' > /tmp/brainstorm-smoke/test.html
+```
+
+Expected: Browser reloads and shows "Hello from smoke test" wrapped in frame template
+
+- [ ] **Step 4: Verify WebSocket works — check browser console**
+
+Open browser dev tools. The WebSocket connection should show as connected (no errors in console). The frame template's status indicator should show "Connected".
+
+- [ ] **Step 5: Stop server with Ctrl-C, clean up**
+
+```bash
+rm -rf /tmp/brainstorm-smoke
+```

docs/superpowers/specs/2026-03-11-zero-dep-brainstorm-server-design.md

@@ -0,0 +1,118 @@
+# Zero-Dependency Brainstorm Server
+
+Replace the brainstorm companion server's vendored node_modules (express, ws, chokidar — 714 tracked files) with a single zero-dependency `server.js` using only Node.js built-ins.
+
+## Motivation
+
+Vendoring node_modules into the git repo creates a supply chain risk: frozen dependencies don't get security patches, 714 files of third-party code are committed without audit, and modifications to vendored code look like normal commits. While the actual risk is low (localhost-only dev server), eliminating it is straightforward.
+
+## Architecture
+
+A single `server.js` file (~250-300 lines) using `http`, `crypto`, `fs`, and `path`. The file serves two roles:
+
+- **When run directly** (`node server.js`): starts the HTTP/WebSocket server
+- **When required** (`require('./server.js')`): exports WebSocket protocol functions for unit testing
+
+### WebSocket Protocol
+
+Implements RFC 6455 for text frames only:
+
+**Handshake:** Compute `Sec-WebSocket-Accept` from client's `Sec-WebSocket-Key` using SHA-1 + the RFC 6455 magic GUID. Return 101 Switching Protocols.
+
+**Frame decoding (client to server):** Handle three masked length encodings:
+- Small: payload < 126 bytes
+- Medium: 126-65535 bytes (16-bit extended)
+- Large: > 65535 bytes (64-bit extended)
+
+XOR-unmask payload using 4-byte mask key. Return `{ opcode, payload, bytesConsumed }` or `null` for incomplete buffers. Reject unmasked frames.
+
+**Frame encoding (server to client):** Unmasked frames with the same three length encodings.
+
+**Opcodes handled:** TEXT (0x01), CLOSE (0x08), PING (0x09), PONG (0x0A). Unrecognized opcodes get a close frame with status 1003 (Unsupported Data).
+
+**Deliberately skipped:** Binary frames, fragmented messages, extensions (permessage-deflate), subprotocols. These are unnecessary for small JSON text messages between localhost clients. Extensions and subprotocols are negotiated in the handshake — by not advertising them, they are never active.
+
+**Buffer accumulation:** Each connection maintains a buffer. On `data`, append and loop `decodeFrame` until it returns null or buffer is empty.
+
+### HTTP Server
+
+Three routes:
+
+1. **`GET /`** — Serve newest `.html` from screen directory by mtime. Detect full documents vs fragments, wrap fragments in frame template, inject helper.js. Return `text/html`. When no `.html` files exist, serve a hardcoded waiting page ("Waiting for Claude to push a screen...") with helper.js injected.
+2. **`GET /files/*`** — Serve static files from screen directory with MIME type lookup from a hardcoded extension map (html, css, js, png, jpg, gif, svg, json). Return 404 if not found.
+3. **Everything else** — 404.
+
+WebSocket upgrade handled via the `'upgrade'` event on the HTTP server, separate from the request handler.
+
+### Configuration
+
+Environment variables (all optional):
+
+- `BRAINSTORM_PORT` — port to bind (default: random high port 49152-65535)
+- `BRAINSTORM_HOST` — interface to bind (default: `127.0.0.1`)
+- `BRAINSTORM_URL_HOST` — hostname for the URL in startup JSON (default: `localhost` when host is `127.0.0.1`, otherwise same as host)
+- `BRAINSTORM_DIR` — screen directory path (default: `/tmp/brainstorm`)
+
+### Startup Sequence
+
+1. Create `SCREEN_DIR` if it doesn't exist (`mkdirSync` recursive)
+2. Load frame template and helper.js from `__dirname`
+3. Start HTTP server on configured host/port
+4. Start `fs.watch` on `SCREEN_DIR`
+5. On successful listen, log `server-started` JSON to stdout: `{ type, port, host, url_host, url, screen_dir }`
+6. Write the same JSON to `SCREEN_DIR/.server-info` so agents can find connection details when stdout is hidden (background execution)
+
+### Application-Level WebSocket Messages
+
+When a TEXT frame arrives from a client:
+
+1. Parse as JSON. If parsing fails, log to stderr and continue.
+2. Log to stdout as `{ source: 'user-event', ...event }`.
+3. If the event contains a `choice` property, append the JSON to `SCREEN_DIR/.events` (one line per event).
+
+### File Watching
+
+`fs.watch(SCREEN_DIR)` replaces chokidar. On HTML file events:
+
+- On new file (`rename` event for a file that exists): delete `.events` file if present (`unlinkSync`), log `screen-added` to stdout as JSON
+- On file change (`change` event): log `screen-updated` to stdout as JSON (do NOT clear `.events`)
+- Both events: send `{ type: 'reload' }` to all connected WebSocket clients
+
+Debounce per-filename with ~100ms timeout to prevent duplicate events (common on macOS and Linux).
+
+### Error Handling
+
+- Malformed JSON from WebSocket clients: log to stderr, continue
+- Unhandled opcodes: close with status 1003
+- Client disconnects: remove from broadcast set
+- `fs.watch` errors: log to stderr, continue
+- No graceful shutdown logic — shell scripts handle process lifecycle via SIGTERM
+
+## What Changes
+
+| Before | After |
+|---|---|
+| `index.js` + `package.json` + `package-lock.json` + 714 `node_modules` files | `server.js` (single file) |
+| express, ws, chokidar dependencies | none |
+| No static file serving | `/files/*` serves from screen directory |
+
+## What Stays the Same
+
+- `helper.js` — no changes
+- `frame-template.html` — no changes
+- `start-server.sh` — one-line update: `index.js` to `server.js`
+- `stop-server.sh` — no changes
+- `visual-companion.md` — no changes
+- All existing server behavior and external contract
+
+## Platform Compatibility
+
+- `server.js` uses only cross-platform Node built-ins
+- `fs.watch` is reliable for single flat directories on macOS, Linux, and Windows
+- Shell scripts require bash (Git Bash on Windows, which is required for Claude Code)
+
+## Testing
+
+**Unit tests** (`ws-protocol.test.js`): Test WebSocket frame encoding/decoding, handshake computation, and protocol edge cases directly by requiring `server.js` exports.
+
+**Integration tests** (`server.test.js`): Test full server behavior — HTTP serving, WebSocket communication, file watching, brainstorming workflow. Uses `ws` npm package as a test-only client dependency (not shipped to end users).

gemini-extension.json

@@ -0,0 +1,6 @@
+{
+  "name": "superpowers",
+  "description": "Core skills library: TDD, debugging, collaboration patterns, and proven techniques",
+  "version": "5.0.0",
+  "contextFileName": "GEMINI.md"
+}

hooks/hooks.json

@@ -2,11 +2,11 @@
   "hooks": {
     "SessionStart": [
       {
-        "matcher": "startup|resume|clear|compact",
+        "matcher": "startup|clear|compact",
         "hooks": [
           {
             "type": "command",
-            "command": "${CLAUDE_PLUGIN_ROOT}/hooks/run-hook.cmd session-start",
+            "command": "\"${CLAUDE_PLUGIN_ROOT}/hooks/run-hook.cmd\" session-start",
             "async": false
           }
         ]

hooks/run-hook.cmd

@@ -40,7 +40,7 @@ exit /b 0
 CMDBLOCK
 
 # Unix: run the named script directly
-SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]:-$0}")" && pwd)"
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
 SCRIPT_NAME="$1"
 shift
 exec bash "${SCRIPT_DIR}/${SCRIPT_NAME}" "$@"

hooks/session-start

@@ -35,17 +35,27 @@ warning_escaped=$(escape_for_json "$warning_message")
 session_context="<EXTREMELY_IMPORTANT>\nYou have superpowers.\n\n**Below is the full content of your 'superpowers:using-superpowers' skill - your introduction to using skills. For all other skills, use the 'Skill' tool:**\n\n${using_superpowers_escaped}\n\n${warning_escaped}\n</EXTREMELY_IMPORTANT>"
 
 # Output context injection as JSON.
-# Keep both shapes for compatibility:
-# - Cursor hooks expect additional_context.
-# - Claude hooks expect hookSpecificOutput.additionalContext.
-cat <<EOF
+# Cursor hooks expect additional_context.
+# Claude Code hooks expect hookSpecificOutput.additionalContext.
+# Claude Code reads BOTH fields without deduplication, so we must only
+# emit the field consumed by the current platform to avoid double injection.
+if [ -n "${CLAUDE_PLUGIN_ROOT:-}" ]; then
+  # Claude Code sets CLAUDE_PLUGIN_ROOT — emit only hookSpecificOutput
+  cat <<EOF
 {
-  "additional_context": "${session_context}",
   "hookSpecificOutput": {
     "hookEventName": "SessionStart",
     "additionalContext": "${session_context}"
   }
 }
 EOF
+else
+  # Other platforms (Cursor, etc.) — emit only additional_context
+  cat <<EOF
+{
+  "additional_context": "${session_context}"
+}
+EOF
+fi
 
 exit 0

lib/brainstorm-server/index.js

@@ -1,141 +0,0 @@
-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 || (49152 + Math.floor(Math.random() * 16383));
-const HOST = process.env.BRAINSTORM_HOST || '127.0.0.1';
-const URL_HOST = process.env.BRAINSTORM_URL_HOST || (HOST === '127.0.0.1' ? 'localhost' : HOST);
-const SCREEN_DIR = process.env.BRAINSTORM_DIR || '/tmp/brainstorm';
-
-if (!fs.existsSync(SCREEN_DIR)) {
-  fs.mkdirSync(SCREEN_DIR, { recursive: true });
-}
-
-// Load frame template and helper script once at startup
-const frameTemplate = fs.readFileSync(path.join(__dirname, 'frame-template.html'), 'utf-8');
-const helperScript = fs.readFileSync(path.join(__dirname, 'helper.js'), 'utf-8');
-const helperInjection = `<script>\n${helperScript}\n</script>`;
-
-// Detect whether content is a full HTML document or a bare fragment
-function isFullDocument(html) {
-  const trimmed = html.trimStart().toLowerCase();
-  return trimmed.startsWith('<!doctype') || trimmed.startsWith('<html');
-}
-
-// Wrap a content fragment in the frame template
-function wrapInFrame(content) {
-  return frameTemplate.replace('<!-- CONTENT -->', content);
-}
-
-// Find the newest .html file in the directory by mtime
-function getNewestScreen() {
-  const files = fs.readdirSync(SCREEN_DIR)
-    .filter(f => f.endsWith('.html'))
-    .map(f => ({
-      name: f,
-      path: path.join(SCREEN_DIR, f),
-      mtime: fs.statSync(path.join(SCREEN_DIR, f)).mtime.getTime()
-    }))
-    .sort((a, b) => b.mtime - a.mtime);
-
-  return files.length > 0 ? files[0].path : null;
-}
-
-const WAITING_PAGE = `<!DOCTYPE html>
-<html>
-<head>
-  <title>Brainstorm Companion</title>
-  <style>
-    body { font-family: system-ui, sans-serif; padding: 2rem; max-width: 800px; margin: 0 auto; }
-    h1 { color: #333; }
-    p { color: #666; }
-  </style>
-</head>
-<body>
-  <h1>Brainstorm Companion</h1>
-  <p>Waiting for Claude to push a screen...</p>
-</body>
-</html>`;
-
-const app = express();
-const server = http.createServer(app);
-const wss = new WebSocket.Server({ server });
-
-const clients = new Set();
-
-wss.on('connection', (ws) => {
-  clients.add(ws);
-  ws.on('close', () => clients.delete(ws));
-
-  ws.on('message', (data) => {
-    const event = JSON.parse(data.toString());
-    console.log(JSON.stringify({ source: 'user-event', ...event }));
-    // 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');
-    }
-  });
-});
-
-// Serve newest screen with helper.js injected
-app.get('/', (req, res) => {
-  const screenFile = getNewestScreen();
-  let html;
-
-  if (!screenFile) {
-    html = WAITING_PAGE;
-  } else {
-    const raw = fs.readFileSync(screenFile, 'utf-8');
-    html = isFullDocument(raw) ? raw : wrapInFrame(raw);
-  }
-
-  // Inject helper script
-  if (html.includes('</body>')) {
-    html = html.replace('</body>', `${helperInjection}\n</body>`);
-  } else {
-    html += helperInjection;
-  }
-
-  res.type('html').send(html);
-});
-
-// Watch for new or changed .html files
-chokidar.watch(SCREEN_DIR, { ignoreInitial: true })
-  .on('add', (filePath) => {
-    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 }));
-      clients.forEach(ws => {
-        if (ws.readyState === WebSocket.OPEN) {
-          ws.send(JSON.stringify({ type: 'reload' }));
-        }
-      });
-    }
-  })
-  .on('change', (filePath) => {
-    if (filePath.endsWith('.html')) {
-      console.log(JSON.stringify({ type: 'screen-updated', file: filePath }));
-      clients.forEach(ws => {
-        if (ws.readyState === WebSocket.OPEN) {
-          ws.send(JSON.stringify({ type: 'reload' }));
-        }
-      });
-    }
-  });
-
-server.listen(PORT, HOST, () => {
-  console.log(JSON.stringify({
-    type: 'server-started',
-    port: PORT,
-    host: HOST,
-    url_host: URL_HOST,
-    url: `http://${URL_HOST}:${PORT}`,
-    screen_dir: SCREEN_DIR
-  }));
-});

lib/brainstorm-server/package.json

@@ -1,11 +0,0 @@
-{
-  "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"
-  }
-}

lib/skills-core.js

@@ -1,208 +0,0 @@
-import fs from 'fs';
-import path from 'path';
-import { execSync } from 'child_process';
-
-/**
- * Extract YAML frontmatter from a skill file.
- * Current format:
- * ---
- * name: skill-name
- * description: Use when [condition] - [what it does]
- * ---
- *
- * @param {string} filePath - Path to SKILL.md file
- * @returns {{name: string, description: string}}
- */
-function extractFrontmatter(filePath) {
-    try {
-        const content = fs.readFileSync(filePath, 'utf8');
-        const lines = content.split('\n');
-
-        let inFrontmatter = false;
-        let name = '';
-        let description = '';
-
-        for (const line of lines) {
-            if (line.trim() === '---') {
-                if (inFrontmatter) break;
-                inFrontmatter = true;
-                continue;
-            }
-
-            if (inFrontmatter) {
-                const match = line.match(/^(\w+):\s*(.*)$/);
-                if (match) {
-                    const [, key, value] = match;
-                    switch (key) {
-                        case 'name':
-                            name = value.trim();
-                            break;
-                        case 'description':
-                            description = value.trim();
-                            break;
-                    }
-                }
-            }
-        }
-
-        return { name, description };
-    } catch (error) {
-        return { name: '', description: '' };
-    }
-}
-
-/**
- * Find all SKILL.md files in a directory recursively.
- *
- * @param {string} dir - Directory to search
- * @param {string} sourceType - 'personal' or 'superpowers' for namespacing
- * @param {number} maxDepth - Maximum recursion depth (default: 3)
- * @returns {Array<{path: string, name: string, description: string, sourceType: string}>}
- */
-function findSkillsInDir(dir, sourceType, maxDepth = 3) {
-    const skills = [];
-
-    if (!fs.existsSync(dir)) return skills;
-
-    function recurse(currentDir, depth) {
-        if (depth > maxDepth) return;
-
-        const entries = fs.readdirSync(currentDir, { withFileTypes: true });
-
-        for (const entry of entries) {
-            const fullPath = path.join(currentDir, entry.name);
-
-            if (entry.isDirectory()) {
-                // Check for SKILL.md in this directory
-                const skillFile = path.join(fullPath, 'SKILL.md');
-                if (fs.existsSync(skillFile)) {
-                    const { name, description } = extractFrontmatter(skillFile);
-                    skills.push({
-                        path: fullPath,
-                        skillFile: skillFile,
-                        name: name || entry.name,
-                        description: description || '',
-                        sourceType: sourceType
-                    });
-                }
-
-                // Recurse into subdirectories
-                recurse(fullPath, depth + 1);
-            }
-        }
-    }
-
-    recurse(dir, 0);
-    return skills;
-}
-
-/**
- * Resolve a skill name to its file path, handling shadowing
- * (personal skills override superpowers skills).
- *
- * @param {string} skillName - Name like "superpowers:brainstorming" or "my-skill"
- * @param {string} superpowersDir - Path to superpowers skills directory
- * @param {string} personalDir - Path to personal skills directory
- * @returns {{skillFile: string, sourceType: string, skillPath: string} | null}
- */
-function resolveSkillPath(skillName, superpowersDir, personalDir) {
-    // Strip superpowers: prefix if present
-    const forceSuperpowers = skillName.startsWith('superpowers:');
-    const actualSkillName = forceSuperpowers ? skillName.replace(/^superpowers:/, '') : skillName;
-
-    // Try personal skills first (unless explicitly superpowers:)
-    if (!forceSuperpowers && personalDir) {
-        const personalPath = path.join(personalDir, actualSkillName);
-        const personalSkillFile = path.join(personalPath, 'SKILL.md');
-        if (fs.existsSync(personalSkillFile)) {
-            return {
-                skillFile: personalSkillFile,
-                sourceType: 'personal',
-                skillPath: actualSkillName
-            };
-        }
-    }
-
-    // Try superpowers skills
-    if (superpowersDir) {
-        const superpowersPath = path.join(superpowersDir, actualSkillName);
-        const superpowersSkillFile = path.join(superpowersPath, 'SKILL.md');
-        if (fs.existsSync(superpowersSkillFile)) {
-            return {
-                skillFile: superpowersSkillFile,
-                sourceType: 'superpowers',
-                skillPath: actualSkillName
-            };
-        }
-    }
-
-    return null;
-}
-
-/**
- * Check if a git repository has updates available.
- *
- * @param {string} repoDir - Path to git repository
- * @returns {boolean} - True if updates are available
- */
-function checkForUpdates(repoDir) {
-    try {
-        // Quick check with 3 second timeout to avoid delays if network is down
-        const output = execSync('git fetch origin && git status --porcelain=v1 --branch', {
-            cwd: repoDir,
-            timeout: 3000,
-            encoding: 'utf8',
-            stdio: 'pipe'
-        });
-
-        // Parse git status output to see if we're behind
-        const statusLines = output.split('\n');
-        for (const line of statusLines) {
-            if (line.startsWith('## ') && line.includes('[behind ')) {
-                return true; // We're behind remote
-            }
-        }
-        return false; // Up to date
-    } catch (error) {
-        // Network down, git error, timeout, etc. - don't block bootstrap
-        return false;
-    }
-}
-
-/**
- * Strip YAML frontmatter from skill content, returning just the content.
- *
- * @param {string} content - Full content including frontmatter
- * @returns {string} - Content without frontmatter
- */
-function stripFrontmatter(content) {
-    const lines = content.split('\n');
-    let inFrontmatter = false;
-    let frontmatterEnded = false;
-    const contentLines = [];
-
-    for (const line of lines) {
-        if (line.trim() === '---') {
-            if (inFrontmatter) {
-                frontmatterEnded = true;
-                continue;
-            }
-            inFrontmatter = true;
-            continue;
-        }
-
-        if (frontmatterEnded || !inFrontmatter) {
-            contentLines.push(line);
-        }
-    }
-
-    return contentLines.join('\n').trim();
-}
-
-export {
-    extractFrontmatter,
-    findSkillsInDir,
-    resolveSkillPath,
-    checkForUpdates,
-    stripFrontmatter
-};

skills/brainstorming/SKILL.md

@@ -26,8 +26,10 @@ You MUST create a task for each of these items and complete them in order:
 3. **Ask clarifying questions** — one at a time, understand purpose/constraints/success criteria
 4. **Propose 2-3 approaches** — with trade-offs and your recommendation
 5. **Present design** — in sections scaled to their complexity, get user approval after each section
-6. **Write design doc** — save to `docs/plans/YYYY-MM-DD-<topic>-design.md` and commit
-7. **Transition to implementation** — invoke writing-plans skill to create implementation plan
+6. **Write design doc** — save to `docs/superpowers/specs/YYYY-MM-DD-<topic>-design.md` and commit
+7. **Spec review loop** — dispatch spec-document-reviewer subagent with precisely crafted review context (never your session history); fix issues and re-dispatch until approved (max 5 iterations, then surface to human)
+8. **User reviews written spec** — ask user to review the spec file before proceeding
+9. **Transition to implementation** — invoke writing-plans skill to create implementation plan
 
 ## Process Flow
 
@@ -41,6 +43,9 @@ digraph brainstorming {
     "Present design sections" [shape=box];
     "User approves design?" [shape=diamond];
     "Write design doc" [shape=box];
+    "Spec review loop" [shape=box];
+    "Spec review passed?" [shape=diamond];
+    "User reviews spec?" [shape=diamond];
     "Invoke writing-plans skill" [shape=doublecircle];
 
     "Explore project context" -> "Visual questions ahead?";
@@ -52,7 +57,12 @@ digraph brainstorming {
     "Present design sections" -> "User approves design?";
     "User approves design?" -> "Present design sections" [label="no, revise"];
     "User approves design?" -> "Write design doc" [label="yes"];
-    "Write design doc" -> "Invoke writing-plans skill";
+    "Write design doc" -> "Spec review loop";
+    "Spec review loop" -> "Spec review passed?";
+    "Spec review passed?" -> "Spec review loop" [label="issues found,\nfix and re-dispatch"];
+    "Spec review passed?" -> "User reviews spec?" [label="approved"];
+    "User reviews spec?" -> "Write design doc" [label="changes requested"];
+    "User reviews spec?" -> "Invoke writing-plans skill" [label="approved"];
 }
 ```
 
@@ -113,6 +123,13 @@ After writing the spec document:
 2. If Issues Found: fix, re-dispatch, repeat until Approved
 3. If loop exceeds 5 iterations, surface to human for guidance
 
+**User Review Gate:**
+After the spec review loop passes, ask the user to review the written spec before proceeding:
+
+> "Spec written and committed to `<path>`. Please review it and let me know if you want to make any changes before we start writing out the implementation plan."
+
+Wait for the user's response. If they request changes, make them and re-run the spec review loop. Only proceed once the user approves.
+
 **Implementation:**
 
 - Invoke the writing-plans skill to create a detailed implementation plan
@@ -132,7 +149,7 @@ After writing the spec document:
 A browser-based companion for showing mockups, diagrams, and visual options during brainstorming. Available as a tool — not a mode. Accepting the companion means it's available for questions that benefit from visual treatment; it does NOT mean every question goes through the browser.
 
 **Offering the companion:** When you anticipate that upcoming questions will involve visual content (mockups, layouts, diagrams), offer it once for consent:
-> "Some of the upcoming design questions would benefit from visual mockups. I can show those in a browser window so you can see and compare options visually. This feature is still new — it can be token-intensive and a bit slow, but it works well for layout and design questions. Want to try it? (Requires opening a local URL)"
+> "Some of what we're working on might be easier to explain if I can show it to you in a web browser. I can put together mockups, diagrams, comparisons, and other visuals as we go. This feature is still new and can be token-intensive. Want to try it? (Requires opening a local URL)"
 
 **This offer MUST be its own message.** Do not combine it with clarifying questions, context summaries, or any other content. The message should contain ONLY the offer above and nothing else. Wait for the user's response before continuing. If they decline, proceed with text-only brainstorming.
 

skills/brainstorming/scripts/frame-template.html

@@ -1,7 +1,8 @@
 <!DOCTYPE html>
 <html>
 <head>
-  <title>Brainstorm Companion</title>
+  <meta charset="utf-8">
+  <title>Superpowers Brainstorming</title>
   <style>
     /*
      * BRAINSTORM COMPANION FRAME TEMPLATE
@@ -195,7 +196,7 @@
 </head>
 <body>
   <div class="header">
-    <h1>Brainstorm Companion</h1>
+    <h1><a href="https://github.com/obra/superpowers" style="color: inherit; text-decoration: none;">Superpowers Brainstorming</a></h1>
     <div class="status">Connected</div>
   </div>
 

skills/brainstorming/scripts/server.js

@@ -0,0 +1,338 @@
+const crypto = require('crypto');
+const http = require('http');
+const fs = require('fs');
+const path = require('path');
+
+// ========== WebSocket Protocol (RFC 6455) ==========
+
+const OPCODES = { TEXT: 0x01, CLOSE: 0x08, PING: 0x09, PONG: 0x0A };
+const WS_MAGIC = '258EAFA5-E914-47DA-95CA-C5AB0DC85B11';
+
+function computeAcceptKey(clientKey) {
+  return crypto.createHash('sha1').update(clientKey + WS_MAGIC).digest('base64');
+}
+
+function encodeFrame(opcode, payload) {
+  const fin = 0x80;
+  const len = payload.length;
+  let header;
+
+  if (len < 126) {
+    header = Buffer.alloc(2);
+    header[0] = fin | opcode;
+    header[1] = len;
+  } else if (len < 65536) {
+    header = Buffer.alloc(4);
+    header[0] = fin | opcode;
+    header[1] = 126;
+    header.writeUInt16BE(len, 2);
+  } else {
+    header = Buffer.alloc(10);
+    header[0] = fin | opcode;
+    header[1] = 127;
+    header.writeBigUInt64BE(BigInt(len), 2);
+  }
+
+  return Buffer.concat([header, payload]);
+}
+
+function decodeFrame(buffer) {
+  if (buffer.length < 2) return null;
+
+  const secondByte = buffer[1];
+  const opcode = buffer[0] & 0x0F;
+  const masked = (secondByte & 0x80) !== 0;
+  let payloadLen = secondByte & 0x7F;
+  let offset = 2;
+
+  if (!masked) throw new Error('Client frames must be masked');
+
+  if (payloadLen === 126) {
+    if (buffer.length < 4) return null;
+    payloadLen = buffer.readUInt16BE(2);
+    offset = 4;
+  } else if (payloadLen === 127) {
+    if (buffer.length < 10) return null;
+    payloadLen = Number(buffer.readBigUInt64BE(2));
+    offset = 10;
+  }
+
+  const maskOffset = offset;
+  const dataOffset = offset + 4;
+  const totalLen = dataOffset + payloadLen;
+  if (buffer.length < totalLen) return null;
+
+  const mask = buffer.slice(maskOffset, dataOffset);
+  const data = Buffer.alloc(payloadLen);
+  for (let i = 0; i < payloadLen; i++) {
+    data[i] = buffer[dataOffset + i] ^ mask[i % 4];
+  }
+
+  return { opcode, payload: data, bytesConsumed: totalLen };
+}
+
+// ========== Configuration ==========
+
+const PORT = process.env.BRAINSTORM_PORT || (49152 + Math.floor(Math.random() * 16383));
+const HOST = process.env.BRAINSTORM_HOST || '127.0.0.1';
+const URL_HOST = process.env.BRAINSTORM_URL_HOST || (HOST === '127.0.0.1' ? 'localhost' : HOST);
+const SCREEN_DIR = process.env.BRAINSTORM_DIR || '/tmp/brainstorm';
+const OWNER_PID = process.env.BRAINSTORM_OWNER_PID ? Number(process.env.BRAINSTORM_OWNER_PID) : null;
+
+const MIME_TYPES = {
+  '.html': 'text/html', '.css': 'text/css', '.js': 'application/javascript',
+  '.json': 'application/json', '.png': 'image/png', '.jpg': 'image/jpeg',
+  '.jpeg': 'image/jpeg', '.gif': 'image/gif', '.svg': 'image/svg+xml'
+};
+
+// ========== Templates and Constants ==========
+
+const WAITING_PAGE = `<!DOCTYPE html>
+<html>
+<head><meta charset="utf-8"><title>Brainstorm Companion</title>
+<style>body { font-family: system-ui, sans-serif; padding: 2rem; max-width: 800px; margin: 0 auto; }
+h1 { color: #333; } p { color: #666; }</style>
+</head>
+<body><h1>Brainstorm Companion</h1>
+<p>Waiting for Claude to push a screen...</p></body></html>`;
+
+const frameTemplate = fs.readFileSync(path.join(__dirname, 'frame-template.html'), 'utf-8');
+const helperScript = fs.readFileSync(path.join(__dirname, 'helper.js'), 'utf-8');
+const helperInjection = '<script>\n' + helperScript + '\n</script>';
+
+// ========== Helper Functions ==========
+
+function isFullDocument(html) {
+  const trimmed = html.trimStart().toLowerCase();
+  return trimmed.startsWith('<!doctype') || trimmed.startsWith('<html');
+}
+
+function wrapInFrame(content) {
+  return frameTemplate.replace('<!-- CONTENT -->', content);
+}
+
+function getNewestScreen() {
+  const files = fs.readdirSync(SCREEN_DIR)
+    .filter(f => f.endsWith('.html'))
+    .map(f => {
+      const fp = path.join(SCREEN_DIR, f);
+      return { path: fp, mtime: fs.statSync(fp).mtime.getTime() };
+    })
+    .sort((a, b) => b.mtime - a.mtime);
+  return files.length > 0 ? files[0].path : null;
+}
+
+// ========== HTTP Request Handler ==========
+
+function handleRequest(req, res) {
+  touchActivity();
+  if (req.method === 'GET' && req.url === '/') {
+    const screenFile = getNewestScreen();
+    let html = screenFile
+      ? (raw => isFullDocument(raw) ? raw : wrapInFrame(raw))(fs.readFileSync(screenFile, 'utf-8'))
+      : WAITING_PAGE;
+
+    if (html.includes('</body>')) {
+      html = html.replace('</body>', helperInjection + '\n</body>');
+    } else {
+      html += helperInjection;
+    }
+
+    res.writeHead(200, { 'Content-Type': 'text/html; charset=utf-8' });
+    res.end(html);
+  } else if (req.method === 'GET' && req.url.startsWith('/files/')) {
+    const fileName = req.url.slice(7);
+    const filePath = path.join(SCREEN_DIR, path.basename(fileName));
+    if (!fs.existsSync(filePath)) {
+      res.writeHead(404);
+      res.end('Not found');
+      return;
+    }
+    const ext = path.extname(filePath).toLowerCase();
+    const contentType = MIME_TYPES[ext] || 'application/octet-stream';
+    res.writeHead(200, { 'Content-Type': contentType });
+    res.end(fs.readFileSync(filePath));
+  } else {
+    res.writeHead(404);
+    res.end('Not found');
+  }
+}
+
+// ========== WebSocket Connection Handling ==========
+
+const clients = new Set();
+
+function handleUpgrade(req, socket) {
+  const key = req.headers['sec-websocket-key'];
+  if (!key) { socket.destroy(); return; }
+
+  const accept = computeAcceptKey(key);
+  socket.write(
+    'HTTP/1.1 101 Switching Protocols\r\n' +
+    'Upgrade: websocket\r\n' +
+    'Connection: Upgrade\r\n' +
+    'Sec-WebSocket-Accept: ' + accept + '\r\n\r\n'
+  );
+
+  let buffer = Buffer.alloc(0);
+  clients.add(socket);
+
+  socket.on('data', (chunk) => {
+    buffer = Buffer.concat([buffer, chunk]);
+    while (buffer.length > 0) {
+      let result;
+      try {
+        result = decodeFrame(buffer);
+      } catch (e) {
+        socket.end(encodeFrame(OPCODES.CLOSE, Buffer.alloc(0)));
+        clients.delete(socket);
+        return;
+      }
+      if (!result) break;
+      buffer = buffer.slice(result.bytesConsumed);
+
+      switch (result.opcode) {
+        case OPCODES.TEXT:
+          handleMessage(result.payload.toString());
+          break;
+        case OPCODES.CLOSE:
+          socket.end(encodeFrame(OPCODES.CLOSE, Buffer.alloc(0)));
+          clients.delete(socket);
+          return;
+        case OPCODES.PING:
+          socket.write(encodeFrame(OPCODES.PONG, result.payload));
+          break;
+        case OPCODES.PONG:
+          break;
+        default: {
+          const closeBuf = Buffer.alloc(2);
+          closeBuf.writeUInt16BE(1003);
+          socket.end(encodeFrame(OPCODES.CLOSE, closeBuf));
+          clients.delete(socket);
+          return;
+        }
+      }
+    }
+  });
+
+  socket.on('close', () => clients.delete(socket));
+  socket.on('error', () => clients.delete(socket));
+}
+
+function handleMessage(text) {
+  let event;
+  try {
+    event = JSON.parse(text);
+  } catch (e) {
+    console.error('Failed to parse WebSocket message:', e.message);
+    return;
+  }
+  touchActivity();
+  console.log(JSON.stringify({ source: 'user-event', ...event }));
+  if (event.choice) {
+    const eventsFile = path.join(SCREEN_DIR, '.events');
+    fs.appendFileSync(eventsFile, JSON.stringify(event) + '\n');
+  }
+}
+
+function broadcast(msg) {
+  const frame = encodeFrame(OPCODES.TEXT, Buffer.from(JSON.stringify(msg)));
+  for (const socket of clients) {
+    try { socket.write(frame); } catch (e) { clients.delete(socket); }
+  }
+}
+
+// ========== Activity Tracking ==========
+
+const IDLE_TIMEOUT_MS = 30 * 60 * 1000; // 30 minutes
+let lastActivity = Date.now();
+
+function touchActivity() {
+  lastActivity = Date.now();
+}
+
+// ========== File Watching ==========
+
+const debounceTimers = new Map();
+
+// ========== Server Startup ==========
+
+function startServer() {
+  if (!fs.existsSync(SCREEN_DIR)) fs.mkdirSync(SCREEN_DIR, { recursive: true });
+
+  // Track known files to distinguish new screens from updates.
+  // macOS fs.watch reports 'rename' for both new files and overwrites,
+  // so we can't rely on eventType alone.
+  const knownFiles = new Set(
+    fs.readdirSync(SCREEN_DIR).filter(f => f.endsWith('.html'))
+  );
+
+  const server = http.createServer(handleRequest);
+  server.on('upgrade', handleUpgrade);
+
+  const watcher = fs.watch(SCREEN_DIR, (eventType, filename) => {
+    if (!filename || !filename.endsWith('.html')) return;
+
+    if (debounceTimers.has(filename)) clearTimeout(debounceTimers.get(filename));
+    debounceTimers.set(filename, setTimeout(() => {
+      debounceTimers.delete(filename);
+      const filePath = path.join(SCREEN_DIR, filename);
+
+      if (!fs.existsSync(filePath)) return; // file was deleted
+      touchActivity();
+
+      if (!knownFiles.has(filename)) {
+        knownFiles.add(filename);
+        const eventsFile = path.join(SCREEN_DIR, '.events');
+        if (fs.existsSync(eventsFile)) fs.unlinkSync(eventsFile);
+        console.log(JSON.stringify({ type: 'screen-added', file: filePath }));
+      } else {
+        console.log(JSON.stringify({ type: 'screen-updated', file: filePath }));
+      }
+
+      broadcast({ type: 'reload' });
+    }, 100));
+  });
+  watcher.on('error', (err) => console.error('fs.watch error:', err.message));
+
+  function shutdown(reason) {
+    console.log(JSON.stringify({ type: 'server-stopped', reason }));
+    const infoFile = path.join(SCREEN_DIR, '.server-info');
+    if (fs.existsSync(infoFile)) fs.unlinkSync(infoFile);
+    fs.writeFileSync(
+      path.join(SCREEN_DIR, '.server-stopped'),
+      JSON.stringify({ reason, timestamp: Date.now() }) + '\n'
+    );
+    watcher.close();
+    clearInterval(lifecycleCheck);
+    server.close(() => process.exit(0));
+  }
+
+  function ownerAlive() {
+    if (!OWNER_PID) return true;
+    try { process.kill(OWNER_PID, 0); return true; } catch (e) { return false; }
+  }
+
+  // Check every 60s: exit if owner process died or idle for 30 minutes
+  const lifecycleCheck = setInterval(() => {
+    if (!ownerAlive()) shutdown('owner process exited');
+    else if (Date.now() - lastActivity > IDLE_TIMEOUT_MS) shutdown('idle timeout');
+  }, 60 * 1000);
+  lifecycleCheck.unref();
+
+  server.listen(PORT, HOST, () => {
+    const info = JSON.stringify({
+      type: 'server-started', port: Number(PORT), host: HOST,
+      url_host: URL_HOST, url: 'http://' + URL_HOST + ':' + PORT,
+      screen_dir: SCREEN_DIR
+    });
+    console.log(info);
+    fs.writeFileSync(path.join(SCREEN_DIR, '.server-info'), info + '\n');
+  });
+}
+
+if (require.main === module) {
+  startServer();
+}
+
+module.exports = { computeAcceptKey, encodeFrame, decodeFrame, OPCODES };

skills/brainstorming/scripts/start-server.sh

@@ -59,7 +59,7 @@ if [[ -z "$URL_HOST" ]]; then
   fi
 fi
 
-# Codex environments may reap detached/background processes. Prefer foreground by default.
+# Some environments reap detached/background processes. Auto-foreground when detected.
 if [[ -n "${CODEX_CI:-}" && "$FOREGROUND" != "true" && "$FORCE_BACKGROUND" != "true" ]]; then
   FOREGROUND="true"
 fi
@@ -88,16 +88,24 @@ fi
 
 cd "$SCRIPT_DIR"
 
+# Resolve the harness PID (grandparent of this script).
+# $PPID is the ephemeral shell the harness spawned to run us — it dies
+# when this script exits. The harness itself is $PPID's parent.
+OWNER_PID="$(ps -o ppid= -p "$PPID" 2>/dev/null | tr -d ' ')"
+if [[ -z "$OWNER_PID" || "$OWNER_PID" == "1" ]]; then
+  OWNER_PID="$PPID"
+fi
+
 # Foreground mode for environments that reap detached/background processes.
 if [[ "$FOREGROUND" == "true" ]]; then
   echo "$$" > "$PID_FILE"
-  env BRAINSTORM_DIR="$SCREEN_DIR" BRAINSTORM_HOST="$BIND_HOST" BRAINSTORM_URL_HOST="$URL_HOST" node index.js
+  env BRAINSTORM_DIR="$SCREEN_DIR" BRAINSTORM_HOST="$BIND_HOST" BRAINSTORM_URL_HOST="$URL_HOST" BRAINSTORM_OWNER_PID="$OWNER_PID" node server.js
   exit $?
 fi
 
 # Start server, capturing output to log file
 # Use nohup to survive shell exit; disown to remove from job table
-nohup env BRAINSTORM_DIR="$SCREEN_DIR" BRAINSTORM_HOST="$BIND_HOST" BRAINSTORM_URL_HOST="$URL_HOST" node index.js > "$LOG_FILE" 2>&1 &
+nohup env BRAINSTORM_DIR="$SCREEN_DIR" BRAINSTORM_HOST="$BIND_HOST" BRAINSTORM_URL_HOST="$URL_HOST" BRAINSTORM_OWNER_PID="$OWNER_PID" node server.js > "$LOG_FILE" 2>&1 &
 SERVER_PID=$!
 disown "$SERVER_PID" 2>/dev/null
 echo "$SERVER_PID" > "$PID_FILE"

skills/brainstorming/visual-companion.md

@@ -34,7 +34,7 @@ The server watches a directory for HTML files and serves the newest one to the b
 
 ```bash
 # Start server with persistence (mockups saved to project)
-${CLAUDE_PLUGIN_ROOT}/lib/brainstorm-server/start-server.sh --project-dir /path/to/project
+scripts/start-server.sh --project-dir /path/to/project
 
 # Returns: {"type":"server-started","port":52341,"url":"http://localhost:52341",
 #           "screen_dir":"/path/to/project/.superpowers/brainstorm/12345-1706000000"}
@@ -42,22 +42,38 @@ ${CLAUDE_PLUGIN_ROOT}/lib/brainstorm-server/start-server.sh --project-dir /path/
 
 Save `screen_dir` from the response. Tell user to open the URL.
 
+**Finding connection info:** The server writes its startup JSON to `$SCREEN_DIR/.server-info`. If you launched the server in the background and didn't capture stdout, read that file to get the URL and port. When using `--project-dir`, check `<project>/.superpowers/brainstorm/` for the session directory.
+
 **Note:** Pass the project root as `--project-dir` so mockups persist in `.superpowers/brainstorm/` and survive server restarts. Without it, files go to `/tmp` and get cleaned up. Remind the user to add `.superpowers/` to `.gitignore` if it's not already there.
 
-**Codex behavior:** In Codex (`CODEX_CI=1`), `start-server.sh` auto-switches to foreground mode by default because background jobs may be reaped. Use `--background` only if your environment reliably preserves detached processes.
-
-**If background processes are reaped in your environment:** run in foreground from a persistent terminal session:
+**Launching the server by platform:**
 
+**Claude Code:**
 ```bash
-${CLAUDE_PLUGIN_ROOT}/lib/brainstorm-server/start-server.sh --project-dir /path/to/project --foreground
+# Default mode works — the script backgrounds the server itself
+scripts/start-server.sh --project-dir /path/to/project
 ```
 
-In `--foreground` mode, the command stays attached and serves until interrupted.
+**Codex:**
+```bash
+# Codex reaps background processes. The script auto-detects CODEX_CI and
+# switches to foreground mode. Run it normally — no extra flags needed.
+scripts/start-server.sh --project-dir /path/to/project
+```
+
+**Gemini CLI:**
+```bash
+# Use --foreground and set is_background: true on your shell tool call
+# so the process survives across turns
+scripts/start-server.sh --project-dir /path/to/project --foreground
+```
+
+**Other environments:** The server must keep running in the background across conversation turns. If your environment reaps detached processes, use `--foreground` and launch the command with your platform's background execution mechanism.
 
 If the URL is unreachable from your browser (common in remote/containerized setups), bind a non-loopback host:
 
 ```bash
-${CLAUDE_PLUGIN_ROOT}/lib/brainstorm-server/start-server.sh \
+scripts/start-server.sh \
   --project-dir /path/to/project \
   --host 0.0.0.0 \
   --url-host localhost
@@ -67,7 +83,8 @@ Use `--url-host` to control what hostname is printed in the returned URL JSON.
 
 ## The Loop
 
-1. **Write HTML** to a new file in `screen_dir`:
+1. **Check server is alive**, then **write HTML** to a new file in `screen_dir`:
+   - Before each write, check that `$SCREEN_DIR/.server-info` exists. If it doesn't (or `.server-stopped` exists), the server has shut down — restart it with `start-server.sh` before continuing. The server auto-exits after 30 minutes of inactivity.
    - Use semantic filenames: `platform.html`, `visual-style.html`, `layout.html`
    - **Never reuse filenames** — each screen gets a fresh file
    - Use Write tool — **never use cat/heredoc** (dumps noise into terminal)
@@ -249,12 +266,12 @@ If `.events` doesn't exist, the user didn't interact with the browser — use on
 ## Cleaning Up
 
 ```bash
-${CLAUDE_PLUGIN_ROOT}/lib/brainstorm-server/stop-server.sh $SCREEN_DIR
+scripts/stop-server.sh $SCREEN_DIR
 ```
 
 If the session used `--project-dir`, mockup files persist in `.superpowers/brainstorm/` for later reference. Only `/tmp` sessions get deleted on stop.
 
 ## Reference
 
-- Frame template (CSS reference): `${CLAUDE_PLUGIN_ROOT}/lib/brainstorm-server/frame-template.html`
-- Helper script (client-side): `${CLAUDE_PLUGIN_ROOT}/lib/brainstorm-server/helper.js`
+- Frame template (CSS reference): `scripts/frame-template.html`
+- Helper script (client-side): `scripts/helper.js`

skills/dispatching-parallel-agents/SKILL.md

@@ -7,6 +7,8 @@ description: Use when facing 2+ independent tasks that can be worked on without
 
 ## Overview
 
+You delegate tasks to specialized agents with isolated context. By precisely crafting their instructions and context, you ensure they stay focused and succeed at their task. They should never inherit your session's context or history — you construct exactly what they need. This also preserves your own context for coordination work.
+
 When you have multiple unrelated failures (different test files, different subsystems, different bugs), investigating them sequentially wastes time. Each investigation is independent and can happen in parallel.
 
 **Core principle:** Dispatch one agent per independent problem domain. Let them work concurrently.

skills/executing-plans/SKILL.md

@@ -7,12 +7,12 @@ description: Use when you have a written implementation plan to execute in a sep
 
 ## Overview
 
-Load plan, review critically, execute tasks in batches, report for review between batches.
-
-**Core principle:** Batch execution with checkpoints for architect review.
+Load plan, review critically, execute all tasks, report when complete.
 
 **Announce at start:** "I'm using the executing-plans skill to implement this plan."
 
+**Note:** Tell your human partner that Superpowers works much better with access to subagents. The quality of its work will be significantly higher if run on a platform with subagent support (such as Claude Code or Codex). If subagents are available, use superpowers:subagent-driven-development instead of this skill.
+
 ## The Process
 
 ### Step 1: Load and Review Plan
@@ -21,8 +21,7 @@ Load plan, review critically, execute tasks in batches, report for review betwee
 3. If concerns: Raise them with your human partner before starting
 4. If no concerns: Create TodoWrite and proceed
 
-### Step 2: Execute Batch
-**Default: First 3 tasks**
+### Step 2: Execute Tasks
 
 For each task:
 1. Mark as in_progress
@@ -30,19 +29,7 @@ For each task:
 3. Run verifications as specified
 4. Mark as completed
 
-### Step 3: Report
-When batch complete:
-- Show what was implemented
-- Show verification output
-- Say: "Ready for feedback."
-
-### Step 4: Continue
-Based on feedback:
-- Apply changes if needed
-- Execute next batch
-- Repeat until complete
-
-### Step 5: Complete Development
+### Step 3: Complete Development
 
 After all tasks complete and verified:
 - Announce: "I'm using the finishing-a-development-branch skill to complete this work."
@@ -52,7 +39,7 @@ After all tasks complete and verified:
 ## When to Stop and Ask for Help
 
 **STOP executing immediately when:**
-- Hit a blocker mid-batch (missing dependency, test fails, instruction unclear)
+- Hit a blocker (missing dependency, test fails, instruction unclear)
 - Plan has critical gaps preventing starting
 - You don't understand an instruction
 - Verification fails repeatedly
@@ -72,7 +59,6 @@ After all tasks complete and verified:
 - Follow plan steps exactly
 - Don't skip verifications
 - Reference skills when plan says to
-- Between batches: just report and wait
 - Stop when blocked, don't guess
 - Never start implementation on main/master branch without explicit user consent
 

skills/requesting-code-review/SKILL.md

@@ -5,7 +5,7 @@ description: Use when completing tasks, implementing major features, or before m
 
 # Requesting Code Review
 
-Dispatch superpowers:code-reviewer subagent to catch issues before they cascade.
+Dispatch superpowers:code-reviewer subagent to catch issues before they cascade. The reviewer gets precisely crafted context for evaluation — never your session's history. This keeps the reviewer focused on the work product, not your thought process, and preserves your own context for continued work.
 
 **Core principle:** Review early, review often.
 

skills/subagent-driven-development/SKILL.md

@@ -7,6 +7,8 @@ description: Use when executing implementation plans with independent tasks in t
 
 Execute plan by dispatching fresh subagent per task, with two-stage review after each: spec compliance review first, then code quality review.
 
+**Why subagents:** You delegate tasks to specialized agents with isolated context. By precisely crafting their instructions and context, you ensure they stay focused and succeed at their task. They should never inherit your session's context or history — you construct exactly what they need. This also preserves your own context for coordination work.
+
 **Core principle:** Fresh subagent per task + two-stage review (spec then quality) = high quality, fast iteration
 
 ## When to Use

skills/using-superpowers/SKILL.md

@@ -19,21 +19,23 @@ This is not negotiable. This is not optional. You cannot rationalize your way ou
 
 Superpowers skills override default system prompt behavior, but **user instructions always take precedence**:
 
-1. **User's explicit instructions** (CLAUDE.md, direct requests) — highest priority
+1. **User's explicit instructions** (CLAUDE.md, GEMINI.md, AGENTS.md, direct requests) — highest priority
 2. **Superpowers skills** — override default system behavior where they conflict
 3. **Default system prompt** — lowest priority
 
-If CLAUDE.md says "don't use TDD" and a skill says "always use TDD," follow CLAUDE.md. The user is in control.
+If CLAUDE.md, GEMINI.md, or AGENTS.md says "don't use TDD" and a skill says "always use TDD," follow the user's instructions. The user is in control.
 
 ## How to Access Skills
 
 **In Claude Code:** Use the `Skill` tool. When you invoke a skill, its content is loaded and presented to you—follow it directly. Never use the Read tool on skill files.
 
+**In Gemini CLI:** Skills activate via the `activate_skill` tool. Gemini loads skill metadata at session start and activates the full content on demand.
+
 **In other environments:** Check your platform's documentation for how skills are loaded.
 
 ## Platform Adaptation
 
-Skills use Claude Code tool names. Non-CC platforms: see `references/codex-tools.md` for tool equivalents.
+Skills use Claude Code tool names. Non-CC platforms: see `references/codex-tools.md` (Codex) for tool equivalents. Gemini CLI users get the tool mapping loaded automatically via GEMINI.md.
 
 # Using Skills
 

skills/using-superpowers/references/gemini-tools.md

@@ -0,0 +1,33 @@
+# Gemini CLI Tool Mapping
+
+Skills use Claude Code tool names. When you encounter these in a skill, use your platform equivalent:
+
+| Skill references | Gemini CLI equivalent |
+|-----------------|----------------------|
+| `Read` (file reading) | `read_file` |
+| `Write` (file creation) | `write_file` |
+| `Edit` (file editing) | `replace` |
+| `Bash` (run commands) | `run_shell_command` |
+| `Grep` (search file content) | `grep_search` |
+| `Glob` (search files by name) | `glob` |
+| `TodoWrite` (task tracking) | `write_todos` |
+| `Skill` tool (invoke a skill) | `activate_skill` |
+| `WebSearch` | `google_web_search` |
+| `WebFetch` | `web_fetch` |
+| `Task` tool (dispatch subagent) | No equivalent — Gemini CLI does not support subagents |
+
+## No subagent support
+
+Gemini CLI has no equivalent to Claude Code's `Task` tool. Skills that rely on subagent dispatch (`subagent-driven-development`, `dispatching-parallel-agents`) will fall back to single-session execution via `executing-plans`.
+
+## Additional Gemini CLI tools
+
+These tools are available in Gemini CLI but have no Claude Code equivalent:
+
+| Tool | Purpose |
+|------|---------|
+| `list_directory` | List files and subdirectories |
+| `save_memory` | Persist facts to GEMINI.md across sessions |
+| `ask_user` | Request structured input from the user |
+| `tracker_create_task` | Rich task management (create, update, list, visualize) |
+| `enter_plan_mode` / `exit_plan_mode` | Switch to read-only research mode before making changes |

skills/writing-plans/SKILL.md

@@ -49,7 +49,7 @@ This structure informs the task decomposition. Each task should produce self-con
 ```markdown
 # [Feature Name] Implementation Plan
 
-> **For Claude:** REQUIRED: Use superpowers:subagent-driven-development (if subagents available) or superpowers:executing-plans to implement this plan. Steps use checkbox (`- [ ]`) syntax for tracking.
+> **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:** [One sentence describing what this builds]
 
@@ -114,7 +114,7 @@ git commit -m "feat: add specific feature"
 
 After completing each chunk of the plan:
 
-1. Dispatch plan-document-reviewer subagent (see plan-document-reviewer-prompt.md) for the current chunk
+1. Dispatch plan-document-reviewer subagent (see plan-document-reviewer-prompt.md) with precisely crafted review context — never your session history. This keeps the reviewer focused on the plan, not your thought process.
    - Provide: chunk content, path to spec document
 2. If ❌ Issues Found:
    - Fix the issues in the chunk

tests/brainstorm-server/server.test.js

@@ -1,3 +1,13 @@
+/**
+ * Integration tests for the brainstorm server.
+ *
+ * Tests the full server behavior: HTTP serving, WebSocket communication,
+ * file watching, and the brainstorming workflow.
+ *
+ * Uses the `ws` npm package as a test client (test-only dependency,
+ * not shipped to end users).
+ */
+
 const { spawn } = require('child_process');
 const http = require('http');
 const WebSocket = require('ws');
@@ -5,7 +15,7 @@ const fs = require('fs');
 const path = require('path');
 const assert = require('assert');
 
-const SERVER_PATH = path.join(__dirname, '../../lib/brainstorm-server/index.js');
+const SERVER_PATH = path.join(__dirname, '../../skills/brainstorming/scripts/server.js');
 const TEST_PORT = 3334;
 const TEST_DIR = '/tmp/brainstorm-test';
 
@@ -24,7 +34,11 @@ async function fetch(url) {
     http.get(url, (res) => {
       let data = '';
       res.on('data', chunk => data += chunk);
-      res.on('end', () => resolve({ status: res.statusCode, body: data }));
+      res.on('end', () => resolve({
+        status: res.statusCode,
+        headers: res.headers,
+        body: data
+      }));
     }).on('error', reject);
   });
 }
@@ -35,153 +49,371 @@ function startServer() {
   });
 }
 
+async function waitForServer(server) {
+  let stdout = '';
+  let stderr = '';
+
+  return new Promise((resolve, reject) => {
+    server.stdout.on('data', (data) => {
+      stdout += data.toString();
+      if (stdout.includes('server-started')) {
+        resolve({ stdout, stderr, getStdout: () => stdout });
+      }
+    });
+    server.stderr.on('data', (data) => { stderr += data.toString(); });
+    server.on('error', reject);
+
+    setTimeout(() => reject(new Error(`Server didn't start. stderr: ${stderr}`)), 5000);
+  });
+}
+
 async function runTests() {
   cleanup();
   fs.mkdirSync(TEST_DIR, { recursive: true });
 
   const server = startServer();
+  let stdoutAccum = '';
+  server.stdout.on('data', (data) => { stdoutAccum += data.toString(); });
 
-  let stdout = '';
-  let stderr = '';
-  server.stdout.on('data', (data) => { stdout += data.toString(); });
-  server.stderr.on('data', (data) => { stderr += data.toString(); });
+  const { stdout: initialStdout } = await waitForServer(server);
+  let passed = 0;
+  let failed = 0;
 
-  // Wait for server to start (up to 3 seconds)
-  for (let i = 0; i < 30; i++) {
-    if (stdout.includes('server-started')) break;
-    await sleep(100);
+  function test(name, fn) {
+    return fn().then(() => {
+      console.log(`  PASS: ${name}`);
+      passed++;
+    }).catch(e => {
+      console.log(`  FAIL: ${name}`);
+      console.log(`    ${e.message}`);
+      failed++;
+    });
   }
-  if (stderr) console.error('Server stderr:', stderr);
 
   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');
+    // ========== Server Startup ==========
+    console.log('\n--- Server Startup ---');
 
-    // Test 2: GET / returns waiting page with helper injected when no screens exist
-    console.log('Test 2: Serves waiting page with helper injected');
-    const res = await fetch(`http://localhost:${TEST_PORT}/`);
-    assert.strictEqual(res.status, 200);
-    assert(res.body.includes('Waiting for Claude'), 'Should show waiting message');
-    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 = '';
-    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(300);
-
-    assert(stdout.includes('"source":"user-event"'), 'Should relay user events with source field');
-    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;
+    await test('outputs server-started JSON on startup', () => {
+      const msg = JSON.parse(initialStdout.trim());
+      assert.strictEqual(msg.type, 'server-started');
+      assert.strictEqual(msg.port, TEST_PORT);
+      assert(msg.url, 'Should include URL');
+      assert(msg.screen_dir, 'Should include screen_dir');
+      return Promise.resolve();
     });
 
-    fs.writeFileSync(path.join(TEST_DIR, 'test-screen.html'), '<html><body>Full doc</body></html>');
-    await sleep(500);
+    await test('writes .server-info file', () => {
+      const infoPath = path.join(TEST_DIR, '.server-info');
+      assert(fs.existsSync(infoPath), '.server-info should exist');
+      const info = JSON.parse(fs.readFileSync(infoPath, 'utf-8').trim());
+      assert.strictEqual(info.type, 'server-started');
+      assert.strictEqual(info.port, TEST_PORT);
+      return Promise.resolve();
+    });
 
-    assert(gotReload, 'Should send reload message on file change');
-    ws2.close();
-    console.log('  PASS');
+    // ========== HTTP Serving ==========
+    console.log('\n--- HTTP Serving ---');
 
-    // 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));
+    await test('serves waiting page when no screens exist', async () => {
+      const res = await fetch(`http://localhost:${TEST_PORT}/`);
+      assert.strictEqual(res.status, 200);
+      assert(res.body.includes('Waiting for Claude'), 'Should show waiting message');
+    });
 
-    ws3.send(JSON.stringify({ type: 'click', choice: 'a', text: 'Option A' }));
-    await sleep(300);
+    await test('injects helper.js into waiting page', async () => {
+      const res = await fetch(`http://localhost:${TEST_PORT}/`);
+      assert(res.body.includes('WebSocket'), 'Should have helper.js injected');
+      assert(res.body.includes('toggleSelect'), 'Should have toggleSelect from helper');
+      assert(res.body.includes('brainstorm'), 'Should have brainstorm API from helper');
+    });
 
-    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');
+    await test('returns Content-Type text/html', async () => {
+      const res = await fetch(`http://localhost:${TEST_PORT}/`);
+      assert(res.headers['content-type'].includes('text/html'), 'Should be text/html');
+    });
 
-    // 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'), '<h2>New screen</h2>');
-    await sleep(500);
-    assert(!fs.existsSync(path.join(TEST_DIR, '.events')), '.events should be cleared after new screen');
-    console.log('  PASS');
+    await test('serves full HTML documents as-is (not wrapped)', async () => {
+      const fullDoc = '<!DOCTYPE html>\n<html><head><title>Custom</title></head><body><h1>Custom Page</h1></body></html>';
+      fs.writeFileSync(path.join(TEST_DIR, 'full-doc.html'), fullDoc);
+      await sleep(300);
 
-    // Test 5: Full HTML document served as-is (not wrapped)
-    console.log('Test 5: Full HTML document served without frame wrapping');
-    const fullDoc = '<!DOCTYPE html>\n<html><head><title>Custom</title></head><body><h1>Custom Page</h1></body></html>';
-    fs.writeFileSync(path.join(TEST_DIR, 'full-doc.html'), fullDoc);
-    await sleep(300);
+      const res = await fetch(`http://localhost:${TEST_PORT}/`);
+      assert(res.body.includes('<h1>Custom Page</h1>'), 'Should contain original content');
+      assert(res.body.includes('WebSocket'), 'Should still inject helper.js');
+      assert(!res.body.includes('indicator-bar'), 'Should NOT wrap in frame template');
+    });
 
-    const fullRes = await fetch(`http://localhost:${TEST_PORT}/`);
-    assert(fullRes.body.includes('<h1>Custom Page</h1>'), 'Should contain original content');
-    assert(fullRes.body.includes('WebSocket'), 'Should still inject helper.js');
-    // Should NOT have the frame template's indicator bar
-    assert(!fullRes.body.includes('indicator-bar') || fullDoc.includes('indicator-bar'),
-      'Should not wrap full documents in frame template');
-    console.log('  PASS');
+    await test('wraps content fragments in frame template', async () => {
+      const fragment = '<h2>Pick a layout</h2>\n<div class="options"><div class="option" data-choice="a"><div class="letter">A</div></div></div>';
+      fs.writeFileSync(path.join(TEST_DIR, 'fragment.html'), fragment);
+      await sleep(300);
 
-    // Test 6: Bare HTML fragment gets wrapped in frame template
-    console.log('Test 6: Content fragment wrapped in frame template');
-    const fragment = '<h2>Pick a layout</h2>\n<p class="subtitle">Choose one</p>\n<div class="options"><div class="option" data-choice="a"><div class="letter">A</div><div class="content"><h3>Simple</h3></div></div></div>';
-    fs.writeFileSync(path.join(TEST_DIR, 'fragment.html'), fragment);
-    await sleep(300);
+      const res = await fetch(`http://localhost:${TEST_PORT}/`);
+      assert(res.body.includes('indicator-bar'), 'Fragment should get indicator bar');
+      assert(!res.body.includes('<!-- CONTENT -->'), 'Placeholder should be replaced');
+      assert(res.body.includes('Pick a layout'), 'Fragment content should be present');
+      assert(res.body.includes('data-choice="a"'), 'Fragment interactive elements intact');
+    });
 
-    const fragRes = await fetch(`http://localhost:${TEST_PORT}/`);
-    // Should have the frame template structure
-    assert(fragRes.body.includes('indicator-bar'), 'Fragment should get indicator bar from frame');
-    assert(!fragRes.body.includes('<!-- CONTENT -->'), 'Content placeholder should be replaced');
-    // Should have the original content inside
-    assert(fragRes.body.includes('Pick a layout'), 'Fragment content should be present');
-    assert(fragRes.body.includes('data-choice="a"'), 'Fragment content should be intact');
-    // Should have helper.js injected
-    assert(fragRes.body.includes('WebSocket'), 'Fragment should have helper.js injected');
-    console.log('  PASS');
+    await test('serves newest file by mtime', async () => {
+      fs.writeFileSync(path.join(TEST_DIR, 'older.html'), '<h2>Older</h2>');
+      await sleep(100);
+      fs.writeFileSync(path.join(TEST_DIR, 'newer.html'), '<h2>Newer</h2>');
+      await sleep(300);
 
-    // Test 7: Helper.js includes toggleSelect and send functions
-    console.log('Test 7: Helper.js provides toggleSelect and send');
-    const helperContent = fs.readFileSync(
-      path.join(__dirname, '../../lib/brainstorm-server/helper.js'), 'utf-8'
-    );
-    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');
-    console.log('  PASS');
+      const res = await fetch(`http://localhost:${TEST_PORT}/`);
+      assert(res.body.includes('Newer'), 'Should serve newest file');
+    });
 
-    // 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');
+    await test('ignores non-html files for serving', async () => {
+      // Write a newer non-HTML file — should still serve newest .html
+      fs.writeFileSync(path.join(TEST_DIR, 'data.json'), '{"not": "html"}');
+      await sleep(300);
 
-    console.log('\nAll tests passed!');
+      const res = await fetch(`http://localhost:${TEST_PORT}/`);
+      assert(res.body.includes('Newer'), 'Should still serve newest HTML');
+      assert(!res.body.includes('"not"'), 'Should not serve JSON');
+    });
+
+    await test('returns 404 for non-root paths', async () => {
+      const res = await fetch(`http://localhost:${TEST_PORT}/other`);
+      assert.strictEqual(res.status, 404);
+    });
+
+    // ========== WebSocket Communication ==========
+    console.log('\n--- WebSocket Communication ---');
+
+    await test('accepts WebSocket upgrade on /', async () => {
+      const ws = new WebSocket(`ws://localhost:${TEST_PORT}`);
+      await new Promise((resolve, reject) => {
+        ws.on('open', resolve);
+        ws.on('error', reject);
+      });
+      ws.close();
+    });
+
+    await test('relays user events to stdout with source field', async () => {
+      stdoutAccum = '';
+      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(300);
+
+      assert(stdoutAccum.includes('"source":"user-event"'), 'Should tag with source');
+      assert(stdoutAccum.includes('Test Button'), 'Should include event data');
+      ws.close();
+    });
+
+    await test('writes choice events to .events file', async () => {
+      // Clean up events from prior tests
+      const eventsFile = path.join(TEST_DIR, '.events');
+      if (fs.existsSync(eventsFile)) fs.unlinkSync(eventsFile);
+
+      const ws = new WebSocket(`ws://localhost:${TEST_PORT}`);
+      await new Promise(resolve => ws.on('open', resolve));
+
+      ws.send(JSON.stringify({ type: 'click', choice: 'b', text: 'Option B' }));
+      await sleep(300);
+
+      assert(fs.existsSync(eventsFile), '.events should exist');
+      const lines = fs.readFileSync(eventsFile, 'utf-8').trim().split('\n');
+      const event = JSON.parse(lines[lines.length - 1]);
+      assert.strictEqual(event.choice, 'b');
+      assert.strictEqual(event.text, 'Option B');
+      ws.close();
+    });
+
+    await test('does NOT write non-choice events to .events file', async () => {
+      const eventsFile = path.join(TEST_DIR, '.events');
+      if (fs.existsSync(eventsFile)) fs.unlinkSync(eventsFile);
+
+      const ws = new WebSocket(`ws://localhost:${TEST_PORT}`);
+      await new Promise(resolve => ws.on('open', resolve));
+
+      ws.send(JSON.stringify({ type: 'hover', text: 'Something' }));
+      await sleep(300);
+
+      // Non-choice events should not create .events file
+      assert(!fs.existsSync(eventsFile), '.events should not exist for non-choice events');
+      ws.close();
+    });
+
+    await test('handles multiple concurrent WebSocket clients', async () => {
+      const ws1 = new WebSocket(`ws://localhost:${TEST_PORT}`);
+      const ws2 = new WebSocket(`ws://localhost:${TEST_PORT}`);
+      await Promise.all([
+        new Promise(resolve => ws1.on('open', resolve)),
+        new Promise(resolve => ws2.on('open', resolve))
+      ]);
+
+      let ws1Reload = false;
+      let ws2Reload = false;
+      ws1.on('message', (data) => {
+        if (JSON.parse(data.toString()).type === 'reload') ws1Reload = true;
+      });
+      ws2.on('message', (data) => {
+        if (JSON.parse(data.toString()).type === 'reload') ws2Reload = true;
+      });
+
+      fs.writeFileSync(path.join(TEST_DIR, 'multi-client.html'), '<h2>Multi</h2>');
+      await sleep(500);
+
+      assert(ws1Reload, 'Client 1 should receive reload');
+      assert(ws2Reload, 'Client 2 should receive reload');
+      ws1.close();
+      ws2.close();
+    });
+
+    await test('cleans up closed clients from broadcast list', async () => {
+      const ws1 = new WebSocket(`ws://localhost:${TEST_PORT}`);
+      await new Promise(resolve => ws1.on('open', resolve));
+      ws1.close();
+      await sleep(100);
+
+      // This should not throw even though ws1 is closed
+      fs.writeFileSync(path.join(TEST_DIR, 'after-close.html'), '<h2>After</h2>');
+      await sleep(300);
+      // If we got here without error, the test passes
+    });
+
+    await test('handles malformed JSON from client gracefully', async () => {
+      const ws = new WebSocket(`ws://localhost:${TEST_PORT}`);
+      await new Promise(resolve => ws.on('open', resolve));
+
+      // Send invalid JSON — server should not crash
+      ws.send('not json at all {{{');
+      await sleep(300);
+
+      // Verify server is still responsive
+      const res = await fetch(`http://localhost:${TEST_PORT}/`);
+      assert.strictEqual(res.status, 200, 'Server should still be running');
+      ws.close();
+    });
+
+    // ========== File Watching ==========
+    console.log('\n--- File Watching ---');
+
+    await test('sends reload on new .html file', async () => {
+      const ws = new WebSocket(`ws://localhost:${TEST_PORT}`);
+      await new Promise(resolve => ws.on('open', resolve));
+
+      let gotReload = false;
+      ws.on('message', (data) => {
+        if (JSON.parse(data.toString()).type === 'reload') gotReload = true;
+      });
+
+      fs.writeFileSync(path.join(TEST_DIR, 'watch-new.html'), '<h2>New</h2>');
+      await sleep(500);
+
+      assert(gotReload, 'Should send reload on new file');
+      ws.close();
+    });
+
+    await test('sends reload on .html file change', async () => {
+      const filePath = path.join(TEST_DIR, 'watch-change.html');
+      fs.writeFileSync(filePath, '<h2>Original</h2>');
+      await sleep(500);
+
+      const ws = new WebSocket(`ws://localhost:${TEST_PORT}`);
+      await new Promise(resolve => ws.on('open', resolve));
+
+      let gotReload = false;
+      ws.on('message', (data) => {
+        if (JSON.parse(data.toString()).type === 'reload') gotReload = true;
+      });
+
+      fs.writeFileSync(filePath, '<h2>Modified</h2>');
+      await sleep(500);
+
+      assert(gotReload, 'Should send reload on file change');
+      ws.close();
+    });
+
+    await test('does NOT send reload for non-.html files', async () => {
+      const ws = new WebSocket(`ws://localhost:${TEST_PORT}`);
+      await new Promise(resolve => ws.on('open', resolve));
+
+      let gotReload = false;
+      ws.on('message', (data) => {
+        if (JSON.parse(data.toString()).type === 'reload') gotReload = true;
+      });
+
+      fs.writeFileSync(path.join(TEST_DIR, 'data.txt'), 'not html');
+      await sleep(500);
+
+      assert(!gotReload, 'Should NOT reload for non-HTML files');
+      ws.close();
+    });
+
+    await test('clears .events on new screen', async () => {
+      // Create an .events file
+      const eventsFile = path.join(TEST_DIR, '.events');
+      fs.writeFileSync(eventsFile, '{"choice":"a"}\n');
+      assert(fs.existsSync(eventsFile));
+
+      fs.writeFileSync(path.join(TEST_DIR, 'clear-events.html'), '<h2>New screen</h2>');
+      await sleep(500);
+
+      assert(!fs.existsSync(eventsFile), '.events should be cleared on new screen');
+    });
+
+    await test('logs screen-added on new file', async () => {
+      stdoutAccum = '';
+      fs.writeFileSync(path.join(TEST_DIR, 'log-test.html'), '<h2>Log</h2>');
+      await sleep(500);
+
+      assert(stdoutAccum.includes('screen-added'), 'Should log screen-added');
+    });
+
+    await test('logs screen-updated on file change', async () => {
+      const filePath = path.join(TEST_DIR, 'log-update.html');
+      fs.writeFileSync(filePath, '<h2>V1</h2>');
+      await sleep(500);
+
+      stdoutAccum = '';
+      fs.writeFileSync(filePath, '<h2>V2</h2>');
+      await sleep(500);
+
+      assert(stdoutAccum.includes('screen-updated'), 'Should log screen-updated');
+    });
+
+    // ========== Helper.js Content ==========
+    console.log('\n--- Helper.js Verification ---');
+
+    await test('helper.js defines required APIs', () => {
+      const helperContent = fs.readFileSync(
+        path.join(__dirname, '../../skills/brainstorming/scripts/helper.js'), 'utf-8'
+      );
+      assert(helperContent.includes('toggleSelect'), 'Should define toggleSelect');
+      assert(helperContent.includes('sendEvent'), 'Should define sendEvent');
+      assert(helperContent.includes('selectedChoice'), 'Should track selectedChoice');
+      assert(helperContent.includes('brainstorm'), 'Should expose brainstorm API');
+      return Promise.resolve();
+    });
+
+    // ========== Frame Template ==========
+    console.log('\n--- Frame Template Verification ---');
+
+    await test('frame template has required structure', () => {
+      const template = fs.readFileSync(
+        path.join(__dirname, '../../skills/brainstorming/scripts/frame-template.html'), 'utf-8'
+      );
+      assert(template.includes('indicator-bar'), 'Should have indicator bar');
+      assert(template.includes('indicator-text'), 'Should have indicator text');
+      assert(template.includes('<!-- CONTENT -->'), 'Should have content placeholder');
+      assert(template.includes('claude-content'), 'Should have content container');
+      return Promise.resolve();
+    });
+
+    // ========== Summary ==========
+    console.log(`\n--- Results: ${passed} passed, ${failed} failed ---`);
+    if (failed > 0) process.exit(1);
 
   } finally {
     server.kill();
+    await sleep(100);
     cleanup();
   }
 }

tests/brainstorm-server/ws-protocol.test.js

@@ -0,0 +1,392 @@
+/**
+ * Unit tests for the zero-dependency WebSocket protocol implementation.
+ *
+ * Tests the WebSocket frame encoding/decoding, handshake computation,
+ * and protocol-level behavior independent of the HTTP server.
+ *
+ * The module under test exports:
+ *   - computeAcceptKey(clientKey) -> string
+ *   - encodeFrame(opcode, payload) -> Buffer
+ *   - decodeFrame(buffer) -> { opcode, payload, bytesConsumed } | null
+ *   - OPCODES: { TEXT, CLOSE, PING, PONG }
+ */
+
+const assert = require('assert');
+const crypto = require('crypto');
+const path = require('path');
+
+// The module under test — will be the new zero-dep server file
+const SERVER_PATH = path.join(__dirname, '../../skills/brainstorming/scripts/server.js');
+let ws;
+
+try {
+  ws = require(SERVER_PATH);
+} catch (e) {
+  // Module doesn't exist yet (TDD — tests written before implementation)
+  console.error(`Cannot load ${SERVER_PATH}: ${e.message}`);
+  console.error('This is expected if running tests before implementation.');
+  process.exit(1);
+}
+
+function runTests() {
+  let passed = 0;
+  let failed = 0;
+
+  function test(name, fn) {
+    try {
+      fn();
+      console.log(`  PASS: ${name}`);
+      passed++;
+    } catch (e) {
+      console.log(`  FAIL: ${name}`);
+      console.log(`    ${e.message}`);
+      failed++;
+    }
+  }
+
+  // ========== Handshake ==========
+  console.log('\n--- WebSocket Handshake ---');
+
+  test('computeAcceptKey produces correct RFC 6455 accept value', () => {
+    // RFC 6455 Section 4.2.2 example
+    // The magic GUID is "258EAFA5-E914-47DA-95CA-C5AB0DC85B11"
+    const clientKey = 'dGhlIHNhbXBsZSBub25jZQ==';
+    const expected = 's3pPLMBiTxaQ9kYGzzhZRbK+xOo=';
+    assert.strictEqual(ws.computeAcceptKey(clientKey), expected);
+  });
+
+  test('computeAcceptKey produces valid base64 for random keys', () => {
+    for (let i = 0; i < 10; i++) {
+      const randomKey = crypto.randomBytes(16).toString('base64');
+      const result = ws.computeAcceptKey(randomKey);
+      // Result should be valid base64
+      assert.strictEqual(Buffer.from(result, 'base64').toString('base64'), result);
+      // SHA-1 output is 20 bytes, base64 encoded = 28 chars
+      assert.strictEqual(result.length, 28);
+    }
+  });
+
+  // ========== Frame Encoding ==========
+  console.log('\n--- Frame Encoding (server -> client) ---');
+
+  test('encodes small text frame (< 126 bytes)', () => {
+    const payload = 'Hello';
+    const frame = ws.encodeFrame(ws.OPCODES.TEXT, Buffer.from(payload));
+    // FIN bit + TEXT opcode = 0x81, length = 5
+    assert.strictEqual(frame[0], 0x81);
+    assert.strictEqual(frame[1], 5);
+    assert.strictEqual(frame.slice(2).toString(), 'Hello');
+    assert.strictEqual(frame.length, 7);
+  });
+
+  test('encodes empty text frame', () => {
+    const frame = ws.encodeFrame(ws.OPCODES.TEXT, Buffer.alloc(0));
+    assert.strictEqual(frame[0], 0x81);
+    assert.strictEqual(frame[1], 0);
+    assert.strictEqual(frame.length, 2);
+  });
+
+  test('encodes medium text frame (126-65535 bytes)', () => {
+    const payload = Buffer.alloc(200, 0x41); // 200 'A's
+    const frame = ws.encodeFrame(ws.OPCODES.TEXT, payload);
+    assert.strictEqual(frame[0], 0x81);
+    assert.strictEqual(frame[1], 126); // extended length marker
+    assert.strictEqual(frame.readUInt16BE(2), 200);
+    assert.strictEqual(frame.slice(4).toString(), payload.toString());
+    assert.strictEqual(frame.length, 204);
+  });
+
+  test('encodes frame at exactly 126 bytes (boundary)', () => {
+    const payload = Buffer.alloc(126, 0x42);
+    const frame = ws.encodeFrame(ws.OPCODES.TEXT, payload);
+    assert.strictEqual(frame[1], 126); // extended length marker
+    assert.strictEqual(frame.readUInt16BE(2), 126);
+    assert.strictEqual(frame.length, 130);
+  });
+
+  test('encodes frame at exactly 125 bytes (max small)', () => {
+    const payload = Buffer.alloc(125, 0x43);
+    const frame = ws.encodeFrame(ws.OPCODES.TEXT, payload);
+    assert.strictEqual(frame[1], 125);
+    assert.strictEqual(frame.length, 127);
+  });
+
+  test('encodes large frame (> 65535 bytes)', () => {
+    const payload = Buffer.alloc(70000, 0x44);
+    const frame = ws.encodeFrame(ws.OPCODES.TEXT, payload);
+    assert.strictEqual(frame[0], 0x81);
+    assert.strictEqual(frame[1], 127); // 64-bit length marker
+    // 8-byte extended length at offset 2
+    const len = Number(frame.readBigUInt64BE(2));
+    assert.strictEqual(len, 70000);
+    assert.strictEqual(frame.length, 10 + 70000);
+  });
+
+  test('encodes close frame', () => {
+    const frame = ws.encodeFrame(ws.OPCODES.CLOSE, Buffer.alloc(0));
+    assert.strictEqual(frame[0], 0x88); // FIN + CLOSE
+    assert.strictEqual(frame[1], 0);
+  });
+
+  test('encodes pong frame with payload', () => {
+    const payload = Buffer.from('ping-data');
+    const frame = ws.encodeFrame(ws.OPCODES.PONG, payload);
+    assert.strictEqual(frame[0], 0x8A); // FIN + PONG
+    assert.strictEqual(frame[1], payload.length);
+    assert.strictEqual(frame.slice(2).toString(), 'ping-data');
+  });
+
+  test('server frames are never masked (per RFC 6455)', () => {
+    const frame = ws.encodeFrame(ws.OPCODES.TEXT, Buffer.from('test'));
+    // Bit 7 of byte 1 is the mask bit — must be 0 for server frames
+    assert.strictEqual(frame[1] & 0x80, 0);
+  });
+
+  // ========== Frame Decoding ==========
+  console.log('\n--- Frame Decoding (client -> server) ---');
+
+  // Helper: create a masked client frame
+  function makeClientFrame(opcode, payload, fin = true) {
+    const buf = Buffer.from(payload);
+    const mask = crypto.randomBytes(4);
+    const masked = Buffer.alloc(buf.length);
+    for (let i = 0; i < buf.length; i++) {
+      masked[i] = buf[i] ^ mask[i % 4];
+    }
+
+    let header;
+    const finBit = fin ? 0x80 : 0x00;
+    if (buf.length < 126) {
+      header = Buffer.alloc(6);
+      header[0] = finBit | opcode;
+      header[1] = 0x80 | buf.length; // mask bit set
+      mask.copy(header, 2);
+    } else if (buf.length < 65536) {
+      header = Buffer.alloc(8);
+      header[0] = finBit | opcode;
+      header[1] = 0x80 | 126;
+      header.writeUInt16BE(buf.length, 2);
+      mask.copy(header, 4);
+    } else {
+      header = Buffer.alloc(14);
+      header[0] = finBit | opcode;
+      header[1] = 0x80 | 127;
+      header.writeBigUInt64BE(BigInt(buf.length), 2);
+      mask.copy(header, 10);
+    }
+
+    return Buffer.concat([header, masked]);
+  }
+
+  test('decodes small masked text frame', () => {
+    const frame = makeClientFrame(0x01, 'Hello');
+    const result = ws.decodeFrame(frame);
+    assert(result, 'Should return a result');
+    assert.strictEqual(result.opcode, ws.OPCODES.TEXT);
+    assert.strictEqual(result.payload.toString(), 'Hello');
+    assert.strictEqual(result.bytesConsumed, frame.length);
+  });
+
+  test('decodes empty masked text frame', () => {
+    const frame = makeClientFrame(0x01, '');
+    const result = ws.decodeFrame(frame);
+    assert(result, 'Should return a result');
+    assert.strictEqual(result.opcode, ws.OPCODES.TEXT);
+    assert.strictEqual(result.payload.length, 0);
+  });
+
+  test('decodes medium masked text frame (126-65535 bytes)', () => {
+    const payload = 'A'.repeat(200);
+    const frame = makeClientFrame(0x01, payload);
+    const result = ws.decodeFrame(frame);
+    assert(result, 'Should return a result');
+    assert.strictEqual(result.payload.toString(), payload);
+  });
+
+  test('decodes large masked text frame (> 65535 bytes)', () => {
+    const payload = 'B'.repeat(70000);
+    const frame = makeClientFrame(0x01, payload);
+    const result = ws.decodeFrame(frame);
+    assert(result, 'Should return a result');
+    assert.strictEqual(result.payload.length, 70000);
+    assert.strictEqual(result.payload.toString(), payload);
+  });
+
+  test('decodes masked close frame', () => {
+    const frame = makeClientFrame(0x08, '');
+    const result = ws.decodeFrame(frame);
+    assert(result, 'Should return a result');
+    assert.strictEqual(result.opcode, ws.OPCODES.CLOSE);
+  });
+
+  test('decodes masked ping frame', () => {
+    const frame = makeClientFrame(0x09, 'ping!');
+    const result = ws.decodeFrame(frame);
+    assert(result, 'Should return a result');
+    assert.strictEqual(result.opcode, ws.OPCODES.PING);
+    assert.strictEqual(result.payload.toString(), 'ping!');
+  });
+
+  test('returns null for incomplete frame (not enough header bytes)', () => {
+    const result = ws.decodeFrame(Buffer.from([0x81]));
+    assert.strictEqual(result, null, 'Should return null for 1-byte buffer');
+  });
+
+  test('returns null for incomplete frame (header ok, payload truncated)', () => {
+    // Create a valid frame then truncate it
+    const frame = makeClientFrame(0x01, 'Hello World');
+    const truncated = frame.slice(0, frame.length - 3);
+    const result = ws.decodeFrame(truncated);
+    assert.strictEqual(result, null, 'Should return null for truncated frame');
+  });
+
+  test('returns null for incomplete extended-length header', () => {
+    // Frame claiming 16-bit length but only 3 bytes total
+    const buf = Buffer.alloc(3);
+    buf[0] = 0x81;
+    buf[1] = 0x80 | 126; // masked, 16-bit extended
+    // Missing the 2 length bytes + mask
+    const result = ws.decodeFrame(buf);
+    assert.strictEqual(result, null);
+  });
+
+  test('rejects unmasked client frame', () => {
+    // Server MUST reject unmasked client frames per RFC 6455 Section 5.1
+    const buf = Buffer.alloc(7);
+    buf[0] = 0x81; // FIN + TEXT
+    buf[1] = 5;    // length 5, NO mask bit
+    Buffer.from('Hello').copy(buf, 2);
+    assert.throws(() => ws.decodeFrame(buf), /mask/i, 'Should reject unmasked client frame');
+  });
+
+  test('handles multiple frames in a single buffer', () => {
+    const frame1 = makeClientFrame(0x01, 'first');
+    const frame2 = makeClientFrame(0x01, 'second');
+    const combined = Buffer.concat([frame1, frame2]);
+
+    const result1 = ws.decodeFrame(combined);
+    assert(result1, 'Should decode first frame');
+    assert.strictEqual(result1.payload.toString(), 'first');
+    assert.strictEqual(result1.bytesConsumed, frame1.length);
+
+    const result2 = ws.decodeFrame(combined.slice(result1.bytesConsumed));
+    assert(result2, 'Should decode second frame');
+    assert.strictEqual(result2.payload.toString(), 'second');
+  });
+
+  test('correctly unmasks with all mask byte values', () => {
+    // Use a known mask to verify unmasking arithmetic
+    const payload = Buffer.from('ABCDEFGH');
+    const mask = Buffer.from([0xFF, 0x00, 0xAA, 0x55]);
+    const masked = Buffer.alloc(payload.length);
+    for (let i = 0; i < payload.length; i++) {
+      masked[i] = payload[i] ^ mask[i % 4];
+    }
+
+    // Build frame manually
+    const header = Buffer.alloc(6);
+    header[0] = 0x81; // FIN + TEXT
+    header[1] = 0x80 | payload.length;
+    mask.copy(header, 2);
+    const frame = Buffer.concat([header, masked]);
+
+    const result = ws.decodeFrame(frame);
+    assert.strictEqual(result.payload.toString(), 'ABCDEFGH');
+  });
+
+  // ========== Frame Encoding Boundary at 65535/65536 ==========
+  console.log('\n--- Frame Size Boundaries ---');
+
+  test('encodes frame at exactly 65535 bytes (max 16-bit)', () => {
+    const payload = Buffer.alloc(65535, 0x45);
+    const frame = ws.encodeFrame(ws.OPCODES.TEXT, payload);
+    assert.strictEqual(frame[1], 126);
+    assert.strictEqual(frame.readUInt16BE(2), 65535);
+    assert.strictEqual(frame.length, 4 + 65535);
+  });
+
+  test('encodes frame at exactly 65536 bytes (min 64-bit)', () => {
+    const payload = Buffer.alloc(65536, 0x46);
+    const frame = ws.encodeFrame(ws.OPCODES.TEXT, payload);
+    assert.strictEqual(frame[1], 127);
+    assert.strictEqual(Number(frame.readBigUInt64BE(2)), 65536);
+    assert.strictEqual(frame.length, 10 + 65536);
+  });
+
+  test('decodes frame at 65535 bytes boundary', () => {
+    const payload = 'X'.repeat(65535);
+    const frame = makeClientFrame(0x01, payload);
+    const result = ws.decodeFrame(frame);
+    assert(result);
+    assert.strictEqual(result.payload.length, 65535);
+  });
+
+  test('decodes frame at 65536 bytes boundary', () => {
+    const payload = 'Y'.repeat(65536);
+    const frame = makeClientFrame(0x01, payload);
+    const result = ws.decodeFrame(frame);
+    assert(result);
+    assert.strictEqual(result.payload.length, 65536);
+  });
+
+  // ========== Close Frame with Status Code ==========
+  console.log('\n--- Close Frame Details ---');
+
+  test('decodes close frame with status code', () => {
+    // Close frame payload: 2-byte status code + optional reason
+    const statusBuf = Buffer.alloc(2);
+    statusBuf.writeUInt16BE(1000); // Normal closure
+    const frame = makeClientFrame(0x08, statusBuf);
+    const result = ws.decodeFrame(frame);
+    assert.strictEqual(result.opcode, ws.OPCODES.CLOSE);
+    assert.strictEqual(result.payload.readUInt16BE(0), 1000);
+  });
+
+  test('decodes close frame with status code and reason', () => {
+    const reason = 'Normal shutdown';
+    const payload = Buffer.alloc(2 + reason.length);
+    payload.writeUInt16BE(1000);
+    payload.write(reason, 2);
+    const frame = makeClientFrame(0x08, payload);
+    const result = ws.decodeFrame(frame);
+    assert.strictEqual(result.opcode, ws.OPCODES.CLOSE);
+    assert.strictEqual(result.payload.slice(2).toString(), reason);
+  });
+
+  // ========== JSON Roundtrip ==========
+  console.log('\n--- JSON Message Roundtrip ---');
+
+  test('roundtrip encode/decode of JSON message', () => {
+    const msg = { type: 'reload' };
+    const payload = Buffer.from(JSON.stringify(msg));
+    const serverFrame = ws.encodeFrame(ws.OPCODES.TEXT, payload);
+
+    // Verify we can read what we encoded (unmasked server frame)
+    // Server frames don't go through decodeFrame (that expects masked),
+    // so just verify the payload bytes directly
+    let offset;
+    if (serverFrame[1] < 126) {
+      offset = 2;
+    } else if (serverFrame[1] === 126) {
+      offset = 4;
+    } else {
+      offset = 10;
+    }
+    const decoded = JSON.parse(serverFrame.slice(offset).toString());
+    assert.deepStrictEqual(decoded, msg);
+  });
+
+  test('roundtrip masked client JSON message', () => {
+    const msg = { type: 'click', choice: 'a', text: 'Option A', timestamp: 1706000101 };
+    const frame = makeClientFrame(0x01, JSON.stringify(msg));
+    const result = ws.decodeFrame(frame);
+    const decoded = JSON.parse(result.payload.toString());
+    assert.deepStrictEqual(decoded, msg);
+  });
+
+  // ========== Summary ==========
+  console.log(`\n--- Results: ${passed} passed, ${failed} failed ---`);
+  if (failed > 0) process.exit(1);
+}
+
+runTests();

tests/claude-code/analyze-token-usage.py

@@ -64,7 +64,7 @@ def analyze_main_session(filepath):
                         subagent_usage[agent_id]['output_tokens'] += usage.get('output_tokens', 0)
                         subagent_usage[agent_id]['cache_creation'] += usage.get('cache_creation_input_tokens', 0)
                         subagent_usage[agent_id]['cache_read'] += usage.get('cache_read_input_tokens', 0)
-            except:
+            except Exception:
                 pass
 
     return main_usage, dict(subagent_usage)

tests/opencode/run-tests.sh

@@ -44,7 +44,6 @@ while [[ $# -gt 0 ]]; do
             echo ""
             echo "Tests:"
             echo "  test-plugin-loading.sh  Verify plugin installation and structure"
-            echo "  test-skills-core.sh     Test skills-core.js library functions"
             echo "  test-tools.sh           Test use_skill and find_skills tools (integration)"
             echo "  test-priority.sh        Test skill priority resolution (integration)"
             exit 0
@@ -60,7 +59,6 @@ done
 # List of tests to run (no external dependencies)
 tests=(
     "test-plugin-loading.sh"
-    "test-skills-core.sh"
 )
 
 # Integration tests (require OpenCode)

tests/opencode/test-plugin-loading.sh

@@ -30,17 +30,8 @@ else
     exit 1
 fi
 
-# Test 2: Verify lib/skills-core.js is in place
-echo "Test 2: Checking skills-core.js..."
-if [ -f "$HOME/.config/opencode/superpowers/lib/skills-core.js" ]; then
-    echo "  [PASS] skills-core.js exists"
-else
-    echo "  [FAIL] skills-core.js not found"
-    exit 1
-fi
-
-# Test 3: Verify skills directory is populated
-echo "Test 3: Checking skills directory..."
+# Test 2: Verify skills directory is populated
+echo "Test 2: Checking skills directory..."
 skill_count=$(find "$HOME/.config/opencode/superpowers/skills" -name "SKILL.md" | wc -l)
 if [ "$skill_count" -gt 0 ]; then
     echo "  [PASS] Found $skill_count skills installed"

tests/opencode/test-skills-core.sh

@@ -1,440 +0,0 @@
-#!/usr/bin/env bash
-# Test: Skills Core Library
-# Tests the skills-core.js library functions directly via Node.js
-# Does not require OpenCode - tests pure library functionality
-set -euo pipefail
-
-SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
-
-echo "=== Test: Skills Core Library ==="
-
-# Source setup to create isolated environment
-source "$SCRIPT_DIR/setup.sh"
-
-# Trap to cleanup on exit
-trap cleanup_test_env EXIT
-
-# Test 1: Test extractFrontmatter function
-echo "Test 1: Testing extractFrontmatter..."
-
-# Create test file with frontmatter
-test_skill_dir="$TEST_HOME/test-skill"
-mkdir -p "$test_skill_dir"
-cat > "$test_skill_dir/SKILL.md" <<'EOF'
----
-name: test-skill
-description: A test skill for unit testing
----
-# Test Skill Content
-
-This is the content.
-EOF
-
-# Run Node.js test using inline function (avoids ESM path resolution issues in test env)
-result=$(node -e "
-const path = require('path');
-const fs = require('fs');
-
-// Inline the extractFrontmatter function for testing
-function extractFrontmatter(filePath) {
-    try {
-        const content = fs.readFileSync(filePath, 'utf8');
-        const lines = content.split('\n');
-        let inFrontmatter = false;
-        let name = '';
-        let description = '';
-        for (const line of lines) {
-            if (line.trim() === '---') {
-                if (inFrontmatter) break;
-                inFrontmatter = true;
-                continue;
-            }
-            if (inFrontmatter) {
-                const match = line.match(/^(\w+):\s*(.*)$/);
-                if (match) {
-                    const [, key, value] = match;
-                    if (key === 'name') name = value.trim();
-                    if (key === 'description') description = value.trim();
-                }
-            }
-        }
-        return { name, description };
-    } catch (error) {
-        return { name: '', description: '' };
-    }
-}
-
-const result = extractFrontmatter('$TEST_HOME/test-skill/SKILL.md');
-console.log(JSON.stringify(result));
-" 2>&1)
-
-if echo "$result" | grep -q '"name":"test-skill"'; then
-    echo "  [PASS] extractFrontmatter parses name correctly"
-else
-    echo "  [FAIL] extractFrontmatter did not parse name"
-    echo "  Result: $result"
-    exit 1
-fi
-
-if echo "$result" | grep -q '"description":"A test skill for unit testing"'; then
-    echo "  [PASS] extractFrontmatter parses description correctly"
-else
-    echo "  [FAIL] extractFrontmatter did not parse description"
-    exit 1
-fi
-
-# Test 2: Test stripFrontmatter function
-echo ""
-echo "Test 2: Testing stripFrontmatter..."
-
-result=$(node -e "
-const fs = require('fs');
-
-function stripFrontmatter(content) {
-    const lines = content.split('\n');
-    let inFrontmatter = false;
-    let frontmatterEnded = false;
-    const contentLines = [];
-    for (const line of lines) {
-        if (line.trim() === '---') {
-            if (inFrontmatter) {
-                frontmatterEnded = true;
-                continue;
-            }
-            inFrontmatter = true;
-            continue;
-        }
-        if (frontmatterEnded || !inFrontmatter) {
-            contentLines.push(line);
-        }
-    }
-    return contentLines.join('\n').trim();
-}
-
-const content = fs.readFileSync('$TEST_HOME/test-skill/SKILL.md', 'utf8');
-const stripped = stripFrontmatter(content);
-console.log(stripped);
-" 2>&1)
-
-if echo "$result" | grep -q "# Test Skill Content"; then
-    echo "  [PASS] stripFrontmatter preserves content"
-else
-    echo "  [FAIL] stripFrontmatter did not preserve content"
-    echo "  Result: $result"
-    exit 1
-fi
-
-if ! echo "$result" | grep -q "name: test-skill"; then
-    echo "  [PASS] stripFrontmatter removes frontmatter"
-else
-    echo "  [FAIL] stripFrontmatter did not remove frontmatter"
-    exit 1
-fi
-
-# Test 3: Test findSkillsInDir function
-echo ""
-echo "Test 3: Testing findSkillsInDir..."
-
-# Create multiple test skills
-mkdir -p "$TEST_HOME/skills-dir/skill-a"
-mkdir -p "$TEST_HOME/skills-dir/skill-b"
-mkdir -p "$TEST_HOME/skills-dir/nested/skill-c"
-
-cat > "$TEST_HOME/skills-dir/skill-a/SKILL.md" <<'EOF'
----
-name: skill-a
-description: First skill
----
-# Skill A
-EOF
-
-cat > "$TEST_HOME/skills-dir/skill-b/SKILL.md" <<'EOF'
----
-name: skill-b
-description: Second skill
----
-# Skill B
-EOF
-
-cat > "$TEST_HOME/skills-dir/nested/skill-c/SKILL.md" <<'EOF'
----
-name: skill-c
-description: Nested skill
----
-# Skill C
-EOF
-
-result=$(node -e "
-const fs = require('fs');
-const path = require('path');
-
-function extractFrontmatter(filePath) {
-    try {
-        const content = fs.readFileSync(filePath, 'utf8');
-        const lines = content.split('\n');
-        let inFrontmatter = false;
-        let name = '';
-        let description = '';
-        for (const line of lines) {
-            if (line.trim() === '---') {
-                if (inFrontmatter) break;
-                inFrontmatter = true;
-                continue;
-            }
-            if (inFrontmatter) {
-                const match = line.match(/^(\w+):\s*(.*)$/);
-                if (match) {
-                    const [, key, value] = match;
-                    if (key === 'name') name = value.trim();
-                    if (key === 'description') description = value.trim();
-                }
-            }
-        }
-        return { name, description };
-    } catch (error) {
-        return { name: '', description: '' };
-    }
-}
-
-function findSkillsInDir(dir, sourceType, maxDepth = 3) {
-    const skills = [];
-    if (!fs.existsSync(dir)) return skills;
-    function recurse(currentDir, depth) {
-        if (depth > maxDepth) return;
-        const entries = fs.readdirSync(currentDir, { withFileTypes: true });
-        for (const entry of entries) {
-            const fullPath = path.join(currentDir, entry.name);
-            if (entry.isDirectory()) {
-                const skillFile = path.join(fullPath, 'SKILL.md');
-                if (fs.existsSync(skillFile)) {
-                    const { name, description } = extractFrontmatter(skillFile);
-                    skills.push({
-                        path: fullPath,
-                        skillFile: skillFile,
-                        name: name || entry.name,
-                        description: description || '',
-                        sourceType: sourceType
-                    });
-                }
-                recurse(fullPath, depth + 1);
-            }
-        }
-    }
-    recurse(dir, 0);
-    return skills;
-}
-
-const skills = findSkillsInDir('$TEST_HOME/skills-dir', 'test', 3);
-console.log(JSON.stringify(skills, null, 2));
-" 2>&1)
-
-skill_count=$(echo "$result" | grep -c '"name":' || echo "0")
-
-if [ "$skill_count" -ge 3 ]; then
-    echo "  [PASS] findSkillsInDir found all skills (found $skill_count)"
-else
-    echo "  [FAIL] findSkillsInDir did not find all skills (expected 3, found $skill_count)"
-    echo "  Result: $result"
-    exit 1
-fi
-
-if echo "$result" | grep -q '"name": "skill-c"'; then
-    echo "  [PASS] findSkillsInDir found nested skills"
-else
-    echo "  [FAIL] findSkillsInDir did not find nested skill"
-    exit 1
-fi
-
-# Test 4: Test resolveSkillPath function
-echo ""
-echo "Test 4: Testing resolveSkillPath..."
-
-# Create skills in personal and superpowers locations for testing
-mkdir -p "$TEST_HOME/personal-skills/shared-skill"
-mkdir -p "$TEST_HOME/superpowers-skills/shared-skill"
-mkdir -p "$TEST_HOME/superpowers-skills/unique-skill"
-
-cat > "$TEST_HOME/personal-skills/shared-skill/SKILL.md" <<'EOF'
----
-name: shared-skill
-description: Personal version
----
-# Personal Shared
-EOF
-
-cat > "$TEST_HOME/superpowers-skills/shared-skill/SKILL.md" <<'EOF'
----
-name: shared-skill
-description: Superpowers version
----
-# Superpowers Shared
-EOF
-
-cat > "$TEST_HOME/superpowers-skills/unique-skill/SKILL.md" <<'EOF'
----
-name: unique-skill
-description: Only in superpowers
----
-# Unique
-EOF
-
-result=$(node -e "
-const fs = require('fs');
-const path = require('path');
-
-function resolveSkillPath(skillName, superpowersDir, personalDir) {
-    const forceSuperpowers = skillName.startsWith('superpowers:');
-    const actualSkillName = forceSuperpowers ? skillName.replace(/^superpowers:/, '') : skillName;
-
-    if (!forceSuperpowers && personalDir) {
-        const personalPath = path.join(personalDir, actualSkillName);
-        const personalSkillFile = path.join(personalPath, 'SKILL.md');
-        if (fs.existsSync(personalSkillFile)) {
-            return {
-                skillFile: personalSkillFile,
-                sourceType: 'personal',
-                skillPath: actualSkillName
-            };
-        }
-    }
-
-    if (superpowersDir) {
-        const superpowersPath = path.join(superpowersDir, actualSkillName);
-        const superpowersSkillFile = path.join(superpowersPath, 'SKILL.md');
-        if (fs.existsSync(superpowersSkillFile)) {
-            return {
-                skillFile: superpowersSkillFile,
-                sourceType: 'superpowers',
-                skillPath: actualSkillName
-            };
-        }
-    }
-
-    return null;
-}
-
-const superpowersDir = '$TEST_HOME/superpowers-skills';
-const personalDir = '$TEST_HOME/personal-skills';
-
-// Test 1: Shared skill should resolve to personal
-const shared = resolveSkillPath('shared-skill', superpowersDir, personalDir);
-console.log('SHARED:', JSON.stringify(shared));
-
-// Test 2: superpowers: prefix should force superpowers
-const forced = resolveSkillPath('superpowers:shared-skill', superpowersDir, personalDir);
-console.log('FORCED:', JSON.stringify(forced));
-
-// Test 3: Unique skill should resolve to superpowers
-const unique = resolveSkillPath('unique-skill', superpowersDir, personalDir);
-console.log('UNIQUE:', JSON.stringify(unique));
-
-// Test 4: Non-existent skill
-const notfound = resolveSkillPath('not-a-skill', superpowersDir, personalDir);
-console.log('NOTFOUND:', JSON.stringify(notfound));
-" 2>&1)
-
-if echo "$result" | grep -q 'SHARED:.*"sourceType":"personal"'; then
-    echo "  [PASS] Personal skills shadow superpowers skills"
-else
-    echo "  [FAIL] Personal skills not shadowing correctly"
-    echo "  Result: $result"
-    exit 1
-fi
-
-if echo "$result" | grep -q 'FORCED:.*"sourceType":"superpowers"'; then
-    echo "  [PASS] superpowers: prefix forces superpowers resolution"
-else
-    echo "  [FAIL] superpowers: prefix not working"
-    exit 1
-fi
-
-if echo "$result" | grep -q 'UNIQUE:.*"sourceType":"superpowers"'; then
-    echo "  [PASS] Unique superpowers skills are found"
-else
-    echo "  [FAIL] Unique superpowers skills not found"
-    exit 1
-fi
-
-if echo "$result" | grep -q 'NOTFOUND: null'; then
-    echo "  [PASS] Non-existent skills return null"
-else
-    echo "  [FAIL] Non-existent skills should return null"
-    exit 1
-fi
-
-# Test 5: Test checkForUpdates function
-echo ""
-echo "Test 5: Testing checkForUpdates..."
-
-# Create a test git repo
-mkdir -p "$TEST_HOME/test-repo"
-cd "$TEST_HOME/test-repo"
-git init --quiet
-git config user.email "test@test.com"
-git config user.name "Test"
-echo "test" > file.txt
-git add file.txt
-git commit -m "initial" --quiet
-cd "$SCRIPT_DIR"
-
-# Test checkForUpdates on repo without remote (should return false, not error)
-result=$(node -e "
-const { execSync } = require('child_process');
-
-function checkForUpdates(repoDir) {
-    try {
-        const output = execSync('git fetch origin && git status --porcelain=v1 --branch', {
-            cwd: repoDir,
-            timeout: 3000,
-            encoding: 'utf8',
-            stdio: 'pipe'
-        });
-        const statusLines = output.split('\n');
-        for (const line of statusLines) {
-            if (line.startsWith('## ') && line.includes('[behind ')) {
-                return true;
-            }
-        }
-        return false;
-    } catch (error) {
-        return false;
-    }
-}
-
-// Test 1: Repo without remote should return false (graceful error handling)
-const result1 = checkForUpdates('$TEST_HOME/test-repo');
-console.log('NO_REMOTE:', result1);
-
-// Test 2: Non-existent directory should return false
-const result2 = checkForUpdates('$TEST_HOME/nonexistent');
-console.log('NONEXISTENT:', result2);
-
-// Test 3: Non-git directory should return false
-const result3 = checkForUpdates('$TEST_HOME');
-console.log('NOT_GIT:', result3);
-" 2>&1)
-
-if echo "$result" | grep -q 'NO_REMOTE: false'; then
-    echo "  [PASS] checkForUpdates handles repo without remote gracefully"
-else
-    echo "  [FAIL] checkForUpdates should return false for repo without remote"
-    echo "  Result: $result"
-    exit 1
-fi
-
-if echo "$result" | grep -q 'NONEXISTENT: false'; then
-    echo "  [PASS] checkForUpdates handles non-existent directory"
-else
-    echo "  [FAIL] checkForUpdates should return false for non-existent directory"
-    exit 1
-fi
-
-if echo "$result" | grep -q 'NOT_GIT: false'; then
-    echo "  [PASS] checkForUpdates handles non-git directory"
-else
-    echo "  [FAIL] checkForUpdates should return false for non-git directory"
-    exit 1
-fi
-
-echo ""
-echo "=== All skills-core library tests passed ==="