📦 deps(superpowers): vendor snapshot

2026-03-17 08:53:55 +00:00 · 2026-03-17 08:53:55 +00:00 · 69d12d51b4
parent e51bcbd5bd
commit 69d12d51b4
36 changed files with 287 additions and 403 deletions
--- a/superpowers/.claude-plugin/marketplace.json
+++ b/superpowers/.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": "5.0.2",
+      "version": "5.0.4",
      "source": "./",
      "author": {
        "name": "Jesse Vincent",
--- a/superpowers/.claude-plugin/plugin.json
+++ b/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": "5.0.2",
+  "version": "5.0.4",
  "author": {
    "name": "Jesse Vincent",
    "email": "jesse@fsck.com"
--- a/superpowers/.cursor-plugin/plugin.json
+++ b/superpowers/.cursor-plugin/plugin.json
@ -14,5 +14,5 @@
  "skills": "./skills/",
  "agents": "./agents/",
  "commands": "./commands/",
-  "hooks": "./hooks/hooks.json"
+  "hooks": "./hooks/hooks-cursor.json"
 }
--- a/superpowers/.opencode/INSTALL.md
+++ b/superpowers/.opencode/INSTALL.md
@ -3,107 +3,71 @@
 ## Prerequisites

 - [OpenCode.ai](https://opencode.ai) installed
- Git installed

-## Installation Steps
+## Installation

-### 1. Clone Superpowers
+Add superpowers to the `plugin` array in your `opencode.json` (global or project-level):

-```bash
-git clone https://github.com/obra/superpowers.git ~/.config/opencode/superpowers
+```json
+{
+  "plugin": ["superpowers@git+https://github.com/obra/superpowers.git"]
+}
 ```

-### 2. Register the Plugin
+Restart OpenCode. That's it — the plugin auto-installs and registers all skills.

-Create a symlink so OpenCode discovers the plugin:
+Verify by asking: "Tell me about your superpowers"
+
+## Migrating from the old symlink-based install
+
+If you previously installed superpowers using `git clone` and symlinks, remove the old setup:

 ```bash
-mkdir -p ~/.config/opencode/plugins
+# Remove old symlinks
 rm -f ~/.config/opencode/plugins/superpowers.js
-ln -s ~/.config/opencode/superpowers/.opencode/plugins/superpowers.js ~/.config/opencode/plugins/superpowers.js
-```
-
-### 3. Symlink Skills
-
-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
+
+# Optionally remove the cloned repo
+rm -rf ~/.config/opencode/superpowers
+
+# Remove skills.paths from opencode.json if you added one for superpowers
 ```

-### 4. Restart OpenCode
-
-Restart OpenCode. The plugin will automatically inject superpowers context.
-
-Verify by asking: "do you have superpowers?"
+Then follow the installation steps above.

 ## Usage

-### Finding Skills
-
-Use OpenCode's native `skill` tool to list available skills:
+Use OpenCode's native `skill` tool:

 ```
 use skill tool to list skills
-```
-
-### Loading a Skill
-
-Use OpenCode's native `skill` tool to load a specific skill:
-
-```
 use skill tool to load superpowers/brainstorming
 ```

-### Personal Skills
-
-Create your own skills in `~/.config/opencode/skills/`:
-
-```bash
-mkdir -p ~/.config/opencode/skills/my-skill
-```
-
-Create `~/.config/opencode/skills/my-skill/SKILL.md`:
-
-```markdown
---
-name: my-skill
-description: Use when [condition] - [what it does]
---
-
-# My Skill
-
-[Your skill content here]
-```
-
-### Project Skills
-
-Create project-specific skills in `.opencode/skills/` within your project.
-
-**Skill Priority:** Project skills > Personal skills > Superpowers skills
-
 ## Updating

-```bash
-cd ~/.config/opencode/superpowers
-git pull
+Superpowers updates automatically when you restart OpenCode.
+
+To pin a specific version:
+
+```json
+{
+  "plugin": ["superpowers@git+https://github.com/obra/superpowers.git#v5.0.3"]
+}
 ```

 ## Troubleshooting

 ### 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
+1. Check logs: `opencode run --print-logs "hello" 2>&1 | grep -i superpowers`
+2. Verify the plugin line in your `opencode.json`
+3. Make sure you're running a recent version of OpenCode

 ### 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
+1. Use `skill` tool to list what's discovered
+2. Check that the plugin is loading (see above)

 ### Tool mapping

--- a/superpowers/.opencode/plugins/superpowers.js
+++ b/superpowers/.opencode/plugins/superpowers.js
@ -2,7 +2,7 @@
 * Superpowers plugin for OpenCode.ai
 *
 * Injects superpowers bootstrap context via system prompt transform.
- * Skills are discovered via OpenCode's native skill tool from symlinked directory.
+ * Auto-registers skills directory via config hook (no symlinks needed).
 */

 import path from 'path';
@ -84,6 +84,18 @@ ${toolMapping}
  };

  return {
+    // Inject skills path into live config so OpenCode discovers superpowers skills
+    // without requiring manual symlinks or config file edits.
+    // This works because Config.get() returns a cached singleton — modifications
+    // here are visible when skills are lazily discovered later.
+    config: async (config) => {
+      config.skills = config.skills || {};
+      config.skills.paths = config.skills.paths || [];
+      if (!config.skills.paths.includes(superpowersSkillsDir)) {
+        config.skills.paths.push(superpowersSkillsDir);
+      }
+    },
+
    // Use system prompt transform to inject bootstrap (fixes #226 agent reset bug)
    'experimental.chat.system.transform': async (_input, output) => {
      const bootstrap = getBootstrapContent();
--- a/superpowers/CHANGELOG.md
+++ b/superpowers/CHANGELOG.md
@ -0,0 +1,20 @@
+# Changelog
+
+## Unreleased
+
+### Fixed
+
+- **Brainstorm server on Windows**: Auto-detect Windows/Git Bash (`OSTYPE=msys*`, `MSYSTEM`) and switch to foreground mode, fixing silent server failure caused by `nohup`/`disown` process reaping. Applies to all Windows shells (CMD, PowerShell, Git Bash) since they all route through Git Bash. ([#737](https://github.com/obra/superpowers/issues/737), based on [#740](https://github.com/obra/superpowers/pull/740))
+- **Portable shebangs**: Replace `#!/bin/bash` with `#!/usr/bin/env bash` in all 13 shell scripts. Fixes execution on NixOS, FreeBSD, and macOS with Homebrew bash where `/bin/bash` is outdated or missing. ([#700](https://github.com/obra/superpowers/pull/700), dupes: [#747](https://github.com/obra/superpowers/pull/747))
+- **POSIX-safe hook script**: Replace `${BASH_SOURCE[0]:-$0}` with `$0` in `hooks/session-start` and polyglot-hooks docs. Fixes 'Bad substitution' error on Ubuntu/Debian where `/bin/sh` is dash. ([#553](https://github.com/obra/superpowers/pull/553))
+- **Bash 5.3+ hook hang**: Replace heredoc (`cat <<EOF`) with `printf` in `hooks/session-start`. Fixes indefinite hang on macOS with Homebrew bash 5.3+ caused by a bash regression with large variable expansion in heredocs. ([#572](https://github.com/obra/superpowers/pull/572), [#571](https://github.com/obra/superpowers/issues/571))
+- **Cursor hooks support**: Add `hooks/hooks-cursor.json` with Cursor's camelCase format (`sessionStart`, `version: 1`) and update `.cursor-plugin/plugin.json` to reference it. Fix platform detection in `session-start` to check `CURSOR_PLUGIN_ROOT` first (Cursor may also set `CLAUDE_PLUGIN_ROOT`). (Based on [#709](https://github.com/obra/superpowers/pull/709))
+
+### Already fixed on dev (closed PRs)
+
+- **Windows hook quoting** ([#630](https://github.com/obra/superpowers/pull/630), [#529](https://github.com/obra/superpowers/issues/529)): `hooks.json` already uses escaped double quotes on dev.
+- **Windows symlink path** ([#539](https://github.com/obra/superpowers/pull/539)): Closed — the PR introduced a bug (literal `~` in path alongside `$env:USERPROFILE`). Current docs are correct.
+
+### Known Issues
+
+- **`BRAINSTORM_OWNER_PID` on Windows (main branch only)**: The main branch's `server.js` uses `process.kill(OWNER_PID, 0)` for lifecycle checks, but receives MSYS2 PIDs which are invisible to Node.js (different PID namespace). This causes the server to self-terminate after 60 seconds. Fix: resolve `OWNER_PID` via `/proc/$PPID/winpid` to get the Windows-native PID. The dev branch's `index.js` does not have this issue since it has no OWNER_PID lifecycle check.
--- a/superpowers/README.md
+++ b/superpowers/README.md
@ -174,7 +174,14 @@ Skills update automatically when you update the plugin:

 MIT License - see LICENSE file for details

+## Community
+
+Superpowers is built by [Jesse Vincent](https://blog.fsck.com) and the rest of the folks at [Prime Radiant](https://primeradiant.com).
+
+For community support, questions, and sharing what you're building with Superpowers, join us on [Discord](https://discord.gg/Jd8Vphy9jq).
+
 ## Support

+- **Discord**: [Join us on Discord](https://discord.gg/Jd8Vphy9jq)
 - **Issues**: https://github.com/obra/superpowers/issues
 - **Marketplace**: https://github.com/obra/superpowers-marketplace
--- a/superpowers/RELEASE-NOTES.md
+++ b/superpowers/RELEASE-NOTES.md
@ -1,5 +1,41 @@
 # Superpowers Release Notes

+## v5.0.4 (2026-03-16)
+
+### Review Loop Refinements
+
+Dramatically reduces token usage and speeds up spec and plan reviews by eliminating unnecessary review passes and tightening reviewer focus.
+
+- **Single whole-plan review** — plan reviewer now reviews the complete plan in one pass instead of chunk-by-chunk. Removed all chunk-related concepts (`## Chunk N:` headings, 1000-line chunk limits, per-chunk dispatch).
+- **Raised the bar for blocking issues** — both spec and plan reviewer prompts now include a "Calibration" section: only flag issues that would cause real problems during implementation. Minor wording, stylistic preferences, and formatting quibbles should not block approval.
+- **Reduced max review iterations** — from 5 to 3 for both spec and plan review loops. If the reviewer is calibrated correctly, 3 rounds is plenty.
+- **Streamlined reviewer checklists** — spec reviewer trimmed from 7 categories to 5; plan reviewer from 7 to 4. Removed formatting-focused checks (task syntax, chunk size) in favor of substance (buildability, spec alignment).
+
+### OpenCode
+
+- **One-line plugin install** — OpenCode plugin now auto-registers the skills directory via a `config` hook. No symlinks or `skills.paths` config needed. Install is just adding one line to `opencode.json`. (PR #753)
+- **Added `package.json`** so OpenCode can install superpowers as an npm package from git.
+
+### Bug Fixes
+
+- **Verify server actually stopped** — `stop-server.sh` now confirms the process is dead before reporting success. SIGTERM + 2s wait + SIGKILL fallback. Reports failure if the process survives. (PR #751)
+- **Generic agent language** — brainstorm companion waiting page now says "the agent" instead of "Claude".
+
+## v5.0.3 (2026-03-15)
+
+### Cursor Support
+
+- **Cursor hooks** — added `hooks/hooks-cursor.json` with Cursor's camelCase format (`sessionStart`, `version: 1`) and updated `.cursor-plugin/plugin.json` to reference it. Fixed platform detection in `session-start` to check `CURSOR_PLUGIN_ROOT` first (Cursor may also set `CLAUDE_PLUGIN_ROOT`). (Based on PR #709)
+
+### 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`.
+- **Bash 5.3+ hook hang** — replaced heredoc (`cat <<EOF`) with `printf` in `hooks/session-start`. Fixes indefinite hang on macOS with Homebrew bash 5.3+ caused by a bash regression with large variable expansion in heredocs. (#572, #571)
+- **POSIX-safe hook script** — replaced `${BASH_SOURCE[0]:-$0}` with `$0` in `hooks/session-start`. Fixes "Bad substitution" error on Ubuntu/Debian where `/bin/sh` is dash. (#553)
+- **Portable shebangs** — replaced `#!/bin/bash` with `#!/usr/bin/env bash` in all shell scripts. Fixes execution on NixOS, FreeBSD, and macOS with Homebrew bash where `/bin/bash` is outdated or missing. (#700)
+- **Brainstorm server on Windows** — auto-detect Windows/Git Bash (`OSTYPE=msys*`, `MSYSTEM`) and switch to foreground mode, fixing silent server failure caused by `nohup`/`disown` process reaping. (#737)
+- **Codex docs fix** — replaced deprecated `collab` flag with `multi_agent` in Codex documentation. (PR #749)
+
 ## v5.0.2 (2026-03-11)

 ### Zero-Dependency Brainstorm Server
--- a/superpowers/SOURCE.md
+++ b/superpowers/SOURCE.md
@ -1,6 +1,6 @@
 # Source

 - Repo: https://github.com/obra/superpowers
- Ref: 363923f74aa9cd7b470c0aaa73dee629a8bfdc90
- Snapshot: 2026-03-12
+- Ref: 3cee13e516e91d44b957c1336c3d08c8a8392702
+- Snapshot: 2026-03-17
 - Notes: vendored into playbook branch thirdparty/skill
--- a/superpowers/docs/README.codex.md
+++ b/superpowers/docs/README.codex.md
@ -32,10 +32,10 @@ Fetch and follow instructions from https://raw.githubusercontent.com/obra/superp

 3. Restart Codex.

-4. **For subagent skills** (optional): Skills like `dispatching-parallel-agents` and `subagent-driven-development` require Codex's collab feature. Add to your Codex config:
+4. **For subagent skills** (optional): Skills like `dispatching-parallel-agents` and `subagent-driven-development` require Codex's multi-agent feature. Add to your Codex config:
   ```toml
   [features]
-   collab = true
+   multi_agent = true
   ```

 ### Windows
--- a/superpowers/docs/README.opencode.md
+++ b/superpowers/docs/README.opencode.md
@ -2,169 +2,36 @@

 Complete guide for using Superpowers with [OpenCode.ai](https://opencode.ai).

-## Quick Install
+## Installation

-Tell OpenCode:
+Add superpowers to the `plugin` array in your `opencode.json` (global or project-level):

-```
-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.
+```json
+{
+  "plugin": ["superpowers@git+https://github.com/obra/superpowers.git"]
+}
 ```

-## Manual Installation
+Restart OpenCode. The plugin auto-installs via Bun and registers all skills automatically.

-### Prerequisites
+Verify by asking: "Tell me about your superpowers"

- [OpenCode.ai](https://opencode.ai) installed
- Git installed
+### Migrating from the old symlink-based install

-### macOS / Linux
+If you previously installed superpowers using `git clone` and symlinks, remove the old setup:

 ```bash
-# 1. Install Superpowers (or update existing)
-if [ -d ~/.config/opencode/superpowers ]; then
-  cd ~/.config/opencode/superpowers && git pull
-else
-  git clone https://github.com/obra/superpowers.git ~/.config/opencode/superpowers
-fi
-
-# 2. Create directories
-mkdir -p ~/.config/opencode/plugins ~/.config/opencode/skills
-
-# 3. Remove old symlinks/directories if they exist
+# Remove old symlinks
 rm -f ~/.config/opencode/plugins/superpowers.js
 rm -rf ~/.config/opencode/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
+# Optionally remove the cloned repo
+rm -rf ~/.config/opencode/superpowers

-# 5. Restart OpenCode
+# Remove skills.paths from opencode.json if you added one for superpowers
 ```

-#### Verify Installation
-
-```bash
-ls -l ~/.config/opencode/plugins/superpowers.js
-ls -l ~/.config/opencode/skills/superpowers
-```
-
-Both should show symlinks pointing to the superpowers directory.
-
-### Windows
-
-**Prerequisites:**
- Git installed
- Either **Developer Mode** enabled OR **Administrator privileges**
-  - Windows 10: Settings → Update & Security → For developers
-  - Windows 11: Settings → System → For developers
-
-Pick your shell below: [Command Prompt](#command-prompt) | [PowerShell](#powershell) | [Git Bash](#git-bash)
-
-#### Command Prompt
-
-Run as Administrator, or with Developer Mode enabled:
-
-```cmd
-:: 1. Install Superpowers
-git clone https://github.com/obra/superpowers.git "%USERPROFILE%\.config\opencode\superpowers"
-
-:: 2. Create directories
-mkdir "%USERPROFILE%\.config\opencode\plugins" 2>nul
-mkdir "%USERPROFILE%\.config\opencode\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
-
-:: 4. Create plugin symlink (requires Developer Mode or Admin)
-mklink "%USERPROFILE%\.config\opencode\plugins\superpowers.js" "%USERPROFILE%\.config\opencode\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"
-
-:: 6. Restart OpenCode
-```
-
-#### PowerShell
-
-Run as Administrator, or with Developer Mode enabled:
-
-```powershell
-# 1. Install Superpowers
-git clone https://github.com/obra/superpowers.git "$env:USERPROFILE\.config\opencode\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"
-
-# 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
-
-# 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"
-
-# 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"
-
-# 6. Restart OpenCode
-```
-
-#### Git Bash
-
-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
-# 1. Install Superpowers
-git clone https://github.com/obra/superpowers.git ~/.config/opencode/superpowers
-
-# 2. Create directories
-mkdir -p ~/.config/opencode/plugins ~/.config/opencode/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
-
-# 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)\""
-
-# 5. Create skills junction (works without special privileges)
-cmd //c "mklink /J \"$(cygpath -w ~/.config/opencode/skills/superpowers)\" \"$(cygpath -w ~/.config/opencode/superpowers/skills)\""
-
-# 6. Restart OpenCode
-```
-
-#### WSL Users
-
-If running OpenCode inside WSL, use the [macOS / Linux](#macos--linux) instructions instead.
-
-#### Verify Installation
-
-**Command Prompt:**
-```cmd
-dir /AL "%USERPROFILE%\.config\opencode\plugins"
-dir /AL "%USERPROFILE%\.config\opencode\skills"
-```
-
-**PowerShell:**
-```powershell
-Get-ChildItem "$env:USERPROFILE\.config\opencode\plugins" | Where-Object { $_.LinkType }
-Get-ChildItem "$env:USERPROFILE\.config\opencode\skills" | Where-Object { $_.LinkType }
-```
-
-Look for `<SYMLINK>` or `<JUNCTION>` in the output.
-
-#### Troubleshooting Windows
-
-**"You do not have sufficient privilege" error:**
- Enable Developer Mode in Windows Settings, OR
- Right-click your terminal → "Run as Administrator"
-
-**"Cannot create a file when that file already exists":**
- Run the removal commands (step 3) first, then retry
-
-**Symlinks not working after git clone:**
- Run `git config --global core.symlinks true` and re-clone
+Then follow the installation steps above.

 ## Usage

@ -178,8 +45,6 @@ use skill tool to list skills

 ### Loading a Skill

-Use OpenCode's native `skill` tool to load a specific skill:
-
 ```
 use skill tool to load superpowers/brainstorming
 ```
@ -207,124 +72,59 @@ description: Use when [condition] - [what it does]

 ### Project Skills

-Create project-specific skills in your OpenCode project:
+Create project-specific skills in `.opencode/skills/` within your project.

-```bash
-# In your OpenCode project
-mkdir -p .opencode/skills/my-project-skill
+**Skill Priority:** Project skills > Personal skills > Superpowers skills
+
+## Updating
+
+Superpowers updates automatically when you restart OpenCode. The plugin is re-installed from the git repository on each launch.
+
+To pin a specific version, use a branch or tag:
+
+```json
+{
+  "plugin": ["superpowers@git+https://github.com/obra/superpowers.git#v5.0.3"]
+}
 ```

-Create `.opencode/skills/my-project-skill/SKILL.md`:
+## How It Works

-```markdown
---
-name: my-project-skill
-description: Use when [condition] - [what it does]
---
+The plugin does two things:

-# My Project Skill
-
-[Your skill content here]
-```
-
-## Skill Locations
-
-OpenCode discovers skills from these locations:
-
-1. **Project skills** (`.opencode/skills/`) - Highest priority
-2. **Personal skills** (`~/.config/opencode/skills/`)
-3. **Superpowers skills** (`~/.config/opencode/skills/superpowers/`) - via symlink
-
-## Features
-
-### Automatic Context Injection
-
-The plugin automatically injects superpowers context via the `experimental.chat.system.transform` hook. This adds the "using-superpowers" skill content to the system prompt on every request.
-
-### 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.
+1. **Injects bootstrap context** via the `experimental.chat.system.transform` hook, adding superpowers awareness to every conversation.
+2. **Registers the skills directory** via the `config` hook, so OpenCode discovers all superpowers skills without symlinks or manual config.

 ### Tool Mapping

-Skills written for Claude Code are automatically adapted for OpenCode. The bootstrap provides mapping instructions:
+Skills written for Claude Code are automatically adapted for OpenCode:

 - `TodoWrite` → `todowrite`
 - `Task` with subagents → OpenCode's `@mention` system
 - `Skill` tool → OpenCode's native `skill` tool
 - File operations → Native OpenCode tools

-## Architecture
-
-### Plugin Structure
-
-**Location:** `~/.config/opencode/superpowers/.opencode/plugins/superpowers.js`
-
-**Components:**
- `experimental.chat.system.transform` hook for bootstrap injection
- Reads and injects the "using-superpowers" skill content
-
-### Skills
-
-**Location:** `~/.config/opencode/skills/superpowers/` (symlink to `~/.config/opencode/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
-git pull
-```
-
-Restart OpenCode to load the updates.
-
 ## Troubleshooting

 ### 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)
-3. Check OpenCode logs: `opencode run "test" --print-logs --log-level DEBUG`
-4. Look for plugin loading message in logs
+1. Check OpenCode logs: `opencode run --print-logs "hello" 2>&1 | grep -i superpowers`
+2. Verify the plugin line in your `opencode.json` is correct
+3. Make sure you're running a recent version of OpenCode

 ### Skills not found

-1. Verify skills symlink: `ls -l ~/.config/opencode/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
-
-### Windows: Module not found error
-
-If you see `Cannot find module` errors on Windows:
- **Cause:** Git Bash `ln -sf` copies files instead of creating symlinks
- **Fix:** Use `mklink /J` directory junctions instead (see Windows installation steps)
+1. Use OpenCode's `skill` tool to list available skills
+2. Check that the plugin is loading (see above)
+3. Each skill needs a `SKILL.md` file with valid YAML frontmatter

 ### Bootstrap not appearing

-1. Verify using-superpowers skill exists: `ls ~/.config/opencode/superpowers/skills/using-superpowers/SKILL.md`
-2. Check OpenCode version supports `experimental.chat.system.transform` hook
-3. Restart OpenCode after plugin changes
+1. Check OpenCode version supports `experimental.chat.system.transform` hook
+2. Restart OpenCode after config changes

 ## Getting Help

 - Report issues: https://github.com/obra/superpowers/issues
 - Main documentation: https://github.com/obra/superpowers
 - OpenCode docs: https://opencode.ai/docs/
-
-## Testing
-
-Verify your installation:
-
-```bash
-# Check plugin loads
-opencode run --print-logs "hello" 2>&1 | grep -i superpowers
-
-# Check skills are discoverable
-opencode run "use skill tool to list all skills" 2>&1 | grep -i superpowers
-
-# Check bootstrap injection
-opencode run "what superpowers do you have?"
-```
-
-The agent should mention having superpowers and be able to list skills from `superpowers/`.
--- a/superpowers/docs/windows/polyglot-hooks.md
+++ b/superpowers/docs/windows/polyglot-hooks.md
@ -148,7 +148,7 @@ exit /b
 CMDBLOCK

 # Unix shell runs from here
-SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]:-$0}")" && pwd)"
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
 SCRIPT_NAME="$1"
 shift
 "${SCRIPT_DIR}/${SCRIPT_NAME}" "$@"
--- a/superpowers/hooks/hooks-cursor.json
+++ b/superpowers/hooks/hooks-cursor.json
@ -0,0 +1,10 @@
+{
+  "version": 1,
+  "hooks": {
+    "sessionStart": [
+      {
+        "command": "./hooks/session-start"
+      }
+    ]
+  }
+}
--- a/superpowers/hooks/hooks.json
+++ b/superpowers/hooks/hooks.json
@ -2,7 +2,7 @@
  "hooks": {
    "SessionStart": [
      {
-        "matcher": "startup|resume|clear|compact",
+        "matcher": "startup|clear|compact",
        "hooks": [
          {
            "type": "command",
--- a/superpowers/hooks/session-start
+++ b/superpowers/hooks/session-start
@ -4,7 +4,7 @@
 set -euo pipefail

 # Determine plugin root directory
-SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]:-$0}")" && pwd)"
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
 PLUGIN_ROOT="$(cd "${SCRIPT_DIR}/.." && pwd)"

 # Check if legacy skills directory exists and build warning
@ -39,23 +39,19 @@ session_context="<EXTREMELY_IMPORTANT>\nYou have superpowers.\n\n**Below is the
 # 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
+#
+# Uses printf instead of heredoc (cat <<EOF) to work around a bash 5.3+
+# bug where heredoc variable expansion hangs when content exceeds ~512 bytes.
+# See: https://github.com/obra/superpowers/issues/571
+if [ -n "${CURSOR_PLUGIN_ROOT:-}" ]; then
+  # Cursor sets CURSOR_PLUGIN_ROOT (may also set CLAUDE_PLUGIN_ROOT) — emit additional_context
+  printf '{\n  "additional_context": "%s"\n}\n' "$session_context"
+elif [ -n "${CLAUDE_PLUGIN_ROOT:-}" ]; then
  # Claude Code sets CLAUDE_PLUGIN_ROOT — emit only hookSpecificOutput
-  cat <<EOF
-{
-  "hookSpecificOutput": {
-    "hookEventName": "SessionStart",
-    "additionalContext": "${session_context}"
-  }
-}
-EOF
+  printf '{\n  "hookSpecificOutput": {\n    "hookEventName": "SessionStart",\n    "additionalContext": "%s"\n  }\n}\n' "$session_context"
 else
-  # Other platforms (Cursor, etc.) — emit only additional_context
-  cat <<EOF
-{
-  "additional_context": "${session_context}"
-}
-EOF
+  # Other platforms — emit additional_context as fallback
+  printf '{\n  "additional_context": "%s"\n}\n' "$session_context"
 fi

 exit 0
--- a/superpowers/package.json
+++ b/superpowers/package.json
@ -0,0 +1,6 @@
+{
+  "name": "superpowers",
+  "version": "5.0.4",
+  "type": "module",
+  "main": ".opencode/plugins/superpowers.js"
+}
--- a/superpowers/skills/brainstorming/SKILL.md
+++ b/superpowers/skills/brainstorming/SKILL.md
@ -27,7 +27,7 @@ You MUST create a task for each of these items and complete them in order:
 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/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)
+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 3 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

@ -121,7 +121,7 @@ After writing the spec document:

 1. Dispatch spec-document-reviewer subagent (see spec-document-reviewer-prompt.md)
 2. If Issues Found: fix, re-dispatch, repeat until Approved
-3. If loop exceeds 5 iterations, surface to human for guidance
+3. If loop exceeds 3 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:
--- a/superpowers/skills/brainstorming/scripts/server.js
+++ b/superpowers/skills/brainstorming/scripts/server.js
@ -94,7 +94,7 @@ const WAITING_PAGE = `<!DOCTYPE html>
 h1 { color: #333; } p { color: #666; }</style>
 </head>
 <body><h1>Brainstorm Companion</h1>
-<p>Waiting for Claude to push a screen...</p></body></html>`;
+<p>Waiting for the agent 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');
--- a/superpowers/skills/brainstorming/scripts/start-server.sh
+++ b/superpowers/skills/brainstorming/scripts/start-server.sh
@ -1,4 +1,4 @@
-#!/bin/bash
+#!/usr/bin/env bash
 # Start the brainstorm server and output connection info
 # Usage: start-server.sh [--project-dir <path>] [--host <bind-host>] [--url-host <display-host>] [--foreground] [--background]
 #
@ -64,6 +64,16 @@ if [[ -n "${CODEX_CI:-}" && "$FOREGROUND" != "true" && "$FORCE_BACKGROUND" != "t
  FOREGROUND="true"
 fi

+# Windows/Git Bash reaps nohup background processes. Auto-foreground when detected.
+if [[ "$FOREGROUND" != "true" && "$FORCE_BACKGROUND" != "true" ]]; then
+  case "${OSTYPE:-}" in
+    msys*|cygwin*|mingw*) FOREGROUND="true" ;;
+  esac
+  if [[ -n "${MSYSTEM:-}" ]]; then
+    FOREGROUND="true"
+  fi
+fi
+
 # Generate unique session directory
 SESSION_ID="$$-$(date +%s)"

--- a/superpowers/skills/brainstorming/scripts/stop-server.sh
+++ b/superpowers/skills/brainstorming/scripts/stop-server.sh
@ -1,4 +1,4 @@
-#!/bin/bash
+#!/usr/bin/env bash
 # Stop the brainstorm server and clean up
 # Usage: stop-server.sh <screen_dir>
 #
@ -17,7 +17,31 @@ PID_FILE="${SCREEN_DIR}/.server.pid"

 if [[ -f "$PID_FILE" ]]; then
  pid=$(cat "$PID_FILE")
-  kill "$pid" 2>/dev/null
+
+  # Try to stop gracefully, fallback to force if still alive
+  kill "$pid" 2>/dev/null || true
+
+  # Wait for graceful shutdown (up to ~2s)
+  for i in {1..20}; do
+    if ! kill -0 "$pid" 2>/dev/null; then
+      break
+    fi
+    sleep 0.1
+  done
+
+  # If still running, escalate to SIGKILL
+  if kill -0 "$pid" 2>/dev/null; then
+    kill -9 "$pid" 2>/dev/null || true
+
+    # Give SIGKILL a moment to take effect
+    sleep 0.1
+  fi
+
+  if kill -0 "$pid" 2>/dev/null; then
+    echo '{"status": "failed", "error": "process still running"}'
+    exit 1
+  fi
+
  rm -f "$PID_FILE" "${SCREEN_DIR}/.server.log"

  # Only delete ephemeral /tmp directories
--- a/superpowers/skills/brainstorming/spec-document-reviewer-prompt.md
+++ b/superpowers/skills/brainstorming/spec-document-reviewer-prompt.md
@ -19,32 +19,31 @@ Task tool (general-purpose):
    | Category | What to Look For |
    |----------|------------------|
    | Completeness | TODOs, placeholders, "TBD", incomplete sections |
-    | Coverage | Missing error handling, edge cases, integration points |
    | Consistency | Internal contradictions, conflicting requirements |
-    | Clarity | Ambiguous requirements |
-    | YAGNI | Unrequested features, over-engineering |
+    | Clarity | Requirements ambiguous enough to cause someone to build the wrong thing |
    | Scope | Focused enough for a single plan — not covering multiple independent subsystems |
-    | Architecture | Units with clear boundaries, well-defined interfaces, independently understandable and testable |
+    | YAGNI | Unrequested features, over-engineering |

-    ## CRITICAL
+    ## Calibration

-    Look especially hard for:
-    - Any TODO markers or placeholder text
-    - Sections saying "to be defined later" or "will spec when X is done"
-    - Sections noticeably less detailed than others
-    - Units that lack clear boundaries or interfaces — can you understand what each unit does without reading its internals?
+    **Only flag issues that would cause real problems during implementation planning.**
+    A missing section, a contradiction, or a requirement so ambiguous it could be
+    interpreted two different ways — those are issues. Minor wording improvements,
+    stylistic preferences, and "sections less detailed than others" are not.
+
+    Approve unless there are serious gaps that would lead to a flawed plan.

    ## Output Format

    ## Spec Review

-    **Status:** ✅ Approved | ❌ Issues Found
+    **Status:** Approved | Issues Found

    **Issues (if any):**
-    - [Section X]: [specific issue] - [why it matters]
+    - [Section X]: [specific issue] - [why it matters for planning]

-    **Recommendations (advisory):**
-    - [suggestions that don't block approval]
+    **Recommendations (advisory, do not block approval):**
+    - [suggestions for improvement]
 ```

 **Reviewer returns:** Status, Issues (if any), Recommendations
--- a/superpowers/skills/brainstorming/visual-companion.md
+++ b/superpowers/skills/brainstorming/visual-companion.md
@ -61,6 +61,14 @@ scripts/start-server.sh --project-dir /path/to/project
 scripts/start-server.sh --project-dir /path/to/project
 ```

+**Windows (Git Bash / CMD / PowerShell):**
+```bash
+# Windows/Git Bash reaps nohup background processes. The script auto-detects
+# this via OSTYPE/MSYSTEM and switches to foreground mode automatically.
+# No extra flags needed — all Windows shells route through Git Bash.
+scripts/start-server.sh --project-dir /path/to/project
+```
+
 **Gemini CLI:**
 ```bash
 # Use --foreground and set is_background: true on your shell tool call
--- a/superpowers/skills/using-superpowers/references/codex-tools.md
+++ b/superpowers/skills/using-superpowers/references/codex-tools.md
@ -13,13 +13,13 @@ Skills use Claude Code tool names. When you encounter these in a skill, use your
 | `Read`, `Write`, `Edit` (files) | Use your native file tools |
 | `Bash` (run commands) | Use your native shell tools |

-## Subagent dispatch requires collab
+## Subagent dispatch requires multi-agent support

 Add to your Codex config (`~/.codex/config.toml`):

 ```toml
 [features]
-collab = true
+multi_agent = true
 ```

 This enables `spawn_agent`, `wait`, and `close_agent` for skills like `dispatching-parallel-agents` and `subagent-driven-development`.
--- a/superpowers/skills/writing-plans/SKILL.md
+++ b/superpowers/skills/writing-plans/SKILL.md
@ -112,22 +112,17 @@ git commit -m "feat: add specific feature"

 ## Plan Review Loop

-After completing each chunk of the plan:
+After writing the complete plan:

-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
-   - Re-dispatch reviewer for that chunk
-   - Repeat until ✅ Approved
-3. If ✅ Approved: proceed to next chunk (or execution handoff if last chunk)
-
-**Chunk boundaries:** Use `## Chunk N: <name>` headings to delimit chunks. Each chunk should be ≤1000 lines and logically self-contained.
+1. Dispatch a single 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: path to the plan document, path to spec document
+2. If ❌ Issues Found: fix the issues, re-dispatch reviewer for the whole plan
+3. If ✅ Approved: proceed to execution handoff

 **Review loop guidance:**
 - Same agent that wrote the plan fixes it (preserves context)
- If loop exceeds 5 iterations, surface to human for guidance
- Reviewers are advisory - explain disagreements if you believe feedback is incorrect
+- If loop exceeds 3 iterations, surface to human for guidance
+- Reviewers are advisory — explain disagreements if you believe feedback is incorrect

 ## Execution Handoff

--- a/superpowers/skills/writing-plans/plan-document-reviewer-prompt.md
+++ b/superpowers/skills/writing-plans/plan-document-reviewer-prompt.md
@ -2,17 +2,17 @@

 Use this template when dispatching a plan document reviewer subagent.

-**Purpose:** Verify the plan chunk is complete, matches the spec, and has proper task decomposition.
+**Purpose:** Verify the plan is complete, matches the spec, and has proper task decomposition.

-**Dispatch after:** Each plan chunk is written
+**Dispatch after:** The complete plan is written.

 ```
 Task tool (general-purpose):
-  description: "Review plan chunk N"
+  description: "Review plan document"
  prompt: |
-    You are a plan document reviewer. Verify this plan chunk is complete and ready for implementation.
+    You are a plan document reviewer. Verify this plan is complete and ready for implementation.

-    **Plan chunk to review:** [PLAN_FILE_PATH] - Chunk N only
+    **Plan to review:** [PLAN_FILE_PATH]
    **Spec for reference:** [SPEC_FILE_PATH]

    ## What to Check
@ -20,33 +20,30 @@ Task tool (general-purpose):
    | Category | What to Look For |
    |----------|------------------|
    | Completeness | TODOs, placeholders, incomplete tasks, missing steps |
-    | Spec Alignment | Chunk covers relevant spec requirements, no scope creep |
-    | Task Decomposition | Tasks atomic, clear boundaries, steps actionable |
-    | File Structure | Files have clear single responsibilities, split by responsibility not layer |
-    | File Size | Would any new or modified file likely grow large enough to be hard to reason about as a whole? |
-    | Task Syntax | Checkbox syntax (`- [ ]`) on steps for tracking |
-    | Chunk Size | Each chunk under 1000 lines |
+    | Spec Alignment | Plan covers spec requirements, no major scope creep |
+    | Task Decomposition | Tasks have clear boundaries, steps are actionable |
+    | Buildability | Could an engineer follow this plan without getting stuck? |

-    ## CRITICAL
+    ## Calibration

-    Look especially hard for:
-    - Any TODO markers or placeholder text
-    - Steps that say "similar to X" without actual content
-    - Incomplete task definitions
-    - Missing verification steps or expected outputs
-    - Files planned to hold multiple responsibilities or likely to grow unwieldy
+    **Only flag issues that would cause real problems during implementation.**
+    An implementer building the wrong thing or getting stuck is an issue.
+    Minor wording, stylistic preferences, and "nice to have" suggestions are not.
+
+    Approve unless there are serious gaps — missing requirements from the spec,
+    contradictory steps, placeholder content, or tasks so vague they can't be acted on.

    ## Output Format

-    ## Plan Review - Chunk N
+    ## Plan Review

    **Status:** Approved | Issues Found

    **Issues (if any):**
-    - [Task X, Step Y]: [specific issue] - [why it matters]
+    - [Task X, Step Y]: [specific issue] - [why it matters for implementation]

-    **Recommendations (advisory):**
-    - [suggestions that don't block approval]
+    **Recommendations (advisory, do not block approval):**
+    - [suggestions for improvement]
 ```

 **Reviewer returns:** Status, Issues (if any), Recommendations
--- a/superpowers/tests/explicit-skill-requests/run-all.sh
+++ b/superpowers/tests/explicit-skill-requests/run-all.sh
@ -1,4 +1,4 @@
-#!/bin/bash
+#!/usr/bin/env bash
 # Run all explicit skill request tests
 # Usage: ./run-all.sh

--- a/superpowers/tests/explicit-skill-requests/run-claude-describes-sdd.sh
+++ b/superpowers/tests/explicit-skill-requests/run-claude-describes-sdd.sh
@ -1,4 +1,4 @@
-#!/bin/bash
+#!/usr/bin/env bash
 # Test where Claude explicitly describes subagent-driven-development before user requests it
 # This mimics the original failure scenario

--- a/superpowers/tests/explicit-skill-requests/run-extended-multiturn-test.sh
+++ b/superpowers/tests/explicit-skill-requests/run-extended-multiturn-test.sh
@ -1,4 +1,4 @@
-#!/bin/bash
+#!/usr/bin/env bash
 # Extended multi-turn test with more conversation history
 # This tries to reproduce the failure by building more context

--- a/superpowers/tests/explicit-skill-requests/run-haiku-test.sh
+++ b/superpowers/tests/explicit-skill-requests/run-haiku-test.sh
@ -1,4 +1,4 @@
-#!/bin/bash
+#!/usr/bin/env bash
 # Test with haiku model and user's CLAUDE.md
 # This tests whether a cheaper/faster model fails more easily

--- a/superpowers/tests/explicit-skill-requests/run-multiturn-test.sh
+++ b/superpowers/tests/explicit-skill-requests/run-multiturn-test.sh
@ -1,4 +1,4 @@
-#!/bin/bash
+#!/usr/bin/env bash
 # Test explicit skill requests in multi-turn conversations
 # Usage: ./run-multiturn-test.sh
 #
--- a/superpowers/tests/explicit-skill-requests/run-test.sh
+++ b/superpowers/tests/explicit-skill-requests/run-test.sh
@ -1,4 +1,4 @@
-#!/bin/bash
+#!/usr/bin/env bash
 # Test explicit skill requests (user names a skill directly)
 # Usage: ./run-test.sh <skill-name> <prompt-file>
 #
--- a/superpowers/tests/skill-triggering/run-all.sh
+++ b/superpowers/tests/skill-triggering/run-all.sh
@ -1,4 +1,4 @@
-#!/bin/bash
+#!/usr/bin/env bash
 # Run all skill triggering tests
 # Usage: ./run-all.sh

--- a/superpowers/tests/skill-triggering/run-test.sh
+++ b/superpowers/tests/skill-triggering/run-test.sh
@ -1,4 +1,4 @@
-#!/bin/bash
+#!/usr/bin/env bash
 # Test skill triggering with naive prompts
 # Usage: ./run-test.sh <skill-name> <prompt-file>
 #
--- a/superpowers/tests/subagent-driven-dev/go-fractals/scaffold.sh
+++ b/superpowers/tests/subagent-driven-dev/go-fractals/scaffold.sh
@ -1,4 +1,4 @@
-#!/bin/bash
+#!/usr/bin/env bash
 # Scaffold the Go Fractals test project
 # Usage: ./scaffold.sh /path/to/target/directory

--- a/superpowers/tests/subagent-driven-dev/run-test.sh
+++ b/superpowers/tests/subagent-driven-dev/run-test.sh
@ -1,4 +1,4 @@
-#!/bin/bash
+#!/usr/bin/env bash
 # Run a subagent-driven-development test
 # Usage: ./run-test.sh <test-name> [--plugin-dir <path>]
 #
--- a/superpowers/tests/subagent-driven-dev/svelte-todo/scaffold.sh
+++ b/superpowers/tests/subagent-driven-dev/svelte-todo/scaffold.sh
@ -1,4 +1,4 @@
-#!/bin/bash
+#!/usr/bin/env bash
 # Scaffold the Svelte Todo test project
 # Usage: ./scaffold.sh /path/to/target/directory