docs: tighten reviewer workflow guidance

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

.opencode/INSTALL.md

@@ -7,13 +7,10 @@
 
 ## 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
-OPENCODE_CONFIG_DIR="${OPENCODE_CONFIG_DIR:-$HOME/.config/opencode}"
+git clone https://github.com/obra/superpowers.git ~/.config/opencode/superpowers
-git clone https://github.com/obra/superpowers.git "$OPENCODE_CONFIG_DIR/superpowers"
 ```
 
 ### 2. Register the Plugin
@@ -21,10 +18,9 @@ git clone https://github.com/obra/superpowers.git "$OPENCODE_CONFIG_DIR/superpow
 Create a symlink so OpenCode discovers the plugin:
 
 ```bash
-OPENCODE_CONFIG_DIR="${OPENCODE_CONFIG_DIR:-$HOME/.config/opencode}"
+mkdir -p ~/.config/opencode/plugins
-mkdir -p "$OPENCODE_CONFIG_DIR/plugins"
+rm -f ~/.config/opencode/plugins/superpowers.js
-rm -f "$OPENCODE_CONFIG_DIR/plugins/superpowers.js"
+ln -s ~/.config/opencode/superpowers/.opencode/plugins/superpowers.js ~/.config/opencode/plugins/superpowers.js
-ln -s "$OPENCODE_CONFIG_DIR/superpowers/.opencode/plugins/superpowers.js" "$OPENCODE_CONFIG_DIR/plugins/superpowers.js"
 ```
 
 ### 3. Symlink Skills
@@ -32,10 +28,9 @@ ln -s "$OPENCODE_CONFIG_DIR/superpowers/.opencode/plugins/superpowers.js" "$OPEN
 Create a symlink so OpenCode's native skill tool discovers superpowers skills:
 
 ```bash
-OPENCODE_CONFIG_DIR="${OPENCODE_CONFIG_DIR:-$HOME/.config/opencode}"
+mkdir -p ~/.config/opencode/skills
-mkdir -p "$OPENCODE_CONFIG_DIR/skills"
+rm -rf ~/.config/opencode/skills/superpowers
-rm -rf "$OPENCODE_CONFIG_DIR/skills/superpowers"
+ln -s ~/.config/opencode/superpowers/skills ~/.config/opencode/skills/superpowers
-ln -s "$OPENCODE_CONFIG_DIR/superpowers/skills" "$OPENCODE_CONFIG_DIR/skills/superpowers"
 ```
 
 ### 4. Restart OpenCode
@@ -64,14 +59,13 @@ use skill tool to load superpowers/brainstorming
 
 ### Personal Skills
 
-Create your own skills in your OpenCode skills directory:
+Create your own skills in `~/.config/opencode/skills/`:
 
 ```bash
-OPENCODE_CONFIG_DIR="${OPENCODE_CONFIG_DIR:-$HOME/.config/opencode}"
+mkdir -p ~/.config/opencode/skills/my-skill
-mkdir -p "$OPENCODE_CONFIG_DIR/skills/my-skill"
 ```
 
-Create a `SKILL.md` in that directory:
+Create `~/.config/opencode/skills/my-skill/SKILL.md`:
 
 ```markdown
 ---
@@ -93,8 +87,7 @@ Create project-specific skills in `.opencode/skills/` within your project.
 ## Updating
 
 ```bash
-OPENCODE_CONFIG_DIR="${OPENCODE_CONFIG_DIR:-$HOME/.config/opencode}"
+cd ~/.config/opencode/superpowers
-cd "$OPENCODE_CONFIG_DIR/superpowers"
 git pull
 ```
 
@@ -102,20 +95,15 @@ git pull
 
 ### Plugin not loading
 
-```bash
+1. Check plugin symlink: `ls -l ~/.config/opencode/plugins/superpowers.js`
-OPENCODE_CONFIG_DIR="${OPENCODE_CONFIG_DIR:-$HOME/.config/opencode}"
+2. Check source exists: `ls ~/.config/opencode/superpowers/.opencode/plugins/superpowers.js`
-ls -l "$OPENCODE_CONFIG_DIR/plugins/superpowers.js"
+3. Check OpenCode logs for errors
-ls "$OPENCODE_CONFIG_DIR/superpowers/.opencode/plugins/superpowers.js"
-```
 
 ### Skills not found
 
-```bash
+1. Check skills symlink: `ls -l ~/.config/opencode/skills/superpowers`
-OPENCODE_CONFIG_DIR="${OPENCODE_CONFIG_DIR:-$HOME/.config/opencode}"
+2. Verify it points to: `~/.config/opencode/superpowers/skills`
-ls -l "$OPENCODE_CONFIG_DIR/skills/superpowers"
+3. Use `skill` tool to list what's discovered
-```
-
-Verify the symlink points to `$OPENCODE_CONFIG_DIR/superpowers/skills`. Use `skill` tool to list what's discovered.
 
 ### Tool mapping
 

RELEASE-NOTES.md

@@ -1,35 +1,5 @@
 # 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 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.
+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.
 ```
 
 ## Manual Installation
@@ -17,30 +17,26 @@ Clone https://github.com/obra/superpowers to my OpenCode config directory under
 - [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 "$OPENCODE_CONFIG_DIR/superpowers" ]; then
+if [ -d ~/.config/opencode/superpowers ]; then
-  cd "$OPENCODE_CONFIG_DIR/superpowers" && git pull
+  cd ~/.config/opencode/superpowers && git pull
 else
-  git clone https://github.com/obra/superpowers.git "$OPENCODE_CONFIG_DIR/superpowers"
+  git clone https://github.com/obra/superpowers.git ~/.config/opencode/superpowers
 fi
 
 # 2. Create directories
-mkdir -p "$OPENCODE_CONFIG_DIR/plugins" "$OPENCODE_CONFIG_DIR/skills"
+mkdir -p ~/.config/opencode/plugins ~/.config/opencode/skills
 
 # 3. Remove old symlinks/directories if they exist
-rm -f "$OPENCODE_CONFIG_DIR/plugins/superpowers.js"
+rm -f ~/.config/opencode/plugins/superpowers.js
-rm -rf "$OPENCODE_CONFIG_DIR/skills/superpowers"
+rm -rf ~/.config/opencode/skills/superpowers
 
 # 4. Create symlinks
-ln -s "$OPENCODE_CONFIG_DIR/superpowers/.opencode/plugins/superpowers.js" "$OPENCODE_CONFIG_DIR/plugins/superpowers.js"
+ln -s ~/.config/opencode/superpowers/.opencode/plugins/superpowers.js ~/.config/opencode/plugins/superpowers.js
-ln -s "$OPENCODE_CONFIG_DIR/superpowers/skills" "$OPENCODE_CONFIG_DIR/skills/superpowers"
+ln -s ~/.config/opencode/superpowers/skills ~/.config/opencode/skills/superpowers
 
 # 5. Restart OpenCode
 ```
@@ -48,9 +44,8 @@ ln -s "$OPENCODE_CONFIG_DIR/superpowers/skills" "$OPENCODE_CONFIG_DIR/skills/sup
 #### Verify Installation
 
 ```bash
-OPENCODE_CONFIG_DIR="${OPENCODE_CONFIG_DIR:-$HOME/.config/opencode}"
+ls -l ~/.config/opencode/plugins/superpowers.js
-ls -l "$OPENCODE_CONFIG_DIR/plugins/superpowers.js"
+ls -l ~/.config/opencode/skills/superpowers
-ls -l "$OPENCODE_CONFIG_DIR/skills/superpowers"
 ```
 
 Both should show symlinks pointing to the superpowers directory.
@@ -70,24 +65,22 @@ 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 "%OPENCODE_CONFIG_DIR%\superpowers"
+git clone https://github.com/obra/superpowers.git "%USERPROFILE%\.config\opencode\superpowers"
 
 :: 2. Create directories
-mkdir "%OPENCODE_CONFIG_DIR%\plugins" 2>nul
+mkdir "%USERPROFILE%\.config\opencode\plugins" 2>nul
-mkdir "%OPENCODE_CONFIG_DIR%\skills" 2>nul
+mkdir "%USERPROFILE%\.config\opencode\skills" 2>nul
 
 :: 3. Remove existing links (safe for reinstalls)
-del "%OPENCODE_CONFIG_DIR%\plugins\superpowers.js" 2>nul
+del "%USERPROFILE%\.config\opencode\plugins\superpowers.js" 2>nul
-rmdir "%OPENCODE_CONFIG_DIR%\skills\superpowers" 2>nul
+rmdir "%USERPROFILE%\.config\opencode\skills\superpowers" 2>nul
 
 :: 4. Create plugin symlink (requires Developer Mode or Admin)
-mklink "%OPENCODE_CONFIG_DIR%\plugins\superpowers.js" "%OPENCODE_CONFIG_DIR%\superpowers\.opencode\plugins\superpowers.js"
+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 "%OPENCODE_CONFIG_DIR%\skills\superpowers" "%OPENCODE_CONFIG_DIR%\superpowers\skills"
+mklink /J "%USERPROFILE%\.config\opencode\skills\superpowers" "%USERPROFILE%\.config\opencode\superpowers\skills"
 
 :: 6. Restart OpenCode
 ```
@@ -97,24 +90,22 @@ mklink /J "%OPENCODE_CONFIG_DIR%\skills\superpowers" "%OPENCODE_CONFIG_DIR%\supe
 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:OPENCODE_CONFIG_DIR\superpowers"
+git clone https://github.com/obra/superpowers.git "$env:USERPROFILE\.config\opencode\superpowers"
 
 # 2. Create directories
-New-Item -ItemType Directory -Force -Path "$env:OPENCODE_CONFIG_DIR\plugins"
+New-Item -ItemType Directory -Force -Path "$env:USERPROFILE\.config\opencode\plugins"
-New-Item -ItemType Directory -Force -Path "$env:OPENCODE_CONFIG_DIR\skills"
+New-Item -ItemType Directory -Force -Path "$env:USERPROFILE\.config\opencode\skills"
 
 # 3. Remove existing links (safe for reinstalls)
-Remove-Item "$env:OPENCODE_CONFIG_DIR\plugins\superpowers.js" -Force -ErrorAction SilentlyContinue
+Remove-Item "$env:USERPROFILE\.config\opencode\plugins\superpowers.js" -Force -ErrorAction SilentlyContinue
-Remove-Item "$env:OPENCODE_CONFIG_DIR\skills\superpowers" -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:OPENCODE_CONFIG_DIR\plugins\superpowers.js" -Target "$env:OPENCODE_CONFIG_DIR\superpowers\.opencode\plugins\superpowers.js"
+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:OPENCODE_CONFIG_DIR\skills\superpowers" -Target "$env:OPENCODE_CONFIG_DIR\superpowers\skills"
+New-Item -ItemType Junction -Path "$env:USERPROFILE\.config\opencode\skills\superpowers" -Target "$env:USERPROFILE\.config\opencode\superpowers\skills"
 
 # 6. Restart OpenCode
 ```
@@ -124,23 +115,21 @@ New-Item -ItemType Junction -Path "$env:OPENCODE_CONFIG_DIR\skills\superpowers"
 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 "$OPENCODE_CONFIG_DIR/superpowers"
+git clone https://github.com/obra/superpowers.git ~/.config/opencode/superpowers
 
 # 2. Create directories
-mkdir -p "$OPENCODE_CONFIG_DIR/plugins" "$OPENCODE_CONFIG_DIR/skills"
+mkdir -p ~/.config/opencode/plugins ~/.config/opencode/skills
 
 # 3. Remove existing links (safe for reinstalls)
-rm -f "$OPENCODE_CONFIG_DIR/plugins/superpowers.js" 2>/dev/null
+rm -f ~/.config/opencode/plugins/superpowers.js 2>/dev/null
-rm -rf "$OPENCODE_CONFIG_DIR/skills/superpowers" 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 "$OPENCODE_CONFIG_DIR/plugins/superpowers.js")\" \"$(cygpath -w "$OPENCODE_CONFIG_DIR/superpowers/.opencode/plugins/superpowers.js")\""
+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 "$OPENCODE_CONFIG_DIR/skills/superpowers")\" \"$(cygpath -w "$OPENCODE_CONFIG_DIR/superpowers/skills")\""
+cmd //c "mklink /J \"$(cygpath -w ~/.config/opencode/skills/superpowers)\" \"$(cygpath -w ~/.config/opencode/superpowers/skills)\""
 
 # 6. Restart OpenCode
 ```
@@ -153,16 +142,14 @@ If running OpenCode inside WSL, use the [macOS / Linux](#macos--linux) instructi
 
 **Command Prompt:**
 ```cmd
-if not defined OPENCODE_CONFIG_DIR set OPENCODE_CONFIG_DIR=%USERPROFILE%\.config\opencode
+dir /AL "%USERPROFILE%\.config\opencode\plugins"
-dir /AL "%OPENCODE_CONFIG_DIR%\plugins"
+dir /AL "%USERPROFILE%\.config\opencode\skills"
-dir /AL "%OPENCODE_CONFIG_DIR%\skills"
 ```
 
 **PowerShell:**
 ```powershell
-if (-not $env:OPENCODE_CONFIG_DIR) { $env:OPENCODE_CONFIG_DIR = "$env:USERPROFILE\.config\opencode" }
+Get-ChildItem "$env:USERPROFILE\.config\opencode\plugins" | Where-Object { $_.LinkType }
-Get-ChildItem "$env:OPENCODE_CONFIG_DIR\plugins" | Where-Object { $_.LinkType }
+Get-ChildItem "$env:USERPROFILE\.config\opencode\skills" | Where-Object { $_.LinkType }
-Get-ChildItem "$env:OPENCODE_CONFIG_DIR\skills" | Where-Object { $_.LinkType }
 ```
 
 Look for `<SYMLINK>` or `<JUNCTION>` in the output.
@@ -199,14 +186,13 @@ use skill tool to load superpowers/brainstorming
 
 ### Personal Skills
 
-Create your own skills in your OpenCode skills directory:
+Create your own skills in `~/.config/opencode/skills/`:
 
 ```bash
-OPENCODE_CONFIG_DIR="${OPENCODE_CONFIG_DIR:-$HOME/.config/opencode}"
+mkdir -p ~/.config/opencode/skills/my-skill
-mkdir -p "$OPENCODE_CONFIG_DIR/skills/my-skill"
 ```
 
-Create a `SKILL.md` in that directory:
+Create `~/.config/opencode/skills/my-skill/SKILL.md`:
 
 ```markdown
 ---
@@ -257,7 +243,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 the skills directory 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 `~/.config/opencode/skills/superpowers/` so they appear alongside your personal and project skills.
 
 ### Tool Mapping
 
@@ -272,7 +258,7 @@ Skills written for Claude Code are automatically adapted for OpenCode. The boots
 
 ### Plugin Structure
 
-**Location:** `$OPENCODE_CONFIG_DIR/superpowers/.opencode/plugins/superpowers.js`
+**Location:** `~/.config/opencode/superpowers/.opencode/plugins/superpowers.js`
 
 **Components:**
 - `experimental.chat.system.transform` hook for bootstrap injection
@@ -280,15 +266,14 @@ Skills written for Claude Code are automatically adapted for OpenCode. The boots
 
 ### Skills
 
-**Location:** `$OPENCODE_CONFIG_DIR/skills/superpowers/` (symlink to `$OPENCODE_CONFIG_DIR/superpowers/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
-OPENCODE_CONFIG_DIR="${OPENCODE_CONFIG_DIR:-$HOME/.config/opencode}"
+cd ~/.config/opencode/superpowers
-cd "$OPENCODE_CONFIG_DIR/superpowers"
 git pull
 ```
 
@@ -298,14 +283,14 @@ Restart OpenCode to load the updates.
 
 ### Plugin not loading
 
-1. Check plugin exists: `ls $OPENCODE_CONFIG_DIR/superpowers/.opencode/plugins/superpowers.js`
+1. Check plugin exists: `ls ~/.config/opencode/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)
+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
 
 ### Skills not found
 
-1. Verify skills symlink: `ls -l $OPENCODE_CONFIG_DIR/skills/superpowers` (should point to superpowers/skills/)
+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
 
@@ -317,7 +302,7 @@ If you see `Cannot find module` errors on Windows:
 
 ### Bootstrap not appearing
 
-1. Verify using-superpowers skill exists: `ls $OPENCODE_CONFIG_DIR/superpowers/skills/using-superpowers/SKILL.md`
+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
 

hooks/hooks.json

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

skills/brainstorming/SKILL.md

@@ -119,9 +119,12 @@ digraph brainstorming {
 **Spec Review Loop:**
 After writing the spec document:
 
-1. Dispatch spec-document-reviewer subagent (see spec-document-reviewer-prompt.md)
+1. Dispatch spec-document-reviewer subagent (see spec-document-reviewer-prompt.md) with precisely crafted review context — never your session history
-2. If Issues Found: fix, re-dispatch, repeat until Approved
+2. Use a fresh reviewer with clean context. Never reuse or resume a prior reviewer.
-3. If loop exceeds 5 iterations, surface to human for guidance
+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
 
 **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,6 +10,8 @@ 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]
@@ -36,15 +38,15 @@ Task tool (general-purpose):
 
     ## Output Format
 
-    ## Spec Review
+    First line must be exactly: `APPROVED` or `ISSUES FOUND`
 
-    **Status:** ✅ Approved | ❌ Issues Found
+    ## Issues (if any)
 
-    **Issues (if any):**
     - [Section X]: [specific issue] - [why it matters]
 
-    **Recommendations (advisory):**
+    ## Recommendations (advisory)
+
     - [suggestions that don't block approval]
 ```
 
-**Reviewer returns:** Status, Issues (if any), Recommendations
+**Reviewer returns:** Verdict, Issues (if any), Recommendations

skills/requesting-code-review/SKILL.md

@@ -33,6 +33,21 @@ 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
@@ -96,6 +111,8 @@ 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,5 +1,7 @@
 # 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:**
@@ -62,6 +64,8 @@ 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,6 +99,28 @@ 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:
@@ -149,10 +171,12 @@ Implementer: "Got it. Implementing now..."
   - Committed
 
 [Dispatch spec compliance reviewer]
-Spec reviewer: ✅ Spec compliant - all requirements met, nothing extra
+Spec reviewer: APPROVED
+  All requirements met, nothing extra.
 
 [Get git SHAs, dispatch code quality reviewer]
-Code reviewer: Strengths: Good test coverage, clean. Issues: None. Approved.
+Code reviewer: APPROVED
+  Strengths: Good test coverage, clean. Issues: None.
 
 [Mark Task 1 complete]
 
@@ -169,7 +193,7 @@ Implementer:
   - Committed
 
 [Dispatch spec compliance reviewer]
-Spec reviewer: ❌ Issues:
+Spec reviewer: ISSUES FOUND
   - Missing: Progress reporting (spec says "report every 100 items")
   - Extra: Added --json flag (not requested)
 
@@ -177,7 +201,8 @@ Spec reviewer: ❌ Issues:
 Implementer: Removed --json flag, added progress reporting
 
 [Spec reviewer reviews again]
-Spec reviewer: ✅ Spec compliant now
+Spec reviewer: APPROVED
+  Spec compliant now.
 
 [Dispatch code quality reviewer]
 Code reviewer: Strengths: Solid. Issues (Important): Magic number (100)
@@ -186,7 +211,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]
 
@@ -194,7 +219,8 @@ Code reviewer: ✅ Approved
 
 [After all tasks]
 [Dispatch final code-reviewer]
-Final reviewer: All requirements met, ready to merge
+Final reviewer: APPROVED
+  All requirements met, ready to merge.
 
 Done!
 ```
@@ -244,8 +270,10 @@ 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 ✅** (wrong order)
+- **Start code quality review before spec compliance is `APPROVED`** (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,6 +8,9 @@ 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]
@@ -23,4 +26,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:** Strengths, Issues (Critical/Important/Minor), Assessment
+**Code reviewer returns:** First line `APPROVED` or `ISSUES FOUND`, then Strengths, Issues (Critical/Important/Minor), Assessment

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

@@ -8,6 +8,8 @@ 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
@@ -56,6 +58,7 @@ Task tool (general-purpose):
     **Verify by reading code, not by trusting report.**
 
     Report:
-    - ✅ Spec compliant (if everything matches after code inspection)
+    - First line must be exactly: `APPROVED` or `ISSUES FOUND`
-    - ❌ Issues found: [list specifically what's missing or extra, with file:line references]
+    - If approved, briefly state why after `APPROVED`
+    - If 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
+   - Repeat until `APPROVED`
-3. If ✅ Approved: proceed to next chunk (or execution handoff if last chunk)
+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,6 +128,9 @@ 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,6 +10,8 @@ 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
@@ -38,15 +40,15 @@ Task tool (general-purpose):
 
     ## Output Format
 
-    ## Plan Review - Chunk N
+    First line: `APPROVED` or `ISSUES FOUND`
 
-    **Status:** Approved | Issues Found
+    ## Issues (if any)
 
-    **Issues (if any):**
     - [Task X, Step Y]: [specific issue] - [why it matters]
 
-    **Recommendations (advisory):**
+    ## Recommendations (advisory)
+
     - [suggestions that don't block approval]
 ```
 
-**Reviewer returns:** Status, Issues (if any), Recommendations
+**Reviewer returns:** Verdict, Issues (if any), Recommendations