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: `~/.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
-~/.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,13 +4,14 @@
 You have superpowers.
 
 **Tool for running skills:**
-- `~/.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 → Tell the user that subagents aren't available in Codex yet and you'll do the work the subagent would do
-- `Skill` tool → `~/.codex/superpowers/.codex/superpowers-codex use-skill` command (already available)
+- `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 ~/.codex/superpowers/.codex/superpowers-codex use-skill` command (already available)
 - `Read`, `Write`, `Edit`, `Bash` → Use your native tools with similar functions
 
 **Skills naming:**
@@ -20,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 ~/.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)
@@ -30,4 +31,4 @@ When skills reference tools you don't have, substitute your equivalent tools:
 - Personal skills: ~/.codex/skills/ (override superpowers when names match)
 
 IF A SKILL APPLIES TO YOUR TASK, YOU DO NOT HAVE A CHOICE. YOU MUST USE IT.
-</EXTREMELY_IMPORTANT>
+</EXTREMELY_IMPORTANT>

.codex/superpowers-codex.cmd

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

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 ~/.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 ~/.codex/superpowers/.codex/superpowers-codex find-skills
 ```
 
 ### Loading a Skill
 
 ```
-Run ~/.codex/superpowers/.codex/superpowers-codex use-skill superpowers:brainstorming
+Run node ~/.codex/superpowers/.codex/superpowers-codex use-skill superpowers:brainstorming
 ```
 
 ### Bootstrap All Skills
 
 ```
-Run ~/.codex/superpowers/.codex/superpowers-codex bootstrap
+Run node ~/.codex/superpowers/.codex/superpowers-codex bootstrap
 ```
 
 This loads the complete bootstrap with all skill information.
@@ -107,8 +107,9 @@ The Codex implementation uses the shared `skills-core` module (ES module format)
 Skills written for Claude Code are adapted for Codex with these mappings:
 
 - `TodoWrite` → `update_plan`
-- `Task` with subagents → Tell user subagents aren't available, do work directly
-- `Skill` tool → `~/.codex/superpowers/.codex/superpowers-codex use-skill`
+- `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 ~/.codex/superpowers/.codex/superpowers-codex use-skill`
 - File operations → Native Codex tools
 
 ## Updating
@@ -123,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 ~/.codex/superpowers/.codex/superpowers-codex find-skills`
 3. Verify skills have SKILL.md files
 
 ### CLI script not executable

skills/executing-plans/SKILL.md

@@ -74,3 +74,11 @@ After all tasks complete and verified:
 - 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
+
+## Integration
+
+**Required workflow skills:**
+- **superpowers:using-git-worktrees** - REQUIRED: Set up isolated workspace before starting
+- **superpowers:writing-plans** - Creates the plan this skill executes
+- **superpowers:finishing-a-development-branch** - Complete development after all tasks

skills/subagent-driven-development/SKILL.md

@@ -199,6 +199,7 @@ Done!
 ## Red Flags
 
 **Never:**
+- Start implementation on main/master branch without explicit user consent
 - Skip reviews (spec compliance OR code quality)
 - Proceed with unfixed issues
 - Dispatch multiple implementation subagents in parallel (conflicts)
@@ -229,6 +230,7 @@ Done!
 ## Integration
 
 **Required workflow skills:**
+- **superpowers:using-git-worktrees** - REQUIRED: Set up isolated workspace before starting
 - **superpowers:writing-plans** - Creates the plan this skill executes
 - **superpowers:requesting-code-review** - Code review template for reviewer subagents
 - **superpowers:finishing-a-development-branch** - Complete development after all tasks

skills/using-git-worktrees/SKILL.md

@@ -210,8 +210,9 @@ Ready to implement auth feature
 
 **Called by:**
 - **brainstorming** (Phase 4) - REQUIRED when design is approved and implementation follows
+- **subagent-driven-development** - REQUIRED before executing any tasks
+- **executing-plans** - REQUIRED before executing any tasks
 - Any skill needing isolated workspace
 
 **Pairs with:**
 - **finishing-a-development-branch** - REQUIRED for cleanup after work complete
-- **executing-plans** or **subagent-driven-development** - Work happens in this worktree

tests/claude-code/test-subagent-driven-development.sh

@@ -14,7 +14,7 @@ echo "Test 1: Skill loading..."
 
 output=$(run_claude "What is the subagent-driven-development skill? Describe its key steps briefly." 30)
 
-if assert_contains "$output" "subagent-driven-development" "Skill is recognized"; then
+if assert_contains "$output" "subagent-driven-development\|Subagent-Driven Development\|Subagent Driven" "Skill is recognized"; then
     : # pass
 else
     exit 1
@@ -136,4 +136,30 @@ fi
 
 echo ""
 
+# Test 8: Verify worktree requirement
+echo "Test 8: Worktree requirement..."
+
+output=$(run_claude "What workflow skills are required before using subagent-driven-development? List any prerequisites or required skills." 30)
+
+if assert_contains "$output" "using-git-worktrees\|worktree" "Mentions worktree requirement"; then
+    : # pass
+else
+    exit 1
+fi
+
+echo ""
+
+# Test 9: Verify main branch warning
+echo "Test 9: Main branch red flag..."
+
+output=$(run_claude "In subagent-driven-development, is it okay to start implementation directly on the main branch?" 30)
+
+if assert_contains "$output" "worktree\|feature.*branch\|not.*main\|never.*main\|avoid.*main\|don't.*main\|consent\|permission" "Warns against main branch"; then
+    : # pass
+else
+    exit 1
+fi
+
+echo ""
+
 echo "=== All subagent-driven-development skill tests passed ==="