EricGrill · github-actions · Feb 8, 2026
diff --git a/plugins/superpowers/.claude-plugin/plugin.json b/plugins/superpowers/.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.0.3",
+  "version": "4.2.0",
   "author": {
     "name": "Jesse Vincent",
     "email": "jesse@fsck.com"

diff --git a/plugins/superpowers/hooks/hooks.json b/plugins/superpowers/hooks/hooks.json
@@ -6,7 +6,8 @@
         "hooks": [
           {
             "type": "command",
-            "command": "\"${CLAUDE_PLUGIN_ROOT}/hooks/run-hook.cmd\" session-start.sh"
+            "command": "${CLAUDE_PLUGIN_ROOT}/hooks/session-start.sh",
+            "async": true
           }
         ]
       }

diff --git a/plugins/superpowers/hooks/run-hook.cmd b/plugins/superpowers/hooks/run-hook.cmd
@@ -1,6 +1,30 @@
 : << 'CMDBLOCK'
 @echo off
-REM Polyglot wrapper: runs .sh scripts cross-platform
+REM ============================================================================
+REM DEPRECATED: This polyglot wrapper is no longer used as of Claude Code 2.1.x
+REM ============================================================================
+REM
+REM Claude Code 2.1.x changed the Windows execution model for hooks:
+REM
+REM   Before (2.0.x): Hooks ran with shell:true, using the system default shell.
+REM                   This wrapper provided cross-platform compatibility by
+REM                   being both a valid .cmd file (Windows) and bash script.
+REM
+REM   After (2.1.x):  Claude Code now auto-detects .sh files in hook commands
+REM                   and prepends "bash " on Windows. This broke the wrapper
+REM                   because the command:
+REM                     "run-hook.cmd" session-start.sh
+REM                   became:
+REM                     bash "run-hook.cmd" session-start.sh
+REM                   ...and bash cannot execute a .cmd file.
+REM
+REM The fix: hooks.json now calls session-start.sh directly. Claude Code 2.1.x
+REM handles the bash invocation automatically on Windows.
+REM
+REM This file is kept for reference and potential backward compatibility.
+REM ============================================================================
+REM
+REM Original purpose: Polyglot wrapper to run .sh scripts cross-platform
 REM Usage: run-hook.cmd <script-name> [args...]
 REM The script should be in the same directory as this wrapper
 

diff --git a/plugins/superpowers/hooks/session-start.sh b/plugins/superpowers/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")

diff --git a/plugins/superpowers/skills/executing-plans/SKILL.md b/plugins/superpowers/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
diff --git a/plugins/superpowers/skills/subagent-driven-development/SKILL.md b/plugins/superpowers/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

diff --git a/plugins/superpowers/skills/using-git-worktrees/SKILL.md b/plugins/superpowers/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
diff --git a/plugins/superpowers/skills/writing-skills/SKILL.md b/plugins/superpowers/skills/writing-skills/SKILL.md
@@ -9,7 +9,7 @@ description: Use when creating new skills, editing existing skills, or verifying
 
 **Writing skills IS Test-Driven Development applied to process documentation.**
 
-**Personal skills live in agent-specific directories (`~/.claude/skills` for Claude Code, `~/.codex/skills` for Codex)** 
+**Personal skills live in agent-specific directories (`~/.claude/skills` for Claude Code, `~/.agents/skills/` for Codex)** 
 
 You write test cases (pressure scenarios with subagents), watch them fail (baseline behavior), write the skill (documentation), watch tests pass (agents comply), and refactor (close loopholes).
 

diff --git a/plugins/superpowers/skills/writing-skills/testing-skills-with-subagents.md b/plugins/superpowers/skills/writing-skills/testing-skills-with-subagents.md
@@ -324,7 +324,7 @@ Before deploying skill, verify you followed RED-GREEN-REFACTOR:
 - [ ] Added explicit counters for each loophole
 - [ ] Updated rationalization table
 - [ ] Updated red flags list
-- [ ] Updated description ith violation symptoms
+- [ ] Updated description with violation symptoms
 - [ ] Re-tested - agent still complies
 - [ ] Meta-tested to verify clarity
 - [ ] Agent follows rule under maximum pressure