docs: use OPENCODE_CONFIG_DIR in install docs

Set the variable once at the top of each shell block with a default
fallback, then use it cleanly throughout. Supports custom config
directories without repeating the alternation on every line.

Based on cavanaug's work in PR #704.

Co-Authored-By: John Cavanaugh <cavanaug@users.noreply.github.com>
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

.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.1",
+      "version": "5.0.2",
       "source": "./",
       "author": {
         "name": "Jesse Vincent",

.opencode/INSTALL.md

@@ -7,10 +7,13 @@
 
 ## Installation Steps
 
+> **Custom config directory:** If you've set `OPENCODE_CONFIG_DIR`, the commands below will use it automatically. Otherwise they default to `~/.config/opencode`.
+
 ### 1. Clone Superpowers
 
 ```bash
-git clone https://github.com/obra/superpowers.git ~/.config/opencode/superpowers
+OPENCODE_CONFIG_DIR="${OPENCODE_CONFIG_DIR:-$HOME/.config/opencode}"
+git clone https://github.com/obra/superpowers.git "$OPENCODE_CONFIG_DIR/superpowers"
 ```
 
 ### 2. Register the Plugin
@@ -18,9 +21,10 @@ git clone https://github.com/obra/superpowers.git ~/.config/opencode/superpowers
 Create a symlink so OpenCode discovers the plugin:
 
 ```bash
-mkdir -p ~/.config/opencode/plugins
-rm -f ~/.config/opencode/plugins/superpowers.js
-ln -s ~/.config/opencode/superpowers/.opencode/plugins/superpowers.js ~/.config/opencode/plugins/superpowers.js
+OPENCODE_CONFIG_DIR="${OPENCODE_CONFIG_DIR:-$HOME/.config/opencode}"
+mkdir -p "$OPENCODE_CONFIG_DIR/plugins"
+rm -f "$OPENCODE_CONFIG_DIR/plugins/superpowers.js"
+ln -s "$OPENCODE_CONFIG_DIR/superpowers/.opencode/plugins/superpowers.js" "$OPENCODE_CONFIG_DIR/plugins/superpowers.js"
 ```
 
 ### 3. Symlink Skills
@@ -28,9 +32,10 @@ ln -s ~/.config/opencode/superpowers/.opencode/plugins/superpowers.js ~/.config/
 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
+OPENCODE_CONFIG_DIR="${OPENCODE_CONFIG_DIR:-$HOME/.config/opencode}"
+mkdir -p "$OPENCODE_CONFIG_DIR/skills"
+rm -rf "$OPENCODE_CONFIG_DIR/skills/superpowers"
+ln -s "$OPENCODE_CONFIG_DIR/superpowers/skills" "$OPENCODE_CONFIG_DIR/skills/superpowers"
 ```
 
 ### 4. Restart OpenCode
@@ -59,13 +64,14 @@ use skill tool to load superpowers/brainstorming
 
 ### Personal Skills
 
-Create your own skills in `~/.config/opencode/skills/`:
+Create your own skills in your OpenCode skills directory:
 
 ```bash
-mkdir -p ~/.config/opencode/skills/my-skill
+OPENCODE_CONFIG_DIR="${OPENCODE_CONFIG_DIR:-$HOME/.config/opencode}"
+mkdir -p "$OPENCODE_CONFIG_DIR/skills/my-skill"
 ```
 
-Create `~/.config/opencode/skills/my-skill/SKILL.md`:
+Create a `SKILL.md` in that directory:
 
 ```markdown
 ---
@@ -87,7 +93,8 @@ Create project-specific skills in `.opencode/skills/` within your project.
 ## Updating
 
 ```bash
-cd ~/.config/opencode/superpowers
+OPENCODE_CONFIG_DIR="${OPENCODE_CONFIG_DIR:-$HOME/.config/opencode}"
+cd "$OPENCODE_CONFIG_DIR/superpowers"
 git pull
 ```
 
@@ -95,15 +102,20 @@ git pull
 
 ### 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
+```bash
+OPENCODE_CONFIG_DIR="${OPENCODE_CONFIG_DIR:-$HOME/.config/opencode}"
+ls -l "$OPENCODE_CONFIG_DIR/plugins/superpowers.js"
+ls "$OPENCODE_CONFIG_DIR/superpowers/.opencode/plugins/superpowers.js"
+```
 
 ### 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
+```bash
+OPENCODE_CONFIG_DIR="${OPENCODE_CONFIG_DIR:-$HOME/.config/opencode}"
+ls -l "$OPENCODE_CONFIG_DIR/skills/superpowers"
+```
+
+Verify the symlink points to `$OPENCODE_CONFIG_DIR/superpowers/skills`. Use `skill` tool to list what's discovered.
 
 ### Tool mapping
 

RELEASE-NOTES.md

@@ -1,5 +1,35 @@
 # Superpowers Release Notes
 
+## v5.0.3 (2026-03-15)
+
+### 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`.
+
+## v5.0.2 (2026-03-11)
+
+### Zero-Dependency Brainstorm Server
+
+**Removed all vendored node_modules — server.js is now fully self-contained**
+
+- Replaced Express/Chokidar/WebSocket dependencies with zero-dependency Node.js server using built-in `http`, `fs`, and `crypto` modules
+- Removed ~1,200 lines of vendored `node_modules/`, `package.json`, and `package-lock.json`
+- Custom WebSocket protocol implementation (RFC 6455 framing, ping/pong, proper close handshake)
+- Native `fs.watch()` file watching replaces Chokidar
+- Full test suite: HTTP serving, WebSocket protocol, file watching, and integration tests
+
+### Brainstorm Server Reliability
+
+- **Auto-exit after 30 minutes idle** — server shuts down when no clients are connected, preventing orphaned processes
+- **Owner process tracking** — server monitors the parent harness PID and exits when the owning session dies
+- **Liveness check** — skill verifies server is responsive before reusing an existing instance
+- **Encoding fix** — proper `<meta charset="utf-8">` on served HTML pages
+
+### Subagent Context Isolation
+
+- All delegation skills (brainstorming, dispatching-parallel-agents, requesting-code-review, subagent-driven-development, writing-plans) now include context isolation principle
+- Subagents receive only the context they need, preventing context window pollution
+
 ## v5.0.1 (2026-03-10)
 
 ### Agentskills Compliance

docs/README.opencode.md

@@ -7,7 +7,7 @@ Complete guide for using Superpowers with [OpenCode.ai](https://opencode.ai).
 Tell OpenCode:
 
 ```
-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.
+Clone https://github.com/obra/superpowers to my OpenCode config directory under superpowers/, then create a plugins/ directory there, then symlink superpowers/.opencode/plugins/superpowers.js to plugins/superpowers.js, then symlink superpowers/skills to skills/superpowers, then restart opencode.
 ```
 
 ## Manual Installation
@@ -17,26 +17,30 @@ Clone https://github.com/obra/superpowers to ~/.config/opencode/superpowers, the
 - [OpenCode.ai](https://opencode.ai) installed
 - Git installed
 
+> **Custom config directory:** If you've set `OPENCODE_CONFIG_DIR`, the commands below will use it automatically. Otherwise they default to `~/.config/opencode` (macOS/Linux) or `%USERPROFILE%\.config\opencode` (Windows).
+
 ### macOS / Linux
 
 ```bash
+OPENCODE_CONFIG_DIR="${OPENCODE_CONFIG_DIR:-$HOME/.config/opencode}"
+
 # 1. Install Superpowers (or update existing)
-if [ -d ~/.config/opencode/superpowers ]; then
-  cd ~/.config/opencode/superpowers && git pull
+if [ -d "$OPENCODE_CONFIG_DIR/superpowers" ]; then
+  cd "$OPENCODE_CONFIG_DIR/superpowers" && git pull
 else
-  git clone https://github.com/obra/superpowers.git ~/.config/opencode/superpowers
+  git clone https://github.com/obra/superpowers.git "$OPENCODE_CONFIG_DIR/superpowers"
 fi
 
 # 2. Create directories
-mkdir -p ~/.config/opencode/plugins ~/.config/opencode/skills
+mkdir -p "$OPENCODE_CONFIG_DIR/plugins" "$OPENCODE_CONFIG_DIR/skills"
 
 # 3. Remove old symlinks/directories if they exist
-rm -f ~/.config/opencode/plugins/superpowers.js
-rm -rf ~/.config/opencode/skills/superpowers
+rm -f "$OPENCODE_CONFIG_DIR/plugins/superpowers.js"
+rm -rf "$OPENCODE_CONFIG_DIR/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
+ln -s "$OPENCODE_CONFIG_DIR/superpowers/.opencode/plugins/superpowers.js" "$OPENCODE_CONFIG_DIR/plugins/superpowers.js"
+ln -s "$OPENCODE_CONFIG_DIR/superpowers/skills" "$OPENCODE_CONFIG_DIR/skills/superpowers"
 
 # 5. Restart OpenCode
 ```
@@ -44,8 +48,9 @@ ln -s ~/.config/opencode/superpowers/skills ~/.config/opencode/skills/superpower
 #### Verify Installation
 
 ```bash
-ls -l ~/.config/opencode/plugins/superpowers.js
-ls -l ~/.config/opencode/skills/superpowers
+OPENCODE_CONFIG_DIR="${OPENCODE_CONFIG_DIR:-$HOME/.config/opencode}"
+ls -l "$OPENCODE_CONFIG_DIR/plugins/superpowers.js"
+ls -l "$OPENCODE_CONFIG_DIR/skills/superpowers"
 ```
 
 Both should show symlinks pointing to the superpowers directory.
@@ -65,22 +70,24 @@ Pick your shell below: [Command Prompt](#command-prompt) | [PowerShell](#powersh
 Run as Administrator, or with Developer Mode enabled:
 
 ```cmd
+if not defined OPENCODE_CONFIG_DIR set OPENCODE_CONFIG_DIR=%USERPROFILE%\.config\opencode
+
 :: 1. Install Superpowers
-git clone https://github.com/obra/superpowers.git "%USERPROFILE%\.config\opencode\superpowers"
+git clone https://github.com/obra/superpowers.git "%OPENCODE_CONFIG_DIR%\superpowers"
 
 :: 2. Create directories
-mkdir "%USERPROFILE%\.config\opencode\plugins" 2>nul
-mkdir "%USERPROFILE%\.config\opencode\skills" 2>nul
+mkdir "%OPENCODE_CONFIG_DIR%\plugins" 2>nul
+mkdir "%OPENCODE_CONFIG_DIR%\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
+del "%OPENCODE_CONFIG_DIR%\plugins\superpowers.js" 2>nul
+rmdir "%OPENCODE_CONFIG_DIR%\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"
+mklink "%OPENCODE_CONFIG_DIR%\plugins\superpowers.js" "%OPENCODE_CONFIG_DIR%\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"
+mklink /J "%OPENCODE_CONFIG_DIR%\skills\superpowers" "%OPENCODE_CONFIG_DIR%\superpowers\skills"
 
 :: 6. Restart OpenCode
 ```
@@ -90,22 +97,24 @@ mklink /J "%USERPROFILE%\.config\opencode\skills\superpowers" "%USERPROFILE%\.co
 Run as Administrator, or with Developer Mode enabled:
 
 ```powershell
+if (-not $env:OPENCODE_CONFIG_DIR) { $env:OPENCODE_CONFIG_DIR = "$env:USERPROFILE\.config\opencode" }
+
 # 1. Install Superpowers
-git clone https://github.com/obra/superpowers.git "$env:USERPROFILE\.config\opencode\superpowers"
+git clone https://github.com/obra/superpowers.git "$env:OPENCODE_CONFIG_DIR\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"
+New-Item -ItemType Directory -Force -Path "$env:OPENCODE_CONFIG_DIR\plugins"
+New-Item -ItemType Directory -Force -Path "$env:OPENCODE_CONFIG_DIR\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
+Remove-Item "$env:OPENCODE_CONFIG_DIR\plugins\superpowers.js" -Force -ErrorAction SilentlyContinue
+Remove-Item "$env:OPENCODE_CONFIG_DIR\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"
+New-Item -ItemType SymbolicLink -Path "$env:OPENCODE_CONFIG_DIR\plugins\superpowers.js" -Target "$env:OPENCODE_CONFIG_DIR\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"
+New-Item -ItemType Junction -Path "$env:OPENCODE_CONFIG_DIR\skills\superpowers" -Target "$env:OPENCODE_CONFIG_DIR\superpowers\skills"
 
 # 6. Restart OpenCode
 ```
@@ -115,21 +124,23 @@ New-Item -ItemType Junction -Path "$env:USERPROFILE\.config\opencode\skills\supe
 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
+OPENCODE_CONFIG_DIR="${OPENCODE_CONFIG_DIR:-$HOME/.config/opencode}"
+
 # 1. Install Superpowers
-git clone https://github.com/obra/superpowers.git ~/.config/opencode/superpowers
+git clone https://github.com/obra/superpowers.git "$OPENCODE_CONFIG_DIR/superpowers"
 
 # 2. Create directories
-mkdir -p ~/.config/opencode/plugins ~/.config/opencode/skills
+mkdir -p "$OPENCODE_CONFIG_DIR/plugins" "$OPENCODE_CONFIG_DIR/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
+rm -f "$OPENCODE_CONFIG_DIR/plugins/superpowers.js" 2>/dev/null
+rm -rf "$OPENCODE_CONFIG_DIR/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)\""
+cmd //c "mklink \"$(cygpath -w "$OPENCODE_CONFIG_DIR/plugins/superpowers.js")\" \"$(cygpath -w "$OPENCODE_CONFIG_DIR/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)\""
+cmd //c "mklink /J \"$(cygpath -w "$OPENCODE_CONFIG_DIR/skills/superpowers")\" \"$(cygpath -w "$OPENCODE_CONFIG_DIR/superpowers/skills")\""
 
 # 6. Restart OpenCode
 ```
@@ -142,14 +153,16 @@ If running OpenCode inside WSL, use the [macOS / Linux](#macos--linux) instructi
 
 **Command Prompt:**
 ```cmd
-dir /AL "%USERPROFILE%\.config\opencode\plugins"
-dir /AL "%USERPROFILE%\.config\opencode\skills"
+if not defined OPENCODE_CONFIG_DIR set OPENCODE_CONFIG_DIR=%USERPROFILE%\.config\opencode
+dir /AL "%OPENCODE_CONFIG_DIR%\plugins"
+dir /AL "%OPENCODE_CONFIG_DIR%\skills"
 ```
 
 **PowerShell:**
 ```powershell
-Get-ChildItem "$env:USERPROFILE\.config\opencode\plugins" | Where-Object { $_.LinkType }
-Get-ChildItem "$env:USERPROFILE\.config\opencode\skills" | Where-Object { $_.LinkType }
+if (-not $env:OPENCODE_CONFIG_DIR) { $env:OPENCODE_CONFIG_DIR = "$env:USERPROFILE\.config\opencode" }
+Get-ChildItem "$env:OPENCODE_CONFIG_DIR\plugins" | Where-Object { $_.LinkType }
+Get-ChildItem "$env:OPENCODE_CONFIG_DIR\skills" | Where-Object { $_.LinkType }
 ```
 
 Look for `<SYMLINK>` or `<JUNCTION>` in the output.
@@ -186,13 +199,14 @@ use skill tool to load superpowers/brainstorming
 
 ### Personal Skills
 
-Create your own skills in `~/.config/opencode/skills/`:
+Create your own skills in your OpenCode skills directory:
 
 ```bash
-mkdir -p ~/.config/opencode/skills/my-skill
+OPENCODE_CONFIG_DIR="${OPENCODE_CONFIG_DIR:-$HOME/.config/opencode}"
+mkdir -p "$OPENCODE_CONFIG_DIR/skills/my-skill"
 ```
 
-Create `~/.config/opencode/skills/my-skill/SKILL.md`:
+Create a `SKILL.md` in that directory:
 
 ```markdown
 ---
@@ -243,7 +257,7 @@ The plugin automatically injects superpowers context via the `experimental.chat.
 
 ### 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.
+Superpowers uses OpenCode's native `skill` tool for skill discovery and loading. Skills are symlinked into the skills directory so they appear alongside your personal and project skills.
 
 ### Tool Mapping
 
@@ -258,7 +272,7 @@ Skills written for Claude Code are automatically adapted for OpenCode. The boots
 
 ### Plugin Structure
 
-**Location:** `~/.config/opencode/superpowers/.opencode/plugins/superpowers.js`
+**Location:** `$OPENCODE_CONFIG_DIR/superpowers/.opencode/plugins/superpowers.js`
 
 **Components:**
 - `experimental.chat.system.transform` hook for bootstrap injection
@@ -266,14 +280,15 @@ Skills written for Claude Code are automatically adapted for OpenCode. The boots
 
 ### Skills
 
-**Location:** `~/.config/opencode/skills/superpowers/` (symlink to `~/.config/opencode/superpowers/skills/`)
+**Location:** `$OPENCODE_CONFIG_DIR/skills/superpowers/` (symlink to `$OPENCODE_CONFIG_DIR/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
+OPENCODE_CONFIG_DIR="${OPENCODE_CONFIG_DIR:-$HOME/.config/opencode}"
+cd "$OPENCODE_CONFIG_DIR/superpowers"
 git pull
 ```
 
@@ -283,14 +298,14 @@ Restart OpenCode to load the updates.
 
 ### 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)
+1. Check plugin exists: `ls $OPENCODE_CONFIG_DIR/superpowers/.opencode/plugins/superpowers.js`
+2. Check symlink/junction: `ls -l $OPENCODE_CONFIG_DIR/plugins/` (macOS/Linux) or `dir /AL "%OPENCODE_CONFIG_DIR%\plugins"` (Windows)
 3. Check OpenCode logs: `opencode run "test" --print-logs --log-level DEBUG`
 4. Look for plugin loading message in logs
 
 ### Skills not found
 
-1. Verify skills symlink: `ls -l ~/.config/opencode/skills/superpowers` (should point to superpowers/skills/)
+1. Verify skills symlink: `ls -l $OPENCODE_CONFIG_DIR/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
 
@@ -302,7 +317,7 @@ If you see `Cannot find module` errors on Windows:
 
 ### Bootstrap not appearing
 
-1. Verify using-superpowers skill exists: `ls ~/.config/opencode/superpowers/skills/using-superpowers/SKILL.md`
+1. Verify using-superpowers skill exists: `ls $OPENCODE_CONFIG_DIR/superpowers/skills/using-superpowers/SKILL.md`
 2. Check OpenCode version supports `experimental.chat.system.transform` hook
 3. Restart OpenCode after plugin changes
 

hooks/hooks.json

@@ -2,7 +2,7 @@
   "hooks": {
     "SessionStart": [
       {
-        "matcher": "startup|resume|clear|compact",
+        "matcher": "startup|clear|compact",
         "hooks": [
           {
             "type": "command",

skills/brainstorming/SKILL.md

@@ -119,12 +119,9 @@ digraph brainstorming {
 **Spec Review Loop:**
 After writing the spec document:
 
-1. Dispatch spec-document-reviewer subagent (see spec-document-reviewer-prompt.md) with precisely crafted review context — never your session history
-2. Use a fresh reviewer with clean context. Never reuse or resume a prior reviewer.
-3. If the harness supports reviewer-specific model, profile, or effort controls, use the lightest reviewer configuration that can still do the review competently
-4. Use long waits for reviewer verdicts. If the harness distinguishes timeout from failure, timeout means `no verdict yet`, not review failure.
-5. If `ISSUES FOUND`: fix, re-dispatch, repeat until `APPROVED`
-6. If loop exceeds 5 iterations, surface to human for guidance
+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
 
 **User Review Gate:**
 After the spec review loop passes, ask the user to review the written spec before proceeding:

skills/brainstorming/spec-document-reviewer-prompt.md

@@ -10,8 +10,6 @@ Use this template when dispatching a spec document reviewer subagent.
 Task tool (general-purpose):
   description: "Review spec document"
   prompt: |
-    REVIEW ONLY. DO NOT EDIT FILES. DO NOT COMMIT. DO NOT IMPLEMENT FIXES.
-
     You are a spec document reviewer. Verify this spec is complete and ready for planning.
 
     **Spec to review:** [SPEC_FILE_PATH]
@@ -38,15 +36,15 @@ Task tool (general-purpose):
 
     ## Output Format
 
-    First line must be exactly: `APPROVED` or `ISSUES FOUND`
+    ## Spec Review
 
-    ## Issues (if any)
+    **Status:** ✅ Approved | ❌ Issues Found
 
+    **Issues (if any):**
     - [Section X]: [specific issue] - [why it matters]
 
-    ## Recommendations (advisory)
-
+    **Recommendations (advisory):**
     - [suggestions that don't block approval]
 ```
 
-**Reviewer returns:** Verdict, Issues (if any), Recommendations
+**Reviewer returns:** Status, Issues (if any), Recommendations

skills/requesting-code-review/SKILL.md

@@ -33,21 +33,6 @@ HEAD_SHA=$(git rev-parse HEAD)
 
 Use Task tool with superpowers:code-reviewer type, fill template at `code-reviewer.md`
 
-**Reviewer dispatch rules:**
-- Always use a fresh reviewer with clean context.
-- Never reuse or resume a previous reviewer.
-- Provide only the work product and the minimum context needed to review it.
-- Never pass your session transcript or implementation chatter.
-- Make the prompt boundary explicit: review only, no edits, no implementation, no commits.
-- Require the reviewer to start with `APPROVED` or `ISSUES FOUND`.
-
-**Reviewer runtime rules:**
-- If the harness supports reviewer-specific model, profile, or effort controls, use the lightest reviewer configuration that can still do the job well.
-- If the harness does not expose reviewer controls, use the default reviewer configuration without inventing one.
-- Use long waits for reviewer verdicts.
-- If the harness distinguishes timeout from failure, treat timeout as `no verdict yet`, not as review failure.
-- Only declare review failure on actual error, cancellation, or unusable output.
-
 **Placeholders:**
 - `{WHAT_WAS_IMPLEMENTED}` - What you just built
 - `{PLAN_OR_REQUIREMENTS}` - What it should do
@@ -111,8 +96,6 @@ You: [Fix progress indicators]
 - Ignore Critical issues
 - Proceed with unfixed Important issues
 - Argue with valid technical feedback
-- Reuse a reviewer from an earlier pass
-- Treat a short reviewer timeout as proof the review failed
 
 **If reviewer wrong:**
 - Push back with technical reasoning

skills/requesting-code-review/code-reviewer.md

@@ -1,7 +1,5 @@
 # Code Review Agent
 
-REVIEW ONLY. DO NOT EDIT FILES. DO NOT COMMIT. DO NOT IMPLEMENT FIXES.
-
 You are reviewing code changes for production readiness.
 
 **Your task:**
@@ -64,8 +62,6 @@ git diff {BASE_SHA}..{HEAD_SHA}
 
 ## Output Format
 
-First line: `APPROVED` or `ISSUES FOUND`
-
 ### Strengths
 [What's well done? Be specific.]
 

skills/subagent-driven-development/SKILL.md

@@ -99,28 +99,6 @@ Use the least powerful model that can handle each role to conserve cost and incr
 - Touches multiple files with integration concerns → standard model
 - Requires design judgment or broad codebase understanding → most capable model
 
-If the harness exposes reviewer-specific model, profile, or effort controls, use the lightest reviewer configuration that can still perform the review competently. Narrow diff checks and spec-compliance checks usually fit a fast reviewer profile. Broad architectural or final-merge reviews may justify a stronger profile. If the harness does not expose reviewer controls, use the default reviewer configuration without inventing one.
-
-## Reviewer Dispatch Rules
-
-Reviewers are a special case. They must stay isolated from implementation context.
-
-- Always launch reviewers as fresh agents with clean context.
-- Never reuse, resume, or continue a reviewer. If you need re-review after changes, launch a new reviewer.
-- Give reviewers only the artifact to review plus the minimum context needed to evaluate it.
-- Never pass your session transcript, implementation chatter, or private working notes.
-- Review prompts must make the boundary explicit: review only, no edits, no implementation, no commits.
-- Require a rigid verdict header so drift is obvious immediately. Use `APPROVED` or `ISSUES FOUND` as the first line.
-
-### Reviewer Waiting
-
-Reviewer tasks often take longer than implementation tasks because they must derive context from the work product itself.
-
-- Use long waits for reviewer verdicts when the harness supports waiting.
-- If the harness distinguishes timeout from failure, treat timeout as `no verdict yet`, not as review failure.
-- Only declare a review failed when the harness reports an actual error, cancellation, or unusable result.
-- If reviewers can complete asynchronously, keep working and collect the verdict when it arrives.
-
 ## Handling Implementer Status
 
 Implementer subagents report one of four statuses. Handle each appropriately:
@@ -171,12 +149,10 @@ Implementer: "Got it. Implementing now..."
   - Committed
 
 [Dispatch spec compliance reviewer]
-Spec reviewer: APPROVED
-  All requirements met, nothing extra.
+Spec reviewer: ✅ Spec compliant - all requirements met, nothing extra
 
 [Get git SHAs, dispatch code quality reviewer]
-Code reviewer: APPROVED
-  Strengths: Good test coverage, clean. Issues: None.
+Code reviewer: Strengths: Good test coverage, clean. Issues: None. Approved.
 
 [Mark Task 1 complete]
 
@@ -193,7 +169,7 @@ Implementer:
   - Committed
 
 [Dispatch spec compliance reviewer]
-Spec reviewer: ISSUES FOUND
+Spec reviewer: ❌ Issues:
   - Missing: Progress reporting (spec says "report every 100 items")
   - Extra: Added --json flag (not requested)
 
@@ -201,8 +177,7 @@ Spec reviewer: ISSUES FOUND
 Implementer: Removed --json flag, added progress reporting
 
 [Spec reviewer reviews again]
-Spec reviewer: APPROVED
-  Spec compliant now.
+Spec reviewer: ✅ Spec compliant now
 
 [Dispatch code quality reviewer]
 Code reviewer: Strengths: Solid. Issues (Important): Magic number (100)
@@ -211,7 +186,7 @@ Code reviewer: Strengths: Solid. Issues (Important): Magic number (100)
 Implementer: Extracted PROGRESS_INTERVAL constant
 
 [Code reviewer reviews again]
-Code reviewer: APPROVED
+Code reviewer: ✅ Approved
 
 [Mark Task 2 complete]
 
@@ -219,8 +194,7 @@ Code reviewer: APPROVED
 
 [After all tasks]
 [Dispatch final code-reviewer]
-Final reviewer: APPROVED
-  All requirements met, ready to merge.
+Final reviewer: All requirements met, ready to merge
 
 Done!
 ```
@@ -270,10 +244,8 @@ Done!
 - Accept "close enough" on spec compliance (spec reviewer found issues = not done)
 - Skip review loops (reviewer found issues = implementer fixes = review again)
 - Let implementer self-review replace actual review (both are needed)
-- **Start code quality review before spec compliance is `APPROVED`** (wrong order)
+- **Start code quality review before spec compliance is ✅** (wrong order)
 - Move to next task while either review has open issues
-- Reuse a reviewer from an earlier review pass
-- Treat a short reviewer timeout as proof the reviewer failed
 
 **If subagent asks questions:**
 - Answer clearly and completely

skills/subagent-driven-development/code-quality-reviewer-prompt.md

@@ -8,9 +8,6 @@ Use this template when dispatching a code quality reviewer subagent.
 
 ```
 Task tool (superpowers:code-reviewer):
-  Review prompt must begin with:
-    REVIEW ONLY. DO NOT EDIT FILES. DO NOT COMMIT. DO NOT IMPLEMENT FIXES.
-
   Use template at requesting-code-review/code-reviewer.md
 
   WHAT_WAS_IMPLEMENTED: [from implementer's report]
@@ -26,4 +23,4 @@ Task tool (superpowers:code-reviewer):
 - Is the implementation following the file structure from the plan?
 - Did this implementation create new files that are already large, or significantly grow existing files? (Don't flag pre-existing file sizes — focus on what this change contributed.)
 
-**Code reviewer returns:** First line `APPROVED` or `ISSUES FOUND`, then Strengths, Issues (Critical/Important/Minor), Assessment
+**Code reviewer returns:** Strengths, Issues (Critical/Important/Minor), Assessment

skills/subagent-driven-development/spec-reviewer-prompt.md

@@ -8,8 +8,6 @@ Use this template when dispatching a spec compliance reviewer subagent.
 Task tool (general-purpose):
   description: "Review spec compliance for Task N"
   prompt: |
-    REVIEW ONLY. DO NOT EDIT FILES. DO NOT COMMIT. DO NOT IMPLEMENT FIXES.
-
     You are reviewing whether an implementation matches its specification.
 
     ## What Was Requested
@@ -58,7 +56,6 @@ Task tool (general-purpose):
     **Verify by reading code, not by trusting report.**
 
     Report:
-    - First line must be exactly: `APPROVED` or `ISSUES FOUND`
-    - If approved, briefly state why after `APPROVED`
-    - If issues found, list specifically what's missing or extra, with file:line references
+    - ✅ Spec compliant (if everything matches after code inspection)
+    - ❌ Issues found: [list specifically what's missing or extra, with file:line references]
 ```

skills/writing-plans/SKILL.md

@@ -116,11 +116,11 @@ After completing each chunk of the 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`:
+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)
+   - 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.
 
@@ -128,9 +128,6 @@ After completing each chunk of the plan:
 - 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
-- Plan reviewers follow the same isolation rules as code reviewers: fresh reviewer, clean context, no transcript history, no reuse
-- If the harness supports reviewer-specific model, profile, or effort controls, use the lightest reviewer configuration that can still review the chunk competently
-- Use long waits for reviewer verdicts; if the harness distinguishes timeout from failure, timeout means `no verdict yet`, not review failure
 
 ## Execution Handoff
 

skills/writing-plans/plan-document-reviewer-prompt.md

@@ -10,8 +10,6 @@ Use this template when dispatching a plan document reviewer subagent.
 Task tool (general-purpose):
   description: "Review plan chunk N"
   prompt: |
-    REVIEW ONLY. DO NOT EDIT FILES. DO NOT COMMIT. DO NOT IMPLEMENT FIXES.
-
     You are a plan document reviewer. Verify this plan chunk is complete and ready for implementation.
 
     **Plan chunk to review:** [PLAN_FILE_PATH] - Chunk N only
@@ -40,15 +38,15 @@ Task tool (general-purpose):
 
     ## Output Format
 
-    First line: `APPROVED` or `ISSUES FOUND`
+    ## Plan Review - Chunk N
 
-    ## Issues (if any)
+    **Status:** Approved | Issues Found
 
+    **Issues (if any):**
     - [Task X, Step Y]: [specific issue] - [why it matters]
 
-    ## Recommendations (advisory)
-
+    **Recommendations (advisory):**
     - [suggestions that don't block approval]
 ```
 
-**Reviewer returns:** Verdict, Issues (if any), Recommendations
+**Reviewer returns:** Status, Issues (if any), Recommendations