Fix ~/ path expansion on Windows — use $HOME instead

PowerShell doesn't expand ~ when passed as an argument to node,
causing MODULE_NOT_FOUND errors. $HOME expands correctly in both
bash and PowerShell.

Fixes #285

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

.codex/INSTALL.md

@@ -21,7 +21,7 @@ Quick setup to enable superpowers skills in Codex.
    ## Superpowers System
 
    <EXTREMELY_IMPORTANT>
-   You have superpowers. Superpowers teach you new skills and capabilities. RIGHT NOW run: `~/.codex/superpowers/.codex/superpowers-codex bootstrap` and follow the instructions it returns.
+   You have superpowers. Superpowers teach you new skills and capabilities. RIGHT NOW run: `node $HOME/.codex/superpowers/.codex/superpowers-codex bootstrap` and follow the instructions it returns.
    </EXTREMELY_IMPORTANT>
    ```
 
@@ -29,7 +29,7 @@ Quick setup to enable superpowers skills in Codex.
 
 Test the installation:
 ```bash
-~/.codex/superpowers/.codex/superpowers-codex bootstrap
+node $HOME/.codex/superpowers/.codex/superpowers-codex bootstrap
 ```
 
 You should see skill listings and bootstrap instructions. The system is now ready for use.

.codex/superpowers-bootstrap.md

@@ -4,14 +4,14 @@
 You have superpowers.
 
 **Tool for running skills:**
-- `~/.codex/superpowers/.codex/superpowers-codex use-skill <skill-name>`
+- `node $HOME/.codex/superpowers/.codex/superpowers-codex use-skill <skill-name>`
 
 **Tool Mapping for Codex:**
 When skills reference tools you don't have, substitute your equivalent tools:
 - `TodoWrite` → `update_plan` (your planning/task tracking tool)
 - `Task` tool with subagents → Use Codex collab `spawn_agent` + `wait` when available; if collab is disabled, state that and proceed sequentially
 - `Subagent` / `Agent` tool mentions → Map to `spawn_agent` (collab) or sequential fallback when collab is disabled
-- `Skill` tool → `~/.codex/superpowers/.codex/superpowers-codex use-skill` command (already available)
+- `Skill` tool → `node $HOME/.codex/superpowers/.codex/superpowers-codex use-skill` command (already available)
 - `Read`, `Write`, `Edit`, `Bash` → Use your native tools with similar functions
 
 **Skills naming:**
@@ -21,7 +21,7 @@ When skills reference tools you don't have, substitute your equivalent tools:
 
 **Critical Rules:**
 - Before ANY task, review the skills list (shown below)
-- If a relevant skill exists, you MUST use `~/.codex/superpowers/.codex/superpowers-codex use-skill` to load it
+- If a relevant skill exists, you MUST use `node $HOME/.codex/superpowers/.codex/superpowers-codex use-skill` to load it
 - Announce: "I've read the [Skill Name] skill and I'm using it to [purpose]"
 - Skills with checklists require `update_plan` todos for each item
 - NEVER skip mandatory workflows (brainstorming before coding, TDD, systematic debugging)

.codex/superpowers-codex.cmd

@@ -0,0 +1 @@
+@node "%~dp0superpowers-codex" %*

README.md

@@ -44,18 +44,7 @@ Then install the plugin from this marketplace:
 
 ### Verify Installation
 
-Check that commands appear:
-
-```bash
-/help
-```
-
-```
-# Should see:
-# /superpowers:brainstorm - Interactive design refinement
-# /superpowers:write-plan - Create implementation plan
-# /superpowers:execute-plan - Execute plan in batches
-```
+Start a new session and ask Claude to help with something that would trigger a skill (e.g., "help me plan this feature" or "let's debug this issue"). Claude should automatically invoke the relevant superpowers skill.
 
 ### Codex
 

RELEASE-NOTES.md

@@ -1,5 +1,65 @@
 # Superpowers Release Notes
 
+## Unreleased
+
+### Breaking Changes
+
+**OpenCode: Switched to native skills system**
+
+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
+
+**Fixed Windows hook execution for Claude Code 2.1.x**
+
+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.
+
+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).
+
+**Windows: SessionStart hook runs async to prevent terminal freeze**
+
+The synchronous SessionStart hook blocked the TUI from entering raw mode on Windows, freezing terminal input. The pure-bash `escape_for_json` function is O(n^2) on Windows Git Bash, taking 60+ seconds. Running the hook async prevents the freeze while still injecting superpowers context.
+
+### New Features
+
+**Visual companion for brainstorming skill**
+
+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.
+
+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
+
+The visual companion is opt-in and falls back gracefully to terminal-only operation.
+
+### Improvements
+
+**Instruction priority clarified in using-superpowers**
+
+Added explicit instruction priority hierarchy to prevent conflicts with user preferences:
+
+1. User's explicit instructions (CLAUDE.md, direct requests) — highest priority
+2. Superpowers skills — override default system behavior where they conflict
+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.
+
+---
+
 ## v4.1.1 (2026-01-23)
 
 ### Fixes

docs/README.codex.md

@@ -35,7 +35,7 @@ The bootstrap file is included in the repository at `.codex/superpowers-bootstra
 Tell Codex:
 
 ```
-Run ~/.codex/superpowers/.codex/superpowers-codex find-skills to show available skills
+Run node $HOME/.codex/superpowers/.codex/superpowers-codex find-skills to show available skills
 ```
 
 You should see a list of available skills with descriptions.
@@ -45,19 +45,19 @@ You should see a list of available skills with descriptions.
 ### Finding Skills
 
 ```
-Run ~/.codex/superpowers/.codex/superpowers-codex find-skills
+Run node $HOME/.codex/superpowers/.codex/superpowers-codex find-skills
 ```
 
 ### Loading a Skill
 
 ```
-Run ~/.codex/superpowers/.codex/superpowers-codex use-skill superpowers:brainstorming
+Run node $HOME/.codex/superpowers/.codex/superpowers-codex use-skill superpowers:brainstorming
 ```
 
 ### Bootstrap All Skills
 
 ```
-Run ~/.codex/superpowers/.codex/superpowers-codex bootstrap
+Run node $HOME/.codex/superpowers/.codex/superpowers-codex bootstrap
 ```
 
 This loads the complete bootstrap with all skill information.
@@ -109,7 +109,7 @@ Skills written for Claude Code are adapted for Codex with these mappings:
 - `TodoWrite` → `update_plan`
 - `Task` with subagents → Use collab `spawn_agent` + `wait` when available; if collab is disabled, say so and proceed sequentially
 - `Subagent` / `Agent` tool mentions → Map to `spawn_agent` (collab) or sequential fallback when collab is disabled
-- `Skill` tool → `~/.codex/superpowers/.codex/superpowers-codex use-skill`
+- `Skill` tool → `node $HOME/.codex/superpowers/.codex/superpowers-codex use-skill`
 - File operations → Native Codex tools
 
 ## Updating
@@ -124,7 +124,7 @@ git pull
 ### Skills not found
 
 1. Verify installation: `ls ~/.codex/superpowers/skills`
-2. Check CLI works: `~/.codex/superpowers/.codex/superpowers-codex find-skills`
+2. Check CLI works: `node $HOME/.codex/superpowers/.codex/superpowers-codex find-skills`
 3. Verify skills have SKILL.md files
 
 ### CLI script not executable

hooks/hooks.json

@@ -6,7 +6,8 @@
         "hooks": [
           {
             "type": "command",
-            "command": "${CLAUDE_PLUGIN_ROOT}/hooks/session-start.sh"
+            "command": "${CLAUDE_PLUGIN_ROOT}/hooks/session-start.sh",
+            "async": true
           }
         ]
       }

hooks/session-start.sh

@@ -17,23 +17,17 @@ fi
 # Read using-superpowers content
 using_superpowers_content=$(cat "${PLUGIN_ROOT}/skills/using-superpowers/SKILL.md" 2>&1 || echo "Error reading using-superpowers skill")
 
-# Escape outputs for JSON using pure bash
+# Escape string for JSON embedding using bash parameter substitution.
+# Each ${s//old/new} is a single C-level pass - orders of magnitude
+# faster than the character-by-character loop this replaces.
 escape_for_json() {
-    local input="$1"
-    local output=""
-    local i char
-    for (( i=0; i<${#input}; i++ )); do
-        char="${input:$i:1}"
-        case "$char" in
-            $'\\') output+='\\' ;;
-            '"') output+='\"' ;;
-            $'\n') output+='\n' ;;
-            $'\r') output+='\r' ;;
-            $'\t') output+='\t' ;;
-            *) output+="$char" ;;
-        esac
-    done
-    printf '%s' "$output"
+    local s="$1"
+    s="${s//\\/\\\\}"
+    s="${s//\"/\\\"}"
+    s="${s//$'\n'/\\n}"
+    s="${s//$'\r'/\\r}"
+    s="${s//$'\t'/\\t}"
+    printf '%s' "$s"
 }
 
 using_superpowers_escaped=$(escape_for_json "$using_superpowers_content")