Fix Windows/PowerShell invocation of superpowers-codex

Windows doesn't respect shebangs, so directly invoking the extensionless
superpowers-codex script triggers an "Open with" dialog. Prefix all
invocations with `node` (harmless on Unix, required on Windows) and add
a .cmd wrapper for manual invocation on Windows.

Fixes #285, #243

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: `node $HOME/.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 ~/.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
-node $HOME/.codex/superpowers/.codex/superpowers-codex bootstrap
+node ~/.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:**
-- `node $HOME/.codex/superpowers/.codex/superpowers-codex use-skill <skill-name>`
+- `node ~/.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 → `node $HOME/.codex/superpowers/.codex/superpowers-codex use-skill` command (already available)
+- `Skill` tool → `node ~/.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 `node $HOME/.codex/superpowers/.codex/superpowers-codex use-skill` to load it
+- If a relevant skill exists, you MUST use `node ~/.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)

README.md

@@ -44,7 +44,18 @@ Then install the plugin from this marketplace:
 
 ### Verify Installation
 
-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.
+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
+```
 
 ### Codex
 

RELEASE-NOTES.md

@@ -1,65 +1,5 @@
 # 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 node $HOME/.codex/superpowers/.codex/superpowers-codex find-skills to show available skills
+Run node ~/.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 node $HOME/.codex/superpowers/.codex/superpowers-codex find-skills
+Run node ~/.codex/superpowers/.codex/superpowers-codex find-skills
 ```
 
 ### Loading a Skill
 
 ```
-Run node $HOME/.codex/superpowers/.codex/superpowers-codex use-skill superpowers:brainstorming
+Run node ~/.codex/superpowers/.codex/superpowers-codex use-skill superpowers:brainstorming
 ```
 
 ### Bootstrap All Skills
 
 ```
-Run node $HOME/.codex/superpowers/.codex/superpowers-codex bootstrap
+Run node ~/.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 → `node $HOME/.codex/superpowers/.codex/superpowers-codex use-skill`
+- `Skill` tool → `node ~/.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: `node $HOME/.codex/superpowers/.codex/superpowers-codex find-skills`
+2. Check CLI works: `node ~/.codex/superpowers/.codex/superpowers-codex find-skills`
 3. Verify skills have SKILL.md files
 
 ### CLI script not executable

hooks/hooks.json

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

hooks/session-start.sh

@@ -17,17 +17,23 @@ 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 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 outputs for JSON using pure bash
 escape_for_json() {
-    local s="$1"
-    s="${s//\\/\\\\}"
-    s="${s//\"/\\\"}"
-    s="${s//$'\n'/\\n}"
-    s="${s//$'\r'/\\r}"
-    s="${s//$'\t'/\\t}"
-    printf '%s' "$s"
+    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"
 }
 
 using_superpowers_escaped=$(escape_for_json "$using_superpowers_content")