Auto-register skills from plugin, simplify OpenCode install to one line

The plugin's new `config` hook injects the skills directory into
OpenCode's live config singleton, so skills are discovered automatically
without symlinks or manual config edits.

Installation is now just adding one line to opencode.json:
  "plugin": ["superpowers@git+https://github.com/obra/superpowers.git"]

Rewrote docs/README.opencode.md and .opencode/INSTALL.md to reflect
the new approach, removing ~200 lines of platform-specific symlink
instructions. Added migration notes for existing users.

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

@@ -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
 

.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();

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

@@ -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/`.

hooks/hooks.json

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

package.json

@@ -0,0 +1,6 @@
+{
+  "name": "superpowers",
+  "version": "5.0.3",
+  "type": "module",
+  "main": ".opencode/plugins/superpowers.js"
+}

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