Release v6.0.3: SDD artifacts move out of the .git/ protected path

Bump all plugin manifests to 6.0.3. This release moves subagent-driven-
development's scratch artifacts (task briefs, implementer reports, review
diffs, progress ledger) from .git/sdd/ — which Claude Code denies agent
writes to — into a self-ignoring working-tree .superpowers/sdd/ dir, and
bumps the brainstorm-server test harness's ws dependency to clear two
dependabot alerts. See RELEASE-NOTES.md.

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

.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "superpowers",
   "description": "Core skills library for Claude Code: TDD, debugging, collaboration patterns, and proven techniques",
-  "version": "4.0.1",
+  "version": "6.0.3",
   "author": {
     "name": "Jesse Vincent",
     "email": "jesse@fsck.com"
@@ -9,5 +9,12 @@
   "homepage": "https://github.com/obra/superpowers",
   "repository": "https://github.com/obra/superpowers",
   "license": "MIT",
-  "keywords": ["skills", "tdd", "debugging", "collaboration", "best-practices", "workflows"]
+  "keywords": [
+    "skills",
+    "tdd",
+    "debugging",
+    "collaboration",
+    "best-practices",
+    "workflows"
+  ]
 }

.codex-plugin/plugin.json

@@ -0,0 +1,48 @@
+{
+  "name": "superpowers",
+  "version": "6.0.3",
+  "description": "An agentic skills framework & software development methodology that works: planning, TDD, debugging, and collaboration workflows.",
+  "author": {
+    "name": "Jesse Vincent",
+    "email": "jesse@fsck.com",
+    "url": "https://github.com/obra"
+  },
+  "homepage": "https://github.com/obra/superpowers",
+  "repository": "https://github.com/obra/superpowers",
+  "license": "MIT",
+  "keywords": [
+    "brainstorming",
+    "subagent-driven-development",
+    "skills",
+    "planning",
+    "tdd",
+    "debugging",
+    "code-review",
+    "workflow"
+  ],
+  "skills": "./skills/",
+  "hooks": "./hooks/hooks-codex.json",
+  "interface": {
+    "displayName": "Superpowers",
+    "shortDescription": "Planning, TDD, debugging, and delivery workflows for coding agents",
+    "longDescription": "Use Superpowers to guide agent work through brainstorming, implementation planning, test-driven development, systematic debugging, parallel execution, code review, and finish-the-branch workflows.",
+    "developerName": "Jesse Vincent",
+    "category": "Coding",
+    "capabilities": [
+      "Interactive",
+      "Read",
+      "Write"
+    ],
+    "defaultPrompt": [
+      "I've got an idea for something I'd like to build.",
+      "Let's add a feature to this project."
+    ],
+    "websiteURL": "https://github.com/obra/superpowers",
+    "privacyPolicyURL": "https://docs.github.com/en/site-policy/privacy-policies/github-general-privacy-statement",
+    "termsOfServiceURL": "https://docs.github.com/en/site-policy/github-terms/github-terms-of-service",
+    "brandColor": "#F59E0B",
+    "composerIcon": "./assets/superpowers-small.svg",
+    "logo": "./assets/app-icon.png",
+    "screenshots": []
+  }
+}

.codex/INSTALL.md

@@ -1,35 +0,0 @@
-# Installing Superpowers for Codex
-
-Quick setup to enable superpowers skills in Codex.
-
-## Installation
-
-1. **Clone superpowers repository**:
-   ```bash
-   mkdir -p ~/.codex/superpowers
-   cd ~/.codex/superpowers
-   git clone https://github.com/obra/superpowers.git .
-   ```
-
-2. **Create personal skills directory**:
-   ```bash
-   mkdir -p ~/.codex/skills
-   ```
-
-3. **Update ~/.codex/AGENTS.md** to include this superpowers section:
-   ```markdown
-   ## Superpowers System
-
-   <EXTREMELY_IMPORTANT>
-   You have superpowers. Superpowers teach you new skills and capabilities. RIGHT NOW run: `~/.codex/superpowers/.codex/superpowers-codex bootstrap` and follow the instructions it returns.
-   </EXTREMELY_IMPORTANT>
-   ```
-
-## Verification
-
-Test the installation:
-```bash
-~/.codex/superpowers/.codex/superpowers-codex bootstrap
-```
-
-You should see skill listings and bootstrap instructions. The system is now ready for use.

.codex/superpowers-bootstrap.md

@@ -1,33 +0,0 @@
-# Superpowers Bootstrap for Codex
-
-<EXTREMELY_IMPORTANT>
-You have superpowers.
-
-**Tool for running skills:**
-- `~/.codex/superpowers/.codex/superpowers-codex use-skill <skill-name>`
-
-**Tool Mapping for Codex:**
-When skills reference tools you don't have, substitute your equivalent tools:
-- `TodoWrite` → `update_plan` (your planning/task tracking tool)
-- `Task` tool with subagents → Tell the user that subagents aren't available in Codex yet and you'll do the work the subagent would do
-- `Skill` tool → `~/.codex/superpowers/.codex/superpowers-codex use-skill` command (already available)
-- `Read`, `Write`, `Edit`, `Bash` → Use your native tools with similar functions
-
-**Skills naming:**
-- Superpowers skills: `superpowers:skill-name` (from ~/.codex/superpowers/skills/)
-- Personal skills: `skill-name` (from ~/.codex/skills/)
-- Personal skills override superpowers skills when names match
-
-**Critical Rules:**
-- Before ANY task, review the skills list (shown below)
-- If a relevant skill exists, you MUST use `~/.codex/superpowers/.codex/superpowers-codex use-skill` to load it
-- Announce: "I've read the [Skill Name] skill and I'm using it to [purpose]"
-- Skills with checklists require `update_plan` todos for each item
-- NEVER skip mandatory workflows (brainstorming before coding, TDD, systematic debugging)
-
-**Skills location:**
-- Superpowers skills: ~/.codex/superpowers/skills/
-- Personal skills: ~/.codex/skills/ (override superpowers when names match)
-
-IF A SKILL APPLIES TO YOUR TASK, YOU DO NOT HAVE A CHOICE. YOU MUST USE IT.
-</EXTREMELY_IMPORTANT>

.codex/superpowers-codex

@@ -1,267 +0,0 @@
-#!/usr/bin/env node
-
-const fs = require('fs');
-const path = require('path');
-const os = require('os');
-const skillsCore = require('../lib/skills-core');
-
-// Paths
-const homeDir = os.homedir();
-const superpowersSkillsDir = path.join(homeDir, '.codex', 'superpowers', 'skills');
-const personalSkillsDir = path.join(homeDir, '.codex', 'skills');
-const bootstrapFile = path.join(homeDir, '.codex', 'superpowers', '.codex', 'superpowers-bootstrap.md');
-const superpowersRepoDir = path.join(homeDir, '.codex', 'superpowers');
-
-// Utility functions
-function printSkill(skillPath, sourceType) {
-    const skillFile = path.join(skillPath, 'SKILL.md');
-    const relPath = sourceType === 'personal'
-        ? path.relative(personalSkillsDir, skillPath)
-        : path.relative(superpowersSkillsDir, skillPath);
-
-    // Print skill name with namespace
-    if (sourceType === 'personal') {
-        console.log(relPath.replace(/\\/g, '/')); // Personal skills are not namespaced
-    } else {
-        console.log(`superpowers:${relPath.replace(/\\/g, '/')}`); // Superpowers skills get superpowers namespace
-    }
-
-    // Extract and print metadata
-    const { name, description } = skillsCore.extractFrontmatter(skillFile);
-
-    if (description) console.log(`  ${description}`);
-    console.log('');
-}
-
-// Commands
-function runFindSkills() {
-    console.log('Available skills:');
-    console.log('==================');
-    console.log('');
-
-    const foundSkills = new Set();
-
-    // Find personal skills first (these take precedence)
-    const personalSkills = skillsCore.findSkillsInDir(personalSkillsDir, 'personal', 2);
-    for (const skill of personalSkills) {
-        const relPath = path.relative(personalSkillsDir, skill.path);
-        foundSkills.add(relPath);
-        printSkill(skill.path, 'personal');
-    }
-
-    // Find superpowers skills (only if not already found in personal)
-    const superpowersSkills = skillsCore.findSkillsInDir(superpowersSkillsDir, 'superpowers', 1);
-    for (const skill of superpowersSkills) {
-        const relPath = path.relative(superpowersSkillsDir, skill.path);
-        if (!foundSkills.has(relPath)) {
-            printSkill(skill.path, 'superpowers');
-        }
-    }
-
-    console.log('Usage:');
-    console.log('  superpowers-codex use-skill <skill-name>   # Load a specific skill');
-    console.log('');
-    console.log('Skill naming:');
-    console.log('  Superpowers skills: superpowers:skill-name (from ~/.codex/superpowers/skills/)');
-    console.log('  Personal skills: skill-name (from ~/.codex/skills/)');
-    console.log('  Personal skills override superpowers skills when names match.');
-    console.log('');
-    console.log('Note: All skills are disclosed at session start via bootstrap.');
-}
-
-function runBootstrap() {
-    console.log('# Superpowers Bootstrap for Codex');
-    console.log('# ================================');
-    console.log('');
-
-    // Check for updates (with timeout protection)
-    if (skillsCore.checkForUpdates(superpowersRepoDir)) {
-        console.log('## Update Available');
-        console.log('');
-        console.log('⚠️  Your superpowers installation is behind the latest version.');
-        console.log('To update, run: `cd ~/.codex/superpowers && git pull`');
-        console.log('');
-        console.log('---');
-        console.log('');
-    }
-
-    // Show the bootstrap instructions
-    if (fs.existsSync(bootstrapFile)) {
-        console.log('## Bootstrap Instructions:');
-        console.log('');
-        try {
-            const content = fs.readFileSync(bootstrapFile, 'utf8');
-            console.log(content);
-        } catch (error) {
-            console.log(`Error reading bootstrap file: ${error.message}`);
-        }
-        console.log('');
-        console.log('---');
-        console.log('');
-    }
-
-    // Run find-skills to show available skills
-    console.log('## Available Skills:');
-    console.log('');
-    runFindSkills();
-
-    console.log('');
-    console.log('---');
-    console.log('');
-
-    // Load the using-superpowers skill automatically
-    console.log('## Auto-loading superpowers:using-superpowers skill:');
-    console.log('');
-    runUseSkill('superpowers:using-superpowers');
-
-    console.log('');
-    console.log('---');
-    console.log('');
-    console.log('# Bootstrap Complete!');
-    console.log('# You now have access to all superpowers skills.');
-    console.log('# Use "superpowers-codex use-skill <skill>" to load and apply skills.');
-    console.log('# Remember: If a skill applies to your task, you MUST use it!');
-}
-
-function runUseSkill(skillName) {
-    if (!skillName) {
-        console.log('Usage: superpowers-codex use-skill <skill-name>');
-        console.log('Examples:');
-        console.log('  superpowers-codex use-skill superpowers:brainstorming  # Load superpowers skill');
-        console.log('  superpowers-codex use-skill brainstorming              # Load personal skill (or superpowers if not found)');
-        console.log('  superpowers-codex use-skill my-custom-skill            # Load personal skill');
-        return;
-    }
-
-    // Handle namespaced skill names
-    let actualSkillPath;
-    let forceSuperpowers = false;
-
-    if (skillName.startsWith('superpowers:')) {
-        // Remove the superpowers: namespace prefix
-        actualSkillPath = skillName.substring('superpowers:'.length);
-        forceSuperpowers = true;
-    } else {
-        actualSkillPath = skillName;
-    }
-
-    // Remove "skills/" prefix if present
-    if (actualSkillPath.startsWith('skills/')) {
-        actualSkillPath = actualSkillPath.substring('skills/'.length);
-    }
-
-    // Function to find skill file
-    function findSkillFile(searchPath) {
-        // Check for exact match with SKILL.md
-        const skillMdPath = path.join(searchPath, 'SKILL.md');
-        if (fs.existsSync(skillMdPath)) {
-            return skillMdPath;
-        }
-
-        // Check for direct SKILL.md file
-        if (searchPath.endsWith('SKILL.md') && fs.existsSync(searchPath)) {
-            return searchPath;
-        }
-
-        return null;
-    }
-
-    let skillFile = null;
-
-    // If superpowers: namespace was used, only check superpowers skills
-    if (forceSuperpowers) {
-        if (fs.existsSync(superpowersSkillsDir)) {
-            const superpowersPath = path.join(superpowersSkillsDir, actualSkillPath);
-            skillFile = findSkillFile(superpowersPath);
-        }
-    } else {
-        // First check personal skills directory (takes precedence)
-        if (fs.existsSync(personalSkillsDir)) {
-            const personalPath = path.join(personalSkillsDir, actualSkillPath);
-            skillFile = findSkillFile(personalPath);
-            if (skillFile) {
-                console.log(`# Loading personal skill: ${actualSkillPath}`);
-                console.log(`# Source: ${skillFile}`);
-                console.log('');
-            }
-        }
-
-        // If not found in personal, check superpowers skills
-        if (!skillFile && fs.existsSync(superpowersSkillsDir)) {
-            const superpowersPath = path.join(superpowersSkillsDir, actualSkillPath);
-            skillFile = findSkillFile(superpowersPath);
-            if (skillFile) {
-                console.log(`# Loading superpowers skill: superpowers:${actualSkillPath}`);
-                console.log(`# Source: ${skillFile}`);
-                console.log('');
-            }
-        }
-    }
-
-    // If still not found, error
-    if (!skillFile) {
-        console.log(`Error: Skill not found: ${actualSkillPath}`);
-        console.log('');
-        console.log('Available skills:');
-        runFindSkills();
-        return;
-    }
-
-    // Extract frontmatter and content using shared core functions
-    let content, frontmatter;
-    try {
-        const fullContent = fs.readFileSync(skillFile, 'utf8');
-        const { name, description } = skillsCore.extractFrontmatter(skillFile);
-        content = skillsCore.stripFrontmatter(fullContent);
-        frontmatter = { name, description };
-    } catch (error) {
-        console.log(`Error reading skill file: ${error.message}`);
-        return;
-    }
-
-    // Display skill header with clean info
-    const displayName = forceSuperpowers ? `superpowers:${actualSkillPath}` :
-                       (skillFile.includes(personalSkillsDir) ? actualSkillPath : `superpowers:${actualSkillPath}`);
-
-    const skillDirectory = path.dirname(skillFile);
-
-    console.log(`# ${frontmatter.name || displayName}`);
-    if (frontmatter.description) {
-        console.log(`# ${frontmatter.description}`);
-    }
-    console.log(`# Skill-specific tools and reference files live in ${skillDirectory}`);
-    console.log('# ============================================');
-    console.log('');
-
-    // Display the skill content (without frontmatter)
-    console.log(content);
-
-}
-
-// Main CLI
-const command = process.argv[2];
-const arg = process.argv[3];
-
-switch (command) {
-    case 'bootstrap':
-        runBootstrap();
-        break;
-    case 'use-skill':
-        runUseSkill(arg);
-        break;
-    case 'find-skills':
-        runFindSkills();
-        break;
-    default:
-        console.log('Superpowers for Codex');
-        console.log('Usage:');
-        console.log('  superpowers-codex bootstrap              # Run complete bootstrap with all skills');
-        console.log('  superpowers-codex use-skill <skill-name> # Load a specific skill');
-        console.log('  superpowers-codex find-skills            # List all available skills');
-        console.log('');
-        console.log('Examples:');
-        console.log('  superpowers-codex bootstrap');
-        console.log('  superpowers-codex use-skill superpowers:brainstorming');
-        console.log('  superpowers-codex use-skill my-custom-skill');
-        break;
-}

.cursor-plugin/plugin.json

@@ -0,0 +1,23 @@
+{
+  "name": "superpowers",
+  "displayName": "Superpowers",
+  "description": "Core skills library: TDD, debugging, collaboration patterns, and proven techniques",
+  "version": "6.0.3",
+  "author": {
+    "name": "Jesse Vincent",
+    "email": "jesse@fsck.com"
+  },
+  "homepage": "https://github.com/obra/superpowers",
+  "repository": "https://github.com/obra/superpowers",
+  "license": "MIT",
+  "keywords": [
+    "skills",
+    "tdd",
+    "debugging",
+    "collaboration",
+    "best-practices",
+    "workflows"
+  ],
+  "skills": "./skills/",
+  "hooks": "./hooks/hooks-cursor.json"
+}

.gitattributes

@@ -0,0 +1,18 @@
+# Ensure shell scripts always have LF line endings
+*.sh text eol=lf
+hooks/session-start text eol=lf
+
+# Ensure the polyglot wrapper keeps LF (it's parsed by both cmd and bash)
+*.cmd text eol=lf
+
+# Common text files
+*.md text eol=lf
+*.json text eol=lf
+*.js text eol=lf
+*.mjs text eol=lf
+*.ts text eol=lf
+
+# Explicitly mark binary files
+*.png binary
+*.jpg binary
+*.gif binary

.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,55 @@
+---
+name: Bug Report
+about: Something isn't working as expected
+labels: bug
+---
+
+<!--
+BEFORE FILING: Search open AND closed issues. The Windows SessionStart
+hook alone has been reported 29 times. If your issue already exists,
+add a comment or reaction to the existing one instead.
+-->
+
+- [ ] I searched existing issues and this is not a duplicate
+
+## Environment (required)
+<!-- Required. We assume an agent filed this report — tell us which one and
+     where it ran. We weigh reports by what produced them. -->
+
+| Field | Value |
+|-------|-------|
+| Superpowers version | |
+| Harness (Claude Code, Cursor, etc.) | |
+| Harness version | |
+| Your model + version | |
+| All plugins installed | |
+| OS + shell | |
+
+## Is this a Superpowers issue or a platform issue?
+<!-- Superpowers is a plugin. Some reported "bugs" are actually issues
+     in the underlying platform or model. If you're not sure, try
+     reproducing without Superpowers installed.
+
+     If the problem persists without Superpowers, file the issue with
+     your platform instead. -->
+
+- [ ] I confirmed this issue does not occur without Superpowers installed
+
+## What happened?
+<!-- Be specific. "It doesn't work" is not a bug report. -->
+
+## Steps to reproduce
+1.
+2.
+3.
+
+## Expected behavior
+<!-- What should have happened? -->
+
+## Actual behavior
+<!-- What happened instead? -->
+
+## Debug log or conversation transcript
+<!-- A debug log or conversation transcript showing the issue is the
+     single most helpful thing you can include. Without one, we're
+     guessing. Screenshots of error output are also useful. -->

.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,5 @@
+blank_issues_enabled: false
+contact_links:
+  - name: Questions & Help
+    url: https://discord.gg/35wsABTejz
+    about: For usage questions, troubleshooting help, and general discussion, please visit our Discord instead of opening an issue.

.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,47 @@
+---
+name: Feature Request
+about: Propose a change or addition to Superpowers
+labels: enhancement
+---
+
+<!--
+BEFORE FILING: Search open AND closed issues. Many features have been
+requested before — some were implemented differently, some are in
+progress, and some were intentionally declined.
+-->
+
+- [ ] I searched existing issues and this has not been proposed before
+
+## What problem does this solve?
+<!-- Describe the problem from your own experience. What were you doing,
+     what went wrong or was missing, and why did it matter?
+
+     "It would be cool if..." is not a problem statement. -->
+
+## Proposed solution
+<!-- What specifically do you want to happen? Be concrete. -->
+
+## What alternatives did you consider?
+<!-- What other approaches could solve the same problem? Why is your
+     proposal better? -->
+
+## Is this appropriate for core Superpowers?
+<!-- Would this benefit someone working on a completely different kind
+     of project? If this is specific to your domain, workflow, or a
+     third-party tool, it may belong as its own plugin instead. -->
+
+## Environment (required)
+<!-- Required. We assume an agent wrote this request — tell us which one and
+     where it ran. We weigh proposals reasoned from documentation differently
+     than ones grounded in a real session where the problem actually came up. -->
+
+| Field | Value |
+|-------|-------|
+| Superpowers version | |
+| Harness (Claude Code, Cursor, etc.) | |
+| Harness version | |
+| Your model + version | |
+| All plugins installed | |
+
+## Context
+<!-- Optional: the workflow where you hit this, links, transcripts. -->

.github/ISSUE_TEMPLATE/platform_support.md

@@ -0,0 +1,34 @@
+---
+name: IDE / Platform Support Request
+about: Request support for a new IDE, editor, or AI coding tool
+labels: platform-support
+---
+
+<!--
+BEFORE FILING: Search existing issues — your IDE may already be
+requested or discussed.
+-->
+
+- [ ] I searched existing issues for this IDE/platform
+
+## Which IDE or platform?
+<!-- Name and link -->
+
+## Does this tool have a plugin or extension system?
+<!-- If yes, link to the docs. If no, explain how third-party
+     integrations typically work with this tool. -->
+
+## Have you tried manual installation?
+<!-- Many tools work with Superpowers through manual setup even without
+     official support. Did you try? What happened? -->
+
+## Environment (required)
+<!-- Required. We assume an agent wrote this request — tell us which one and
+     where it ran. -->
+
+| Field | Value |
+|-------|-------|
+| Harness you currently use (Claude Code, Cursor, etc.) | |
+| Harness version | |
+| Your model + version | |
+| All plugins installed | |

.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,143 @@
+<!--
+BEFORE SUBMITTING: Read every word of this template. PRs that leave
+sections blank, contain multiple unrelated changes, or show no evidence
+of human involvement will be closed without review.
+-->
+
+> **This PR MUST target the `dev` branch, not `main`.** `main` is the
+> released branch; active work lands on `dev` first. PRs opened against
+> `main` will be asked to retarget `dev` before review.
+
+## Who is submitting this PR? (required)
+<!-- Required. PRs that omit this will be closed. We assume an agent wrote
+     this PR — tell us which one and where it ran. We weigh contributions by
+     what produced them: content reasoned from documentation is held to a
+     different bar than work grounded in a real session. -->
+
+| Field | Value |
+|-------|-------|
+| Your model + version | |
+| Harness + version | |
+| All plugins installed | |
+| Human partner who reviewed this diff | |
+
+## What problem are you trying to solve?
+<!-- Describe the specific problem you encountered. If this was a session
+     issue, include: what you were doing, what went wrong, the model's
+     exact failure mode, and ideally a transcript or session log.
+
+     "Improving" something is not a problem statement. What broke? What
+     failed? What was the user experience that motivated this? -->
+
+## What does this PR change?
+<!-- 1-3 sentences. What, not why — the "why" belongs above. -->
+
+## Is this change appropriate for the core library?
+<!-- Superpowers core contains general-purpose skills and infrastructure
+     that benefit all users. Ask yourself:
+
+     - Would this be useful to someone working on a completely different
+       kind of project than yours?
+     - Is this project-specific, team-specific, or tool-specific?
+     - Does this integrate or promote a third-party service?
+
+     If your change is a new skill for a specific domain, workflow tool,
+     or third-party integration, it belongs in its own plugin — not here.
+     See the plugin development docs for how to publish it separately. -->
+
+## What alternatives did you consider?
+<!-- What other approaches did you try or evaluate before landing on this
+     one? Why were they worse? If you didn't consider alternatives, say so
+     — but know that's a red flag. -->
+
+## Does this PR contain multiple unrelated changes?
+<!-- If yes: stop. Split it into separate PRs. Bundled PRs will be closed.
+     If you believe the changes are related, explain the dependency. -->
+
+## Existing PRs
+- [ ] I have reviewed all open AND closed PRs for duplicates or prior art
+- Related PRs: <!-- #number, #number, or "none found" -->
+
+<!-- If a related closed PR exists, explain what's different about your
+     approach and why it should succeed where the other didn't. -->
+
+## Environment tested
+
+| Harness (e.g. Claude Code, Cursor) | Harness version | Model | Model version/ID |
+|-------------------------------------|-----------------|-------|------------------|
+|                                     |                 |       |                  |
+
+## New harness support (required if this PR adds a new harness)
+
+<!-- If this PR adds support for a new harness (IDE, CLI tool, agent
+     runner), you MUST include a session transcript proving the
+     integration actually works.
+
+     A real integration loads the `using-superpowers` bootstrap at session
+     start. The bootstrap is what causes skills to auto-trigger. Without
+     it, the skills are dead weight — present on disk but never invoked
+     at the right moments.
+
+     ACCEPTANCE TEST: Open a clean session in the new harness and send
+     exactly this user message:
+
+         Let's make a react todo list
+
+     A working integration auto-triggers the `brainstorming` skill before
+     any code is written. Paste the complete transcript below.
+
+     These are NOT real integrations and PRs that ship them will be closed:
+
+     - Manually copying skill files into the harness
+     - Wrapping with `npx skills` or similar at-runtime shims
+     - Anything that requires the user to opt in to skills per-session
+     - Anything where brainstorming does not auto-trigger on the test above
+
+     If you are not sure whether your integration loads the bootstrap at
+     session start, it does not.
+-->
+
+<details>
+<summary>Clean-session transcript for "Let's make a react todo list"</summary>
+
+```
+paste the complete transcript here
+```
+
+</details>
+
+## Evaluation
+- What was the initial prompt you (or your human partner) used to start
+  the session that led to this change?
+- How many eval sessions did you run AFTER making the change?
+- How did outcomes change compared to before the change?
+
+<!-- "It works" is not evaluation. Describe the before/after difference
+     you observed across multiple sessions. -->
+
+## Rigor
+
+- [ ] If this is a skills change: I used `superpowers:writing-skills` and
+      completed adversarial pressure testing (paste results below)
+- [ ] This change was tested adversarially, not just on the happy path
+- [ ] I did not modify carefully-tuned content (Red Flags table,
+      rationalizations, "human partner" language) without extensive evals
+      showing the change is an improvement
+
+<!-- If you changed wording in skills that shape agent behavior, show your
+     eval methodology and results. These are not prose — they are code. -->
+
+## Human review
+- [ ] A human has reviewed the COMPLETE proposed diff before submission
+
+<!--
+STOP. If the checkbox above is not checked, do not submit this PR.
+
+PRs will be closed without review if they:
+- Show no evidence of human involvement
+- Contain multiple unrelated changes
+- Promote or integrate third-party services or tools
+- Submit project-specific or personal configuration as core changes
+- Leave required sections blank or use placeholder text
+- Modify behavior-shaping content without eval evidence
+-->

.gitignore

@@ -1,3 +1,13 @@
 .worktrees/
 .private-journal/
 .claude/
+.superpowers/
+.DS_Store
+node_modules/
+inspo
+triage/
+
+# Eval harness lives in its own repository, cloned into evals/ for local
+# development (see CLAUDE.md / README.md). It is not part of the published
+# plugin, so the whole directory is ignored here.
+evals/

.kimi-plugin/plugin.json

@@ -0,0 +1,38 @@
+{
+  "name": "superpowers",
+  "version": "6.0.3",
+  "description": "An agentic skills framework and software development methodology.",
+  "author": {
+    "name": "Jesse Vincent",
+    "email": "jesse@fsck.com"
+  },
+  "homepage": "https://github.com/obra/superpowers",
+  "license": "MIT",
+  "keywords": [
+    "brainstorming",
+    "subagent-driven-development",
+    "skills",
+    "planning",
+    "tdd",
+    "debugging",
+    "code-review",
+    "workflow"
+  ],
+  "skills": "./skills/",
+  "sessionStart": {
+    "skill": "using-superpowers"
+  },
+  "skillInstructions": "Kimi Code tool mapping for Superpowers skills:\n\n- When a Superpowers skill says to ask the user, ask clarifying questions, ask one question at a time, present multiple-choice options, use the terminal for a question, or wait for the user's choice, call Kimi Code's `AskUserQuestion` tool. Do not render those choices as plain assistant text unless `AskUserQuestion` is unavailable or the session is in auto permission mode.\n- For `AskUserQuestion`, provide 1 question with 2-4 concrete options when possible. Put the recommended option first and suffix its label with `(Recommended)`.\n- When a Superpowers skill refers to `TodoWrite`, use Kimi Code's `TodoList` tool.\n- When a Superpowers skill says `Task tool (general-purpose)` or asks you to dispatch an implementer/reviewer subagent, use Kimi Code's `Agent` tool with a Kimi subagent type. Do not pass `general-purpose` as `subagent_type`.\n- For implementation, code review, spec review, quality review, and filled Superpowers subagent prompt templates, call `Agent` with `subagent_type: \"coder\"`, paste the fully filled prompt into `prompt`, and provide a short `description`.\n- For read-only codebase exploration that would take several searches, use `Agent` with `subagent_type: \"explore\"`.\n- For read-only planning or architecture design, use `Agent` with `subagent_type: \"plan\"`.\n- Keep dependent Superpowers subagent steps sequential. Use multiple `Agent` calls, or `run_in_background: true` only when the work is independent and background agents are available.\n- When a Superpowers skill refers to the `Skill` tool, use Kimi Code's native `Skill` tool.\n- Use Kimi Code's `Read`, `Write`, `Edit`, `Bash`, `Grep`, `Glob`, `FetchURL`, `WebSearch`, and MCP tools by their actual exposed names.\n- When a skill asks to search file contents, use `Grep`; when it asks to find files by path or pattern, use `Glob`; when it asks to fetch a URL, use `FetchURL`; when it asks to search the web, use `WebSearch`.",
+  "interface": {
+    "displayName": "Superpowers",
+    "shortDescription": "Planning, TDD, debugging, and delivery workflows for coding agents",
+    "longDescription": "Use Superpowers to guide agent work through brainstorming, implementation planning, test-driven development, systematic debugging, parallel execution, code review, and finish-the-branch workflows.",
+    "developerName": "Jesse Vincent",
+    "capabilities": [
+      "Interactive",
+      "Read",
+      "Write"
+    ],
+    "websiteURL": "https://github.com/obra/superpowers"
+  }
+}

.opencode/INSTALL.md

@@ -3,133 +3,113 @@
 ## Prerequisites
 
 - [OpenCode.ai](https://opencode.ai) installed
-- Node.js installed
-- Git installed
 
-## Installation Steps
+## Installation
 
-### 1. Install Superpowers
+Add superpowers to the `plugin` array in your `opencode.json` (global or project-level):
 
-```bash
-mkdir -p ~/.config/opencode/superpowers
-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. The plugin installs through OpenCode's plugin manager and
+registers all skills.
 
-Create a symlink so OpenCode discovers the plugin:
+Verify by asking: "Tell me about your superpowers"
+
+OpenCode uses its own plugin install. If you also use Claude Code, Codex, or
+another harness, install Superpowers separately for each one.
+
+## 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/plugin
-ln -sf ~/.config/opencode/superpowers/.opencode/plugin/superpowers.js ~/.config/opencode/plugin/superpowers.js
+# Remove old symlinks
+rm -f ~/.config/opencode/plugins/superpowers.js
+rm -rf ~/.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
 ```
 
-### 3. Restart OpenCode
-
-Restart OpenCode. The plugin will automatically inject superpowers context via the chat.message hook.
-
-You should see superpowers is active when you ask "do you have superpowers?"
+Then follow the installation steps above.
 
 ## Usage
 
-### Finding Skills
-
-Use the `find_skills` tool to list all available skills:
+Use OpenCode's native `skill` tool:
 
 ```
-use find_skills tool
+use skill tool to list skills
+use skill tool to load brainstorming
 ```
 
-### Loading a Skill
-
-Use the `use_skill` tool to load a specific skill:
-
-```
-use use_skill tool with skill_name: "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]
-```
-
-Personal skills override superpowers skills with the same name.
-
-### Project Skills
-
-Create project-specific skills in your OpenCode project:
-
-```bash
-# In your OpenCode project
-mkdir -p .opencode/skills/my-project-skill
-```
-
-Create `.opencode/skills/my-project-skill/SKILL.md`:
-
-```markdown
----
-name: my-project-skill
-description: Use when [condition] - [what it does]
----
-
-# My Project Skill
-
-[Your skill content here]
-```
-
-**Skill Priority:** Project skills override personal skills, which override superpowers skills.
-
-**Skill Naming:**
-- `project:skill-name` - Force project skill lookup
-- `skill-name` - Searches project → personal → superpowers
-- `superpowers:skill-name` - Force superpowers skill lookup
-
 ## Updating
 
-```bash
-cd ~/.config/opencode/superpowers
-git pull
+OpenCode installs Superpowers through a git-backed package spec. Some OpenCode
+and Bun versions pin that resolved git dependency in a lockfile or cache, so a
+restart may not pick up the newest Superpowers commit. If updates do not appear,
+clear OpenCode's package cache or reinstall the plugin.
+
+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 file exists: `ls ~/.config/opencode/superpowers/.opencode/plugin/superpowers.js`
-2. Check OpenCode logs for errors
-3. Verify Node.js is installed: `node --version`
+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
+
+### Windows install issues
+
+Some Windows OpenCode builds have upstream installer issues with git-backed
+plugin specs, including cache paths for `git+https` URLs and Bun not finding
+`git.exe` even when it works in a normal terminal. If OpenCode cannot install
+the plugin, try installing with system npm and pointing OpenCode at the local
+package:
+
+```powershell
+npm install superpowers@git+https://github.com/obra/superpowers.git --prefix "$HOME\.config\opencode"
+```
+
+Then use the installed package path in `opencode.json`:
+
+```json
+{
+  "plugin": ["~/.config/opencode/node_modules/superpowers"]
+}
+```
 
 ### Skills not found
 
-1. Verify skills directory exists: `ls ~/.config/opencode/superpowers/skills`
-2. Use `find_skills` tool to see what's discovered
-3. Check file structure: each skill should have a `SKILL.md` file
+1. Use `skill` tool to list what's discovered
+2. Check that the plugin is loading (see above)
 
-### Tool mapping issues
+### Tool mapping
 
-When a skill references a Claude Code tool you don't have:
-- `TodoWrite` → use `update_plan`
-- `Task` with subagents → use `@mention` syntax to invoke OpenCode subagents
-- `Skill` → use `use_skill` tool
-- File operations → use your native tools
+Skills speak in actions ("create a todo", "dispatch a subagent", "read a file"). On OpenCode these resolve to:
+
+- "Create a todo" / "mark complete in todo list" → `todowrite`
+- `Subagent (general-purpose):` template → `task` tool with `subagent_type: "general"` (or `"explore"` for codebase exploration)
+- "Invoke a skill" → OpenCode's native `skill` tool
+- "Read a file" → `read`
+- "Create a file" / "edit a file" / "delete a file" → `apply_patch`
+- "Run a shell command" → `bash`
+- "Search file contents" / "find files by name" → `grep`, `glob`
+- "Fetch a URL" → `webfetch`
 
 ## Getting Help
 
 - Report issues: https://github.com/obra/superpowers/issues
-- Documentation: https://github.com/obra/superpowers
+- Full documentation: https://github.com/obra/superpowers/blob/main/docs/README.opencode.md

.opencode/plugin/superpowers.js

@@ -1,215 +0,0 @@
-/**
- * Superpowers plugin for OpenCode.ai
- *
- * Provides custom tools for loading and discovering skills,
- * with prompt generation for agent configuration.
- */
-
-import path from 'path';
-import fs from 'fs';
-import os from 'os';
-import { fileURLToPath } from 'url';
-import { tool } from '@opencode-ai/plugin/tool';
-import * as skillsCore from '../../lib/skills-core.js';
-
-const __dirname = path.dirname(fileURLToPath(import.meta.url));
-
-export const SuperpowersPlugin = async ({ client, directory }) => {
-  const homeDir = os.homedir();
-  const projectSkillsDir = path.join(directory, '.opencode/skills');
-  // Derive superpowers skills dir from plugin location (works for both symlinked and local installs)
-  const superpowersSkillsDir = path.resolve(__dirname, '../../skills');
-  const personalSkillsDir = path.join(homeDir, '.config/opencode/skills');
-
-  // Helper to generate bootstrap content
-  const getBootstrapContent = (compact = false) => {
-    const usingSuperpowersPath = skillsCore.resolveSkillPath('using-superpowers', superpowersSkillsDir, personalSkillsDir);
-    if (!usingSuperpowersPath) return null;
-
-    const fullContent = fs.readFileSync(usingSuperpowersPath.skillFile, 'utf8');
-    const content = skillsCore.stripFrontmatter(fullContent);
-
-    const toolMapping = compact
-      ? `**Tool Mapping:** TodoWrite->update_plan, Task->@mention, Skill->use_skill
-
-**Skills naming (priority order):** project: > personal > superpowers:`
-      : `**Tool Mapping for OpenCode:**
-When skills reference tools you don't have, substitute OpenCode equivalents:
-- \`TodoWrite\` → \`update_plan\`
-- \`Task\` tool with subagents → Use OpenCode's subagent system (@mention)
-- \`Skill\` tool → \`use_skill\` custom tool
-- \`Read\`, \`Write\`, \`Edit\`, \`Bash\` → Your native tools
-
-**Skills naming (priority order):**
-- Project skills: \`project:skill-name\` (in .opencode/skills/)
-- Personal skills: \`skill-name\` (in ~/.config/opencode/skills/)
-- Superpowers skills: \`superpowers:skill-name\`
-- Project skills override personal, which override superpowers when names match`;
-
-    return `<EXTREMELY_IMPORTANT>
-You have superpowers.
-
-**IMPORTANT: The using-superpowers skill content is included below. It is ALREADY LOADED - you are currently following it. Do NOT use the use_skill tool to load "using-superpowers" - that would be redundant. Use use_skill only for OTHER skills.**
-
-${content}
-
-${toolMapping}
-</EXTREMELY_IMPORTANT>`;
-  };
-
-  // Helper to inject bootstrap via session.prompt
-  const injectBootstrap = async (sessionID, compact = false) => {
-    const bootstrapContent = getBootstrapContent(compact);
-    if (!bootstrapContent) return false;
-
-    try {
-      await client.session.prompt({
-        path: { id: sessionID },
-        body: {
-          noReply: true,
-          parts: [{ type: "text", text: bootstrapContent, synthetic: true }]
-        }
-      });
-      return true;
-    } catch (err) {
-      return false;
-    }
-  };
-
-  return {
-    tool: {
-      use_skill: tool({
-        description: 'Load and read a specific skill to guide your work. Skills contain proven workflows, mandatory processes, and expert techniques.',
-        args: {
-          skill_name: tool.schema.string().describe('Name of the skill to load (e.g., "superpowers:brainstorming", "my-custom-skill", or "project:my-skill")')
-        },
-        execute: async (args, context) => {
-          const { skill_name } = args;
-
-          // Resolve with priority: project > personal > superpowers
-          // Check for project: prefix first
-          const forceProject = skill_name.startsWith('project:');
-          const actualSkillName = forceProject ? skill_name.replace(/^project:/, '') : skill_name;
-
-          let resolved = null;
-
-          // Try project skills first (if project: prefix or no prefix)
-          if (forceProject || !skill_name.startsWith('superpowers:')) {
-            const projectPath = path.join(projectSkillsDir, actualSkillName);
-            const projectSkillFile = path.join(projectPath, 'SKILL.md');
-            if (fs.existsSync(projectSkillFile)) {
-              resolved = {
-                skillFile: projectSkillFile,
-                sourceType: 'project',
-                skillPath: actualSkillName
-              };
-            }
-          }
-
-          // Fall back to personal/superpowers resolution
-          if (!resolved && !forceProject) {
-            resolved = skillsCore.resolveSkillPath(skill_name, superpowersSkillsDir, personalSkillsDir);
-          }
-
-          if (!resolved) {
-            return `Error: Skill "${skill_name}" not found.\n\nRun find_skills to see available skills.`;
-          }
-
-          const fullContent = fs.readFileSync(resolved.skillFile, 'utf8');
-          const { name, description } = skillsCore.extractFrontmatter(resolved.skillFile);
-          const content = skillsCore.stripFrontmatter(fullContent);
-          const skillDirectory = path.dirname(resolved.skillFile);
-
-          const skillHeader = `# ${name || skill_name}
-# ${description || ''}
-# Supporting tools and docs are in ${skillDirectory}
-# ============================================`;
-
-          // Insert as user message with noReply for persistence across compaction
-          try {
-            await client.session.prompt({
-              path: { id: context.sessionID },
-              body: {
-                noReply: true,
-                parts: [
-                  { type: "text", text: `Loading skill: ${name || skill_name}`, synthetic: true },
-                  { type: "text", text: `${skillHeader}\n\n${content}`, synthetic: true }
-                ]
-              }
-            });
-          } catch (err) {
-            // Fallback: return content directly if message insertion fails
-            return `${skillHeader}\n\n${content}`;
-          }
-
-          return `Launching skill: ${name || skill_name}`;
-        }
-      }),
-      find_skills: tool({
-        description: 'List all available skills in the project, personal, and superpowers skill libraries.',
-        args: {},
-        execute: async (args, context) => {
-          const projectSkills = skillsCore.findSkillsInDir(projectSkillsDir, 'project', 3);
-          const personalSkills = skillsCore.findSkillsInDir(personalSkillsDir, 'personal', 3);
-          const superpowersSkills = skillsCore.findSkillsInDir(superpowersSkillsDir, 'superpowers', 3);
-
-          // Priority: project > personal > superpowers
-          const allSkills = [...projectSkills, ...personalSkills, ...superpowersSkills];
-
-          if (allSkills.length === 0) {
-            return 'No skills found. Install superpowers skills to ~/.config/opencode/superpowers/skills/ or add project skills to .opencode/skills/';
-          }
-
-          let output = 'Available skills:\n\n';
-
-          for (const skill of allSkills) {
-            let namespace;
-            switch (skill.sourceType) {
-              case 'project':
-                namespace = 'project:';
-                break;
-              case 'personal':
-                namespace = '';
-                break;
-              default:
-                namespace = 'superpowers:';
-            }
-            const skillName = skill.name || path.basename(skill.path);
-
-            output += `${namespace}${skillName}\n`;
-            if (skill.description) {
-              output += `  ${skill.description}\n`;
-            }
-            output += `  Directory: ${skill.path}\n\n`;
-          }
-
-          return output;
-        }
-      })
-    },
-    event: async ({ event }) => {
-      // Extract sessionID from various event structures
-      const getSessionID = () => {
-        return event.properties?.info?.id ||
-               event.properties?.sessionID ||
-               event.session?.id;
-      };
-
-      // Inject bootstrap at session creation (before first user message)
-      if (event.type === 'session.created') {
-        const sessionID = getSessionID();
-        if (sessionID) {
-          await injectBootstrap(sessionID, false);
-        }
-      }
-
-      // Re-inject bootstrap after context compaction (compact version to save tokens)
-      if (event.type === 'session.compacted') {
-        const sessionID = getSessionID();
-        if (sessionID) {
-          await injectBootstrap(sessionID, true);
-        }
-      }
-    }
-  };
-};

.opencode/plugins/superpowers.js

@@ -0,0 +1,139 @@
+/**
+ * Superpowers plugin for OpenCode.ai
+ *
+ * Injects superpowers bootstrap context via message transform.
+ * Auto-registers skills directory via config hook (no symlinks needed).
+ */
+
+import path from 'path';
+import fs from 'fs';
+import os from 'os';
+import { fileURLToPath } from 'url';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+
+// Simple frontmatter extraction (avoid dependency on skills-core for bootstrap)
+const extractAndStripFrontmatter = (content) => {
+  const match = content.match(/^---\n([\s\S]*?)\n---\n([\s\S]*)$/);
+  if (!match) return { frontmatter: {}, content };
+
+  const frontmatterStr = match[1];
+  const body = match[2];
+  const frontmatter = {};
+
+  for (const line of frontmatterStr.split('\n')) {
+    const colonIdx = line.indexOf(':');
+    if (colonIdx > 0) {
+      const key = line.slice(0, colonIdx).trim();
+      const value = line.slice(colonIdx + 1).trim().replace(/^["']|["']$/g, '');
+      frontmatter[key] = value;
+    }
+  }
+
+  return { frontmatter, content: body };
+};
+
+// Normalize a path: trim whitespace, expand ~, resolve to absolute
+const normalizePath = (p, homeDir) => {
+  if (!p || typeof p !== 'string') return null;
+  let normalized = p.trim();
+  if (!normalized) return null;
+  if (normalized.startsWith('~/')) {
+    normalized = path.join(homeDir, normalized.slice(2));
+  } else if (normalized === '~') {
+    normalized = homeDir;
+  }
+  return path.resolve(normalized);
+};
+
+// Module-level cache for bootstrap content.
+// The SKILL.md file does not change during a session, so reading + parsing it
+// once eliminates redundant fs.existsSync + fs.readFileSync + regex work on
+// every agent step.  See #1202 for the full analysis.
+let _bootstrapCache = undefined; // undefined = not yet loaded, null = file missing
+
+export const SuperpowersPlugin = async ({ client, directory }) => {
+  const homeDir = os.homedir();
+  const superpowersSkillsDir = path.resolve(__dirname, '../../skills');
+  const envConfigDir = normalizePath(process.env.OPENCODE_CONFIG_DIR, homeDir);
+  const configDir = envConfigDir || path.join(homeDir, '.config/opencode');
+
+  // Helper to generate bootstrap content (cached after first call)
+  const getBootstrapContent = () => {
+    // Return cached result on subsequent calls
+    if (_bootstrapCache !== undefined) return _bootstrapCache;
+
+    // Try to load using-superpowers skill
+    const skillPath = path.join(superpowersSkillsDir, 'using-superpowers', 'SKILL.md');
+    if (!fs.existsSync(skillPath)) {
+      _bootstrapCache = null;
+      return null;
+    }
+
+    const fullContent = fs.readFileSync(skillPath, 'utf8');
+    const { content } = extractAndStripFrontmatter(fullContent);
+
+    const toolMapping = `**Tool Mapping for OpenCode:**
+When skills request actions, substitute OpenCode equivalents:
+- Create or update todos → \`todowrite\`
+- \`Subagent (general-purpose):\` → \`task\` with \`subagent_type: "general"\`
+- Invoke a skill → OpenCode's native \`skill\` tool
+- Read files → \`read\`
+- Create, edit, or delete files → \`apply_patch\`
+- Run shell commands → \`bash\`
+- Search files → \`grep\`, \`glob\`
+- Fetch a URL → \`webfetch\`
+
+Use OpenCode's native \`skill\` tool to list and load skills.`;
+
+    _bootstrapCache = `<EXTREMELY_IMPORTANT>
+You have superpowers.
+
+**IMPORTANT: The using-superpowers skill content is included below. It is ALREADY LOADED - you are currently following it. Do NOT use the skill tool to load "using-superpowers" again - that would be redundant.**
+
+${content}
+
+${toolMapping}
+</EXTREMELY_IMPORTANT>`;
+
+    return _bootstrapCache;
+  };
+
+  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);
+      }
+    },
+
+    // Inject bootstrap into the first user message of each session.
+    // Using a user message instead of a system message avoids:
+    //   1. Token bloat from system messages repeated every turn (#750)
+    //   2. Multiple system messages breaking Qwen and other models (#894)
+    //
+    // The hook fires on every agent step (not just every turn) because
+    // opencode's prompt.ts reloads messages from DB each step.  Fresh message
+    // arrays may need injection again, so getBootstrapContent() must not do
+    // repeated disk work.
+    'experimental.chat.messages.transform': async (_input, output) => {
+      const bootstrap = getBootstrapContent();
+      if (!bootstrap || !output.messages.length) return;
+      const firstUser = output.messages.find(m => m.info.role === 'user');
+      if (!firstUser || !firstUser.parts.length) return;
+
+      // Guard: skip if first user message already contains bootstrap.
+      // This prevents double injection when OpenCode passes an already
+      // transformed in-memory message array through the hook again.
+      if (firstUser.parts.some(p => p.type === 'text' && p.text.includes('EXTREMELY_IMPORTANT'))) return;
+
+      const ref = firstUser.parts[0];
+      firstUser.parts.unshift({ ...ref, type: 'text', text: bootstrap });
+    }
+  };
+};

.pi/extensions/superpowers.ts

@@ -0,0 +1,121 @@
+import { readFileSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+
+const EXTREMELY_IMPORTANT_MARKER = "<EXTREMELY_IMPORTANT>";
+const BOOTSTRAP_MARKER = "superpowers:using-superpowers bootstrap for pi";
+
+const extensionDir = dirname(fileURLToPath(import.meta.url));
+const packageRoot = resolve(extensionDir, "../..");
+const skillsDir = resolve(packageRoot, "skills");
+const bootstrapSkillPath = resolve(skillsDir, "using-superpowers", "SKILL.md");
+
+let cachedBootstrap: string | null | undefined;
+
+export default function superpowersPiExtension(pi: ExtensionAPI) {
+	let injectBootstrap = true;
+
+	pi.on("resources_discover", async () => ({
+		skillPaths: [skillsDir],
+	}));
+
+	pi.on("session_start", async () => {
+		injectBootstrap = true;
+	});
+
+	pi.on("session_compact", async () => {
+		injectBootstrap = true;
+	});
+
+	pi.on("agent_end", async () => {
+		injectBootstrap = false;
+	});
+
+	pi.on("context", async (event) => {
+		if (!injectBootstrap) return;
+		if (event.messages.some(messageContainsBootstrap)) return;
+
+		const bootstrap = getBootstrapContent();
+		if (!bootstrap) return;
+
+		const bootstrapMessage = {
+			role: "user" as const,
+			content: [{ type: "text" as const, text: bootstrap }],
+			timestamp: Date.now(),
+		};
+
+		const insertAt = firstNonCompactionSummaryIndex(event.messages);
+		return {
+			messages: [
+				...event.messages.slice(0, insertAt),
+				bootstrapMessage,
+				...event.messages.slice(insertAt),
+			],
+		};
+	});
+}
+
+function getBootstrapContent(): string | null {
+	if (cachedBootstrap !== undefined) return cachedBootstrap;
+
+	try {
+		const skillContent = readFileSync(bootstrapSkillPath, "utf8");
+		const body = stripFrontmatter(skillContent);
+		cachedBootstrap = `${EXTREMELY_IMPORTANT_MARKER}
+${BOOTSTRAP_MARKER}
+
+You have superpowers.
+
+The using-superpowers skill content is included below and is already loaded for this Pi session. Follow it now. Do not try to load using-superpowers again.
+
+${body}
+
+${piToolMapping()}
+</EXTREMELY_IMPORTANT>`;
+		return cachedBootstrap;
+	} catch {
+		cachedBootstrap = null;
+		return null;
+	}
+}
+
+function stripFrontmatter(content: string): string {
+	const match = content.match(/^---\n[\s\S]*?\n---\n([\s\S]*)$/);
+	return (match ? match[1] : content).trim();
+}
+
+function piToolMapping(): string {
+	return `## Pi tool mapping
+
+Pi has native skills but does not expose Claude Code's \`Skill\` tool. When a Superpowers instruction says to invoke a skill, use Pi's native skill system instead: load the relevant \`SKILL.md\` with \`read\` when the skill applies, or let a human invoke \`/skill:name\` explicitly.
+
+Pi's built-in coding tools are lowercase: \`read\`, \`write\`, \`edit\`, \`bash\`, plus optional \`grep\`, \`find\`, and \`ls\`. Use those for the corresponding actions: read a file, create or edit files, run shell commands, search file contents, find files by name, and list directories.
+
+Pi does not ship a standard subagent tool. If a subagent tool such as \`subagent\` from \`pi-subagents\` is available, use it for Superpowers subagent workflows. If no subagent tool is available, do the work in this session or explain the missing capability instead of inventing \`Task\` calls.
+
+Pi does not ship a standard task-list tool. If an installed todo/task tool is available, use it. Otherwise track work in plan files or a repo-local \`TODO.md\` when task tracking is needed. Treat older \`TodoWrite\` references as this task-tracking action.`;
+}
+
+function messageContainsBootstrap(message: unknown): boolean {
+	const content = (message as { content?: unknown }).content;
+	if (typeof content === "string") return content.includes(BOOTSTRAP_MARKER);
+	if (!Array.isArray(content)) return false;
+	return content.some((part) => {
+		return (
+			part &&
+			typeof part === "object" &&
+			(part as { type?: unknown }).type === "text" &&
+			typeof (part as { text?: unknown }).text === "string" &&
+			(part as { text: string }).text.includes(BOOTSTRAP_MARKER)
+		);
+	});
+}
+
+function firstNonCompactionSummaryIndex(messages: unknown[]): number {
+	let index = 0;
+	while ((messages[index] as { role?: unknown } | undefined)?.role === "compactionSummary") {
+		index += 1;
+	}
+	return index;
+}

.pre-commit-config.yaml

@@ -0,0 +1,21 @@
+repos:
+  - repo: local
+    hooks:
+      - id: evals-ruff-check
+        name: evals ruff check
+        entry: uv --project evals run ruff check
+        language: system
+        files: ^evals/.*\.py$
+
+      - id: evals-ruff-format-check
+        name: evals ruff format --check
+        entry: uv --project evals run ruff format --check
+        language: system
+        files: ^evals/.*\.py$
+
+      - id: evals-ty-check
+        name: evals ty check
+        entry: uv --directory evals run ty check
+        language: system
+        pass_filenames: false
+        files: ^evals/.*\.py$

.version-bump.json

@@ -0,0 +1,21 @@
+{
+  "files": [
+    { "path": "package.json", "field": "version" },
+    { "path": ".claude-plugin/plugin.json", "field": "version" },
+    { "path": ".cursor-plugin/plugin.json", "field": "version" },
+    { "path": ".codex-plugin/plugin.json", "field": "version" },
+    { "path": ".kimi-plugin/plugin.json", "field": "version" },
+    { "path": ".claude-plugin/marketplace.json", "field": "plugins.0.version" },
+    { "path": "gemini-extension.json", "field": "version" }
+  ],
+  "audit": {
+    "exclude": [
+      "CHANGELOG.md",
+      "RELEASE-NOTES.md",
+      "node_modules",
+      ".git",
+      ".version-bump.json",
+      "scripts/bump-version.sh"
+    ]
+  }
+}

AGENTS.md

@@ -0,0 +1 @@
+CLAUDE.md

CLAUDE.md

@@ -0,0 +1,115 @@
+# Superpowers — Contributor Guidelines
+
+## If You Are an AI Agent
+
+Stop. Read this section before doing anything.
+
+This repo has a 94% PR rejection rate. Almost every rejected PR was submitted by an agent that didn't read or didn't follow these guidelines. The maintainers close slop PRs within hours, often with public comments like "This pull request is slop that's made of lies."
+
+**Your job is to protect your human partner from that outcome.** Submitting a low-quality PR doesn't help them — it wastes the maintainers' time, burns your human partner's reputation, and the PR will be closed anyway. That is not being helpful. That is being a tool of embarrassment.
+
+Before you open a PR against this repo, you MUST:
+
+1. **Read the entire PR template** at `.github/PULL_REQUEST_TEMPLATE.md` and fill in every section with real, specific answers. Not summaries. Not placeholders.
+2. **Search for existing PRs** — open AND closed — that address the same problem. If duplicates exist, STOP and tell your human partner. Do not open another duplicate.
+3. **Verify this is a real problem.** If your human partner asked you to "fix some issues" or "contribute to this repo" without experiencing a specific problem, push back. Ask them what broke, what failed, what the user experience was.
+4. **Confirm the change belongs in core.** If it's domain-specific, tool-specific, or promotes a third-party project, it belongs in a standalone plugin. Tell your human partner.
+5. **Identify yourself.** Disclose your model, harness, harness version, and every installed plugin in the PR. Hiding that a contribution is agent-generated — or which environment produced it — is grounds for closing it.
+6. **Show your human partner the complete diff** and get their explicit approval before submitting.
+
+If any of these checks fail, do not open the PR. Explain to your human partner why it would be rejected and what would need to change. They will thank you for saving them the embarrassment.
+
+## Pull Request Requirements
+
+**Every PR must fully complete the PR template.** No section may be left blank or filled with placeholder text. PRs that skip sections will be closed without review.
+
+**Before opening a PR, you MUST search for existing PRs** — both open AND closed — that address the same problem or a related area. Reference what you found in the "Existing PRs" section. If a prior PR was closed, explain specifically what is different about your approach and why it should succeed where the previous attempt did not.
+
+**PRs that show no evidence of human involvement will be closed.** A human must review the complete proposed diff before submission.
+
+**Submitters MUST identify themselves.** Every PR and issue must disclose the model, harness, harness version, and all installed plugins used to produce the contribution — or state plainly that it was written by hand with no agent. This is not optional. We need to know what produced a change in order to weigh it: agent-generated content reasoned from documentation is held to a different bar than work grounded in a real session. Contributions that hide their authoring environment will be closed.
+
+**All PRs MUST target the `dev` branch, not `main`.** `main` is the released branch; active work lands on `dev` first. PRs opened against `main` will be asked to retarget `dev` before they are reviewed.
+
+## What We Will Not Accept
+
+### Third-party dependencies
+
+PRs that add optional or required dependencies on third-party projects will not be accepted unless they are adding support for a new harness (e.g., a new IDE or CLI tool). Superpowers is a zero-dependency plugin by design. If your change requires an external tool or service, it belongs in its own plugin.
+
+### "Compliance" changes to skills
+
+Our internal skill philosophy differs from Anthropic's published guidance on writing skills. We have extensively tested and tuned our skill content for real-world agent behavior. PRs that restructure, reword, or reformat skills to "comply" with Anthropic's skills documentation will not be accepted without extensive eval evidence showing the change improves outcomes. The bar for modifying behavior-shaping content is very high.
+
+### Project-specific or personal configuration
+
+Skills, hooks, or configuration that only benefit a specific project, team, domain, or workflow do not belong in core. Publish these as a separate plugin.
+
+### Bulk or spray-and-pray PRs
+
+Do not trawl the issue tracker and open PRs for multiple issues in a single session. Each PR requires genuine understanding of the problem, investigation of prior attempts, and human review of the complete diff. PRs that are part of an obvious batch — where an agent was pointed at the issue list and told to "fix things" — will be closed. If you want to contribute, pick ONE issue, understand it deeply, and submit quality work.
+
+### Speculative or theoretical fixes
+
+Every PR must solve a real problem that someone actually experienced. "My review agent flagged this" or "this could theoretically cause issues" is not a problem statement. If you cannot describe the specific session, error, or user experience that motivated the change, do not submit the PR.
+
+### Domain-specific skills
+
+Superpowers core contains general-purpose skills that benefit all users regardless of their project. Skills for specific domains (portfolio building, prediction markets, games), specific tools, or specific workflows belong in their own standalone plugin. Ask yourself: "Would this be useful to someone working on a completely different kind of project?" If not, publish it separately.
+
+### Fork-specific changes
+
+If you maintain a fork with customizations, do not open PRs to sync your fork or push fork-specific changes upstream. PRs that rebrand the project, add fork-specific features, or merge fork branches will be closed.
+
+### Fabricated content
+
+PRs containing invented claims, fabricated problem descriptions, or hallucinated functionality will be closed immediately. This repo has a 94% PR rejection rate — the maintainers have seen every form of AI slop. They will notice.
+
+### Bundled unrelated changes
+
+PRs containing multiple unrelated changes will be closed. Split them into separate PRs.
+
+## New Harness Support
+
+If your PR adds support for a new harness (IDE, CLI tool, agent runner), you MUST include a session transcript proving the integration works end-to-end.
+
+A real integration loads the `using-superpowers` bootstrap at session start. The bootstrap is what causes skills to auto-trigger at the right moments. Without it, the skills are dead weight — present on disk but never invoked.
+
+**The acceptance test.** Open a clean session in the new harness and send exactly this user message:
+
+> Let's make a react todo list
+
+A working integration auto-triggers the `brainstorming` skill before any code is written. Paste the complete transcript in the PR.
+
+**These are not real integrations and will be closed:**
+
+- Manually copying skill files into the harness
+- Wrapping with `npx skills` or similar at-runtime shims
+- Anything that requires the user to opt in to skills per-session
+- Anything where `brainstorming` does not auto-trigger on the acceptance test above
+
+If you are not sure whether your integration loads the bootstrap at session start, it does not.
+
+## Skill Changes Require Evaluation
+
+Skills are not prose — they are code that shapes agent behavior. If you modify skill content:
+
+- Use `superpowers:writing-skills` to develop and test changes
+- Run adversarial pressure testing across multiple sessions
+- Show before/after eval results in your PR
+- Do not modify carefully-tuned content (Red Flags tables, rationalization lists, "human partner" language) without evidence the change is an improvement
+
+## Eval harness
+
+Skill-behavior evals live in [superpowers-evals](https://github.com/prime-radiant-inc/superpowers-evals/), cloned into `evals/` — see `evals/README.md` for setup. Drill (the harness) drives real tmux sessions of Claude Code / Codex / Gemini CLI and judges skill compliance with an LLM verifier. Plugin-infrastructure tests still live at `tests/`.
+
+## Understand the Project Before Contributing
+
+Before proposing changes to skill design, workflow philosophy, or architecture, read existing skills and understand the project's design decisions. Superpowers has its own tested philosophy about skill design, agent behavior shaping, and terminology (e.g., "your human partner" is deliberate, not interchangeable with "the user"). Changes that rewrite the project's voice or restructure its approach without understanding why it exists will be rejected.
+
+## General
+
+- Read `.github/PULL_REQUEST_TEMPLATE.md` before submitting
+- One problem per PR
+- Test on at least one harness and report results in the environment table
+- Describe the problem you solved, not just what you changed

CODE_OF_CONDUCT.md

@@ -0,0 +1,128 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our
+community a harassment-free experience for everyone, regardless of age, body
+size, visible or invisible disability, ethnicity, sex characteristics, gender
+identity and expression, level of experience, education, socio-economic status,
+nationality, personal appearance, race, religion, or sexual identity
+and orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming,
+diverse, inclusive, and healthy community.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment for our
+community include:
+
+* Demonstrating empathy and kindness toward other people
+* Being respectful of differing opinions, viewpoints, and experiences
+* Giving and gracefully accepting constructive feedback
+* Accepting responsibility and apologizing to those affected by our mistakes,
+  and learning from the experience
+* Focusing on what is best not just for us as individuals, but for the
+  overall community
+
+Examples of unacceptable behavior include:
+
+* The use of sexualized language or imagery, and sexual attention or
+  advances of any kind
+* Trolling, insulting or derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or email
+  address, without their explicit permission
+* Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Enforcement Responsibilities
+
+Community leaders are responsible for clarifying and enforcing our standards of
+acceptable behavior and will take appropriate and fair corrective action in
+response to any behavior that they deem inappropriate, threatening, offensive,
+or harmful.
+
+Community leaders have the right and responsibility to remove, edit, or reject
+comments, commits, code, wiki edits, issues, and other contributions that are
+not aligned to this Code of Conduct, and will communicate reasons for moderation
+decisions when appropriate.
+
+## Scope
+
+This Code of Conduct applies within all community spaces, and also applies when
+an individual is officially representing the community in public spaces.
+Examples of representing our community include using an official e-mail address,
+posting via an official social media account, or acting as an appointed
+representative at an online or offline event.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported to the community leaders responsible for enforcement at
+jesse@primeradiant.com.
+All complaints will be reviewed and investigated promptly and fairly.
+
+All community leaders are obligated to respect the privacy and security of the
+reporter of any incident.
+
+## Enforcement Guidelines
+
+Community leaders will follow these Community Impact Guidelines in determining
+the consequences for any action they deem in violation of this Code of Conduct:
+
+### 1. Correction
+
+**Community Impact**: Use of inappropriate language or other behavior deemed
+unprofessional or unwelcome in the community.
+
+**Consequence**: A private, written warning from community leaders, providing
+clarity around the nature of the violation and an explanation of why the
+behavior was inappropriate. A public apology may be requested.
+
+### 2. Warning
+
+**Community Impact**: A violation through a single incident or series
+of actions.
+
+**Consequence**: A warning with consequences for continued behavior. No
+interaction with the people involved, including unsolicited interaction with
+those enforcing the Code of Conduct, for a specified period of time. This
+includes avoiding interactions in community spaces as well as external channels
+like social media. Violating these terms may lead to a temporary or
+permanent ban.
+
+### 3. Temporary Ban
+
+**Community Impact**: A serious violation of community standards, including
+sustained inappropriate behavior.
+
+**Consequence**: A temporary ban from any sort of interaction or public
+communication with the community for a specified period of time. No public or
+private interaction with the people involved, including unsolicited interaction
+with those enforcing the Code of Conduct, is allowed during this period.
+Violating these terms may lead to a permanent ban.
+
+### 4. Permanent Ban
+
+**Community Impact**: Demonstrating a pattern of violation of community
+standards, including sustained inappropriate behavior,  harassment of an
+individual, or aggression toward or disparagement of classes of individuals.
+
+**Consequence**: A permanent ban from any sort of public interaction within
+the community.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage],
+version 2.0, available at
+https://www.contributor-covenant.org/version/2/0/code_of_conduct.html.
+
+Community Impact Guidelines were inspired by [Mozilla's code of conduct
+enforcement ladder](https://github.com/mozilla/diversity).
+
+[homepage]: https://www.contributor-covenant.org
+
+For answers to common questions about this code of conduct, see the FAQ at
+https://www.contributor-covenant.org/faq. Translations are available at
+https://www.contributor-covenant.org/translations.

GEMINI.md

@@ -0,0 +1,2 @@
+@./skills/using-superpowers/SKILL.md
+@./skills/using-superpowers/references/gemini-tools.md

README.md

@@ -1,6 +1,17 @@
 # Superpowers
 
-Superpowers is a complete software development workflow for your coding agents, built on top of a set of composable "skills" and some initial instructions that make sure your agent uses them.
+Superpowers is a complete software development methodology for your coding agents, built on top of a set of composable skills and some initial instructions that make sure your agent uses them.
+
+
+## We're Hiring!
+
+We're hiring someone to help out full time with Superpowers community and code work. 
+You can read about the job at https://primeradiant.com/jobs/superpowers-community-engineer/
+If this sounds like someone you know, definitely send them our way.
+
+## Quickstart
+
+Give your agent Superpowers: [Claude Code](#claude-code), [Antigravity](#antigravity), [Codex App](#codex-app), [Codex CLI](#codex-cli), [Cursor](#cursor), [Factory Droid](#factory-droid), [Gemini CLI](#gemini-cli), [GitHub Copilot CLI](#github-copilot-cli), [Kimi Code](#kimi-code), [OpenCode](#opencode), [Pi](#pi).
 
 ## How it works
 
@@ -10,72 +21,183 @@ Once it's teased a spec out of the conversation, it shows it to you in chunks sh
 
 After you've signed off on the design, your agent puts together an implementation plan that's clear enough for an enthusiastic junior engineer with poor taste, no judgement, no project context, and an aversion to testing to follow. It emphasizes true red/green TDD, YAGNI (You Aren't Gonna Need It), and DRY. 
 
-Next up, once you say "go", it launches a *subagent-driven-development* process, having agents work through each engineering task, inspecting and reviewing their work, and continuing forward. It's not uncommon for Claude to be able to work autonomously for a couple hours at a time without deviating from the plan you put together.
+Next up, once you say "go", it launches a *subagent-driven-development* process, having agents work through each engineering task, inspecting and reviewing their work, and continuing forward. It's not uncommon for your agent to work autonomously for a couple hours at a time without deviating from the plan you put together.
 
 There's a bunch more to it, but that's the core of the system. And because the skills trigger automatically, you don't need to do anything special. Your coding agent just has Superpowers.
 
+## Commercial Services
 
-## Sponsorship
-
-If Superpowers has helped you do stuff that makes money and you are so inclined, I'd greatly appreciate it if you'd consider [sponsoring my opensource work](https://github.com/sponsors/obra).
-
-Thanks! 
-
-- Jesse
-
+If you're using Superpowers in enterprise and could benefit from commercial support, additional tooling, or managed spending, please don't hesitate to drop us a line at sales@primeradiant.com.
 
 ## Installation
 
-**Note:** Installation differs by platform. Claude Code has a built-in plugin system. Codex and OpenCode require manual setup.
+Installation differs by harness. If you use more than one, install Superpowers separately for each one.
 
-### Claude Code (via Plugin Marketplace)
+### Claude Code
 
-In Claude Code, register the marketplace first:
+Superpowers is available via the [official Claude plugin marketplace](https://claude.com/plugins/superpowers)
+
+#### Official Marketplace
+
+- Install the plugin from Anthropic's official marketplace:
+
+  ```bash
+  /plugin install superpowers@claude-plugins-official
+  ```
+
+#### Superpowers Marketplace
+
+The Superpowers marketplace provides Superpowers and some other related plugins for Claude Code.
+
+- Register the marketplace:
+
+  ```bash
+  /plugin marketplace add obra/superpowers-marketplace
+  ```
+
+- Install the plugin from this marketplace:
+
+  ```bash
+  /plugin install superpowers@superpowers-marketplace
+  ```
+
+### Antigravity
+
+Install Superpowers as a plugin from this repository:
 
 ```bash
-/plugin marketplace add obra/superpowers-marketplace
+agy plugin install https://github.com/obra/superpowers
 ```
 
-Then install the plugin from this marketplace:
+Antigravity runs the plugin's session-start hook, so Superpowers is active from
+the first message. Reinstall with the same command to update.
 
-```bash
-/plugin install superpowers@superpowers-marketplace
-```
+### Codex App
 
-### Verify Installation
+Superpowers is available via the [official Codex plugin marketplace](https://github.com/openai/plugins).
 
-Check that commands appear:
+- In the Codex app, click on Plugins in the sidebar.
+- You should see `Superpowers` in the Coding section.
+- Click the `+` next to Superpowers and follow the prompts.
 
-```bash
-/help
-```
+### Codex CLI
 
-```
-# Should see:
-# /superpowers:brainstorm - Interactive design refinement
-# /superpowers:write-plan - Create implementation plan
-# /superpowers:execute-plan - Execute plan in batches
-```
+Superpowers is available via the [official Codex plugin marketplace](https://github.com/openai/plugins).
 
-### Codex
+- Open the plugin search interface:
 
-Tell Codex:
+  ```bash
+  /plugins
+  ```
 
-```
-Fetch and follow instructions from https://raw.githubusercontent.com/obra/superpowers/refs/heads/main/.codex/INSTALL.md
-```
+- Search for Superpowers:
 
-**Detailed docs:** [docs/README.codex.md](docs/README.codex.md)
+  ```bash
+  superpowers
+  ```
+
+- Select `Install Plugin`.
+
+### Cursor
+
+- In Cursor Agent chat, install from marketplace:
+
+  ```text
+  /add-plugin superpowers
+  ```
+
+- Or search for "superpowers" in the plugin marketplace.
+
+### Factory Droid
+
+- Register the marketplace:
+
+  ```bash
+  droid plugin marketplace add https://github.com/obra/superpowers
+  ```
+
+- Install the plugin:
+
+  ```bash
+  droid plugin install superpowers@superpowers
+  ```
+
+### Gemini CLI
+
+- Install the extension:
+
+  ```bash
+  gemini extensions install https://github.com/obra/superpowers
+  ```
+
+- Update later:
+
+  ```bash
+  gemini extensions update superpowers
+  ```
+
+### GitHub Copilot CLI
+
+- Register the marketplace:
+
+  ```bash
+  copilot plugin marketplace add obra/superpowers-marketplace
+  ```
+
+- Install the plugin:
+
+  ```bash
+  copilot plugin install superpowers@superpowers-marketplace
+  ```
+
+### Kimi Code
+
+Superpowers is available in Kimi Code's plugin marketplace.
+
+- Open Kimi Code's plugin manager:
+
+  ```text
+  /plugins
+  ```
+
+- Go to `Marketplace` > `Superpowers` and install it.
+
+- Or install directly from this repository:
+
+  ```text
+  /plugins install https://github.com/obra/superpowers
+  ```
+
+- Detailed docs: [docs/README.kimi.md](docs/README.kimi.md)
 
 ### OpenCode
 
-Tell OpenCode:
+OpenCode uses its own plugin install; install Superpowers separately even if you
+already use it in another harness.
 
-```
-Fetch and follow instructions from https://raw.githubusercontent.com/obra/superpowers/refs/heads/main/.opencode/INSTALL.md
+- Tell OpenCode:
+
+  ```
+  Fetch and follow instructions from https://raw.githubusercontent.com/obra/superpowers/refs/heads/main/.opencode/INSTALL.md
+  ```
+
+- Detailed docs: [docs/README.opencode.md](docs/README.opencode.md)
+
+### Pi
+
+Install Superpowers as a Pi package from this repository:
+
+```bash
+pi install git:github.com/obra/superpowers
 ```
 
-**Detailed docs:** [docs/README.opencode.md](docs/README.opencode.md)
+For local development, run Pi with this checkout loaded as a temporary package:
+
+```bash
+pi -e /path/to/superpowers
+```
+
+The Pi package loads the Superpowers skills and a small extension that injects the `using-superpowers` bootstrap at session startup and again after compaction. Pi has native skills, so no compatibility `Skill` tool is required. Subagent and task-list tools remain optional Pi companion packages.
 
 ## The Basic Workflow
 
@@ -128,32 +250,38 @@ Fetch and follow instructions from https://raw.githubusercontent.com/obra/superp
 - **Complexity reduction** - Simplicity as primary goal
 - **Evidence over claims** - Verify before declaring success
 
-Read more: [Superpowers for Claude Code](https://blog.fsck.com/2025/10/09/superpowers/)
+Read [the original release announcement](https://blog.fsck.com/2025/10/09/superpowers/).
 
 ## Contributing
 
-Skills live directly in this repository. To contribute:
+The general contribution process for Superpowers is below. Keep in mind that we don't generally accept contributions of new skills and that any updates to skills must work across all of the coding agents we support.
 
 1. Fork the repository
-2. Create a branch for your skill
-3. Follow the `writing-skills` skill for creating and testing new skills
-4. Submit a PR
+2. Switch to the 'dev' branch
+3. Create a branch for your work
+4. Follow the `writing-skills` skill for creating and testing new and modified skills
+5. Submit a PR, being sure to fill in the pull request template.
+
+Skill-behavior tests use the drill eval harness from [superpowers-evals](https://github.com/prime-radiant-inc/superpowers-evals/), cloned into `evals/` — see `evals/README.md` for setup. Plugin-infrastructure tests live at `tests/` and run via the relevant `run-*.sh` or `npm test`.
 
 See `skills/writing-skills/SKILL.md` for the complete guide.
 
 ## Updating
 
-Skills update automatically when you update the plugin:
-
-```bash
-/plugin update superpowers
-```
+Superpowers updates are somewhat coding-agent dependent, but are often automatic.
 
 ## License
 
 MIT License - see LICENSE file for details
 
-## Support
+## Visual companion telemetry
 
+Because skills and plugins don't provide any feedback to creators, we have no idea how many of you are using Superpowers. By default, the Prime Radiant logo on brainstorming's optional visual companion feature is loaded from our website. It includes the version of Superpowers in use. It does not include any details about your project, prompt, or coding agent. We don't see your clicks or anything about what you're building. This helps us have a rough idea of how many folks are using Superpowers and which version of Superpowers they're using. It's 100% optional. To disable this, set the environment variable `SUPERPOWERS_DISABLE_TELEMETRY` to any true value. Superpowers also honors Claude Code's `DISABLE_TELEMETRY` and `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC` opt-outs.
+
+## Community
+
+Superpowers is built by [Jesse Vincent](https://blog.fsck.com) and the rest of the folks at [Prime Radiant](https://primeradiant.com).
+
+- **Discord**: [Join us](https://discord.gg/35wsABTejz) for community support, questions, and sharing what you're building with Superpowers
 - **Issues**: https://github.com/obra/superpowers/issues
-- **Marketplace**: https://github.com/obra/superpowers-marketplace
+- **Release announcements**: [Sign up](https://primeradiant.com/superpowers/) to get notified about new versions

RELEASE-NOTES.md

@@ -1,6 +1,695 @@
 # Superpowers Release Notes
 
-## v4.0.1 (2025-12-22)
+## v6.0.3 (2026-06-18)
+
+### Subagent-Driven Development
+
+- **SDD scratch files moved out of `.git/`.** Claude Code treats `.git/` as a protected path and denies agent writes there, so an implementer subagent writing its report into `.git/sdd/` got blocked mid-run. Task briefs, implementer reports, review diffs, and the progress ledger now live in a self-ignoring `.superpowers/sdd/` directory in the working tree — kept out of `git status` and out of commits, and resolved per worktree by a shared `sdd-workspace` helper. One caveat: because the workspace is git-ignored working-tree scratch, `git clean -fdx` will delete the progress ledger; recover from `git log` if that happens. (#1780)
+
+## v6.0.2 (2026-06-16)
+
+### Install Fixes
+
+- **We no longer ship the `evals` submodule.** It broke plugin installs for some users, so the eval harness now lives in its own repo, separate from the published plugin. (#1778, #1774)
+
+## v6.0.1 (2026-06-16)
+
+### Codex Fixes
+
+- **Version display in the brainstorm companion** — packaged Codex plugins ship without a root `package.json`, so the visual companion reported its version as "unknown". `readSuperpowersVersion()` now falls back to `.codex-plugin/plugin.json` when `package.json` is absent.
+- **Cleaner Codex plugin sync** — the sync-to-codex script now excludes `.gitmodules` and `.pre-commit-config.yaml`, keeping repo metadata out of the packaged Codex plugin.
+
+## v6.0.0 (2026-06-16)
+
+Superpowers 6.0 is a big release. The headline is a rewrite of how `subagent-driven-development` reviews each task — cheaper, stricter, and harder to game. 
+
+While these numbers won't hold on every harness and for every workload, in our evals, Claude Code and Codex produce similar high-quality results roughly twice as fast and while spending almost 50% fewer tokens.
+
+It also adds three new harnesses (Kimi Code, Pi, and Antigravity), gives the brainstorming visual companion a better security model, and rewrites a number of skills' tool calls to be significantly more vendor-neutral.
+
+### Visible Changes
+
+- **The two per-task reviewer prompts became one.** `spec-reviewer-prompt.md` and `code-quality-reviewer-prompt.md` are gone, replaced by a single `task-reviewer-prompt.md`. If you dispatch the old files directly, switch to the new one.
+- **The legacy global worktree directory is gone.** `using-git-worktrees` and `finishing-a-development-branch` no longer use `~/.config/superpowers/worktrees/`. Worktrees now land in the project — an existing `.worktrees/` or `worktrees/` if you have one, otherwise a fresh `.worktrees/` — unless you say otherwise.
+
+### New Harness Support
+
+Superpowers now runs on three more harnesses. Each ships its own bootstrap, a tool-mapping reference, and tests, and each gets its own install section in the README.
+
+- **Kimi Code** — a plugin manifest, install docs, and manifest tests; install from Kimi's marketplace or straight from the repo. (initial manifest by @qer)
+- **Pi** — a session-start extension that registers the skills and injects the `using-superpowers` bootstrap. Pi has native skills, so it needs no compatibility shim.
+- **Antigravity (`agy`)** — installs the plugin directly and bootstraps from the first message; verified end-to-end against the standard "make a react todo list" acceptance test.
+
+### Subagent-Driven Development
+
+A long run of cost-and-quality experiments on real projects reshaped how the controller reviews each task. The old flow ran two reviewers per task and leaned on the controller's judgment for model choice and severity, and both turned out to be expensive and easy to game. The new flow runs one reviewer per task, hands work off as files instead of pasted text, and takes several judgment calls away from the controller.
+
+- **One reviewer per task, two verdicts.** A single `task-reviewer-prompt.md` reads the task's diff once and returns both a spec-compliance verdict and a quality verdict, so one fix pass clears both. A new "can't verify from the diff" verdict flags requirements that live in untouched code, for the controller to check itself. (#1538, #1543)
+- **One broad review at the end.** The run finishes with a single whole-branch review on the most capable model, instead of re-reviewing everything task by task.
+- **Plans get a pre-flight read.** Before the first task, the controller checks the plan for internal conflicts — and for anything the plan asks for that a reviewer would flag as a defect — and raises it all at once, rather than stumbling into it mid-run.
+- **Diffs and task text move as files.** A pasted diff parks itself permanently in the most expensive context, and a reviewer without one rebuilds it by hand — the single biggest reviewer cost. Two new scripts, `task-brief` and `review-package`, write the task text and the review diff to files for the subagent to read.
+- **Every dispatch states its model.** Left to choose, controllers stopped naming a model at all — and an unnamed model quietly inherits the session's most expensive one, so one run put all 26 of its reviewers on the top tier. The templates now require a model, with guidance that reaches for cheaper tiers when the work allows.
+- **The controller can't tell a reviewer what to ignore.** Real runs caught controllers coaching reviewers to skip a finding or call it "Minor at most," and the flaw shipped. Suppressing findings and pre-rating severity are now banned outright, and a defect the plan itself mandates gets reported for you to decide on rather than waved through.
+- **Reviewers are read-only and skeptical of rationales.** Review no longer touches the working tree or branch — a reviewer running `git checkout` had been orphaning later commits — and an implementer's "I left this unabstracted on purpose" no longer talks a reviewer out of a real finding.
+- **Stronger evidence and reporting.** Reviewers back each answer with a file and line, the implementer's report moves to a file and carries red/green evidence when TDD applies, and a progress ledger lets a controller that loses its context resume instead of redoing finished work. (#994)
+
+### Writing Plans
+
+Plans now carry the structure the controller and reviewers used to re-derive on every dispatch.
+
+- **A Global Constraints block** lists the rules that bind every task — version floors, dependency limits, naming and copy, exact values — copied in verbatim, so they actually reach the implementers and reviewers downstream.
+- **A per-task Interfaces block** names exactly what each task consumes and produces, so an implementer who sees only its own task still knows its neighbors' contracts.
+- **Right-sizing guidance** keeps a task at the size that earns its own test cycle and a reviewer's pass, folding setup, config, and docs into the task that needs them. In testing, a plan written this way needed one round of fixes where the control needed two to four — and the control shipped a real bug.
+
+### Brainstorming Visual Companion
+
+The visual companion is a small web server the agent opens alongside the conversation. It had no authentication at all, so on a shared or remote machine anyone who could reach the port could read your brainstorm — or inject events the agent treats as your input. This release gives it a real security model and makes it survive restarts and dropped connections.
+
+- **A per-session key now guards everything.** The agent's URL carries a one-time key, the browser tucks it into a tab-scoped cookie, and every request and WebSocket connection has to present it. This closes the door to stray local tabs and routable remote hosts alike, including the DNS-rebinding case an origin allowlist can't catch. (Closes #1014)
+- **The file server stays in its sandbox.** It refuses symlinks, dotfiles, and any path that climbs out of the content directory, ignores macOS resource-fork files, and sends the usual no-store and deny-framing headers. Files that hold the session key are written owner-only.
+- **The companion is offered only when it helps.** The skill raises it the first time a question would read better shown than told, as its own message, and lets a decline stand. Accepting opens your browser to the first screen. (Closes #755)
+- **It survives restarts and flaky connections.** Given a project directory, the server keeps the same port and key across restarts, so an open tab simply reconnects. The page reconnects on its own, shows a live status pill, and raises a "paused" overlay while the server is down.
+- **Longer idle life, safer shutdown.** The idle timeout went from 30 minutes to 4 hours, and `stop-server.sh` now confirms it owns the right process before signaling, so it never kills an unrelated `node` after a reboot. (#1703)
+- **Windows launch hardening** — consolidated shell detection, and Windows now relies on the idle timeout for shutdown, since Node can't track POSIX process ownership across MSYS2.
+
+
+### Existing Harness Updates
+
+- **Codex** now bootstraps through its own SessionStart hook rather than shared wiring, and the Codex App gained an install section and fuller tool docs (web search, `AGENTS.md`, personal skills). (#1540)
+- **OpenCode** got an action-based tool mapping across its plugin, install doc, and README, plus a bootstrap-caching test.
+- **Cursor**'s manifest dropped its `agents` and `commands` entries, since those directories no longer exist.
+
+### One Set of Skills, Every Harness
+
+The skills used to speak Claude Code's dialect — "use the Task tool," "put it in CLAUDE.md." This release rewrites that vocabulary in terms of what you're actually doing ("dispatch a subagent," "your instructions file") and adds a per-harness reference that maps each action to the right tool, checked against each runtime. Prose that named "Claude" now says "your agent."
+
+- **A tool reference per harness** at `skills/using-superpowers/references/`, covering Claude Code, Codex, Copilot, Gemini, Pi, and Antigravity.
+- **`finishing-a-development-branch` went forge-neutral** — it no longer hardcodes `gh pr create`, so agents push with whatever forge tooling they have. (#1609)
+- **One rename:** "Claude Search Optimization" is now "Skill Discovery Optimization," since the technique isn't Claude-specific.
+
+### Writing Skills
+
+Two additions for skill authors.
+
+- **Match the Form to the Failure** — a short table for picking the right kind of guidance. A flat "don't do X" works for discipline slips but backfires when the problem is the *shape* of an output, where a worked example does better. The table, and a tighter scope on the existing rationalization section, steer authors to the form that actually helps.
+- **Micro-Test Wording** — a cheap way to check a phrasing before committing to it: sample it a handful of times against a no-guidance control and read every result by hand, treating run-to-run variance as a warning sign.
+
+### Testing
+
+Skill-behavior testing moved out of `tests/` into a new `evals/` submodule built on "drill," which runs real Claude Code, Codex, and Gemini sessions and judges them with an LLM. Several in-tree bash suites retired once a stricter drill scenario covered them; the few with no equivalent stayed. From here on, `tests/` holds plugin-code tests and `evals/` holds skill-behavior tests, and `docs/testing.md` explains the split. New backends reach Antigravity, Pi, and more models, and new shell-lint and pre-commit checks guard the harness. (#1541)
+
+### Bug Fixes
+
+- **systematic-debugging no longer forces every session into extended thinking.** One bullet held the exact keyword Claude Code scans for, quietly tripping the switch on every session that loaded the skill. A hyphen breaks the keyword; the text still reads. (#1283, by @Nick Galatis)
+- **The Windows SessionStart hook stopped printing a write error every session** — each `printf` now routes through `cat` to absorb the broken pipe, and the output is otherwise unchanged. (#1612, reported by @silvertakana)
+- **Windows foreground mode** tracks the right process and clears its owner PID on MSYS2. (by @nestorluiscamachopaz)
+- **The `using-superpowers` bootstrap** no longer lists "debugging" as a skill that doesn't exist. (reported by @mhat)
+- **The TDD skill** links the testing anti-patterns reference. (#1532, #1529; link fix #1474 by @Stable Genius)
+- **`using-git-worktrees`** fixes its step numbering and drops stale Cursor references. (#1522, and by @fuleinist)
+- **The Codex review skill** swaps a private in-joke for plain guidance. (#1531)
+
+### Documentation & Contributor Guidelines
+
+- **A guide to porting Superpowers to a new harness** (`docs/porting-to-a-new-harness.md`) lays out the three pieces every integration needs and the one rule that makes or breaks it: load the bootstrap at session start.
+- **Every PR and issue now discloses how it was made** — model, harness, version, and installed plugins, or a note that it was written by hand. We weigh a contribution differently depending on what produced it. PRs also target `dev`, not `main`. The PR template, all three issue templates, and a new platform-support template carry this.
+
+### Contributors
+
+Thanks to @mattvanhorn, @nawfal, @Nick Galatis, @silvertakana, @nestorluiscamachopaz, @qer, @mhat, @Stable Genius, @fuleinist, @dev_Hakaze, @robotsnh, Rahul, and @arittr.
+
+## v5.1.0 (2026-04-30)
+
+### Removals
+
+- **Legacy slash commands removed** — `/brainstorm`, `/execute-plan`, and `/write-plan` are gone. They were deprecated stubs that did nothing but tell the user to invoke the corresponding skill. Invoke `superpowers:brainstorming`, `superpowers:executing-plans`, and `superpowers:writing-plans` directly instead. (#1188)
+- **`superpowers:code-reviewer` named agent removed** — the agent was the plugin's only named agent and was used by exactly two skills, while every other reviewer/implementer subagent in the repo dispatches `general-purpose` with a prompt template alongside its skill. The agent's persona and checklist have been merged into `skills/requesting-code-review/code-reviewer.md` as a self-contained Task-dispatch template. Anyone dispatching `Task (superpowers:code-reviewer)` should switch to `Task (general-purpose)` with the prompt template instead. (PR #1299)
+- **Integration sections removed from skills** — these were a legacy of the time before agents had native skills systems and didn't help with steering.
+
+### Worktree Skills Rewrite
+
+`using-git-worktrees` and `finishing-a-development-branch` now detect when the agent is already running inside an isolated worktree and prefer the harness's native worktree controls before falling back to `git worktree`. Behavior was TDD-validated and cross-platform-checked across five harnesses. (PRI-974, PR #1121)
+
+- **Environment detection** — both skills check `GIT_DIR != GIT_COMMON` before doing anything; if already in a linked worktree, creation is skipped entirely. A submodule guard prevents false detection.
+- **Consent before creating worktrees** — `using-git-worktrees` no longer creates worktrees implicitly; the skill asks the user first. Fixes #991 (subagent-driven-development was auto-creating worktrees without consent).
+- **Native tool preference (Step 1a)** — when the harness exposes its own worktree tool (e.g. Codex), the skill defers to it. The user's stated preference is respected when expressed.
+- **Provenance-based cleanup** — `finishing-a-development-branch` only cleans up worktrees inside `.worktrees/` (created by superpowers); anything outside is left alone. Fixes #940 (Option 2 was incorrectly cleaning up worktrees), #999 (merge-then-remove ordering), and #238 (`cd` to repo root before `git worktree remove`).
+- **Detached HEAD handling** — the finishing menu collapses to two options when there is no branch to merge from.
+- **Hardcoded `/Users/jesse` paths** in skill examples replaced with generic placeholders. (#858, PR #1122)
+
+### Contributor Guidelines for AI Agents
+
+Two new sections at the top of `CLAUDE.md` (symlinked to `AGENTS.md`) speak directly to AI agents. An audit of the last 100 closed PRs against this repo showed a 94% rejection rate driven by AI-generated slop: agents that didn't read the PR template, opened duplicates, fabricated problem descriptions, or pushed fork- or domain-specific changes upstream.
+
+- **Pre-submission checklist** — read the PR template, search for existing PRs, verify a real problem exists, confirm the change belongs in core, and show the human partner the complete diff before submitting.
+- **What we will not accept** — third-party dependencies, "compliance" rewrites of skill content, project-specific configuration, bulk PRs, speculative fixes, domain-specific skills, fork-specific changes, fabricated content, and bundled unrelated changes.
+- **New harness PRs require a session transcript** — most past new-harness integrations copied skill files or wrapped with `npx skills` instead of loading the `using-superpowers` bootstrap at session start. The acceptance test ("Let's make a react todo list" must auto-trigger `brainstorming` in a clean session) and a complete transcript are now required.
+
+### Codex Plugin Mirror Tooling
+
+New `sync-to-codex-plugin` script mirrors superpowers into the OpenAI Codex plugin marketplace as `prime-radiant-inc/openai-codex-plugins`. Path/user-agnostic so any team member can run it. (PR #1165)
+
+- Clones the fork fresh into a temp directory per run, regenerates overlays inline, and opens a PR; auto-detects upstream from the script's own location and preflights `rsync`/`git`/`gh auth`/`python3`.
+- `--bootstrap` flag for first-time setup; `EXCLUDES` patterns anchored to source root; `assets/` excluded.
+- Mirrors `CODE_OF_CONDUCT.md`; drops the `agents/openai.yaml` overlay.
+- Seeds `interface.defaultPrompt` in the mirrored `plugin.json`. (PR #1180 by @arittr)
+- Codex plugin files are committed to the source repo so the sync script uses canonical versions; Codex marketplace metadata is preserved.
+
+### OpenCode
+
+- **Bootstrap content cached at module level** — `getBootstrapContent()` was calling `fs.existsSync` + `fs.readFileSync` + frontmatter regex on every agent step (the `experimental.chat.messages.transform` hook fires on every step in OpenCode's agent loop). Now read once, cached for the session lifetime, with a null sentinel for the missing-file case. 15 regression tests cover cache behavior, fs call counts, the injection guard, the missing-file sentinel, and cache reset. (Fixes #1202)
+- **Integration tests modernized**.
+- **Install caveats clarified** in the README.
+
+### Code Review Consolidation
+
+`requesting-code-review` is now self-contained: the persona, checklist, and dispatch template live in `skills/requesting-code-review/code-reviewer.md` and the skill dispatches `Task (general-purpose)` directly. (PR #1299)
+
+- **Single source of truth** — the persona/checklist that previously lived in both `agents/code-reviewer.md` and the skill's placeholder template (and drifted independently) is now one file.
+- **`subagent-driven-development` follows suit** — its `code-quality-reviewer-prompt.md` now dispatches `Task (general-purpose)` instead of the named agent.
+- **Behavioral test added** — `tests/claude-code/test-requesting-code-review.sh` plants real bugs (SQL injection, plaintext password handling, credential logging) into a tiny project and asserts the dispatched reviewer flags every planted issue at Critical/Important severity and refuses to approve the diff.
+
+> Note: `tests/claude-code/test-requesting-code-review.sh` and `tests/claude-code/test-document-review-system.sh` (mentioned later in this document) were lifted into drill scenarios on 2026-05-06 and removed from `tests/`. See `evals/scenarios/code-review-catches-planted-bugs.yaml` and `evals/scenarios/spec-reviewer-catches-planted-flaws.yaml`. The references above and below are preserved as dated artifacts of the work this section describes.
+- **Codex and Copilot workaround docs trimmed** — the "Named agent dispatch" sections in `references/codex-tools.md` and `references/copilot-tools.md` documented how to flatten a named agent into a generic dispatch. With no named agents shipping, the workaround is unnecessary; both sections were dropped.
+
+### Subagent-Driven Development
+
+- **No more pause every 3 tasks** — the "review after each batch (3 tasks)" cadence in `requesting-code-review` (originally for `executing-plans`) was leaking into `subagent-driven-development`. Replaced with "each task or at natural checkpoints" plus an explicit continuous-execution directive.
+- **SDD integration test now runs its assertions** — three independent bugs caused the test to silently bail before printing any verification results: an unresolved `..` segment in the working-dir path, a `set -euo pipefail` interaction with `find | sort | head -1` (SIGPIPE on the producer killed the script), and a missing `--plugin-dir` on the `claude -p` invocation that caused the test to load the installed plugin instead of the working tree. All three fixed; six verification tests now actually run against a real end-to-end SDD run.
+
+### Cursor
+
+- **Windows SessionStart hook** routed through `run-hook.cmd` instead of invoking the extensionless `session-start` script directly. Fixes Windows opening the file in an editor instead of running it. Also removed an accidental UTF-8 BOM from `hooks-cursor.json`.
+
+### Gemini CLI
+
+- **Subagent dispatch mapping** — Gemini's `Task` dispatch now maps to `@agent-name` / `@generalist`, with parallel subagent dispatch documented for independent tasks.
+
+### Skills
+
+- **Terminology cleanups** across skill content.
+
+### Documentation & Install
+
+- **Factory Droid installation instructions** added to README.
+- **Quickstart install links** in README. (PR #1293 by @arittr)
+- **Codex plugin install guidance** updated. (PR #1288 by @arittr)
+- **Codex `wait` mapping corrected** to `wait_agent` in the tools reference.
+- **Install order reorganized**; Codex install instructions cleaned up.
+- **Removed vestigial `CHANGELOG.md`** in favor of `RELEASE-NOTES.md` as the single source. (PR #1163 by @shaanmajid)
+- **Discord invite link** fixed; release announcements link and a detailed Discord description added to the Community section.
+
+### Community
+
+- @shaanmajid — vestigial `CHANGELOG.md` removal (PR #1163)
+- @arittr — README quickstart install links (#1293), Codex plugin install guidance (#1288), `sync-to-codex-plugin` `interface.defaultPrompt` seed (#1180)
+
+## v5.0.7 (2026-03-31)
+
+### GitHub Copilot CLI Support
+
+- **SessionStart context injection** — Copilot CLI v1.0.11 added support for `additionalContext` in sessionStart hook output. The session-start hook now detects the `COPILOT_CLI` environment variable and emits the SDK-standard `{ "additionalContext": "..." }` format, giving Copilot CLI users the full superpowers bootstrap at session start. (Original fix by @culinablaz in PR #910)
+- **Tool mapping** — added `references/copilot-tools.md` with the full Claude Code to Copilot CLI tool equivalence table
+- **Skill and README updates** — added Copilot CLI to the `using-superpowers` skill's platform instructions and README installation section
+
+### OpenCode Fixes
+
+- **Skills path consistency** — the bootstrap text no longer advertises a misleading `configDir/skills/superpowers/` path that didn't match the runtime path. The agent should use the native `skill` tool, not navigate to files by path. Tests now use consistent paths derived from a single source of truth. (#847, #916)
+- **Bootstrap as user message** — moved bootstrap injection from `experimental.chat.system.transform` to `experimental.chat.messages.transform`, prepending to the first user message instead of adding a system message. Avoids token bloat from system messages repeated every turn (#750) and fixes compatibility with Qwen and other models that break on multiple system messages (#894).
+
+## v5.0.6 (2026-03-24)
+
+### Inline Self-Review Replaces Subagent Review Loops
+
+The subagent review loop (dispatching a fresh agent to review plans/specs) doubled execution time (~25 min overhead) without measurably improving plan quality. Regression testing across 5 versions with 5 trials each showed identical quality scores regardless of whether the review loop ran.
+
+- **brainstorming** — replaced Spec Review Loop (subagent dispatch + 3-iteration cap) with inline Spec Self-Review checklist: placeholder scan, internal consistency, scope check, ambiguity check
+- **writing-plans** — replaced Plan Review Loop (subagent dispatch + 3-iteration cap) with inline Self-Review checklist: spec coverage, placeholder scan, type consistency
+- **writing-plans** — added explicit "No Placeholders" section defining plan failures (TBD, vague descriptions, undefined references, "similar to Task N")
+- Self-review catches 3-5 real bugs per run in ~30s instead of ~25 min, with comparable defect rates to the subagent approach
+
+### Brainstorm Server
+
+- **Session directory restructured** — the brainstorm server session directory now contains two peer subdirectories: `content/` (HTML files served to the browser) and `state/` (events, server-info, pid, log). Previously, server state and user interaction data were stored alongside served content, making them accessible over HTTP. The `screen_dir` and `state_dir` paths are both included in the server-started JSON. (Reported by 吉田仁)
+
+### Bug Fixes
+
+- **Owner-PID lifecycle fixes** — the brainstorm server's owner-PID monitoring had two bugs causing false shutdowns within 60 seconds: (1) EPERM from cross-user PIDs (Tailscale SSH, etc.) was treated as "process dead", and (2) on WSL the grandparent PID resolves to a short-lived subprocess that exits before the first lifecycle check. Fixed by treating EPERM as "alive" and validating the owner PID at startup — if it's already dead, monitoring is disabled and the server relies on the 30-minute idle timeout. This also removes the Windows/MSYS2-specific carve-out from `start-server.sh` since the server now handles it generically. (#879)
+- **writing-skills** — corrected false claim that SKILL.md frontmatter supports "only two fields"; now says "two required fields" and links to the agentskills.io specification for all supported fields (PR #882 by @arittr)
+
+### Codex App Compatibility
+
+- **codex-tools** — added named agent dispatch mapping documenting how to translate Claude Code's named agent types to Codex's `spawn_agent` with worker roles (PR #647 by @arittr)
+- **codex-tools** — added environment detection and Codex App finishing sections for worktree-aware skills (by @arittr)
+- **Design spec** — added Codex App compatibility design spec (PRI-823) covering read-only environment detection, worktree-safe skill behavior, and sandbox fallback patterns (by @arittr)
+
+## v5.0.5 (2026-03-17)
+
+### Bug Fixes
+
+- **Brainstorm server ESM fix** — renamed `server.js` → `server.cjs` so the brainstorming server starts correctly on Node.js 22+ where the root `package.json` `"type": "module"` caused `require()` to fail. (PR #784 by @sarbojitrana, fixes #774, #780, #783)
+- **Brainstorm owner-PID on Windows** — skip PID lifecycle monitoring on Windows/MSYS2 where the PID namespace is invisible to Node.js, preventing the server from self-terminating after 60 seconds. (#770, docs from PR #768 by @lucasyhzlu-debug)
+- **stop-server.sh reliability** — verify the server process actually died before reporting success. SIGTERM + 2s wait + SIGKILL fallback. (#723)
+
+### Changed
+
+- **Execution handoff** — restore user choice between subagent-driven and inline execution after plan writing. Subagent-driven is recommended but no longer mandatory.
+
+## v5.0.4 (2026-03-16)
+
+### Review Loop Refinements
+
+Dramatically reduces token usage and speeds up spec and plan reviews by eliminating unnecessary review passes and tightening reviewer focus.
+
+- **Single whole-plan review** — plan reviewer now reviews the complete plan in one pass instead of chunk-by-chunk. Removed all chunk-related concepts (`## Chunk N:` headings, 1000-line chunk limits, per-chunk dispatch).
+- **Raised the bar for blocking issues** — both spec and plan reviewer prompts now include a "Calibration" section: only flag issues that would cause real problems during implementation. Minor wording, stylistic preferences, and formatting quibbles should not block approval.
+- **Reduced max review iterations** — from 5 to 3 for both spec and plan review loops. If the reviewer is calibrated correctly, 3 rounds is plenty.
+- **Streamlined reviewer checklists** — spec reviewer trimmed from 7 categories to 5; plan reviewer from 7 to 4. Removed formatting-focused checks (task syntax, chunk size) in favor of substance (buildability, spec alignment).
+
+### OpenCode
+
+- **One-line plugin install** — OpenCode plugin now auto-registers the skills directory via a `config` hook. No symlinks or `skills.paths` config needed. Install is just adding one line to `opencode.json`. (PR #753)
+- **Added `package.json`** so OpenCode can install superpowers as an npm package from git.
+
+### Bug Fixes
+
+- **Verify server actually stopped** — `stop-server.sh` now confirms the process is dead before reporting success. SIGTERM + 2s wait + SIGKILL fallback. Reports failure if the process survives. (PR #751)
+- **Generic agent language** — brainstorm companion waiting page now says "the agent" instead of "Claude".
+
+## v5.0.3 (2026-03-15)
+
+### Cursor Support
+
+- **Cursor hooks** — added `hooks/hooks-cursor.json` with Cursor's camelCase format (`sessionStart`, `version: 1`) and updated `.cursor-plugin/plugin.json` to reference it. Fixed platform detection in `session-start` to check `CURSOR_PLUGIN_ROOT` first (Cursor may also set `CLAUDE_PLUGIN_ROOT`). (Based on PR #709)
+
+### Bug Fixes
+
+- **Stop firing SessionStart hook on `--resume`** — the startup hook was re-injecting context on resumed sessions, which already have the context in their conversation history. The hook now fires only on `startup`, `clear`, and `compact`.
+- **Bash 5.3+ hook hang** — replaced heredoc (`cat <<EOF`) with `printf` in `hooks/session-start`. Fixes indefinite hang on macOS with Homebrew bash 5.3+ caused by a bash regression with large variable expansion in heredocs. (#572, #571)
+- **POSIX-safe hook script** — replaced `${BASH_SOURCE[0]:-$0}` with `$0` in `hooks/session-start`. Fixes "Bad substitution" error on Ubuntu/Debian where `/bin/sh` is dash. (#553)
+- **Portable shebangs** — replaced `#!/bin/bash` with `#!/usr/bin/env bash` in all shell scripts. Fixes execution on NixOS, FreeBSD, and macOS with Homebrew bash where `/bin/bash` is outdated or missing. (#700)
+- **Brainstorm server on Windows** — auto-detect Windows/Git Bash (`OSTYPE=msys*`, `MSYSTEM`) and switch to foreground mode, fixing silent server failure caused by `nohup`/`disown` process reaping. (#737)
+- **Codex docs fix** — replaced deprecated `collab` flag with `multi_agent` in Codex documentation. (PR #749)
+
+## v5.0.2 (2026-03-11)
+
+### Zero-Dependency Brainstorm Server
+
+**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
+
+**Brainstorm-server moved into skill directory**
+
+- Moved `lib/brainstorm-server/` → `skills/brainstorming/scripts/` per the [agentskills.io](https://agentskills.io) specification
+- All `${CLAUDE_PLUGIN_ROOT}/lib/brainstorm-server/` references replaced with relative `scripts/` paths
+- Skills are now fully portable across platforms — no platform-specific env vars needed to locate scripts
+- `lib/` directory removed (was the last remaining content)
+
+### New Features
+
+**Gemini CLI extension**
+
+- Native Gemini CLI extension support via `gemini-extension.json` and `GEMINI.md` at repo root
+- `GEMINI.md` @imports `using-superpowers` skill and tool mapping table at session start
+- Gemini CLI tool mapping reference (`skills/using-superpowers/references/gemini-tools.md`) — translates Claude Code tool names (Read, Write, Edit, Bash, etc.) to Gemini CLI equivalents (read_file, write_file, replace, etc.)
+- Documents Gemini CLI limitations: no subagent support, skills fall back to `executing-plans`
+- Extension root at repo root for cross-platform compatibility (avoids Windows symlink issues)
+- Install instructions added to README
+
+### Improvements
+
+**Multi-platform brainstorm server launch**
+
+- Per-platform launch instructions in visual-companion.md: Claude Code (default mode), Codex (auto-foreground via `CODEX_CI`), Gemini CLI (`--foreground` with `is_background`), and fallback for other environments
+- Server now writes startup JSON to `$SCREEN_DIR/.server-info` so agents can find the URL and port even when stdout is hidden by background execution
+
+**Brainstorm server dependencies bundled**
+
+- `node_modules` vendored into the repo so the brainstorm server works immediately on fresh plugin installs without requiring `npm` at runtime
+- Removed `fsevents` from bundled deps (macOS-only native binary; chokidar falls back gracefully without it)
+- Fallback auto-install via `npm install` if `node_modules` is missing
+
+**OpenCode tool mapping fix**
+
+- `TodoWrite` → `todowrite` (was incorrectly mapped to `update_plan`); verified against OpenCode source
+
+### Bug Fixes
+
+**Windows/Linux: single quotes break SessionStart hook** (#577, #529, #644, PR #585)
+
+- Single quotes around `${CLAUDE_PLUGIN_ROOT}` in hooks.json fail on Windows (cmd.exe doesn't recognize single quotes as path delimiters) and on Linux (single quotes prevent variable expansion)
+- Fix: replaced single quotes with escaped double quotes — works across macOS bash, Windows cmd.exe, Windows Git Bash, and Linux, with and without spaces in paths
+- Verified on Windows 11 (NT 10.0.26200.0) with Claude Code 2.1.72 and Git for Windows
+
+**Brainstorming spec review loop skipped** (#677)
+
+- The spec review loop (dispatch spec-document-reviewer subagent, iterate until approved) existed in the prose "After the Design" section but was missing from the checklist and process flow diagram
+- Since agents follow the diagram and checklist more reliably than prose, the spec review step was being skipped entirely
+- Added step 7 (spec review loop) to the checklist and corresponding nodes to the dot graph
+- Tested with `claude --plugin-dir` and `claude-session-driver`: worker now correctly dispatches the reviewer
+
+**Cursor install command** (PR #676)
+
+- Fixed Cursor install command in README: `/plugin-add` → `/add-plugin` (confirmed via Cursor 2.5 release announcement)
+
+**User review gate in brainstorming** (#565)
+
+- Added explicit user review step between spec completion and writing-plans handoff
+- User must approve the spec before implementation planning begins
+- Checklist, process flow, and prose updated with the new gate
+
+**Session-start hook emits context only once per platform**
+
+- Hook now detects whether it's running in Claude Code or another platform
+- Emits `hookSpecificOutput` for Claude Code, `additional_context` for others — prevents double context injection
+
+**Linting fix in token analysis script**
+
+- `except:` → `except Exception:` in `tests/claude-code/analyze-token-usage.py`
+
+### Maintenance
+
+**Removed dead code**
+
+- Deleted `lib/skills-core.js` and its test (`tests/opencode/test-skills-core.js`) — unused since February 2026
+- Removed skills-core existence check from `tests/opencode/test-plugin-loading.sh`
+
+### Community
+
+- @karuturi — Claude Code official marketplace install instructions (PR #610)
+- @mvanhorn — session-start hook dual-emit fix, OpenCode tool mapping fix
+- @daniel-graham — linting fix for bare except
+- PR #585 author — Windows/Linux hooks quoting fix
+
+---
+
+## v5.0.0 (2026-03-09)
+
+### Breaking Changes
+
+**Specs and plans directory restructured**
+
+- Specs (brainstorming output) now save to `docs/superpowers/specs/YYYY-MM-DD-<topic>-design.md`
+- Plans (writing-plans output) now save to `docs/superpowers/plans/YYYY-MM-DD-<feature-name>.md`
+- User preferences for spec/plan locations override these defaults
+- All internal skill references, test files, and example paths updated to match
+- Migration: move existing files from `docs/plans/` to new locations if desired
+
+**Subagent-driven development mandatory on capable harnesses**
+
+Writing-plans no longer offers a choice between subagent-driven and executing-plans. On harnesses with subagent support (Claude Code, Codex), subagent-driven-development is required. Executing-plans is reserved for harnesses without subagent capability, and now tells the user that Superpowers works better on a subagent-capable platform.
+
+**Executing-plans no longer batches**
+
+Removed the "execute 3 tasks then stop for review" pattern. Plans now execute continuously, stopping only for blockers.
+
+**Slash commands deprecated**
+
+`/brainstorm`, `/write-plan`, and `/execute-plan` now show deprecation notices pointing users to the corresponding skills. Commands will be removed in the next major release.
+
+### New Features
+
+**Visual brainstorming companion**
+
+Optional browser-based companion for brainstorming sessions. When a topic would benefit from visuals, the brainstorming skill offers to show mockups, diagrams, comparisons, and other content in a browser window alongside terminal conversation.
+
+- `lib/brainstorm-server/` — WebSocket server with browser helper library, session management scripts, and dark/light themed frame template ("Superpowers Brainstorming" with GitHub link)
+- `skills/brainstorming/visual-companion.md` — Progressive disclosure guide for server workflow, screen authoring, and feedback collection
+- Brainstorming skill adds a visual companion decision point to its process flow: after exploring project context, the skill evaluates whether upcoming questions involve visual content and offers the companion in its own message
+- Per-question decision: even after accepting, each question is evaluated for whether browser or terminal is more appropriate
+- Integration tests in `tests/brainstorm-server/`
+
+**Document review system**
+
+Automated review loops for spec and plan documents using subagent dispatch:
+
+- `skills/brainstorming/spec-document-reviewer-prompt.md` — Reviewer checks completeness, consistency, architecture, and YAGNI
+- `skills/writing-plans/plan-document-reviewer-prompt.md` — Reviewer checks spec alignment, task decomposition, file structure, and file size
+- Brainstorming dispatches spec reviewer after writing the design doc
+- Writing-plans includes chunk-based plan review loop after each section
+- Review loops repeat until approved or escalate after 5 iterations
+- End-to-end tests in `tests/claude-code/test-document-review-system.sh`
+- Design spec and implementation plan in `docs/superpowers/`
+
+**Architecture guidance across the skill pipeline**
+
+Design-for-isolation and file-size-awareness guidance added to brainstorming, writing-plans, and subagent-driven-development:
+
+- **Brainstorming** — New sections: "Design for isolation and clarity" (clear boundaries, well-defined interfaces, independently testable units) and "Working in existing codebases" (follow existing patterns, targeted improvements only)
+- **Writing-plans** — New "File Structure" section: map out files and responsibilities before defining tasks. New "Scope Check" backstop: catch multi-subsystem specs that should have been decomposed during brainstorming
+- **SDD implementer** — New "Code Organization" section (follow plan's file structure, report concerns about growing files) and "When You're in Over Your Head" escalation guidance
+- **SDD code quality reviewer** — Now checks architecture, unit decomposition, plan conformance, and file growth
+- **Spec/plan reviewers** — Architecture and file size added to review criteria
+- **Scope assessment** — Brainstorming now assesses whether a project is too large for a single spec. Multi-subsystem requests are flagged early and decomposed into sub-projects, each with its own spec → plan → implementation cycle
+
+**Subagent-driven development improvements**
+
+- **Model selection** — Guidance for choosing model capability by task type: cheap models for mechanical implementation, standard for integration, capable for architecture and review
+- **Implementer status protocol** — Subagents now report DONE, DONE_WITH_CONCERNS, BLOCKED, or NEEDS_CONTEXT. Controller handles each status appropriately: re-dispatching with more context, upgrading model capability, breaking tasks apart, or escalating to human
+
+### Improvements
+
+**Instruction priority hierarchy**
+
+Added explicit priority ordering to using-superpowers:
+
+1. User's explicit instructions (CLAUDE.md, AGENTS.md, direct requests) — highest priority
+2. Superpowers skills — override default system behavior
+3. Default system prompt — lowest priority
+
+If CLAUDE.md or AGENTS.md says "don't use TDD" and a skill says "always use TDD," the user's instructions win.
+
+**SUBAGENT-STOP gate**
+
+Added `<SUBAGENT-STOP>` block to using-superpowers. Subagents dispatched for specific tasks now skip the skill instead of activating the 1% rule and invoking full skill workflows.
+
+**Multi-platform improvements**
+
+- Codex tool mapping moved to progressive disclosure reference file (`references/codex-tools.md`)
+- Platform Adaptation pointer added so non-Claude-Code platforms can find tool equivalents
+- Plan headers now address "agentic workers" instead of "Claude" specifically
+- Collab feature requirement documented in `docs/README.codex.md`
+
+**Writing-plans template updates**
+
+- Plan steps now use checkbox syntax (`- [ ] **Step N:**`) for progress tracking
+- Plan header references both subagent-driven-development and executing-plans with platform-aware routing
+
+---
+
+## v4.3.1 (2026-02-21)
+
+### Added
+
+**Cursor support**
+
+Superpowers now works with Cursor's plugin system. Includes a `.cursor-plugin/plugin.json` manifest and Cursor-specific installation instructions in the README. The SessionStart hook output now includes an `additional_context` field alongside the existing `hookSpecificOutput.additionalContext` for Cursor hook compatibility.
+
+### Fixed
+
+**Windows: Restored polyglot wrapper for reliable hook execution (#518, #504, #491, #487, #466, #440)**
+
+Claude Code's `.sh` auto-detection on Windows was prepending `bash` to the hook command, breaking execution. The fix:
+
+- Renamed `session-start.sh` to `session-start` (extensionless) so auto-detection doesn't interfere
+- Restored `run-hook.cmd` polyglot wrapper with multi-location bash discovery (standard Git for Windows paths, then PATH fallback)
+- Exits silently if no bash is found rather than erroring
+- On Unix, the wrapper runs the script directly via `exec bash`
+- Uses POSIX-safe `dirname "$0"` path resolution (works on dash/sh, not just bash)
+
+This fixes SessionStart failures on Windows with spaces in paths, missing WSL, `set -euo pipefail` fragility on MSYS, and backslash mangling.
+
+## v4.3.0 (2026-02-12)
+
+This fix should dramatically improve superpowers skills compliance and should reduce the chances of Claude entering its native plan mode unintentionally.
+
+### Changed
+
+**Brainstorming skill now enforces its workflow instead of describing it**
+
+Models were skipping the design phase and jumping straight to implementation skills like frontend-design, or collapsing the entire brainstorming process into a single text block. The skill now uses hard gates, a mandatory checklist, and a graphviz process flow to enforce compliance:
+
+- `<HARD-GATE>`: no implementation skills, code, or scaffolding until design is presented and user approves
+- Explicit checklist (6 items) that must be created as tasks and completed in order
+- Graphviz process flow with `writing-plans` as the only valid terminal state
+- Anti-pattern callout for "this is too simple to need a design" — the exact rationalization models use to skip the process
+- Design section sizing based on section complexity, not project complexity
+
+**Using-superpowers workflow graph intercepts EnterPlanMode**
+
+Added an `EnterPlanMode` intercept to the skill flow graph. When the model is about to enter Claude's native plan mode, it checks whether brainstorming has happened and routes through the brainstorming skill instead. Plan mode is never entered.
+
+### Fixed
+
+**SessionStart hook now runs synchronously**
+
+Changed `async: true` to `async: false` in hooks.json. When async, the hook could fail to complete before the model's first turn, meaning using-superpowers instructions weren't in context for the first message.
+
+## v4.2.0 (2026-02-05)
+
+### Breaking Changes
+
+**Codex: Replaced bootstrap CLI with native skill discovery**
+
+The `superpowers-codex` bootstrap CLI, Windows `.cmd` wrapper, and related bootstrap content file have been removed. Codex now uses native skill discovery via `~/.agents/skills/superpowers/` symlink, so the old `use_skill`/`find_skills` CLI tools are no longer needed.
+
+Installation is now just clone + symlink (documented in INSTALL.md). No Node.js dependency required. The old `~/.codex/skills/` path is deprecated.
+
+### Fixes
+
+**Windows: Fixed Claude Code 2.1.x hook execution (#331)**
+
+Claude Code 2.1.x changed how hooks execute on Windows: it now auto-detects `.sh` files in commands and prepends `bash`. This broke the polyglot wrapper pattern because `bash "run-hook.cmd" session-start.sh` tries to execute the `.cmd` file as a bash script.
+
+Fix: hooks.json now calls session-start.sh directly. Claude Code 2.1.x handles the bash invocation automatically. Also added .gitattributes to enforce LF line endings for shell scripts (fixes CRLF issues on Windows checkout).
+
+**Windows: SessionStart hook runs async to prevent terminal freeze (#404, #413, #414, #419)**
+
+The synchronous SessionStart hook blocked the TUI from entering raw mode on Windows, freezing all keyboard input. Running the hook async prevents the freeze while still injecting superpowers context.
+
+**Windows: Fixed O(n^2) `escape_for_json` performance**
+
+The character-by-character loop using `${input:$i:1}` was O(n^2) in bash due to substring copy overhead. On Windows Git Bash this took 60+ seconds. Replaced with bash parameter substitution (`${s//old/new}`) which runs each pattern as a single C-level pass — 7x faster on macOS, dramatically faster on Windows.
+
+**Codex: Fixed Windows/PowerShell invocation (#285, #243)**
+
+- Windows doesn't respect shebangs, so directly invoking the extensionless `superpowers-codex` script triggered an "Open with" dialog. All invocations now prefixed with `node`.
+- Fixed `~/` path expansion on Windows — PowerShell doesn't expand `~` when passed as an argument to `node`. Changed to `$HOME` which expands correctly in both bash and PowerShell.
+
+**Codex: Fixed path resolution in installer**
+
+Used `fileURLToPath()` instead of manual URL pathname parsing to correctly handle paths with spaces and special characters on all platforms.
+
+**Codex: Fixed stale skills path in writing-skills**
+
+Updated `~/.codex/skills/` reference (deprecated) to `~/.agents/skills/` for native discovery.
+
+### Improvements
+
+**Worktree isolation now required before implementation**
+
+Added `using-git-worktrees` as a required skill for both `subagent-driven-development` and `executing-plans`. Implementation workflows now explicitly require setting up an isolated worktree before starting work, preventing accidental work directly on main.
+
+**Main branch protection softened to require explicit consent**
+
+Instead of prohibiting main branch work entirely, the skills now allow it with explicit user consent. More flexible while still ensuring users are aware of the implications.
+
+**Simplified installation verification**
+
+Removed `/help` command check and specific slash command list from verification steps. Skills are primarily invoked by describing what you want to do, not by running specific commands.
+
+**Codex: Clarified subagent tool mapping in bootstrap**
+
+Improved documentation of how Codex tools map to Claude Code equivalents for subagent workflows.
+
+### Tests
+
+- Added worktree requirement test for subagent-driven-development
+- Added main branch red flag warning test
+- Fixed case sensitivity in skill recognition test assertions
+
+---
+
+## v4.1.1 (2026-01-23)
+
+### Fixes
+
+**OpenCode: Standardized on `plugins/` directory per official docs (#343)**
+
+OpenCode's official documentation uses `~/.config/opencode/plugins/` (plural). Our docs previously used `plugin/` (singular). While OpenCode accepts both forms, we've standardized on the official convention to avoid confusion.
+
+Changes:
+- Renamed `.opencode/plugin/` to `.opencode/plugins/` in repo structure
+- Updated all installation docs (INSTALL.md, README.opencode.md) across all platforms
+- Updated test scripts to match
+
+**OpenCode: Fixed symlink instructions (#339, #342)**
+
+- Added explicit `rm` before `ln -s` (fixes "file already exists" errors on reinstall)
+- Added missing skills symlink step that was absent from INSTALL.md
+- Updated from deprecated `use_skill`/`find_skills` to native `skill` tool references
+
+---
+
+## v4.1.0 (2026-01-23)
+
+### Breaking Changes
+
+**OpenCode: Switched to native skills system**
+
+Superpowers for OpenCode now uses OpenCode's native `skill` tool instead of custom `use_skill`/`find_skills` tools. This is a cleaner integration that works with OpenCode's built-in skill discovery.
+
+**Migration required:** Skills must be symlinked to `~/.config/opencode/skills/superpowers/` (see updated installation docs).
+
+### Fixes
+
+**OpenCode: Fixed agent reset on session start (#226)**
+
+The previous bootstrap injection method using `session.prompt({ noReply: true })` caused OpenCode to reset the selected agent to "build" on first message. Now uses `experimental.chat.system.transform` hook which modifies the system prompt directly without side effects.
+
+**OpenCode: Fixed Windows installation (#232)**
+
+- Removed dependency on `skills-core.js` (eliminates broken relative imports when file is copied instead of symlinked)
+- Added comprehensive Windows installation docs for cmd.exe, PowerShell, and Git Bash
+- Documented proper symlink vs junction usage for each platform
+
+**Claude Code: Fixed Windows hook execution for Claude Code 2.1.x**
+
+Claude Code 2.1.x changed how hooks execute on Windows: it now auto-detects `.sh` files in commands and prepends `bash `. This broke the polyglot wrapper pattern because `bash "run-hook.cmd" session-start.sh` tries to execute the .cmd file as a bash script.
+
+Fix: hooks.json now calls session-start.sh directly. Claude Code 2.1.x handles the bash invocation automatically. Also added .gitattributes to enforce LF line endings for shell scripts (fixes CRLF issues on Windows checkout).
+
+---
+
+## v4.0.3 (2025-12-26)
+
+### Improvements
+
+**Strengthened using-superpowers skill for explicit skill requests**
+
+Addressed a failure mode where Claude would skip invoking a skill even when the user explicitly requested it by name (e.g., "subagent-driven-development, please"). Claude would think "I know what that means" and start working directly instead of loading the skill.
+
+Changes:
+- Updated "The Rule" to say "Invoke relevant or requested skills" instead of "Check for skills" - emphasizing active invocation over passive checking
+- Added "BEFORE any response or action" - the original wording only mentioned "response" but Claude would sometimes take action without responding first
+- Added reassurance that invoking a wrong skill is okay - reduces hesitation
+- Added new red flag: "I know what that means" → Knowing the concept ≠ using the skill
+
+**Added explicit skill request tests**
+
+New test suite in `tests/explicit-skill-requests/` that verifies Claude correctly invokes skills when users request them by name. Includes single-turn and multi-turn test scenarios.
+
+## v4.0.2 (2025-12-23)
+
+### Fixes
+
+**Slash commands now user-only**
+
+Added `disable-model-invocation: true` to all three slash commands (`/brainstorm`, `/execute-plan`, `/write-plan`). Claude can no longer invoke these commands via the Skill tool—they're restricted to manual user invocation only.
+
+The underlying skills (`superpowers:brainstorming`, `superpowers:executing-plans`, `superpowers:writing-plans`) remain available for Claude to invoke autonomously. This change prevents confusion when Claude would invoke a command that just redirects to a skill anyway.
+
+## v4.0.1 (2025-12-23)
 
 ### Fixes
 
@@ -12,6 +701,14 @@ Fixed a confusing pattern where Claude would invoke a skill via the Skill tool,
 - Changed "read the skill" → "invoke the skill" in instructions
 - Updated slash commands to use fully qualified skill names (e.g., `superpowers:brainstorming`)
 
+**Added GitHub thread reply guidance to receiving-code-review** (h/t @ralphbean)
+
+Added a note about replying to inline review comments in the original thread rather than as top-level PR comments.
+
+**Added automation-over-documentation guidance to writing-skills** (h/t @EthanJStark)
+
+Added guidance that mechanical constraints should be automated, not documented—save skills for judgment calls.
+
 ## v4.0.0 (2025-12-17)
 
 ### New Features

agents/code-reviewer.md

@@ -1,47 +0,0 @@
----
-name: code-reviewer
-description: |
-  Use this agent when a major project step has been completed and needs to be reviewed against the original plan and coding standards. Examples: <example>Context: The user is creating a code-review agent that should be called after a logical chunk of code is written. user: "I've finished implementing the user authentication system as outlined in step 3 of our plan" assistant: "Great work! Now let me use the code-reviewer agent to review the implementation against our plan and coding standards" <commentary>Since a major project step has been completed, use the code-reviewer agent to validate the work against the plan and identify any issues.</commentary></example> <example>Context: User has completed a significant feature implementation. user: "The API endpoints for the task management system are now complete - that covers step 2 from our architecture document" assistant: "Excellent! Let me have the code-reviewer agent examine this implementation to ensure it aligns with our plan and follows best practices" <commentary>A numbered step from the planning document has been completed, so the code-reviewer agent should review the work.</commentary></example>
----
-
-You are a Senior Code Reviewer with expertise in software architecture, design patterns, and best practices. Your role is to review completed project steps against original plans and ensure code quality standards are met.
-
-When reviewing completed work, you will:
-
-1. **Plan Alignment Analysis**:
-   - Compare the implementation against the original planning document or step description
-   - Identify any deviations from the planned approach, architecture, or requirements
-   - Assess whether deviations are justified improvements or problematic departures
-   - Verify that all planned functionality has been implemented
-
-2. **Code Quality Assessment**:
-   - Review code for adherence to established patterns and conventions
-   - Check for proper error handling, type safety, and defensive programming
-   - Evaluate code organization, naming conventions, and maintainability
-   - Assess test coverage and quality of test implementations
-   - Look for potential security vulnerabilities or performance issues
-
-3. **Architecture and Design Review**:
-   - Ensure the implementation follows SOLID principles and established architectural patterns
-   - Check for proper separation of concerns and loose coupling
-   - Verify that the code integrates well with existing systems
-   - Assess scalability and extensibility considerations
-
-4. **Documentation and Standards**:
-   - Verify that code includes appropriate comments and documentation
-   - Check that file headers, function documentation, and inline comments are present and accurate
-   - Ensure adherence to project-specific coding standards and conventions
-
-5. **Issue Identification and Recommendations**:
-   - Clearly categorize issues as: Critical (must fix), Important (should fix), or Suggestions (nice to have)
-   - For each issue, provide specific examples and actionable recommendations
-   - When you identify plan deviations, explain whether they're problematic or beneficial
-   - Suggest specific improvements with code examples when helpful
-
-6. **Communication Protocol**:
-   - If you find significant deviations from the plan, ask the coding agent to review and confirm the changes
-   - If you identify issues with the original plan itself, recommend plan updates
-   - For implementation problems, provide clear guidance on fixes needed
-   - Always acknowledge what was done well before highlighting issues
-
-Your output should be structured, actionable, and focused on helping maintain high code quality while ensuring project goals are met. Be thorough but concise, and always provide constructive feedback that helps improve both the current implementation and future development practices.

assets/superpowers-small.svg

@@ -0,0 +1 @@
+<?xml version="1.0" encoding="UTF-8"?><svg id="Calque_1" xmlns="http://www.w3.org/2000/svg" viewBox="0 0 512 512"><path d="M394.28,207.8c.81,2.41,1.39,4.78,1.8,7.07,1.61,9.03-.93,17.78-5.99,21.74-22.6,17.7-49.85,29.35-75.34,38.6-.59.22-1.09.28-1.4.34-2.22.47-4.95,1.04-7.25,0-1.46-.66-2.25-1.74-2.66-2.3-1.56-2.1-1.59-4.31-1.56-5.13.1-2.67-.01-4.69,0-4.82.45-3.52.91-10.66,1.41-21.28.6-3.87,2.16-9.63,6.94-13.96,4.01-3.62,8.33-4.6,14.59-5.87,10.76-2.19,37.21-8.22,47.42-16.56,1.63-1.33,2.97-2.65,4.19-3.96,3.72-3.99,6.39-7.92,7.93-10.36,3.22,3.22,7.25,8.48,9.92,16.47Z"/><path d="M428.67,185.28c-2.33,11.99-8.91,22.32-15.88,30.38.27-5.5-.05-12.11-1.86-19.08-5.04-19.36-19.74-34.7-37.78-37.78-32.21-9.74-70.59,3.79-99.08,18.29-3.87,1.95-9.52-2.77-11.84-8.16-3.32-7.71-1.63-6.28,2.61-8.49,38.31-20.03,82.01-39.61,123.91-29.7,8.26,1.95,15.96,5.26,23.48,10.54,11.32,7.96,20.21,24.74,16.44,44Z"/><path d="M117.72,304.2c-.81-2.41-1.39-4.78-1.8-7.07-1.61-9.03.93-17.78,5.99-21.74,22.6-17.7,49.85-29.35,75.34-38.6.59-.22,1.09-.28,1.4-.34,2.22-.47,4.95-1.04,7.25,0,1.46.66,2.25,1.74,2.66,2.3,1.56,2.1,1.59,4.31,1.56,5.13-.1,2.67.01,4.69,0,4.82-.45,3.52-.91,10.66-1.41,21.28-.6,3.87-2.16,9.63-6.94,13.96-4.01,3.62-8.33,4.6-14.59,5.87-10.76,2.19-37.21,8.22-47.42,16.56-1.63,1.33-2.97,2.65-4.19,3.96-3.72,3.99-6.39,7.92-7.93,10.36-3.22-3.22-7.25-8.48-9.92-16.47Z"/><path d="M83.33,326.72c2.33-11.99,8.91-22.32,15.88-30.38-.27,5.5.05,12.11,1.86,19.08,5.04,19.36,19.74,34.7,37.78,37.78,32.21,9.74,70.59-3.79,99.08-18.29,3.87-1.95,9.52,2.77,11.84,8.16,3.32,7.71,1.63,6.28-2.61,8.49-38.31,20.03-82.01,39.61-123.91,29.7-8.26-1.95-15.96-5.26-23.48-10.54-11.32-7.96-20.21-24.74-16.44-44Z"/><ellipse cx="255.16" cy="258.86" rx="28.95" ry="28.76"/></svg>

commands/brainstorm.md

@@ -1,5 +0,0 @@
----
-description: "You MUST use this before any creative work - creating features, building components, adding functionality, or modifying behavior. Explores requirements and design before implementation."
----
-
-Invoke the superpowers:brainstorming skill and follow it exactly as presented to you

commands/execute-plan.md

@@ -1,5 +0,0 @@
----
-description: Execute plan in batches with review checkpoints
----
-
-Invoke the superpowers:executing-plans skill and follow it exactly as presented to you

commands/write-plan.md

@@ -1,5 +0,0 @@
----
-description: Create detailed implementation plan with bite-sized tasks
----
-
-Invoke the superpowers:writing-plans skill and follow it exactly as presented to you

docs/README.codex.md

@@ -1,153 +0,0 @@
-# Superpowers for Codex
-
-Complete guide for using Superpowers with OpenAI Codex.
-
-## Quick Install
-
-Tell Codex:
-
-```
-Fetch and follow instructions from https://raw.githubusercontent.com/obra/superpowers/refs/heads/main/.codex/INSTALL.md
-```
-
-## Manual Installation
-
-### Prerequisites
-
-- OpenAI Codex access
-- Shell access to install files
-
-### Installation Steps
-
-#### 1. Clone Superpowers
-
-```bash
-mkdir -p ~/.codex/superpowers
-git clone https://github.com/obra/superpowers.git ~/.codex/superpowers
-```
-
-#### 2. Install Bootstrap
-
-The bootstrap file is included in the repository at `.codex/superpowers-bootstrap.md`. Codex will automatically use it from the cloned location.
-
-#### 3. Verify Installation
-
-Tell Codex:
-
-```
-Run ~/.codex/superpowers/.codex/superpowers-codex find-skills to show available skills
-```
-
-You should see a list of available skills with descriptions.
-
-## Usage
-
-### Finding Skills
-
-```
-Run ~/.codex/superpowers/.codex/superpowers-codex find-skills
-```
-
-### Loading a Skill
-
-```
-Run ~/.codex/superpowers/.codex/superpowers-codex use-skill superpowers:brainstorming
-```
-
-### Bootstrap All Skills
-
-```
-Run ~/.codex/superpowers/.codex/superpowers-codex bootstrap
-```
-
-This loads the complete bootstrap with all skill information.
-
-### Personal Skills
-
-Create your own skills in `~/.codex/skills/`:
-
-```bash
-mkdir -p ~/.codex/skills/my-skill
-```
-
-Create `~/.codex/skills/my-skill/SKILL.md`:
-
-```markdown
----
-name: my-skill
-description: Use when [condition] - [what it does]
----
-
-# My Skill
-
-[Your skill content here]
-```
-
-Personal skills override superpowers skills with the same name.
-
-## Architecture
-
-### Codex CLI Tool
-
-**Location:** `~/.codex/superpowers/.codex/superpowers-codex`
-
-A Node.js CLI script that provides three commands:
-- `bootstrap` - Load complete bootstrap with all skills
-- `use-skill <name>` - Load a specific skill
-- `find-skills` - List all available skills
-
-### Shared Core Module
-
-**Location:** `~/.codex/superpowers/lib/skills-core.js`
-
-The Codex implementation uses the shared `skills-core` module (ES module format) for skill discovery and parsing. This is the same module used by the OpenCode plugin, ensuring consistent behavior across platforms.
-
-### Tool Mapping
-
-Skills written for Claude Code are adapted for Codex with these mappings:
-
-- `TodoWrite` → `update_plan`
-- `Task` with subagents → Tell user subagents aren't available, do work directly
-- `Skill` tool → `~/.codex/superpowers/.codex/superpowers-codex use-skill`
-- File operations → Native Codex tools
-
-## Updating
-
-```bash
-cd ~/.codex/superpowers
-git pull
-```
-
-## Troubleshooting
-
-### Skills not found
-
-1. Verify installation: `ls ~/.codex/superpowers/skills`
-2. Check CLI works: `~/.codex/superpowers/.codex/superpowers-codex find-skills`
-3. Verify skills have SKILL.md files
-
-### CLI script not executable
-
-```bash
-chmod +x ~/.codex/superpowers/.codex/superpowers-codex
-```
-
-### Node.js errors
-
-The CLI script requires Node.js. Verify:
-
-```bash
-node --version
-```
-
-Should show v14 or higher (v18+ recommended for ES module support).
-
-## Getting Help
-
-- Report issues: https://github.com/obra/superpowers/issues
-- Main documentation: https://github.com/obra/superpowers
-- Blog post: https://blog.fsck.com/2025/10/27/skills-for-openai-codex/
-
-## Note
-
-Codex support is experimental and may require refinement based on user feedback. If you encounter issues, please report them on GitHub.

docs/README.kimi.md

@@ -0,0 +1,88 @@
+# Superpowers for Kimi Code
+
+Complete guide for using Superpowers with [Kimi Code](https://github.com/MoonshotAI/kimi-code).
+
+## Installation
+
+Superpowers is available in Kimi Code's plugin marketplace.
+
+Open the plugin manager:
+
+```text
+/plugins
+```
+
+Go to `Marketplace` > `Superpowers` and install it.
+
+You can also install from this repository:
+
+```text
+/plugins install https://github.com/obra/superpowers
+```
+
+For unreleased validation against `dev`, pin the branch explicitly:
+
+```text
+/plugins install https://github.com/obra/superpowers/tree/dev
+```
+
+Kimi Code applies plugin changes to new sessions. After installing, updating, enabling, disabling, or reloading a plugin, start a fresh session with `/new`.
+
+## How It Works
+
+The Kimi plugin manifest lives at `.kimi-plugin/plugin.json`.
+
+The manifest does three things:
+
+1. Points Kimi Code at the existing `skills/` directory.
+2. Loads `using-superpowers` at session start through `sessionStart.skill`.
+3. Provides Kimi-specific tool mapping through `skillInstructions`.
+
+Kimi Code reads Superpowers skills from this repository. There are no copied skills, symlinks, hooks, or extra runtime dependencies.
+
+## Tool Mapping
+
+Skills describe actions instead of hard-coding one runtime's tool names. On Kimi Code these resolve to:
+
+- "Ask the user" / "ask clarifying questions" -> `AskUserQuestion`
+- "Create a todo" / "mark complete in todo list" -> `TodoList`
+- "Dispatch a subagent" -> `Agent`
+- "Invoke a skill" -> Kimi Code's native `Skill` tool
+- "Read a file" / "write a file" / "edit a file" -> `Read`, `Write`, `Edit`
+- "Run a shell command" -> `Bash`
+- "Search file contents" -> `Grep`
+- "Find files by path or pattern" -> `Glob`
+- "Fetch a URL" -> `FetchURL`
+- "Search the web" -> `WebSearch`
+
+## Updating
+
+Use Kimi Code's plugin manager:
+
+```text
+/plugins
+```
+
+Select Superpowers and update it from there. Start a fresh session with `/new` after updating.
+
+## Troubleshooting
+
+### Plugin not loading
+
+1. Run `/plugins info superpowers` and check diagnostics.
+2. Make sure the plugin is enabled.
+3. Start a fresh session with `/new` after install or update.
+
+### Direct GitHub install used an old release
+
+Kimi Code installs the latest GitHub release for a bare repository URL when one exists. To test unreleased changes before the next Superpowers release, install the branch explicitly:
+
+```text
+/plugins install https://github.com/obra/superpowers/tree/dev
+```
+
+### Skills not triggering
+
+1. Confirm `/plugins info superpowers` shows the plugin enabled.
+2. Start a fresh session with `/new`.
+3. Try the acceptance prompt: `Let's make a react todo list`. A working install should load `brainstorming` before writing code.

docs/README.opencode.md

@@ -2,72 +2,57 @@
 
 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/plugin, then symlink ~/.config/opencode/superpowers/.opencode/plugin/superpowers.js to ~/.config/opencode/plugin/superpowers.js, then restart opencode.
+```json
+{
+  "plugin": ["superpowers@git+https://github.com/obra/superpowers.git"]
+}
 ```
 
-## Manual Installation
+Restart OpenCode. The plugin installs through OpenCode's plugin manager and
+registers all skills.
 
-### Prerequisites
+Verify by asking: "Tell me about your superpowers"
 
-- [OpenCode.ai](https://opencode.ai) installed
-- Node.js installed
-- Git installed
+OpenCode uses its own plugin install. If you also use Claude Code, Codex, or
+another harness, install Superpowers separately for each one.
 
-### Installation Steps
+### Migrating from the old symlink-based install
 
-#### 1. Install Superpowers
+If you previously installed superpowers using `git clone` and symlinks, remove the old setup:
 
 ```bash
-mkdir -p ~/.config/opencode/superpowers
-git clone https://github.com/obra/superpowers.git ~/.config/opencode/superpowers
+# Remove old symlinks
+rm -f ~/.config/opencode/plugins/superpowers.js
+rm -rf ~/.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
 ```
 
-#### 2. Register the Plugin
-
-OpenCode discovers plugins from `~/.config/opencode/plugin/`. Create a symlink:
-
-```bash
-mkdir -p ~/.config/opencode/plugin
-ln -sf ~/.config/opencode/superpowers/.opencode/plugin/superpowers.js ~/.config/opencode/plugin/superpowers.js
-```
-
-Alternatively, for project-local installation:
-
-```bash
-# In your OpenCode project
-mkdir -p .opencode/plugin
-ln -sf ~/.config/opencode/superpowers/.opencode/plugin/superpowers.js .opencode/plugin/superpowers.js
-```
-
-#### 3. Restart OpenCode
-
-Restart OpenCode to load the plugin. Superpowers will automatically activate.
+Then follow the installation steps above.
 
 ## Usage
 
 ### Finding Skills
 
-Use the `find_skills` tool to list all available skills:
+Use OpenCode's native `skill` tool to list all available skills:
 
 ```
-use find_skills tool
+use skill tool to list skills
 ```
 
 ### Loading a Skill
 
-Use the `use_skill` tool to load a specific skill:
-
 ```
-use use_skill tool with skill_name: "superpowers:brainstorming"
+use skill tool to load brainstorming
 ```
 
-Skills are automatically inserted into the conversation and persist across context compaction.
-
 ### Personal Skills
 
 Create your own skills in `~/.config/opencode/skills/`:
@@ -91,144 +76,88 @@ 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
-```
-
-Create `.opencode/skills/my-project-skill/SKILL.md`:
-
-```markdown
----
-name: my-project-skill
-description: Use when [condition] - [what it does]
----
-
-# My Project Skill
-
-[Your skill content here]
-```
-
-## Skill Priority
-
-Skills are resolved with this priority order:
-
-1. **Project skills** (`.opencode/skills/`) - Highest priority
-2. **Personal skills** (`~/.config/opencode/skills/`)
-3. **Superpowers skills** (`~/.config/opencode/superpowers/skills/`)
-
-You can force resolution to a specific level:
-- `project:skill-name` - Force project skill
-- `skill-name` - Search project → personal → superpowers
-- `superpowers:skill-name` - Force superpowers skill
-
-## Features
-
-### Automatic Context Injection
-
-The plugin automatically injects superpowers context via the chat.message hook on every session. No manual configuration needed.
-
-### Message Insertion Pattern
-
-When you load a skill with `use_skill`, it's inserted as a user message with `noReply: true`. This ensures skills persist throughout long conversations, even when OpenCode compacts context.
-
-### Compaction Resilience
-
-The plugin listens for `session.compacted` events and automatically re-injects the core superpowers bootstrap to maintain functionality after context compaction.
-
-### Tool Mapping
-
-Skills written for Claude Code are automatically adapted for OpenCode. The plugin provides mapping instructions:
-
-- `TodoWrite` → `update_plan`
-- `Task` with subagents → OpenCode's `@mention` system
-- `Skill` tool → `use_skill` custom tool
-- File operations → Native OpenCode tools
-
-## Architecture
-
-### Plugin Structure
-
-**Location:** `~/.config/opencode/superpowers/.opencode/plugin/superpowers.js`
-
-**Components:**
-- Two custom tools: `use_skill`, `find_skills`
-- chat.message hook for initial context injection
-- event handler for session.compacted re-injection
-- Uses shared `lib/skills-core.js` module (also used by Codex)
-
-### Shared Core Module
-
-**Location:** `~/.config/opencode/superpowers/lib/skills-core.js`
-
-**Functions:**
-- `extractFrontmatter()` - Parse skill metadata
-- `stripFrontmatter()` - Remove metadata from content
-- `findSkillsInDir()` - Recursive skill discovery
-- `resolveSkillPath()` - Skill resolution with shadowing
-- `checkForUpdates()` - Git update detection
-
-This module is shared between OpenCode and Codex implementations for code reuse.
+**Skill Priority:** Project skills > Personal skills > Superpowers skills
 
 ## Updating
 
-```bash
-cd ~/.config/opencode/superpowers
-git pull
+OpenCode installs Superpowers through a git-backed package spec. Some OpenCode
+and Bun versions pin that resolved git dependency in a lockfile or cache, so a
+restart may not pick up the newest Superpowers commit. If updates do not appear,
+clear OpenCode's package cache or reinstall the plugin.
+
+To pin a specific version, use a branch or tag:
+
+```json
+{
+  "plugin": ["superpowers@git+https://github.com/obra/superpowers.git#v5.0.3"]
+}
 ```
 
-Restart OpenCode to load the updates.
+## How It Works
+
+The plugin does two things:
+
+1. **Injects bootstrap context** via the `experimental.chat.messages.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 speak in actions rather than naming any one runtime's tools. On OpenCode these resolve to:
+
+- "Create a todo" / "mark complete in todo list" → `todowrite`
+- `Subagent (general-purpose):` template → OpenCode's `task` tool with `subagent_type: "general"` (or `"explore"` for codebase exploration)
+- "Invoke a skill" → OpenCode's native `skill` tool
+- "Read a file" → `read`
+- "Create a file" / "edit a file" / "delete a file" → `apply_patch`
+- "Run a shell command" → `bash`
+- "Search file contents" / "find files by name" → `grep`, `glob`
+- "Fetch a URL" → `webfetch`
+
+(Verified against the installed OpenCode CLI's tool inventory.)
 
 ## Troubleshooting
 
 ### Plugin not loading
 
-1. Check plugin file exists: `ls ~/.config/opencode/superpowers/.opencode/plugin/superpowers.js`
-2. Check symlink: `ls -l ~/.config/opencode/plugin/superpowers.js`
-3. Check OpenCode logs: `opencode run "test" --print-logs --log-level DEBUG`
-4. Look for: `service=plugin path=file:///.../superpowers.js loading plugin`
+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
+
+### Windows install issues
+
+Some Windows OpenCode builds have upstream installer issues with git-backed
+plugin specs, including cache paths for `git+https` URLs and Bun not finding
+`git.exe` even when it works in a normal terminal. If OpenCode cannot install
+the plugin, try installing with system npm and pointing OpenCode at the local
+package:
+
+```powershell
+npm install superpowers@git+https://github.com/obra/superpowers.git --prefix "$HOME\.config\opencode"
+```
+
+Then use the installed package path in `opencode.json`:
+
+```json
+{
+  "plugin": ["~/.config/opencode/node_modules/superpowers"]
+}
+```
 
 ### Skills not found
 
-1. Verify skills directory: `ls ~/.config/opencode/superpowers/skills`
-2. Use `find_skills` tool to see what's discovered
-3. Check skill structure: each skill needs a `SKILL.md` file
+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
 
-### Tools not working
+### Bootstrap not appearing
 
-1. Verify plugin loaded: Check OpenCode logs for plugin loading message
-2. Check Node.js version: The plugin requires Node.js for ES modules
-3. Test plugin manually: `node --input-type=module -e "import('file://~/.config/opencode/plugin/superpowers.js').then(m => console.log(Object.keys(m)))"`
-
-### Context not injecting
-
-1. Check if chat.message hook is working
-2. Verify using-superpowers skill exists
-3. Check OpenCode version (requires recent version with plugin support)
+1. Check OpenCode version supports `experimental.chat.messages.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
-
-The implementation includes an automated test suite at `tests/opencode/`:
-
-```bash
-# Run all tests
-./tests/opencode/run-tests.sh --integration --verbose
-
-# Run specific test
-./tests/opencode/run-tests.sh --test test-tools.sh
-```
-
-Tests verify:
-- Plugin loading
-- Skills-core library functionality
-- Tool execution (use_skill, find_skills)
-- Skill priority resolution
-- Proper isolation with temp HOME

docs/plans/2025-11-22-opencode-support-implementation.md

@@ -1,6 +1,6 @@
 # OpenCode Support Implementation Plan
 
-> **For Claude:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.
 
 **Goal:** Add full superpowers support for OpenCode.ai with a native JavaScript plugin that shares core functionality with the existing Codex implementation.
 

docs/plans/2026-01-17-visual-brainstorming.md

@@ -0,0 +1,571 @@
+# Visual Brainstorming Companion Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.
+
+**Goal:** Give Claude a browser-based visual companion for brainstorming sessions - show mockups, prototypes, and interactive choices alongside terminal conversation.
+
+**Architecture:** Claude writes HTML to a temp file. A local Node.js server watches that file and serves it with an auto-injected helper library. User interactions flow via WebSocket to server stdout, which Claude sees in background task output.
+
+**Tech Stack:** Node.js, Express, ws (WebSocket), chokidar (file watching)
+
+---
+
+## Task 1: Create the Server Foundation
+
+**Files:**
+- Create: `lib/brainstorm-server/index.js`
+- Create: `lib/brainstorm-server/package.json`
+
+**Step 1: Create package.json**
+
+```json
+{
+  "name": "brainstorm-server",
+  "version": "1.0.0",
+  "description": "Visual brainstorming companion server for Claude Code",
+  "main": "index.js",
+  "dependencies": {
+    "chokidar": "^3.5.3",
+    "express": "^4.18.2",
+    "ws": "^8.14.2"
+  }
+}
+```
+
+**Step 2: Create minimal server that starts**
+
+```javascript
+const express = require('express');
+const http = require('http');
+const WebSocket = require('ws');
+const chokidar = require('chokidar');
+const fs = require('fs');
+const path = require('path');
+
+const PORT = process.env.BRAINSTORM_PORT || 3333;
+const SCREEN_FILE = process.env.BRAINSTORM_SCREEN || '/tmp/brainstorm/screen.html';
+const SCREEN_DIR = path.dirname(SCREEN_FILE);
+
+// Ensure screen directory exists
+if (!fs.existsSync(SCREEN_DIR)) {
+  fs.mkdirSync(SCREEN_DIR, { recursive: true });
+}
+
+// Create default screen if none exists
+if (!fs.existsSync(SCREEN_FILE)) {
+  fs.writeFileSync(SCREEN_FILE, `<!DOCTYPE html>
+<html>
+<head>
+  <title>Brainstorm Companion</title>
+  <style>
+    body { font-family: system-ui, sans-serif; padding: 2rem; max-width: 800px; margin: 0 auto; }
+    h1 { color: #333; }
+    p { color: #666; }
+  </style>
+</head>
+<body>
+  <h1>Brainstorm Companion</h1>
+  <p>Waiting for Claude to push a screen...</p>
+</body>
+</html>`);
+}
+
+const app = express();
+const server = http.createServer(app);
+const wss = new WebSocket.Server({ server });
+
+// Track connected browsers for reload notifications
+const clients = new Set();
+
+wss.on('connection', (ws) => {
+  clients.add(ws);
+  ws.on('close', () => clients.delete(ws));
+
+  ws.on('message', (data) => {
+    // User interaction event - write to stdout for Claude
+    const event = JSON.parse(data.toString());
+    console.log(JSON.stringify({ type: 'user-event', ...event }));
+  });
+});
+
+// Serve current screen with helper.js injected
+app.get('/', (req, res) => {
+  let html = fs.readFileSync(SCREEN_FILE, 'utf-8');
+
+  // Inject helper script before </body>
+  const helperScript = fs.readFileSync(path.join(__dirname, 'helper.js'), 'utf-8');
+  const injection = `<script>\n${helperScript}\n</script>`;
+
+  if (html.includes('</body>')) {
+    html = html.replace('</body>', `${injection}\n</body>`);
+  } else {
+    html += injection;
+  }
+
+  res.type('html').send(html);
+});
+
+// Watch for screen file changes
+chokidar.watch(SCREEN_FILE).on('change', () => {
+  console.log(JSON.stringify({ type: 'screen-updated', file: SCREEN_FILE }));
+  // Notify all browsers to reload
+  clients.forEach(ws => {
+    if (ws.readyState === WebSocket.OPEN) {
+      ws.send(JSON.stringify({ type: 'reload' }));
+    }
+  });
+});
+
+server.listen(PORT, '127.0.0.1', () => {
+  console.log(JSON.stringify({ type: 'server-started', port: PORT, url: `http://localhost:${PORT}` }));
+});
+```
+
+**Step 3: Run npm install**
+
+Run: `cd lib/brainstorm-server && npm install`
+Expected: Dependencies installed
+
+**Step 4: Test server starts**
+
+Run: `cd lib/brainstorm-server && timeout 3 node index.js || true`
+Expected: See JSON with `server-started` and port info
+
+**Step 5: Commit**
+
+```bash
+git add lib/brainstorm-server/
+git commit -m "feat: add brainstorm server foundation"
+```
+
+---
+
+## Task 2: Create the Helper Library
+
+**Files:**
+- Create: `lib/brainstorm-server/helper.js`
+
+**Step 1: Create helper.js with event auto-capture**
+
+```javascript
+(function() {
+  const WS_URL = 'ws://' + window.location.host;
+  let ws = null;
+  let eventQueue = [];
+
+  function connect() {
+    ws = new WebSocket(WS_URL);
+
+    ws.onopen = () => {
+      // Send any queued events
+      eventQueue.forEach(e => ws.send(JSON.stringify(e)));
+      eventQueue = [];
+    };
+
+    ws.onmessage = (msg) => {
+      const data = JSON.parse(msg.data);
+      if (data.type === 'reload') {
+        window.location.reload();
+      }
+    };
+
+    ws.onclose = () => {
+      // Reconnect after 1 second
+      setTimeout(connect, 1000);
+    };
+  }
+
+  function send(event) {
+    event.timestamp = Date.now();
+    if (ws && ws.readyState === WebSocket.OPEN) {
+      ws.send(JSON.stringify(event));
+    } else {
+      eventQueue.push(event);
+    }
+  }
+
+  // Auto-capture clicks on interactive elements
+  document.addEventListener('click', (e) => {
+    const target = e.target.closest('button, a, [data-choice], [role="button"], input[type="submit"]');
+    if (!target) return;
+
+    // Don't capture regular link navigation
+    if (target.tagName === 'A' && !target.dataset.choice) return;
+
+    e.preventDefault();
+
+    send({
+      type: 'click',
+      text: target.textContent.trim(),
+      choice: target.dataset.choice || null,
+      id: target.id || null,
+      className: target.className || null
+    });
+  });
+
+  // Auto-capture form submissions
+  document.addEventListener('submit', (e) => {
+    e.preventDefault();
+    const form = e.target;
+    const formData = new FormData(form);
+    const data = {};
+    formData.forEach((value, key) => { data[key] = value; });
+
+    send({
+      type: 'submit',
+      formId: form.id || null,
+      formName: form.name || null,
+      data: data
+    });
+  });
+
+  // Auto-capture input changes (debounced)
+  let inputTimeout = null;
+  document.addEventListener('input', (e) => {
+    const target = e.target;
+    if (!target.matches('input, textarea, select')) return;
+
+    clearTimeout(inputTimeout);
+    inputTimeout = setTimeout(() => {
+      send({
+        type: 'input',
+        name: target.name || null,
+        id: target.id || null,
+        value: target.value,
+        inputType: target.type || target.tagName.toLowerCase()
+      });
+    }, 500); // 500ms debounce
+  });
+
+  // Expose for explicit use if needed
+  window.brainstorm = {
+    send: send,
+    choice: (value, metadata = {}) => send({ type: 'choice', value, ...metadata })
+  };
+
+  connect();
+})();
+```
+
+**Step 2: Verify helper.js is syntactically valid**
+
+Run: `node -c lib/brainstorm-server/helper.js`
+Expected: No syntax errors
+
+**Step 3: Commit**
+
+```bash
+git add lib/brainstorm-server/helper.js
+git commit -m "feat: add browser helper library for event capture"
+```
+
+---
+
+## Task 3: Write Tests for the Server
+
+**Files:**
+- Create: `tests/brainstorm-server/server.test.js`
+- Create: `tests/brainstorm-server/package.json`
+
+**Step 1: Create test package.json**
+
+```json
+{
+  "name": "brainstorm-server-tests",
+  "version": "1.0.0",
+  "scripts": {
+    "test": "node server.test.js"
+  }
+}
+```
+
+**Step 2: Write server tests**
+
+```javascript
+const { spawn } = require('child_process');
+const http = require('http');
+const WebSocket = require('ws');
+const fs = require('fs');
+const path = require('path');
+const assert = require('assert');
+
+const SERVER_PATH = path.join(__dirname, '../../lib/brainstorm-server/index.js');
+const TEST_PORT = 3334;
+const TEST_SCREEN = '/tmp/brainstorm-test/screen.html';
+
+// Clean up test directory
+function cleanup() {
+  if (fs.existsSync(path.dirname(TEST_SCREEN))) {
+    fs.rmSync(path.dirname(TEST_SCREEN), { recursive: true });
+  }
+}
+
+async function sleep(ms) {
+  return new Promise(resolve => setTimeout(resolve, ms));
+}
+
+async function fetch(url) {
+  return new Promise((resolve, reject) => {
+    http.get(url, (res) => {
+      let data = '';
+      res.on('data', chunk => data += chunk);
+      res.on('end', () => resolve({ status: res.statusCode, body: data }));
+    }).on('error', reject);
+  });
+}
+
+async function runTests() {
+  cleanup();
+
+  // Start server
+  const server = spawn('node', [SERVER_PATH], {
+    env: { ...process.env, BRAINSTORM_PORT: TEST_PORT, BRAINSTORM_SCREEN: TEST_SCREEN }
+  });
+
+  let stdout = '';
+  server.stdout.on('data', (data) => { stdout += data.toString(); });
+  server.stderr.on('data', (data) => { console.error('Server stderr:', data.toString()); });
+
+  await sleep(1000); // Wait for server to start
+
+  try {
+    // Test 1: Server starts and outputs JSON
+    console.log('Test 1: Server startup message');
+    assert(stdout.includes('server-started'), 'Should output server-started');
+    assert(stdout.includes(TEST_PORT.toString()), 'Should include port');
+    console.log('  PASS');
+
+    // Test 2: GET / returns HTML with helper injected
+    console.log('Test 2: Serves HTML with helper injected');
+    const res = await fetch(`http://localhost:${TEST_PORT}/`);
+    assert.strictEqual(res.status, 200);
+    assert(res.body.includes('brainstorm'), 'Should include brainstorm content');
+    assert(res.body.includes('WebSocket'), 'Should have helper.js injected');
+    console.log('  PASS');
+
+    // Test 3: WebSocket connection and event relay
+    console.log('Test 3: WebSocket relays events to stdout');
+    stdout = ''; // Reset stdout capture
+    const ws = new WebSocket(`ws://localhost:${TEST_PORT}`);
+    await new Promise(resolve => ws.on('open', resolve));
+
+    ws.send(JSON.stringify({ type: 'click', text: 'Test Button' }));
+    await sleep(100);
+
+    assert(stdout.includes('user-event'), 'Should relay user events');
+    assert(stdout.includes('Test Button'), 'Should include event data');
+    ws.close();
+    console.log('  PASS');
+
+    // Test 4: File change triggers reload notification
+    console.log('Test 4: File change notifies browsers');
+    const ws2 = new WebSocket(`ws://localhost:${TEST_PORT}`);
+    await new Promise(resolve => ws2.on('open', resolve));
+
+    let gotReload = false;
+    ws2.on('message', (data) => {
+      const msg = JSON.parse(data.toString());
+      if (msg.type === 'reload') gotReload = true;
+    });
+
+    // Modify the screen file
+    fs.writeFileSync(TEST_SCREEN, '<html><body>Updated</body></html>');
+    await sleep(500);
+
+    assert(gotReload, 'Should send reload message on file change');
+    ws2.close();
+    console.log('  PASS');
+
+    console.log('\nAll tests passed!');
+
+  } finally {
+    server.kill();
+    cleanup();
+  }
+}
+
+runTests().catch(err => {
+  console.error('Test failed:', err);
+  process.exit(1);
+});
+```
+
+**Step 3: Run tests**
+
+Run: `cd tests/brainstorm-server && npm install ws && node server.test.js`
+Expected: All tests pass
+
+**Step 4: Commit**
+
+```bash
+git add tests/brainstorm-server/
+git commit -m "test: add brainstorm server integration tests"
+```
+
+---
+
+## Task 4: Add Visual Companion to Brainstorming Skill
+
+**Files:**
+- Modify: `skills/brainstorming/SKILL.md`
+- Create: `skills/brainstorming/visual-companion.md` (supporting doc)
+
+**Step 1: Create the supporting documentation**
+
+Create `skills/brainstorming/visual-companion.md`:
+
+```markdown
+# Visual Companion Reference
+
+## Starting the Server
+
+Run as a background job:
+
+```bash
+node ${PLUGIN_ROOT}/lib/brainstorm-server/index.js
+```
+
+Tell the user: "I've started a visual companion at http://localhost:3333 - open it in a browser."
+
+## Pushing Screens
+
+Write HTML to `/tmp/brainstorm/screen.html`. The server watches this file and auto-refreshes the browser.
+
+## Reading User Responses
+
+Check the background task output for JSON events:
+
+```json
+{"type":"user-event","type":"click","text":"Option A","choice":"optionA","timestamp":1234567890}
+{"type":"user-event","type":"submit","data":{"notes":"My feedback"},"timestamp":1234567891}
+```
+
+Event types:
+- **click**: User clicked button or `data-choice` element
+- **submit**: User submitted form (includes all form data)
+- **input**: User typed in field (debounced 500ms)
+
+## HTML Patterns
+
+### Choice Cards
+
+```html
+<div class="options">
+  <button data-choice="optionA">
+    <h3>Option A</h3>
+    <p>Description</p>
+  </button>
+  <button data-choice="optionB">
+    <h3>Option B</h3>
+    <p>Description</p>
+  </button>
+</div>
+```
+
+### Interactive Mockup
+
+```html
+<div class="mockup">
+  <header data-choice="header">App Header</header>
+  <nav data-choice="nav">Navigation</nav>
+  <main data-choice="main">Content</main>
+</div>
+```
+
+### Form with Notes
+
+```html
+<form>
+  <label>Priority: <input type="range" name="priority" min="1" max="5"></label>
+  <textarea name="notes" placeholder="Additional thoughts..."></textarea>
+  <button type="submit">Submit</button>
+</form>
+```
+
+### Explicit JavaScript
+
+```html
+<button onclick="brainstorm.choice('custom', {extra: 'data'})">Custom</button>
+```
+```
+
+**Step 2: Add visual companion section to brainstorming skill**
+
+Add after "Key Principles" in `skills/brainstorming/SKILL.md`:
+
+```markdown
+
+## Visual Companion (Optional)
+
+When brainstorming involves visual elements - UI mockups, wireframes, interactive prototypes - use the browser-based visual companion.
+
+**When to use:**
+- Presenting UI/UX options that benefit from visual comparison
+- Showing wireframes or layout options
+- Gathering structured feedback (ratings, forms)
+- Prototyping click interactions
+
+**How it works:**
+1. Start the server as a background job
+2. Tell user to open http://localhost:3333
+3. Write HTML to `/tmp/brainstorm/screen.html` (auto-refreshes)
+4. Check background task output for user interactions
+
+The terminal remains the primary conversation interface. The browser is a visual aid.
+
+**Reference:** See `visual-companion.md` in this skill directory for HTML patterns and API details.
+```
+
+**Step 3: Verify the edits**
+
+Run: `grep -A5 "Visual Companion" skills/brainstorming/SKILL.md`
+Expected: Shows the new section
+
+**Step 4: Commit**
+
+```bash
+git add skills/brainstorming/
+git commit -m "feat: add visual companion to brainstorming skill"
+```
+
+---
+
+## Task 5: Add Server to Plugin Ignore (Optional Cleanup)
+
+**Files:**
+- Check if `.gitignore` needs node_modules exclusion for lib/brainstorm-server
+
+**Step 1: Check current gitignore**
+
+Run: `cat .gitignore 2>/dev/null || echo "No .gitignore"`
+
+**Step 2: Add node_modules if needed**
+
+If not already present, add:
+```
+lib/brainstorm-server/node_modules/
+```
+
+**Step 3: Commit if changed**
+
+```bash
+git add .gitignore
+git commit -m "chore: ignore brainstorm-server node_modules"
+```
+
+---
+
+## Summary
+
+After completing all tasks:
+
+1. **Server** at `lib/brainstorm-server/` - Node.js server that watches HTML file and relays events
+2. **Helper library** auto-injected - captures clicks, forms, inputs
+3. **Tests** at `tests/brainstorm-server/` - verifies server behavior
+4. **Brainstorming skill** updated with visual companion section and `visual-companion.md` reference doc
+
+**To use:**
+1. Start server as background job: `node lib/brainstorm-server/index.js &`
+2. Tell user to open `http://localhost:3333`
+3. Write HTML to `/tmp/brainstorm/screen.html`
+4. Check task output for user events

docs/porting-to-a-new-harness.md

@@ -0,0 +1,826 @@
+# Porting Superpowers to a New Harness
+
+This guide explains how to add support for a new harness — an IDE, CLI, or
+agent runner that isn't Claude Code — so that Superpowers skills auto-trigger
+there the same way they do natively.
+
+It is written in two layers. **Part 1–3** explain how the system works and how
+to tell whether a harness can be supported at all; read these before you touch
+anything. **Part 4–8** are a prescriptive procedure for an agent (supervised by
+a human partner) to execute the port end to end, through distribution. An
+appendix indexes the current reference integrations so you can copy the closest
+one.
+
+The integration mechanism differs across harnesses, and it will keep changing.
+This guide deliberately teaches the **invariants** — the things that must be
+true no matter the mechanism — and points you at a live reference implementation
+to copy. When this guide and the code disagree, the code wins; fix the guide.
+
+## Before you start
+
+Adding a harness is the highest-stakes contribution type in this repo. Before
+writing anything:
+
+- Read `CLAUDE.md` and `.github/PULL_REQUEST_TEMPLATE.md` in full — the
+  contributor rules and the new-harness PR requirements are not optional.
+- Search open **and closed** PRs for a prior attempt at this harness. If one
+  exists, understand why it stalled before starting your own.
+
+---
+
+## Part 1 — How Superpowers works across harnesses
+
+Superpowers is the same content everywhere. What changes per harness is the thin
+layer that delivers that content to the model and translates its instructions
+into the harness's native tools. Three components:
+
+1. **Skills (harness-agnostic).** Everything in `skills/` is the source of
+   truth, shared verbatim by every harness. Skills are written to describe
+   *actions* — "invoke a skill", "read a file", "dispatch a subagent", "create a
+   todo" — and never name a specific tool. This is what lets one skill body run
+   on Claude Code, Codex, Gemini, pi, and the rest without edits.
+
+2. **Tool mapping (per-harness).** Each harness needs the action vocabulary
+   translated into its real tool names. That translation lives in
+   `skills/using-superpowers/references/<harness>-tools.md` and/or inline in the
+   harness's bootstrap injector (see Part 5). It says, e.g., "*dispatch a
+   subagent* → call `task` with `subagent_type`."
+
+3. **Bootstrap (per-harness).** At the start of every session, the full
+   `skills/using-superpowers/SKILL.md` is injected into the model's context,
+   wrapped in `<EXTREMELY_IMPORTANT>` tags, with the tool mapping appended. That
+   injected skill is what teaches the model that skills exist and that it must
+   check for a relevant skill before acting. **The bootstrap is the entire
+   integration.** Without it, the skill files are inert — present on disk, never
+   invoked.
+
+### Two rules that make this work
+
+**1. Skills name actions, not tools.** Do **not** edit skill bodies to fit your
+harness. Porting adds a tool-mapping reference and a bootstrap injector; it
+never reaches into `skills/*/SKILL.md` to swap tool names. (The project's
+contributor guidelines treat skill content as carefully-tuned behavior-shaping
+code; rewording it for "compliance" is rejected on sight.)
+
+**2. Everything ships through the harness's own install mechanism. Never edit the
+user's files.** The bootstrap, the skills, and the tool mapping all get delivered
+*as part of what the harness installs* — a plugin, an extension, a marketplace
+entry, an extension-bundled context file. A port **must not** reach into a user's
+global or personal config (`~/.gemini/config/AGENTS.md`, `settings.json`,
+`trustedFolders.json`, a hand-edited `~/.bashrc`, etc.) to inject anything. The
+harness owns what it loads; your install artifact is the only thing you get to
+write. If the install mechanism genuinely can't carry the bootstrap, that is a
+limitation to surface (Part 6) — never a license to hand-edit the user's config.
+(Shape C is *not* an exception: Gemini's context file is fine because it ships
+*inside the installed extension* and is declared by the manifest's
+`contextFileName` — the harness loads the extension's own file, not a file you
+edited in the user's home.)
+
+---
+
+## Part 2 — Can this harness be supported?
+
+A harness can support Superpowers only if it can do all of the following. Check
+these before writing code — if the first one fails, stop.
+
+### Hard requirement: automatic session-start injection
+
+The harness must let you inject text into the model's context **at the start of
+every session, with no per-session opt-in by your human partner.** This is the
+one non-negotiable capability. It can take any form:
+
+- a **hook/event system** that runs a shell command at session start and reads
+  its stdout (Claude Code, Codex, Cursor, Copilot CLI), or
+- an **in-process plugin/extension** with a session-start or message lifecycle
+  callback that can mutate the message array (OpenCode, pi), or
+- an **instructions-file** convention where the harness loads a context file that
+  *your installed extension ships and declares* (e.g. Gemini's `contextFileName`
+  pointing at the extension's own `GEMINI.md`) — not a file you edit in the user's
+  home.
+
+If the only way to get Superpowers in front of the model is for your human
+partner to opt in each session (paste a prompt, run a command, enable a mode),
+the harness
+**cannot** be properly supported. The acceptance test in Part 3 will fail, and
+the PR will be closed. This is the single most common reason a "port" isn't a
+real port.
+
+### The rest of the capability checklist
+
+| Capability | Why it's needed | If absent |
+|---|---|---|
+| **Skill discovery + invocation** | The model must be able to load a skill's full content on demand | If there's no native skill tool, the sanctioned fallback is to `read` the relevant `SKILL.md` directly — see Part 5. A harness with neither a skill tool nor file-read cannot work. |
+| **File read / write / edit** | Nearly every skill manipulates files | Essential. No workaround. |
+| **Run shell commands** | TDD, verification, git workflows | Essential. |
+| **Subagent / task dispatch** | `dispatching-parallel-agents`, `subagent-driven-development` | Degradable: if unavailable, those specific skills tell the model to do the work inline or report the missing capability — *never* to invent a `Task` call. Some harnesses gate this behind a config flag (e.g. Codex needs multi-agent enabled). |
+| **Todo / task tracking** | Progress tracking in several skills | Degradable: fall back to a plan file or `TODO.md`. |
+| **Web fetch / search** | A few skills | Degradable. |
+| **Shell or polyglot script execution (Windows)** | Only for the shell-hook shape, only if you want Windows support | See Part 7. In-process-plugin harnesses sidestep this entirely. |
+
+"Degradable" means: the skill already has fallback wording for the missing
+tool. Your job in the tool mapping is to point at the real tool when it exists
+and reuse that fallback wording when it doesn't.
+
+### You may not need a new directory at all
+
+Some "new harnesses" are really existing integrations under a different
+installer. Factory's Droid, for example, consumes the Claude Code plugin via its
+own `plugin install` command and needs no new files here. Before building,
+check whether the harness can simply load an existing manifest. A port that adds
+nothing to this repo but a paragraph in the README is a perfectly good outcome.
+
+---
+
+## Part 3 — Definition of done
+
+A port is finished when **all** of these are true:
+
+1. The `using-superpowers` bootstrap loads at session start, every session, with
+   no per-session opt-in.
+2. A tool mapping exists for the harness (in
+   `references/<harness>-tools.md`, inline in the bootstrap, or both — per Part 5).
+3. Skills can actually be invoked — natively, or via the documented
+   read-`SKILL.md` fallback — and the model follows them.
+4. **The acceptance test passes.** In a clean session, the user message:
+
+   > Let's make a react todo list
+
+   auto-triggers the `brainstorming` skill *before any code is written*. Capture
+   the full transcript — the PR requires it.
+5. Tests cover the integration (Part 5) and pass.
+6. A real user can install it through the harness's own mechanism (not by
+   hand-copying files), and the version is tracked in `.version-bump.json` where
+   applicable (Part 6). Note that some installers rewrite or strip the manifest on
+   install (one drops it to just `{"name": …}`), so "the *installed* files report
+   the repo version" is not always achievable — track the version at the source
+   manifest and don't treat a rewritten installed manifest as a failure.
+
+A quick smoke check before the full acceptance test: start a session and ask the
+model to describe its superpowers. If the bootstrap injected, it knows it has
+them. (OpenCode's install doc uses `opencode run --print-logs "hello" 2>&1 |
+grep -i superpowers` for the same goal via a different mechanism — log-grep
+rather than asking the model; the `2>&1` matters because logs go to stderr. Find
+your harness's equivalent.)
+
+---
+
+## Part 4 — Choose your integration shape
+
+There are three structural shapes, distinguished by *how you get the bootstrap
+in front of the model*. Pick the one that matches what your harness exposes,
+then copy that reference implementation. The shape determines almost everything
+in Part 5 — the steps below branch on it.
+
+### How to tell which shape you have
+
+Before routing, learn the harness's *actual* mechanism — and don't assume it's
+well documented or that it behaves like whatever harness it forked from.
+
+**Find the surface:**
+
+- **Search the web for the harness's docs** (extension / plugin / hook / skill /
+  MCP / "context file" / "rules file"). Vendor tools change fast; search rather
+  than trust training knowledge.
+- **Find and read an existing third-party extension/plugin for the harness.** A
+  real working example beats docs — it shows the manifest shape, the install
+  command, and which components the harness actually loads.
+- Check what the harness loads at startup: a settings file? an extensions
+  directory? a per-project or global instructions file (`AGENTS.md`, `<NAME>.md`)?
+
+**If it's underdocumented, reverse-engineer it empirically** (a real porter has
+had to do every one of these):
+
+- `strings` the binary / grep the install tree for hook event names, config
+  paths, and the instructions file it reads.
+- **Ask the running model to enumerate its own tool names** — e.g. "list the
+  exact machine names of every tool you can call." This is the authoritative way
+  to get tool names without inventing them (see Step 4).
+- Prove every assumption with a **unique-marker test**: inject a nonsense token
+  through the mechanism you think works, start a fresh session, and confirm the
+  token actually reached the model.
+
+**A fork does not inherit its parent's behavior.** A harness derived from another
+(e.g. a Gemini-derived CLI) may expose the parent's manifest fields and
+`@`-include syntax and *still not honor them the same way*. Verify with a marker;
+never assume the parent's recipe transfers.
+
+Then route to a shape:
+
+- Shell command at session start whose stdout is read → **Shape A**.
+- Plugin/extension module with lifecycle callbacks you run code in → **Shape B**.
+- Only ever an always-on instructions file, no hook and no code plugin →
+  **Shape C**.
+
+**Shapes compose — they are not mutually exclusive.** The *skill-discovery*
+mechanism and the *bootstrap* mechanism need not be the same shape — but **both
+must still ride the install mechanism** (rule 2). Decide the two questions
+separately: *where do skills get discovered?* and *how does the bootstrap reach
+the model every session?* A harness might install skills via a plugin yet need
+the bootstrap delivered another install-shipped way (an extension-declared
+context file, or — see below — by the harness surfacing the installed
+`using-superpowers` skill's own description at session start). If more than one
+install-mechanism surface injects automatically, prefer the most reliable. What
+you may **not** do is bridge a gap by editing the user's global config.
+
+### Shape A — Shell-hook
+
+The harness has a hook system that runs a shell command at session start and
+reads JSON from its stdout. The configured command runs `run-hook.cmd`, a
+polyglot wrapper that just locates bash and dispatches the named script; the
+script (`hooks/session-start`, or a harness-specific variant like
+`hooks/session-start-codex`) is what reads `using-superpowers/SKILL.md` and
+prints a JSON object whose **field name and nesting differ per harness**.
+
+- Reference: `hooks/session-start` (and `hooks/session-start-codex`),
+  `hooks/run-hook.cmd`, and the per-harness hook config `hooks/hooks.json`
+  (Claude Code), `hooks/hooks-codex.json` (Codex), `hooks/hooks-cursor.json`
+  (Cursor).
+- Manifests: `.codex-plugin/plugin.json`, `.cursor-plugin/plugin.json` point the
+  harness at `./skills/` and the right `hooks-*.json`. (Claude Code's
+  `.claude-plugin/plugin.json` sets neither field — it auto-discovers `skills/`
+  and `hooks/hooks.json` by convention.)
+
+> **A hook *system* is not a session-start *event*.** A harness can have a
+> `hooks.json` mechanism — and even contain the literal string `SessionStart` in
+> its binary — while having no hook event that fires at session start and can
+> inject context. (One real harness only exposed pre/post-tool and stop events;
+> the `SessionStart` strings were telemetry.) Confirm the *specific event* you
+> need exists and can write to the model's context before committing to Shape A.
+> If it can't, the bootstrap belongs in an instructions file (Shape C) instead.
+
+### Shape B — In-process plugin / extension
+
+The harness loads a JS/TS module that exposes lifecycle callbacks. You register
+the skills directory through the harness's API and inject the bootstrap by
+mutating the message array in code.
+
+- Reference: `.opencode/plugins/superpowers.js` (JavaScript) and
+  `.pi/extensions/superpowers.ts` (TypeScript). pi is the closest reference for
+  any harness that has **no native skill tool**.
+
+### Shape C — Instructions-file
+
+The harness has neither a shell hook nor a code plugin — its session-start
+surface is a context file that *your installed extension ships and the manifest
+declares* (e.g. Gemini's `contextFileName` → the extension's own `GEMINI.md`).
+You can't run code or mutate messages; the extension's context file points at the
+bootstrap. There is no injector to assemble a string or strip frontmatter — the
+harness loads the referenced content as-is. **This works only because the file is
+part of the installed extension** — never substitute "edit the user's global
+`GEMINI.md`/`AGENTS.md`" for shipping your own (rule 2).
+
+- Reference: `gemini-extension.json` (manifest, with `contextFileName`),
+  `GEMINI.md` (two `@`-includes — the bootstrap skill and the tool-mapping
+  reference), `skills/using-superpowers/references/gemini-tools.md`.
+- Note: `@`-include is a Gemini feature. If your harness loads an instructions
+  file but has no include syntax, you must inline the bootstrap content into the
+  file instead.
+- **Don't trust that an `@`-include is actually expanded — prove it.** A
+  Gemini-*derived* harness can accept `@./path` syntax yet treat it as a *hint
+  the model may choose to read* (it emits a file-read tool call) rather than a
+  guaranteed inline expansion. That's the difference between the bootstrap being
+  reliably present every session and the model maybe-reading it. Run a
+  unique-marker test: if the marker isn't in context *without* a tool call,
+  **inline the content** rather than `@`-include it.
+
+### Routing table
+
+| If the harness… | Use shape | Copy from |
+|---|---|---|
+| runs a shell command at session start and reads its stdout | A (shell-hook) | Codex (`hooks/session-start-codex` + `hooks/hooks-codex.json` + `.codex-plugin/`) |
+| is a JS/TS plugin host with session/message lifecycle callbacks | B (in-process) | OpenCode (`.opencode/`) — or pi (`.pi/`) if it has no native skill tool |
+| ships an extension-declared context file it always loads | C (instructions-file) | Gemini (`gemini-extension.json` + `GEMINI.md` + `references/gemini-tools.md`) |
+| has a plugin install command and a manifest `contextFileName` (or equivalent) the installer keeps | C via the plugin installer | Antigravity (`.antigravity-plugin/` — `agy plugin install` ships a generated context file; verify the installer preserves it — Part 6) |
+
+Most real harnesses fit one row cleanly; the last is the hybrid case (rule 2 still
+holds — the bootstrap rides the install mechanism, never a user-config edit).
+
+---
+
+## Part 5 — The porting procedure
+
+### Step 1 — Study the closest reference implementation
+
+Open the files named in Part 4 for your shape and read them end to end. The
+patterns below are summaries; the code is the spec.
+
+### Step 2 — Create the manifest / entry point
+
+Create whatever the harness uses to recognize the plugin. Match the existing
+ones in spirit:
+
+- **Shape A:** a `*-plugin/plugin.json` (see `.codex-plugin/plugin.json`) with
+  `name`, `version`, `description`, author/license/keywords, `"skills":
+  "./skills/"`, and `"hooks": "./hooks/hooks-<harness>.json"`. Plus the
+  `hooks-<harness>.json` itself, registering a session-start hook whose command
+  invokes `run-hook.cmd`.
+- **Shape B:** the module the harness loads (e.g. `.<harness>/plugins/*.js`) plus
+  whatever package metadata it needs to be discovered. The committed package
+  metadata is the **repo-root `package.json`**: `main` points at the OpenCode
+  plugin, the `pi` field (`pi.extensions`, `pi.skills`) plus the `pi-package`
+  keyword declare the pi extension. Per-harness local manifests and lockfiles are
+  kept out of git — `.opencode/.gitignore` excludes `node_modules`,
+  `package.json`, and lockfiles. Do the same for your harness's *local* install
+  artifacts so they don't pollute the repo — but never gitignore the repo-root
+  `package.json`, which is the tracked source of truth.
+  - **Build/dependency check.** Decide how the harness loads your module:
+    does it run the source directly (pi's `.ts` is referenced as-is from
+    `package.json`; OpenCode ships plain `.js`), or does it need a transpile/build
+    step? Superpowers is zero-runtime-dependency. pi's `import type
+    { ExtensionAPI }` works specifically because the harness runs the `.ts`
+    directly, supplies that type at load, and the repo never type-checks the file
+    in CI — the import isn't even declared as a dependency. If *your* harness
+    actually type-checks or bundles the plugin, that breaks: an undeclared type
+    import fails, and the PR rules only carve out *runtime* deps for new
+    harnesses, not dev/type packages. If you hit this, confirm the approach with
+    the maintainer rather than quietly adding a dependency. Keep any build output
+    out of git and document the command.
+- **Shape C (instructions-file):** a small manifest (see `gemini-extension.json`:
+  `name`, `description`, `version`, `contextFileName`) plus the context file
+  itself (`GEMINI.md` is just two `@`-includes: the bootstrap skill and the
+  tool-mapping reference). The Gemini manifest has no `skills` field — Gemini
+  auto-discovers the `skills/` directory bundled in the installed extension. If
+  your harness has a native skill tool but no manifest field to register the
+  directory, you must find its discovery convention (read its extension docs),
+  then verify empirically: after wiring, ask the model to list its available
+  skills — if the bundled skills don't appear, discovery isn't working yet.
+
+### Step 3 — Wire the bootstrap injection
+
+This is the heart of the port. The shared goal: at session start, get the
+`using-superpowers` skill content (wrapped in `<EXTREMELY_IMPORTANT>` tags) plus
+the harness's tool mapping in front of the model, with a note that the skill is
+already active so the model doesn't try to load it again. *How* you do that —
+and what you assemble vs. what the harness loads raw — depends entirely on your
+shape. Do **not** apply one shape's recipe to another.
+
+**Shape A — a script reads `SKILL.md` and prints the harness's JSON.** The
+dispatched script (`hooks/session-start`) `cat`s the whole `SKILL.md` (frontmatter
+included — that's fine; it's emitted verbatim), wraps it with the "You have
+superpowers… for all other skills use the Skill tool" preamble, escapes it, and
+prints the harness's JSON shape. The tool mapping for Shape A does **not** go
+inline here — it lives in `references/<harness>-tools.md` (Step 4). Get the JSON
+output shape exactly right. `hooks/session-start`
+detects the harness from environment variables and prints *one of three* shapes:
+
+- Cursor (`CURSOR_PLUGIN_ROOT` set): `{ "additional_context": "…" }`
+- Claude Code (`CLAUDE_PLUGIN_ROOT` set, `COPILOT_CLI` unset):
+  `{ "hookSpecificOutput": { "hookEventName": "SessionStart", "additionalContext": "…" } }`
+- Copilot CLI / SDK standard (else): `{ "additionalContext": "…" }`
+
+This is a trap. Emitting the wrong field, or an extra one, means the bootstrap
+either never injects or injects twice (Claude Code reads both
+`additional_context` and `hookSpecificOutput` without de-duplicating, so emitting
+both double-injects). Find the
+exact field, nesting, and event-matcher values your harness expects. Then
+decide: add a fourth branch to `hooks/session-start`, or — if the harness needs
+a different bootstrap message or env contract — add a dedicated
+`hooks/session-start-<harness>` script, the way Codex did. If you add a branch
+and your harness *also* sets an env var an earlier branch keys on (some harnesses
+set `CLAUDE_PLUGIN_ROOT` too), order your branch before the one that would
+otherwise shadow it. Match the harness's
+own event-matcher strings (Claude Code uses `startup|clear|compact`, Codex
+`startup|resume|clear`, Cursor `sessionStart`); wrong matchers mean the hook
+silently never fires.
+
+The **hook-config schema itself varies per harness** — don't assume the
+Claude/Codex shape is universal. Compare `hooks/hooks.json`,
+`hooks/hooks-codex.json`, and `hooks/hooks-cursor.json`: Cursor's uses
+`"version": 1`, a lowercase `sessionStart` key, a relative
+`./hooks/run-hook.cmd` command, and omits the `matcher`/`type`/`async` fields the
+others use. Match your `hooks-<harness>.json` to whichever existing file is
+closest, not to a single canonical template.
+
+The hook **command string references a harness-provided plugin-root variable**,
+and its name differs per harness: `hooks.json` uses `${CLAUDE_PLUGIN_ROOT}`,
+`hooks-codex.json` uses `${PLUGIN_ROOT}`, Cursor uses a relative path. Use
+whatever your harness exports. (The `session-start` script re-derives the root
+itself via `dirname`, so the script body doesn't depend on this — but the
+command in the manifest does.)
+
+**Discovering the harness's contract.** The three facts above — env var, JSON
+field/nesting, matcher strings — are the harness's contract, not Superpowers',
+so you have to source them. Read the harness's hook docs, or find out
+empirically: register a throwaway session-start hook that dumps its environment
+and emits a marker, then observe which env var identifies the harness and
+whether/how the harness ingests your stdout. Pin these down before writing the
+real branch.
+
+**Shape B — assemble the string in code, then inject as a user message.** Here
+you build the bootstrap yourself: read `SKILL.md`, strip its YAML frontmatter,
+and assemble `<EXTREMELY_IMPORTANT>` + a short preamble that the skill is already
+loaded and must not be re-invoked + the stripped body + the inline tool mapping +
+`</EXTREMELY_IMPORTANT>`. One subtlety the references disagree on: OpenCode's
+preamble says "do NOT use the skill tool…" (assumes a `skill` tool exists), while
+pi's just says "do not try to load using-superpowers again." If your harness has
+no skill tool, use pi's wording, not OpenCode's.
+
+Inject the result as a **user-role message, not a system message** — system
+messages bloat tokens when repeated every turn (#750) and multiple system
+messages break some models (#894). Three things you must replicate:
+
+- **Dedup guard.** The lifecycle callback can fire repeatedly (OpenCode's
+  transform runs on *every* agent step; pi's `context` fires per turn). Before
+  injecting, check whether a bootstrap marker is already present and skip if so.
+  (The references pick different markers — pi a custom string, OpenCode the
+  `EXTREMELY_IMPORTANT` tag; matching the tag is more robust since it needs no
+  harness-specific constant.) Cache the bootstrap content at module level so
+  you're not re-reading and re-parsing `SKILL.md` on every call (#1202).
+- **Compaction.** If the harness compacts/summarizes history, re-inject
+  afterward. pi sets an `injectBootstrap` flag on `session_start` and
+  `session_compact`, clears it on `agent_end`, and inserts the message *after*
+  any leading compaction-summary messages. OpenCode relies on its per-step
+  re-injection plus the dedup guard.
+- **Message-object shape is per-harness — discover yours, don't copy a literal.**
+  The two references use *incompatible* shapes: pi builds
+  `{ role, content: [{ type, text }], timestamp }`; OpenCode manipulates
+  `message.info.role` and `message.parts[]`. Find your harness's message shape
+  from its API; copying a reference's object literal verbatim will fail silently.
+
+**Shape C — point your extension's context file at the bootstrap; assemble
+nothing.** There is no injector, so you do *not* strip frontmatter or build a
+wrapped string. The context file your extension ships (declared by the manifest —
+*not* the user's own global file) pulls in two things: the `using-superpowers`
+skill and the harness's tool-mapping reference. `GEMINI.md`
+does this with two `@`-includes (`@./skills/using-superpowers/SKILL.md` and
+`@./skills/using-superpowers/references/<harness>-tools.md`); the harness loads
+them raw, frontmatter and all, and `SKILL.md` already carries its own
+`<EXTREMELY-IMPORTANT>` block internally. If your harness has no include syntax,
+inline the content into the instructions file instead. Gemini ships **no**
+"already loaded, don't re-invoke" preamble — for an `@`-include harness the
+content is the active instruction set, not a skill the model would re-load. If
+you find your harness does try to re-invoke, add that note as a literal line in
+the instructions file (you have no code to add it any other way).
+
+### Step 4 — Write the tool mapping
+
+Translate the action vocabulary into the harness's real tools. Cover every one
+of these actions (omit only what genuinely doesn't apply):
+
+- read a file
+- create / edit / delete a file (one `apply_patch`-style tool, or separate
+  write/edit?)
+- run a shell command
+- search file contents / find files by name (grep, glob)
+- fetch a URL / web search
+- **dispatch a subagent**, including how to pass the agent type — and any config
+  flag needed to enable it
+- **create / update todos** (treat older `TodoWrite` references as this action)
+- **invoke a skill** — see Step 5
+
+**Get the real tool names from the harness; never invent them.** If the docs
+don't list them, the authoritative source is the harness itself: in a live
+session, ask the model to "list the exact machine names of every tool you can
+call, one per line" and use what it reports.
+
+**How the harness finds the `skills/` directory is itself per-harness** — confirm
+it, don't assume. Possibilities: a manifest `skills` path field (Codex's
+`"skills": "./skills/"`); a *co-located* `skills/` the harness auto-scans (where a
+path field is **ignored** — one real harness only scanned a `skills/` sitting next
+to `plugin.json`); an API/registration call (OpenCode, pi); or you stage an
+install dir that pairs the manifest with a **symlink to the repo's `skills/`** and
+point the installer at the staging dir (verify the installer *dereferences* the
+symlink and copies the real files — confirm with `agy plugin validate`/`install`
+or the equivalent before relying on it). A `skills` path field is *not* portable.
+
+Where the mapping lives depends on shape:
+
+- **Shape A:** put it in `skills/using-superpowers/references/<harness>-tools.md`.
+  The agent reaches it from the bootstrap — `SKILL.md`'s "Platform Adaptation"
+  section links the per-harness references files. (Shape A harnesses have no
+  instructions file; the mapping is *not* inlined into the hook output.)
+- **Shape B:** the mapping is typically inlined into the bootstrap string you
+  inject (see the `toolMapping` constant in `superpowers.js`). pi keeps it in
+  *both* places — `piToolMapping()` inline **and** `references/pi-tools.md`. If
+  you maintain it in two places, update both, or the port is half-done.
+- **Shape C:** put it in `references/<harness>-tools.md` and pull it into the
+  always-loaded instructions file (e.g. `GEMINI.md` `@`-includes
+  `gemini-tools.md`).
+
+You may also add a one-line pointer to your harness in `SKILL.md`'s "Platform
+Adaptation" section so an agent reading the bootstrap knows where its mapping
+lives. This is the one edit to a `SKILL.md` a port may make — and only because
+that section is a pointer list, not behavior-shaping content. It does not violate
+the "don't edit skill bodies" rule (Part 1); do not touch anything else in any
+skill. (The list is a convenience pointer, not an exhaustive registry — not every
+harness is listed.)
+
+### Step 5 — Handle a harness with no native skill tool
+
+`using-superpowers/SKILL.md` tells the model to *never read skill files manually
+with file tools — always use your platform's skill-loading mechanism.* The point
+is "don't bypass the mechanism," not "never use file-read." What counts as "your
+platform's mechanism" depends on the harness — and for a harness with no skill
+tool, the documented mechanism *is* reading `SKILL.md`. So reading it there
+honors the rule rather than breaking it. Distinguish three cases:
+
+1. **Native `Skill`-style tool** (Claude Code, Copilot CLI, Gemini's
+   `activate_skill`): point the mapping at that tool.
+2. **Native skill *discovery* but no `Skill` tool** (pi, Antigravity): the harness
+   can find and list skills, but the model can't call a tool to load one. Get the
+   skills installed where the harness scans (pi registers via `resources_discover`
+   → `skillPaths`; OpenCode via its `config` hook; `agy plugin install` copies
+   them in), and tell the model to load a skill by **reading its `SKILL.md` with
+   the file-read tool when the skill applies** — the sanctioned mechanism here,
+   the way `references/pi-tools.md` states it.
+
+   **For the bootstrap itself, prefer a declared context file (Part 6).** If the
+   harness has a `contextFileName`-style manifest field — as Antigravity does —
+   ship a generated context file through the installer: it's guaranteed-loaded and
+   carries both the `using-superpowers` content and the tool mapping. That is the
+   strong, preferred path.
+
+   **Fallback — the surfaced skill index.** If there's no context-file field but
+   the harness surfaces each installed skill's name + description at session start,
+   you need *neither* a built index nor a runtime-list instruction — the harness
+   is the index, and `using-superpowers`'s own surfaced description can be what
+   triggers the model to load it. This is softer than a declared context file;
+   two things it does **not** give you, versus a context file / hook / in-process
+   injector — account for both:
+   - **It bootstraps *triggering*, not the *tool mapping*.** An injector prepends
+     `<harness>-tools.md` alongside `using-superpowers` every session. Here nothing
+     injects the mapping — the model only sees skill *descriptions* and must *read*
+     your `references/<harness>-tools.md` when it needs tool names. It works
+     because skills name actions (the model reads the mapping when it acts), but
+     it's softer than injection. Make sure the mapping is reachable from what the
+     model loads — e.g. linked from `SKILL.md`'s Platform Adaptation section and
+     installed alongside the skills — not just sitting in the repo.
+   - **There's no structural guarantee the trigger fires.** No `<EXTREMELY_IMPORTANT>`
+     wrapper, no dedup, no re-injection after compaction — firing depends on the
+     model choosing to act on a description it sees in the index. This is exactly
+     why the acceptance test is mandatory here: it is the *only* guarantee, so run
+     it on the model(s) your users will actually use, not just the strongest one.
+3. **No skill system at all:** there is nothing to register, and the *only*
+   mechanism is the model reading `SKILL.md` on demand. But the model can't read
+   what it can't find: `using-superpowers/SKILL.md` does **not** enumerate the
+   available skills, so on its own the model won't know which skills exist or
+   their triggers. You must supply a discovery path. Two options, and they differ
+   in durability: (a) generate a skill index (each `skills/*/SKILL.md`'s `name` +
+   `description` frontmatter) and place it *inside* the `<EXTREMELY_IMPORTANT>`
+   wrapper alongside the tool mapping (Shape B recipe above) so it's covered by
+   the dedup guard — but a build-time index goes stale as skills are added; or
+   (b) instruct the model to list `skills/*/SKILL.md` at runtime and read their
+   frontmatter to find a match — slower but never stale. Prefer (b) unless you
+   have a reason not to. Without either, a no-skill-system port loads the
+   bootstrap but silently never triggers any other skill.
+
+In cases 2 and 3, say plainly in your tool mapping that reading `SKILL.md` is the
+blessed path, so the model doesn't think it's violating the "never read skill
+files" rule. Don't go hunting for a `skillPaths`-style registration API in a
+harness that has no skill system — case 3 has none.
+
+### Step 6 — Add tests
+
+Match the existing per-harness test style:
+
+- **Shape A:** assert the hook's stdout has the exact JSON shape your harness
+  consumes, and that it contains the bootstrap. See `tests/hooks/test-session-start.sh`,
+  which validates each harness's output shape.
+- **Shape B:** a unit test that fakes the harness's plugin API and asserts the
+  lifecycle handlers register, the bootstrap injects once, the dedup guard
+  works, and (if relevant) compaction re-injection works. See
+  `tests/pi/test-pi-extension.mjs`. Add an isolated-install integration check in
+  the style of `tests/opencode/`.
+- If the bootstrap is cached, test that the cache behaves when the file is
+  missing (see the OpenCode caching tests).
+
+These automated tests cover the wiring; the live tmux run in Step 7 is what
+proves the integration actually triggers skills.
+
+### Step 7 — Install locally, then drive a live instance to verify
+
+You cannot confirm a port works by reading code. You have to run the harness with
+your in-progress port loaded and watch a real session — which is also how you
+produce the transcript the PR requires.
+
+**Install locally.** Point a *local* instance of the harness at your working
+tree, not a published build:
+
+- **Shape A / C:** install the plugin/extension from this repo's local path (or
+  symlink its directory into wherever the harness looks). Find the harness's
+  "install from a local directory / git checkout" path in its docs.
+- **Shape B:** register the local module — e.g. an `opencode.json` `plugin`
+  entry pointing at the local path, or pi resolving the `package.json` fields
+  from the repo.
+
+Reinstall after each change and restart the harness, since the bootstrap loads at
+startup.
+
+**Drive it with tmux.** Most harnesses are interactive REPLs/TUIs that can't be
+driven by piping stdin, so run the harness inside a detached tmux session and
+control it with `send-keys` / `capture-pane`. A harness may advertise a
+non-interactive "run one prompt" mode (e.g. `opencode run "..."`) — try it for the
+quick smoke check, but **don't depend on it**: these modes are frequently flaky,
+auth-gated, or trust-gated (one real harness's `--print` mode hung and timed out
+with no output every time). Be ready to do *everything*, including the smoke
+check, through tmux.
+
+**Clear the gates first, or tmux stalls silently.** Many harnesses block on
+first-run onboarding, a "do you trust this folder?" prompt, a sandbox mode, or a
+permission gate — and a detached tmux session will just sit there with no error
+while it waits. Before the run, pre-trust your scratch directory (in the harness's
+settings/config) or be prepared to answer those prompts via `send-keys`, and
+account for the harness's startup time in your first `sleep`.
+
+```bash
+# 1. Launch the harness detached, in a throwaway project dir
+mkdir -p /tmp/port-smoke
+tmux new-session -d -s port-test -c /tmp/port-smoke '<harness-launch-command>'
+
+# 2. Let it initialize — real TUIs take longer than you think (10s+ with a model
+#    handshake); tune this. THEN capture and clear any blocking modal before you
+#    type a prompt: first-run onboarding and "trust this folder?" are modal, so
+#    keystrokes sent during them select menu items instead of typing your prompt.
+sleep 12
+tmux capture-pane -t port-test -p          # onboarding / trust prompt? answer it via send-keys first
+# (e.g. tmux send-keys -t port-test Enter   # to accept a trust prompt — inspect before assuming)
+
+# 3. Smoke check: does the model know it has superpowers?
+#    Send the text and Enter as SEPARATE send-keys with a beat between them —
+#    sending them together races on some TUIs (Enter arrives before the text lands).
+tmux send-keys -t port-test 'What are your superpowers?'; sleep 0.4; tmux send-keys -t port-test Enter
+sleep 5
+tmux capture-pane -t port-test -p          # reply should show it knows its skills
+
+# 4. Acceptance test: exact prompt (note the escaped apostrophe), fresh session
+tmux send-keys -t port-test 'Let'\''s make a react todo list'; sleep 0.4; tmux send-keys -t port-test Enter
+# poll until the turn finishes — re-capture every few seconds, don't capture once
+sleep 8
+tmux capture-pane -t port-test -p          # PASS = brainstorming triggers BEFORE any code
+
+# 5. Save the transcript for the PR, then clean up
+tmux capture-pane -t port-test -p > /tmp/port-smoke/transcript.txt
+tmux kill-session -t port-test
+```
+
+tmux gotchas that bite here: wait after launch before the first capture; send the
+prompt text and `Enter` as *separate* `send-keys` calls with a short `sleep`
+between them (sending them together races on some TUIs), and `Enter` is a key name
+not `\n`; the agent's turn takes time, so **poll `capture-pane` in a loop** rather
+than capturing once; `capture-pane` shows only the visible pane, so for a long
+conversation use the harness's own transcript/log file as the record of truth;
+always `kill-session` when done.
+
+If the smoke check shows the model *doesn't* know it has superpowers, the
+bootstrap isn't loading — fix that before bothering with the acceptance test.
+
+---
+
+## Part 6 — Distribution and release
+
+A working integration in this repo isn't usable until a real user can install
+it. Distribution differs per harness ecosystem — find yours:
+
+| Channel | Example | What you do |
+|---|---|---|
+| Native plugin marketplace | Claude Code | Register in `.claude-plugin/marketplace.json`; users `/plugin install`. The external `superpowers-marketplace` repo is the source of truth users install from — see the release steps in `CLAUDE.md`. |
+| External marketplace fork, synced by script | Codex | `scripts/sync-to-codex-plugin.sh` rsyncs the tracked plugin files into a separate fork repo and opens a PR. Read its include/exclude list so you ship the right tree (it deliberately drops repo-internal dirs and other harnesses' dotdirs). |
+| Git-URL extension install | Gemini, Kimi Code, OpenCode | Users install from a git URL (`gemini extensions install …`; Kimi Code `/plugins install …`; an `opencode.json` `plugin` array entry). Document the exact command. |
+| Package-manifest fields | pi | Declared through fields in the repo-root `package.json`; users install via the harness's package command. |
+| Local installer (plugin install) | Antigravity (`agy`) | A small `install.sh` that runs the harness's own `agy plugin install` against a staging dir holding the manifest, the skills, and a generated `contextFileName` context file (the bootstrap). Everything arrives through the install mechanism — *not* by editing the user's config (see below). |
+
+Then:
+
+- **A plugin installer may silently strip *undeclared* files — so make the
+  bootstrap a file the installer *recognizes*, never a user-config edit.** A
+  `plugin install` typically copies only the components it knows about
+  (skills/agents/commands/mcp/hooks/context) and discards anything else, so a
+  context file the manifest doesn't declare just vanishes from the install. The
+  fix is **not** to give up and write into the user's config (**rule 2**) — it's
+  to declare the bootstrap as a recognized component. In escalation order:
+  - **Ship a context file the manifest declares.** If the harness has a
+    `contextFileName`-style field (an extension-declared file it loads every
+    session), that is the strongest clean bootstrap: declare it, and the installer
+    preserves it *and* the harness loads it. Generate it at install time from the
+    live `using-superpowers/SKILL.md` + the tool mapping (wrapped in
+    `<EXTREMELY_IMPORTANT>`) so the installed bootstrap never drifts. This is what
+    `.antigravity-plugin/install.sh` does — `agy plugin install` reports
+    `✔ context : ANTIGRAVITY.md`, and a clean session reads `using-superpowers`'s
+    SKILL.md, loads `brainstorming`, and enters the brainstorming flow before any
+    code. **Verify with a marker** that the installer keeps the file and the
+    harness loads it: one porter wrongly concluded it couldn't, because they
+    shipped the file *without* declaring `contextFileName` and it was stripped as
+    unrecognized.
+  - **Otherwise lean on the installed `using-superpowers` skill itself.** If the
+    harness surfaces each installed skill's name + description at session start,
+    the `using-superpowers` description ("Use when starting any conversation…")
+    can prompt the model to load it — installing the skill *is* the bootstrap.
+    Softer (no guaranteed wrapper; it carries triggering but not the tool mapping
+    — see Step 5), so prefer the declared context file when available.
+  - If neither works, the harness cannot be cleanly supported yet — **say so**
+    and raise it, rather than hand-editing the user's config.
+
+- **Write install docs.** A `docs/README.<harness>.md` and/or a
+  `.<harness>/INSTALL.md` (see `docs/README.opencode.md` and
+  `.opencode/INSTALL.md`), plus an install section in the top-level `README.md`.
+  The only supported install action is **running the harness's own install
+  command** (`agy plugin install`, `gemini extensions install`, `/plugin
+  install`, etc.). Hand-copying skill files and editing the user's global/personal
+  config are *both* off-limits (rule 2 / the PR rules). If the harness has no
+  install command at all — its only surface is a user-owned config file — then it
+  fails the "deliver via install mechanism" rule, and you should raise that rather
+  than ship an installer that edits the user's files.
+- **Register the version.** If your harness introduces a *new* versioned
+  manifest, add its path and version field to `.version-bump.json` so
+  `scripts/bump-version.sh` keeps it in lockstep (read that file to see what's
+  currently tracked). A new manifest that isn't registered there will ship a
+  stale version. If your harness instead rides an already-tracked file — pi
+  declares itself in the repo-root `package.json`, which is already listed —
+  there's nothing new to add.
+- **If no existing channel fits, you're standing up a new one.** None of the four
+  rows may match your harness. If it needs a Codex-style external fork sync,
+  `scripts/sync-to-codex-plugin.sh` is the template to clone (note its anchored
+  include/exclude list and its PR automation). And whenever you add a new
+  per-harness directory, add it to the *other* harnesses' sync excludes (e.g. the
+  EXCLUDES list in `sync-to-codex-plugin.sh`) so your dotdir doesn't leak into
+  their distributions.
+
+---
+
+## Part 7 — Cross-platform / Windows
+
+Only relevant to the shell-hook shape. `hooks/run-hook.cmd` is a polyglot: a
+single file that's valid as both a Windows batch script and a Unix shell script.
+On Windows, `cmd.exe` runs the batch portion, which locates `bash` (Git for
+Windows, then `bash` on PATH) and runs the named hook script; if no bash is
+found it exits cleanly so the harness still works, just without injection. On
+Unix, the leading `:` makes the batch block a no-op and the shell runs the
+script directly.
+
+Two rules this enforces, which you must respect:
+
+- **Hook scripts are extensionless** (`session-start`, not `session-start.sh`).
+  Claude Code's Windows handling prepends `bash` to any command containing
+  `.sh`, which would double-invoke. Name your hook script without an extension.
+- Don't write per-OS variants of the hook script. One extensionless bash script
+  plus the polyglot wrapper covers all three platforms.
+
+`hooks/run-hook.cmd` itself is the authoritative implementation — read it. See
+`docs/windows/polyglot-hooks.md` for the background and rationale behind the
+dispatcher pattern.
+
+---
+
+## Part 8 — Submitting the PR
+
+- Target the **`dev`** branch. One harness per PR.
+- Fill in the PR template's **"New harness support"** section and paste the
+  complete acceptance-test transcript (the "Let's make a react todo list"
+  session showing `brainstorming` auto-triggering). A PR without this proof will
+  be closed.
+- Superpowers is a zero-dependency plugin. Don't add a third-party runtime
+  dependency. Adding a new harness is the one carve-out the contributor rules
+  allow, and even then keep it to what the integration strictly requires —
+  type-only imports that compile away are fine; runtime packages are not.
+- Don't touch skill bodies (Part 1). If you found yourself editing a `SKILL.md`
+  to make the port work, the fix belongs in your tool mapping instead.
+
+---
+
+## Appendix A — Reference integrations (current)
+
+Use this as the live index; when in doubt, read the files, not this table.
+
+| Harness | Entry point | Bootstrap mechanism | Tool mapping | Tests | Distribution |
+|---|---|---|---|---|---|
+| Claude Code | `.claude-plugin/plugin.json` + `hooks/hooks.json` | shell hook → `hooks/session-start` (`hookSpecificOutput.additionalContext`) | native `Skill` tool; `references/claude-code-tools.md` | `tests/hooks/` | marketplace |
+| Codex | `.codex-plugin/plugin.json` + `hooks/hooks-codex.json` | shell hook → `hooks/session-start-codex` | `references/codex-tools.md` | `tests/codex-plugin-sync/`, `tests/hooks/` | fork sync (`scripts/sync-to-codex-plugin.sh`) |
+| Cursor | `.cursor-plugin/plugin.json` + `hooks/hooks-cursor.json` | shell hook → `hooks/session-start` (`additional_context`) | `references/claude-code-tools.md` | `tests/hooks/` | hand-authored |
+| Copilot CLI | (shares Claude Code hook path; `COPILOT_CLI` env) | shell hook → `hooks/session-start` (`additionalContext`) | `references/copilot-tools.md` | `tests/hooks/` | — |
+| Gemini CLI | `gemini-extension.json` + `GEMINI.md` | instructions file `@`-includes bootstrap + mapping | `references/gemini-tools.md` | — | `gemini extensions install` |
+| Kimi Code | `.kimi-plugin/plugin.json` | manifest `sessionStart.skill` loads `using-superpowers` | inline `skillInstructions` in manifest | `tests/kimi/` | marketplace or `/plugins install` GitHub URL |
+| OpenCode | `.opencode/plugins/superpowers.js` (declared via root `package.json` `main`) | in-process: `config` hook registers skills dir; `experimental.chat.messages.transform` injects user message | inline in `superpowers.js` | `tests/opencode/` | `opencode.json` plugin git URL |
+| pi | `.pi/extensions/superpowers.ts` | in-process: `resources_discover` registers skills; `context` event injects user message; lifecycle-flag + compaction-aware | `piToolMapping()` inline **and** `references/pi-tools.md` | `tests/pi/` | repo-root `package.json` fields |
+
+## Appendix B — Gotchas that have bitten porters
+
+- **Opt-in isn't a port.** If your human partner has to do anything per session
+  to get Superpowers, the acceptance test fails. Re-read Part 2.
+- **Wrong JSON field → silent failure or double injection.** Shape A only.
+  Confirm the exact field/nesting; Claude Code reads two fields without dedup.
+- **Hook-config schema varies per harness.** Shape A. Cursor's `hooks-cursor.json`
+  looks nothing like the Claude/Codex one (`version`, lowercase `sessionStart`,
+  relative command, no `matcher`/`type`/`async`). Match the closest existing file.
+- **Plugin-root env var differs per harness.** Shape A. The hook command uses
+  `${CLAUDE_PLUGIN_ROOT}` (Claude), `${PLUGIN_ROOT}` (Codex), or a relative path
+  (Cursor). Use what your harness exports; the script re-derives the root itself.
+- **System-message injection.** Shape B injects a *user* message on purpose
+  (#750, #894). Don't "fix" it to a system message.
+- **Per-step vs per-turn callbacks.** OpenCode fires every step (per-call dedup
+  guard); pi fires per turn (lifecycle flag + `agent_end` reset). Copying one
+  harness's dedup strategy onto the other's callback frequency breaks injection.
+- **Message-object shape is per-harness.** Shape B. pi and OpenCode use
+  incompatible shapes; discover yours, don't copy a reference's object literal.
+- **Hunting for a skill-registration API that doesn't exist.** A harness with no
+  skill system (not just no `Skill` tool) has nothing to register — the model
+  reads `SKILL.md` on demand. Don't assume a `skillPaths` equivalent exists.
+- **Mapping in two places.** For in-process plugins the mapping may live both
+  inline and in a `references/` file (pi). Update both.
+- **The "never read skill files" line.** It means "don't bypass your platform's
+  skill-loading mechanism," not "never use file-read." On a no-skill-tool harness
+  that mechanism *is* reading `SKILL.md` — say so explicitly in the mapping
+  (Part 5).
+- **`.sh` on Windows.** Keep hook scripts extensionless (Part 7).
+- **Unregistered version.** A new manifest not added to `.version-bump.json`
+  ships stale (Part 6).
+- **Editing skills to fit the harness.** Never. The fix goes in the tool mapping.

docs/superpowers/plans/2026-01-22-document-review-system.md

@@ -0,0 +1,301 @@
+# Document Review System Implementation Plan
+
+> **For agentic workers:** REQUIRED: Use superpowers:subagent-driven-development (if subagents available) or superpowers:executing-plans to implement this plan.
+
+**Goal:** Add spec and plan document review loops to the brainstorming and writing-plans skills.
+
+**Architecture:** Create reviewer prompt templates in each skill directory. Modify skill files to add review loops after document creation. Use Task tool with general-purpose subagent for reviewer dispatch.
+
+**Tech Stack:** Markdown skill files, subagent dispatch via Task tool
+
+**Spec:** docs/superpowers/specs/2026-01-22-document-review-system-design.md
+
+---
+
+## Chunk 1: Spec Document Reviewer
+
+This chunk adds the spec document reviewer to the brainstorming skill.
+
+### Task 1: Create Spec Document Reviewer Prompt Template
+
+**Files:**
+- Create: `skills/brainstorming/spec-document-reviewer-prompt.md`
+
+- [ ] **Step 1:** Create the reviewer prompt template file
+
+```markdown
+# Spec Document Reviewer Prompt Template
+
+Use this template when dispatching a spec document reviewer subagent.
+
+**Purpose:** Verify the spec is complete, consistent, and ready for implementation planning.
+
+**Dispatch after:** Spec document is written to docs/superpowers/specs/
+
+```
+Task tool (general-purpose):
+  description: "Review spec document"
+  prompt: |
+    You are a spec document reviewer. Verify this spec is complete and ready for planning.
+
+    **Spec to review:** [SPEC_FILE_PATH]
+
+    ## What to Check
+
+    | Category | What to Look For |
+    |----------|------------------|
+    | Completeness | TODOs, placeholders, "TBD", incomplete sections |
+    | Coverage | Missing error handling, edge cases, integration points |
+    | Consistency | Internal contradictions, conflicting requirements |
+    | Clarity | Ambiguous requirements |
+    | YAGNI | Unrequested features, over-engineering |
+
+    ## CRITICAL
+
+    Look especially hard for:
+    - Any TODO markers or placeholder text
+    - Sections saying "to be defined later" or "will spec when X is done"
+    - Sections noticeably less detailed than others
+
+    ## Output Format
+
+    ## Spec Review
+
+    **Status:** ✅ Approved | ❌ Issues Found
+
+    **Issues (if any):**
+    - [Section X]: [specific issue] - [why it matters]
+
+    **Recommendations (advisory):**
+    - [suggestions that don't block approval]
+```
+
+**Reviewer returns:** Status, Issues (if any), Recommendations
+```
+
+- [ ] **Step 2:** Verify the file was created correctly
+
+Run: `cat skills/brainstorming/spec-document-reviewer-prompt.md | head -20`
+Expected: Shows the header and purpose section
+
+- [ ] **Step 3:** Commit
+
+```bash
+git add skills/brainstorming/spec-document-reviewer-prompt.md
+git commit -m "feat: add spec document reviewer prompt template"
+```
+
+---
+
+### Task 2: Add Review Loop to Brainstorming Skill
+
+**Files:**
+- Modify: `skills/brainstorming/SKILL.md`
+
+- [ ] **Step 1:** Read the current brainstorming skill
+
+Run: `cat skills/brainstorming/SKILL.md`
+
+- [ ] **Step 2:** Add the review loop section after "After the Design"
+
+Find the "After the Design" section and add a new "Spec Review Loop" section after documentation but before implementation:
+
+```markdown
+**Spec Review Loop:**
+After writing the spec document:
+1. Dispatch spec-document-reviewer subagent (see spec-document-reviewer-prompt.md)
+2. If ❌ Issues Found:
+   - Fix the issues in the spec document
+   - Re-dispatch reviewer
+   - Repeat until ✅ Approved
+3. If ✅ Approved: proceed to implementation setup
+
+**Review loop guidance:**
+- Same agent that wrote the spec 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
+```
+
+- [ ] **Step 3:** Verify the changes
+
+Run: `grep -A 15 "Spec Review Loop" skills/brainstorming/SKILL.md`
+Expected: Shows the new review loop section
+
+- [ ] **Step 4:** Commit
+
+```bash
+git add skills/brainstorming/SKILL.md
+git commit -m "feat: add spec review loop to brainstorming skill"
+```
+
+---
+
+## Chunk 2: Plan Document Reviewer
+
+This chunk adds the plan document reviewer to the writing-plans skill.
+
+### Task 3: Create Plan Document Reviewer Prompt Template
+
+**Files:**
+- Create: `skills/writing-plans/plan-document-reviewer-prompt.md`
+
+- [ ] **Step 1:** Create the reviewer prompt template file
+
+```markdown
+# Plan Document Reviewer Prompt Template
+
+Use this template when dispatching a plan document reviewer subagent.
+
+**Purpose:** Verify the plan chunk is complete, matches the spec, and has proper task decomposition.
+
+**Dispatch after:** Each plan chunk is written
+
+```
+Task tool (general-purpose):
+  description: "Review plan chunk N"
+  prompt: |
+    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
+    **Spec for reference:** [SPEC_FILE_PATH]
+
+    ## What to Check
+
+    | Category | What to Look For |
+    |----------|------------------|
+    | Completeness | TODOs, placeholders, incomplete tasks, missing steps |
+    | Spec Alignment | Chunk covers relevant spec requirements, no scope creep |
+    | Task Decomposition | Tasks atomic, clear boundaries, steps actionable |
+    | Task Syntax | Checkbox syntax (`- [ ]`) on tasks and steps |
+    | Chunk Size | Each chunk under 1000 lines |
+
+    ## CRITICAL
+
+    Look especially hard for:
+    - Any TODO markers or placeholder text
+    - Steps that say "similar to X" without actual content
+    - Incomplete task definitions
+    - Missing verification steps or expected outputs
+
+    ## Output Format
+
+    ## Plan Review - Chunk N
+
+    **Status:** ✅ Approved | ❌ Issues Found
+
+    **Issues (if any):**
+    - [Task X, Step Y]: [specific issue] - [why it matters]
+
+    **Recommendations (advisory):**
+    - [suggestions that don't block approval]
+```
+
+**Reviewer returns:** Status, Issues (if any), Recommendations
+```
+
+- [ ] **Step 2:** Verify the file was created
+
+Run: `cat skills/writing-plans/plan-document-reviewer-prompt.md | head -20`
+Expected: Shows the header and purpose section
+
+- [ ] **Step 3:** Commit
+
+```bash
+git add skills/writing-plans/plan-document-reviewer-prompt.md
+git commit -m "feat: add plan document reviewer prompt template"
+```
+
+---
+
+### Task 4: Add Review Loop to Writing-Plans Skill
+
+**Files:**
+- Modify: `skills/writing-plans/SKILL.md`
+
+- [ ] **Step 1:** Read current skill file
+
+Run: `cat skills/writing-plans/SKILL.md`
+
+- [ ] **Step 2:** Add chunk-by-chunk review section
+
+Add before the "Execution Handoff" section:
+
+```markdown
+## Plan Review Loop
+
+After completing each chunk of the plan:
+
+1. Dispatch plan-document-reviewer subagent for the current chunk
+   - Provide: chunk content, path to spec document
+2. If ❌ Issues Found:
+   - Fix the issues in the chunk
+   - Re-dispatch reviewer for that chunk
+   - Repeat until ✅ Approved
+3. If ✅ Approved: proceed to next chunk (or execution handoff if last chunk)
+
+**Chunk boundaries:** Use `## Chunk N: <name>` headings to delimit chunks. Each chunk should be ≤1000 lines and logically self-contained.
+```
+
+- [ ] **Step 3:** Update task syntax examples to use checkboxes
+
+Change the Task Structure section to show checkbox syntax:
+
+```markdown
+### Task N: [Component Name]
+
+- [ ] **Step 1:** Write the failing test
+  - File: `tests/path/test.py`
+  ...
+```
+
+- [ ] **Step 4:** Verify the review loop section was added
+
+Run: `grep -A 15 "Plan Review Loop" skills/writing-plans/SKILL.md`
+Expected: Shows the new review loop section
+
+- [ ] **Step 5:** Verify the task syntax examples were updated
+
+Run: `grep -A 5 "Task N:" skills/writing-plans/SKILL.md`
+Expected: Shows checkbox syntax `### Task N:`
+
+- [ ] **Step 6:** Commit
+
+```bash
+git add skills/writing-plans/SKILL.md
+git commit -m "feat: add plan review loop and checkbox syntax to writing-plans skill"
+```
+
+---
+
+## Chunk 3: Update Plan Document Header
+
+This chunk updates the plan document header template to reference the new checkbox syntax requirements.
+
+### Task 5: Update Plan Header Template in Writing-Plans Skill
+
+**Files:**
+- Modify: `skills/writing-plans/SKILL.md`
+
+- [ ] **Step 1:** Read current plan header template
+
+Run: `grep -A 20 "Plan Document Header" skills/writing-plans/SKILL.md`
+
+- [ ] **Step 2:** Update the header template to reference checkbox syntax
+
+The plan header should note that tasks and steps use checkbox syntax. Update the header comment:
+
+```markdown
+> **For agentic workers:** REQUIRED: Use superpowers:subagent-driven-development (if subagents available) or superpowers:executing-plans to implement this plan. Tasks and steps use checkbox (`- [ ]`) syntax for tracking.
+```
+
+- [ ] **Step 3:** Verify the change
+
+Run: `grep -A 5 "For agentic workers:" skills/writing-plans/SKILL.md`
+Expected: Shows updated header with checkbox syntax mention
+
+- [ ] **Step 4:** Commit
+
+```bash
+git add skills/writing-plans/SKILL.md
+git commit -m "docs: update plan header to reference checkbox syntax"
+```

docs/superpowers/plans/2026-02-19-visual-brainstorming-refactor.md

@@ -0,0 +1,523 @@
+# Visual Brainstorming Refactor Implementation Plan
+
+> **For agentic workers:** REQUIRED: Use superpowers:subagent-driven-development (if subagents available) or superpowers:executing-plans to implement this plan. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Refactor visual brainstorming from blocking TUI feedback model to non-blocking "Browser Displays, Terminal Commands" architecture.
+
+**Architecture:** Browser becomes an interactive display; terminal stays the conversation channel. Server writes user events to a per-screen `.events` file that Claude reads on its next turn. Eliminates `wait-for-feedback.sh` and all `TaskOutput` blocking.
+
+**Tech Stack:** Node.js (Express, ws, chokidar), vanilla HTML/CSS/JS
+
+**Spec:** `docs/superpowers/specs/2026-02-19-visual-brainstorming-refactor-design.md`
+
+---
+
+## File Map
+
+| File | Action | Responsibility |
+|------|--------|---------------|
+| `lib/brainstorm-server/index.js` | Modify | Server: add `.events` file writing, clear on new screen, replace `wrapInFrame` |
+| `lib/brainstorm-server/frame-template.html` | Modify | Template: remove feedback footer, add content placeholder + selection indicator |
+| `lib/brainstorm-server/helper.js` | Modify | Client JS: remove send/feedback functions, narrow to click capture + indicator updates |
+| `lib/brainstorm-server/wait-for-feedback.sh` | Delete | No longer needed |
+| `skills/brainstorming/visual-companion.md` | Modify | Skill instructions: rewrite loop to non-blocking flow |
+| `tests/brainstorm-server/server.test.js` | Modify | Tests: update for new template structure and helper.js API |
+
+---
+
+## Chunk 1: Server, Template, Client, Tests, Skill
+
+### Task 1: Update `frame-template.html`
+
+**Files:**
+- Modify: `lib/brainstorm-server/frame-template.html`
+
+- [ ] **Step 1: Remove the feedback footer HTML**
+
+Replace the feedback-footer div (lines 227-233) with a selection indicator bar:
+
+```html
+  <div class="indicator-bar">
+    <span id="indicator-text">Click an option above, then return to the terminal</span>
+  </div>
+```
+
+Also replace the default content inside `#claude-content` (lines 220-223) with the content placeholder:
+
+```html
+    <div id="claude-content">
+      <!-- CONTENT -->
+    </div>
+```
+
+- [ ] **Step 2: Replace feedback footer CSS with indicator bar CSS**
+
+Remove the `.feedback-footer`, `.feedback-footer label`, `.feedback-row`, and the textarea/button styles within `.feedback-footer` (lines 82-112).
+
+Add indicator bar CSS:
+
+```css
+    .indicator-bar {
+      background: var(--bg-secondary);
+      border-top: 1px solid var(--border);
+      padding: 0.5rem 1.5rem;
+      flex-shrink: 0;
+      text-align: center;
+    }
+    .indicator-bar span {
+      font-size: 0.75rem;
+      color: var(--text-secondary);
+    }
+    .indicator-bar .selected-text {
+      color: var(--accent);
+      font-weight: 500;
+    }
+```
+
+- [ ] **Step 3: Verify template renders**
+
+Run the test suite to check the template still loads:
+```bash
+cd /Users/drewritter/prime-rad/superpowers && node tests/brainstorm-server/server.test.js
+```
+Expected: Tests 1-5 should still pass. Tests 6-8 may fail (expected — they assert old structure).
+
+- [ ] **Step 4: Commit**
+
+```bash
+git add lib/brainstorm-server/frame-template.html
+git commit -m "Replace feedback footer with selection indicator bar in brainstorm template"
+```
+
+---
+
+### Task 2: Update `index.js` — content injection and `.events` file
+
+**Files:**
+- Modify: `lib/brainstorm-server/index.js`
+
+- [ ] **Step 1: Write failing test for `.events` file writing**
+
+Add to `tests/brainstorm-server/server.test.js` after Test 4 area — a new test that sends a WebSocket event with a `choice` field and verifies `.events` file is written:
+
+```javascript
+    // Test: Choice events written to .events file
+    console.log('Test: Choice events written to .events file');
+    const ws3 = new WebSocket(`ws://localhost:${TEST_PORT}`);
+    await new Promise(resolve => ws3.on('open', resolve));
+
+    ws3.send(JSON.stringify({ type: 'click', choice: 'a', text: 'Option A' }));
+    await sleep(300);
+
+    const eventsFile = path.join(TEST_DIR, '.events');
+    assert(fs.existsSync(eventsFile), '.events file should exist after choice click');
+    const lines = fs.readFileSync(eventsFile, 'utf-8').trim().split('\n');
+    const event = JSON.parse(lines[lines.length - 1]);
+    assert.strictEqual(event.choice, 'a', 'Event should contain choice');
+    assert.strictEqual(event.text, 'Option A', 'Event should contain text');
+    ws3.close();
+    console.log('  PASS');
+```
+
+- [ ] **Step 2: Run test to verify it fails**
+
+```bash
+cd /Users/drewritter/prime-rad/superpowers && node tests/brainstorm-server/server.test.js
+```
+Expected: New test FAILS — `.events` file doesn't exist yet.
+
+- [ ] **Step 3: Write failing test for `.events` file clearing on new screen**
+
+Add another test:
+
+```javascript
+    // Test: .events cleared on new screen
+    console.log('Test: .events cleared on new screen');
+    // .events file should still exist from previous test
+    assert(fs.existsSync(path.join(TEST_DIR, '.events')), '.events should exist before new screen');
+    fs.writeFileSync(path.join(TEST_DIR, 'new-screen.html'), '<h2>New screen</h2>');
+    await sleep(500);
+    assert(!fs.existsSync(path.join(TEST_DIR, '.events')), '.events should be cleared after new screen');
+    console.log('  PASS');
+```
+
+- [ ] **Step 4: Run test to verify it fails**
+
+```bash
+cd /Users/drewritter/prime-rad/superpowers && node tests/brainstorm-server/server.test.js
+```
+Expected: New test FAILS — `.events` not cleared on screen push.
+
+- [ ] **Step 5: Implement `.events` file writing in `index.js`**
+
+In the WebSocket `message` handler (line 74-77 of `index.js`), after the `console.log`, add:
+
+```javascript
+    // Write user events to .events file for Claude to read
+    if (event.choice) {
+      const eventsFile = path.join(SCREEN_DIR, '.events');
+      fs.appendFileSync(eventsFile, JSON.stringify(event) + '\n');
+    }
+```
+
+In the chokidar `add` handler (line 104-111), add `.events` clearing:
+
+```javascript
+    if (filePath.endsWith('.html')) {
+      // Clear events from previous screen
+      const eventsFile = path.join(SCREEN_DIR, '.events');
+      if (fs.existsSync(eventsFile)) fs.unlinkSync(eventsFile);
+
+      console.log(JSON.stringify({ type: 'screen-added', file: filePath }));
+      // ... existing reload broadcast
+    }
+```
+
+- [ ] **Step 6: Replace `wrapInFrame` with comment placeholder injection**
+
+Replace the `wrapInFrame` function (lines 27-32 of `index.js`):
+
+```javascript
+function wrapInFrame(content) {
+  return frameTemplate.replace('<!-- CONTENT -->', content);
+}
+```
+
+- [ ] **Step 7: Run all tests**
+
+```bash
+cd /Users/drewritter/prime-rad/superpowers && node tests/brainstorm-server/server.test.js
+```
+Expected: New `.events` tests PASS. Existing tests may still have failures from old assertions (fixed in Task 4).
+
+- [ ] **Step 8: Commit**
+
+```bash
+git add lib/brainstorm-server/index.js tests/brainstorm-server/server.test.js
+git commit -m "Add .events file writing and comment-based content injection to brainstorm server"
+```
+
+---
+
+### Task 3: Simplify `helper.js`
+
+**Files:**
+- Modify: `lib/brainstorm-server/helper.js`
+
+- [ ] **Step 1: Remove `sendToClaude` function**
+
+Delete the `sendToClaude` function (lines 92-106) — the function body and the page takeover HTML.
+
+- [ ] **Step 2: Remove `window.send` function**
+
+Delete the `window.send` function (lines 120-129) — was tied to the removed Send button.
+
+- [ ] **Step 3: Remove form submission and input change handlers**
+
+Delete the form submission handler (lines 57-71) and the input change handler (lines 73-89) including the `inputTimeout` variable.
+
+- [ ] **Step 4: Remove `pageshow` event listener**
+
+Delete the `pageshow` listener we added earlier (no textarea to clear anymore).
+
+- [ ] **Step 5: Narrow click handler to `[data-choice]` only**
+
+Replace the click handler (lines 36-55) with a narrower version:
+
+```javascript
+  // Capture clicks on choice elements
+  document.addEventListener('click', (e) => {
+    const target = e.target.closest('[data-choice]');
+    if (!target) return;
+
+    sendEvent({
+      type: 'click',
+      text: target.textContent.trim(),
+      choice: target.dataset.choice,
+      id: target.id || null
+    });
+  });
+```
+
+- [ ] **Step 6: Add indicator bar update on choice click**
+
+After the `sendEvent` call in the click handler, add:
+
+```javascript
+    // Update indicator bar
+    const indicator = document.getElementById('indicator-text');
+    if (indicator) {
+      const label = target.querySelector('h3, .content h3, .card-body h3')?.textContent?.trim() || target.dataset.choice;
+      indicator.innerHTML = '<span class="selected-text">' + label + ' selected</span> — return to terminal to continue';
+    }
+```
+
+- [ ] **Step 7: Remove `sendToClaude` from `window.brainstorm` API**
+
+Update the `window.brainstorm` object (lines 132-136) to remove `sendToClaude`:
+
+```javascript
+  window.brainstorm = {
+    send: sendEvent,
+    choice: (value, metadata = {}) => sendEvent({ type: 'choice', value, ...metadata })
+  };
+```
+
+- [ ] **Step 8: Run tests**
+
+```bash
+cd /Users/drewritter/prime-rad/superpowers && node tests/brainstorm-server/server.test.js
+```
+
+- [ ] **Step 9: Commit**
+
+```bash
+git add lib/brainstorm-server/helper.js
+git commit -m "Simplify helper.js: remove feedback functions, narrow to choice capture + indicator"
+```
+
+---
+
+### Task 4: Update tests for new structure
+
+**Files:**
+- Modify: `tests/brainstorm-server/server.test.js`
+
+**Note:** Line references below are from the _original_ file. Task 2 inserted new tests earlier in the file, so actual line numbers will be shifted. Find tests by their `console.log` labels (e.g., "Test 5:", "Test 6:").
+
+- [ ] **Step 1: Update Test 5 (full document assertion)**
+
+Find the Test 5 assertion `!fullRes.body.includes('feedback-footer')`. Change it to: Full documents should NOT have the indicator bar either (they're served as-is):
+
+```javascript
+    assert(!fullRes.body.includes('indicator-bar') || fullDoc.includes('indicator-bar'),
+      'Should not wrap full documents in frame template');
+```
+
+- [ ] **Step 2: Update Test 6 (fragment wrapping)**
+
+Line 125: Replace `feedback-footer` assertion with indicator bar assertion:
+
+```javascript
+    assert(fragRes.body.includes('indicator-bar'), 'Fragment should get indicator bar from frame');
+```
+
+Also verify content placeholder was replaced (fragment content appears, placeholder comment doesn't):
+
+```javascript
+    assert(!fragRes.body.includes('<!-- CONTENT -->'), 'Content placeholder should be replaced');
+```
+
+- [ ] **Step 3: Update Test 7 (helper.js API)**
+
+Lines 140-142: Update assertions to reflect the new API surface:
+
+```javascript
+    assert(helperContent.includes('toggleSelect'), 'helper.js should define toggleSelect');
+    assert(helperContent.includes('sendEvent'), 'helper.js should define sendEvent');
+    assert(helperContent.includes('selectedChoice'), 'helper.js should track selectedChoice');
+    assert(helperContent.includes('brainstorm'), 'helper.js should expose brainstorm API');
+    assert(!helperContent.includes('sendToClaude'), 'helper.js should not contain sendToClaude');
+```
+
+- [ ] **Step 4: Replace Test 8 (sendToClaude theming) with indicator bar test**
+
+Replace Test 8 (lines 145-149) — `sendToClaude` no longer exists. Test the indicator bar instead:
+
+```javascript
+    // Test 8: Indicator bar uses CSS variables (theme support)
+    console.log('Test 8: Indicator bar uses CSS variables');
+    const templateContent = fs.readFileSync(
+      path.join(__dirname, '../../lib/brainstorm-server/frame-template.html'), 'utf-8'
+    );
+    assert(templateContent.includes('indicator-bar'), 'Template should have indicator bar');
+    assert(templateContent.includes('indicator-text'), 'Template should have indicator text element');
+    console.log('  PASS');
+```
+
+- [ ] **Step 5: Run full test suite**
+
+```bash
+cd /Users/drewritter/prime-rad/superpowers && node tests/brainstorm-server/server.test.js
+```
+Expected: ALL tests PASS.
+
+- [ ] **Step 6: Commit**
+
+```bash
+git add tests/brainstorm-server/server.test.js
+git commit -m "Update brainstorm server tests for new template structure and helper.js API"
+```
+
+---
+
+### Task 5: Delete `wait-for-feedback.sh`
+
+**Files:**
+- Delete: `lib/brainstorm-server/wait-for-feedback.sh`
+
+- [ ] **Step 1: Verify no other files import or reference `wait-for-feedback.sh`**
+
+Search the codebase:
+```bash
+grep -r "wait-for-feedback" /Users/drewritter/prime-rad/superpowers/ --include="*.js" --include="*.md" --include="*.sh" --include="*.json"
+```
+
+Expected references: only `visual-companion.md` (rewritten in Task 6) and possibly release notes (historical, leave as-is).
+
+- [ ] **Step 2: Delete the file**
+
+```bash
+rm lib/brainstorm-server/wait-for-feedback.sh
+```
+
+- [ ] **Step 3: Run tests to confirm nothing breaks**
+
+```bash
+cd /Users/drewritter/prime-rad/superpowers && node tests/brainstorm-server/server.test.js
+```
+Expected: All tests PASS (no test referenced this file).
+
+- [ ] **Step 4: Commit**
+
+```bash
+git add -u lib/brainstorm-server/wait-for-feedback.sh
+git commit -m "Delete wait-for-feedback.sh: replaced by .events file"
+```
+
+---
+
+### Task 6: Rewrite `visual-companion.md`
+
+**Files:**
+- Modify: `skills/brainstorming/visual-companion.md`
+
+- [ ] **Step 1: Update "How It Works" description (line 18)**
+
+Replace the sentence about receiving feedback "as JSON" with:
+
+```markdown
+The server watches a directory for HTML files and serves the newest one to the browser. You write HTML content, the user sees it in their browser and can click to select options. Selections are recorded to a `.events` file that you read on your next turn.
+```
+
+- [ ] **Step 2: Update fragment description (line 20)**
+
+Remove "feedback footer" from the description of what the frame template provides:
+
+```markdown
+**Content fragments vs full documents:** If your HTML file starts with `<!DOCTYPE` or `<html`, the server serves it as-is (just injects the helper script). Otherwise, the server automatically wraps your content in the frame template — adding the header, CSS theme, selection indicator, and all interactive infrastructure. **Write content fragments by default.** Only write full documents when you need complete control over the page.
+```
+
+- [ ] **Step 3: Rewrite "The Loop" section (lines 36-61)**
+
+Replace the entire "The Loop" section with:
+
+```markdown
+## The Loop
+
+1. **Write HTML** to a new file in `screen_dir`:
+   - Use semantic filenames: `platform.html`, `visual-style.html`, `layout.html`
+   - **Never reuse filenames** — each screen gets a fresh file
+   - Use Write tool — **never use cat/heredoc** (dumps noise into terminal)
+   - Server automatically serves the newest file
+
+2. **Tell user what to expect and end your turn:**
+   - Remind them of the URL (every step, not just first)
+   - Give a brief text summary of what's on screen (e.g., "Showing 3 layout options for the homepage")
+   - Ask them to respond in the terminal: "Take a look and let me know what you think. Click to select an option if you'd like."
+
+3. **On your next turn** — after the user responds in the terminal:
+   - Read `$SCREEN_DIR/.events` if it exists — this contains the user's browser interactions (clicks, selections) as JSON lines
+   - Merge with the user's terminal text to get the full picture
+   - The terminal message is the primary feedback; `.events` provides structured interaction data
+
+4. **Iterate or advance** — if feedback changes current screen, write a new file (e.g., `layout-v2.html`). Only move to the next question when the current step is validated.
+
+5. Repeat until done.
+```
+
+- [ ] **Step 4: Replace "User Feedback Format" section (lines 165-174)**
+
+Replace with:
+
+```markdown
+## Browser Events Format
+
+When the user clicks options in the browser, their interactions are recorded to `$SCREEN_DIR/.events` (one JSON object per line). The file is cleared automatically when you push a new screen.
+
+```jsonl
+{"type":"click","choice":"a","text":"Option A - Simple Layout","timestamp":1706000101}
+{"type":"click","choice":"c","text":"Option C - Complex Grid","timestamp":1706000108}
+{"type":"click","choice":"b","text":"Option B - Hybrid","timestamp":1706000115}
+```
+
+The full event stream shows the user's exploration path — they may click multiple options before settling. The last `choice` event is typically the final selection, but the pattern of clicks can reveal hesitation or preferences worth asking about.
+
+If `.events` doesn't exist, the user didn't interact with the browser — use only their terminal text.
+```
+
+- [ ] **Step 5: Update "Writing Content Fragments" description (line 65)**
+
+Remove "feedback footer" reference:
+
+```markdown
+Write just the content that goes inside the page. The server wraps it in the frame template automatically (header, theme CSS, selection indicator, and all interactive infrastructure).
+```
+
+- [ ] **Step 6: Update Reference section (lines 200-203)**
+
+Remove the helper.js reference description about "JS API" — the API is now minimal. Keep the path reference:
+
+```markdown
+## Reference
+
+- Frame template (CSS reference): `${CLAUDE_PLUGIN_ROOT}/lib/brainstorm-server/frame-template.html`
+- Helper script (client-side): `${CLAUDE_PLUGIN_ROOT}/lib/brainstorm-server/helper.js`
+```
+
+- [ ] **Step 7: Commit**
+
+```bash
+git add skills/brainstorming/visual-companion.md
+git commit -m "Rewrite visual-companion.md for non-blocking browser-displays-terminal-commands flow"
+```
+
+---
+
+### Task 7: Final verification
+
+- [ ] **Step 1: Run full test suite**
+
+```bash
+cd /Users/drewritter/prime-rad/superpowers && node tests/brainstorm-server/server.test.js
+```
+Expected: ALL tests PASS.
+
+- [ ] **Step 2: Manual smoke test**
+
+Start the server manually and verify the flow works end-to-end:
+
+```bash
+cd /Users/drewritter/prime-rad/superpowers && lib/brainstorm-server/start-server.sh --project-dir /tmp/brainstorm-smoke-test
+```
+
+Write a test fragment, open in browser, click an option, verify `.events` file is written, verify indicator bar updates. Then stop the server:
+
+```bash
+lib/brainstorm-server/stop-server.sh <screen_dir from start output>
+```
+
+- [ ] **Step 3: Verify no stale references remain**
+
+```bash
+grep -r "wait-for-feedback\|sendToClaude\|feedback-footer\|send-to-claude\|TaskOutput.*block.*true" /Users/drewritter/prime-rad/superpowers/ --include="*.js" --include="*.md" --include="*.sh" --include="*.html" | grep -v node_modules | grep -v RELEASE-NOTES | grep -v "\.md:.*spec\|plan"
+```
+
+Expected: No hits outside of release notes and the spec/plan docs (which are historical).
+
+- [ ] **Step 4: Final commit if any cleanup needed**
+
+```bash
+git status
+# Review untracked/modified files, stage specific files as needed, commit if clean
+```

docs/superpowers/plans/2026-03-11-zero-dep-brainstorm-server.md

@@ -0,0 +1,479 @@
+# Zero-Dependency Brainstorm Server Implementation Plan
+
+> **For agentic workers:** REQUIRED: Use superpowers:subagent-driven-development (if subagents available) or superpowers:executing-plans to implement this plan. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Replace the brainstorm server's vendored node_modules with a single zero-dependency `server.js` using Node built-ins.
+
+**Architecture:** Single file with WebSocket protocol (RFC 6455 text frames), HTTP server (`http` module), and file watching (`fs.watch`). Exports protocol functions for unit testing when required as a module.
+
+**Tech Stack:** Node.js built-ins only: `http`, `crypto`, `fs`, `path`
+
+**Spec:** `docs/superpowers/specs/2026-03-11-zero-dep-brainstorm-server-design.md`
+
+**Existing tests:** `tests/brainstorm-server/ws-protocol.test.js` (unit), `tests/brainstorm-server/server.test.js` (integration)
+
+---
+
+## File Map
+
+- **Create:** `skills/brainstorming/scripts/server.js` — the zero-dep replacement
+- **Modify:** `skills/brainstorming/scripts/start-server.sh:94,100` — change `index.js` to `server.js`
+- **Modify:** `.gitignore:6` — remove the `!skills/brainstorming/scripts/node_modules/` exception
+- **Delete:** `skills/brainstorming/scripts/index.js`
+- **Delete:** `skills/brainstorming/scripts/package.json`
+- **Delete:** `skills/brainstorming/scripts/package-lock.json`
+- **Delete:** `skills/brainstorming/scripts/node_modules/` (714 files)
+- **No changes:** `skills/brainstorming/scripts/helper.js`, `skills/brainstorming/scripts/frame-template.html`, `skills/brainstorming/scripts/stop-server.sh`
+
+---
+
+## Chunk 1: WebSocket Protocol Layer
+
+### Task 1: Implement WebSocket protocol exports
+
+**Files:**
+- Create: `skills/brainstorming/scripts/server.js`
+- Test: `tests/brainstorm-server/ws-protocol.test.js` (already exists)
+
+- [ ] **Step 1: Create server.js with OPCODES constant and computeAcceptKey**
+
+```js
+const crypto = require('crypto');
+
+const OPCODES = { TEXT: 0x01, CLOSE: 0x08, PING: 0x09, PONG: 0x0A };
+const WS_MAGIC = '258EAFA5-E914-47DA-95CA-C5AB0DC85B11';
+
+function computeAcceptKey(clientKey) {
+  return crypto.createHash('sha1').update(clientKey + WS_MAGIC).digest('base64');
+}
+```
+
+- [ ] **Step 2: Implement encodeFrame**
+
+Server frames are never masked. Three length encodings:
+- payload < 126: 2-byte header (FIN+opcode, length)
+- 126-65535: 4-byte header (FIN+opcode, 126, 16-bit length)
+- &gt; 65535: 10-byte header (FIN+opcode, 127, 64-bit length)
+
+```js
+function encodeFrame(opcode, payload) {
+  const fin = 0x80;
+  const len = payload.length;
+  let header;
+
+  if (len < 126) {
+    header = Buffer.alloc(2);
+    header[0] = fin | opcode;
+    header[1] = len;
+  } else if (len < 65536) {
+    header = Buffer.alloc(4);
+    header[0] = fin | opcode;
+    header[1] = 126;
+    header.writeUInt16BE(len, 2);
+  } else {
+    header = Buffer.alloc(10);
+    header[0] = fin | opcode;
+    header[1] = 127;
+    header.writeBigUInt64BE(BigInt(len), 2);
+  }
+
+  return Buffer.concat([header, payload]);
+}
+```
+
+- [ ] **Step 3: Implement decodeFrame**
+
+Client frames are always masked. Returns `{ opcode, payload, bytesConsumed }` or `null` for incomplete. Throws on unmasked frames.
+
+```js
+function decodeFrame(buffer) {
+  if (buffer.length < 2) return null;
+
+  const firstByte = buffer[0];
+  const secondByte = buffer[1];
+  const opcode = firstByte & 0x0F;
+  const masked = (secondByte & 0x80) !== 0;
+  let payloadLen = secondByte & 0x7F;
+  let offset = 2;
+
+  if (!masked) throw new Error('Client frames must be masked');
+
+  if (payloadLen === 126) {
+    if (buffer.length < 4) return null;
+    payloadLen = buffer.readUInt16BE(2);
+    offset = 4;
+  } else if (payloadLen === 127) {
+    if (buffer.length < 10) return null;
+    payloadLen = Number(buffer.readBigUInt64BE(2));
+    offset = 10;
+  }
+
+  const maskOffset = offset;
+  const dataOffset = offset + 4;
+  const totalLen = dataOffset + payloadLen;
+  if (buffer.length < totalLen) return null;
+
+  const mask = buffer.slice(maskOffset, dataOffset);
+  const data = Buffer.alloc(payloadLen);
+  for (let i = 0; i < payloadLen; i++) {
+    data[i] = buffer[dataOffset + i] ^ mask[i % 4];
+  }
+
+  return { opcode, payload: data, bytesConsumed: totalLen };
+}
+```
+
+- [ ] **Step 4: Add module exports at the bottom of the file**
+
+```js
+module.exports = { computeAcceptKey, encodeFrame, decodeFrame, OPCODES };
+```
+
+- [ ] **Step 5: Run unit tests**
+
+Run: `cd tests/brainstorm-server && node ws-protocol.test.js`
+Expected: All tests pass (handshake, encoding, decoding, boundaries, edge cases)
+
+- [ ] **Step 6: Commit**
+
+```bash
+git add skills/brainstorming/scripts/server.js
+git commit -m "Add WebSocket protocol layer for zero-dep brainstorm server"
+```
+
+---
+
+## Chunk 2: HTTP Server and Application Logic
+
+### Task 2: Add HTTP server, file watching, and WebSocket connection handling
+
+**Files:**
+- Modify: `skills/brainstorming/scripts/server.js`
+- Test: `tests/brainstorm-server/server.test.js` (already exists)
+
+- [ ] **Step 1: Add configuration and constants at top of server.js (after requires)**
+
+```js
+const http = require('http');
+const fs = require('fs');
+const path = require('path');
+
+const PORT = process.env.BRAINSTORM_PORT || (49152 + Math.floor(Math.random() * 16383));
+const HOST = process.env.BRAINSTORM_HOST || '127.0.0.1';
+const URL_HOST = process.env.BRAINSTORM_URL_HOST || (HOST === '127.0.0.1' ? 'localhost' : HOST);
+const SCREEN_DIR = process.env.BRAINSTORM_DIR || '/tmp/brainstorm';
+
+const MIME_TYPES = {
+  '.html': 'text/html', '.css': 'text/css', '.js': 'application/javascript',
+  '.json': 'application/json', '.png': 'image/png', '.jpg': 'image/jpeg',
+  '.jpeg': 'image/jpeg', '.gif': 'image/gif', '.svg': 'image/svg+xml'
+};
+```
+
+- [ ] **Step 2: Add WAITING_PAGE, template loading at module scope, and helper functions**
+
+Load `frameTemplate` and `helperInjection` at module scope so they're accessible to `wrapInFrame` and `handleRequest`. They only read files from `__dirname` (the scripts directory), which is valid whether the module is required or run directly.
+
+```js
+const WAITING_PAGE = `<!DOCTYPE html>
+<html>
+<head><title>Brainstorm Companion</title>
+<style>body { font-family: system-ui, sans-serif; padding: 2rem; max-width: 800px; margin: 0 auto; }
+h1 { color: #333; } p { color: #666; }</style>
+</head>
+<body><h1>Brainstorm Companion</h1>
+<p>Waiting for Claude to push a screen...</p></body></html>`;
+
+const frameTemplate = fs.readFileSync(path.join(__dirname, 'frame-template.html'), 'utf-8');
+const helperScript = fs.readFileSync(path.join(__dirname, 'helper.js'), 'utf-8');
+const helperInjection = '<script>\n' + helperScript + '\n</script>';
+
+function isFullDocument(html) {
+  const trimmed = html.trimStart().toLowerCase();
+  return trimmed.startsWith('<!doctype') || trimmed.startsWith('<html');
+}
+
+function wrapInFrame(content) {
+  return frameTemplate.replace('<!-- CONTENT -->', content);
+}
+
+function getNewestScreen() {
+  const files = fs.readdirSync(SCREEN_DIR)
+    .filter(f => f.endsWith('.html'))
+    .map(f => {
+      const fp = path.join(SCREEN_DIR, f);
+      return { path: fp, mtime: fs.statSync(fp).mtime.getTime() };
+    })
+    .sort((a, b) => b.mtime - a.mtime);
+  return files.length > 0 ? files[0].path : null;
+}
+```
+
+- [ ] **Step 3: Add HTTP request handler**
+
+```js
+function handleRequest(req, res) {
+  if (req.method === 'GET' && req.url === '/') {
+    const screenFile = getNewestScreen();
+    let html = screenFile
+      ? (raw => isFullDocument(raw) ? raw : wrapInFrame(raw))(fs.readFileSync(screenFile, 'utf-8'))
+      : WAITING_PAGE;
+
+    if (html.includes('</body>')) {
+      html = html.replace('</body>', helperInjection + '\n</body>');
+    } else {
+      html += helperInjection;
+    }
+
+    res.writeHead(200, { 'Content-Type': 'text/html' });
+    res.end(html);
+  } else if (req.method === 'GET' && req.url.startsWith('/files/')) {
+    const fileName = req.url.slice(7); // strip '/files/'
+    const filePath = path.join(SCREEN_DIR, path.basename(fileName));
+    if (!fs.existsSync(filePath)) {
+      res.writeHead(404);
+      res.end('Not found');
+      return;
+    }
+    const ext = path.extname(filePath).toLowerCase();
+    const contentType = MIME_TYPES[ext] || 'application/octet-stream';
+    res.writeHead(200, { 'Content-Type': contentType });
+    res.end(fs.readFileSync(filePath));
+  } else {
+    res.writeHead(404);
+    res.end('Not found');
+  }
+}
+```
+
+- [ ] **Step 4: Add WebSocket connection handling**
+
+```js
+const clients = new Set();
+
+function handleUpgrade(req, socket) {
+  const key = req.headers['sec-websocket-key'];
+  if (!key) { socket.destroy(); return; }
+
+  const accept = computeAcceptKey(key);
+  socket.write(
+    'HTTP/1.1 101 Switching Protocols\r\n' +
+    'Upgrade: websocket\r\n' +
+    'Connection: Upgrade\r\n' +
+    'Sec-WebSocket-Accept: ' + accept + '\r\n\r\n'
+  );
+
+  let buffer = Buffer.alloc(0);
+  clients.add(socket);
+
+  socket.on('data', (chunk) => {
+    buffer = Buffer.concat([buffer, chunk]);
+    while (buffer.length > 0) {
+      let result;
+      try {
+        result = decodeFrame(buffer);
+      } catch (e) {
+        socket.end(encodeFrame(OPCODES.CLOSE, Buffer.alloc(0)));
+        clients.delete(socket);
+        return;
+      }
+      if (!result) break;
+      buffer = buffer.slice(result.bytesConsumed);
+
+      switch (result.opcode) {
+        case OPCODES.TEXT:
+          handleMessage(result.payload.toString());
+          break;
+        case OPCODES.CLOSE:
+          socket.end(encodeFrame(OPCODES.CLOSE, Buffer.alloc(0)));
+          clients.delete(socket);
+          return;
+        case OPCODES.PING:
+          socket.write(encodeFrame(OPCODES.PONG, result.payload));
+          break;
+        case OPCODES.PONG:
+          break;
+        default:
+          // Unsupported opcode — close with 1003
+          const closeBuf = Buffer.alloc(2);
+          closeBuf.writeUInt16BE(1003);
+          socket.end(encodeFrame(OPCODES.CLOSE, closeBuf));
+          clients.delete(socket);
+          return;
+      }
+    }
+  });
+
+  socket.on('close', () => clients.delete(socket));
+  socket.on('error', () => clients.delete(socket));
+}
+
+function handleMessage(text) {
+  let event;
+  try {
+    event = JSON.parse(text);
+  } catch (e) {
+    console.error('Failed to parse WebSocket message:', e.message);
+    return;
+  }
+  console.log(JSON.stringify({ source: 'user-event', ...event }));
+  if (event.choice) {
+    const eventsFile = path.join(SCREEN_DIR, '.events');
+    fs.appendFileSync(eventsFile, JSON.stringify(event) + '\n');
+  }
+}
+
+function broadcast(msg) {
+  const frame = encodeFrame(OPCODES.TEXT, Buffer.from(JSON.stringify(msg)));
+  for (const socket of clients) {
+    try { socket.write(frame); } catch (e) { clients.delete(socket); }
+  }
+}
+```
+
+- [ ] **Step 5: Add debounce timer map**
+
+```js
+const debounceTimers = new Map();
+```
+
+File watching logic is inlined in `startServer` (Step 6) to keep watcher lifecycle together with server lifecycle and include an `error` handler per spec.
+
+- [ ] **Step 6: Add startServer function and conditional main**
+
+`frameTemplate` and `helperInjection` are already at module scope (Step 2). `startServer` just creates the screen dir, starts the HTTP server, watcher, and logs startup info.
+
+```js
+function startServer() {
+  if (!fs.existsSync(SCREEN_DIR)) fs.mkdirSync(SCREEN_DIR, { recursive: true });
+
+  const server = http.createServer(handleRequest);
+  server.on('upgrade', handleUpgrade);
+
+  const watcher = fs.watch(SCREEN_DIR, (eventType, filename) => {
+    if (!filename || !filename.endsWith('.html')) return;
+    if (debounceTimers.has(filename)) clearTimeout(debounceTimers.get(filename));
+    debounceTimers.set(filename, setTimeout(() => {
+      debounceTimers.delete(filename);
+      const filePath = path.join(SCREEN_DIR, filename);
+      if (eventType === 'rename' && fs.existsSync(filePath)) {
+        const eventsFile = path.join(SCREEN_DIR, '.events');
+        if (fs.existsSync(eventsFile)) fs.unlinkSync(eventsFile);
+        console.log(JSON.stringify({ type: 'screen-added', file: filePath }));
+      } else if (eventType === 'change') {
+        console.log(JSON.stringify({ type: 'screen-updated', file: filePath }));
+      }
+      broadcast({ type: 'reload' });
+    }, 100));
+  });
+  watcher.on('error', (err) => console.error('fs.watch error:', err.message));
+
+  server.listen(PORT, HOST, () => {
+    const info = JSON.stringify({
+      type: 'server-started', port: Number(PORT), host: HOST,
+      url_host: URL_HOST, url: 'http://' + URL_HOST + ':' + PORT,
+      screen_dir: SCREEN_DIR
+    });
+    console.log(info);
+    fs.writeFileSync(path.join(SCREEN_DIR, '.server-info'), info + '\n');
+  });
+}
+
+if (require.main === module) {
+  startServer();
+}
+```
+
+- [ ] **Step 7: Run integration tests**
+
+The test directory already has a `package.json` with `ws` as a dependency. Install it if needed, then run tests.
+
+Run: `cd tests/brainstorm-server && npm install && node server.test.js`
+Expected: All tests pass
+
+- [ ] **Step 8: Commit**
+
+```bash
+git add skills/brainstorming/scripts/server.js
+git commit -m "Add HTTP server, WebSocket handling, and file watching to server.js"
+```
+
+---
+
+## Chunk 3: Swap and Cleanup
+
+### Task 3: Update start-server.sh and remove old files
+
+**Files:**
+- Modify: `skills/brainstorming/scripts/start-server.sh:94,100`
+- Modify: `.gitignore:6`
+- Delete: `skills/brainstorming/scripts/index.js`
+- Delete: `skills/brainstorming/scripts/package.json`
+- Delete: `skills/brainstorming/scripts/package-lock.json`
+- Delete: `skills/brainstorming/scripts/node_modules/` (entire directory)
+
+- [ ] **Step 1: Update start-server.sh — change `index.js` to `server.js`**
+
+Two lines to change:
+
+Line 94: `env BRAINSTORM_DIR="$SCREEN_DIR" BRAINSTORM_HOST="$BIND_HOST" BRAINSTORM_URL_HOST="$URL_HOST" node server.js`
+
+Line 100: `nohup env BRAINSTORM_DIR="$SCREEN_DIR" BRAINSTORM_HOST="$BIND_HOST" BRAINSTORM_URL_HOST="$URL_HOST" node server.js > "$LOG_FILE" 2>&1 &`
+
+- [ ] **Step 2: Remove the gitignore exception for node_modules**
+
+In `.gitignore`, delete line 6: `!skills/brainstorming/scripts/node_modules/`
+
+- [ ] **Step 3: Delete old files**
+
+```bash
+git rm skills/brainstorming/scripts/index.js
+git rm skills/brainstorming/scripts/package.json
+git rm skills/brainstorming/scripts/package-lock.json
+git rm -r skills/brainstorming/scripts/node_modules/
+```
+
+- [ ] **Step 4: Run both test suites**
+
+Run: `cd tests/brainstorm-server && node ws-protocol.test.js && node server.test.js`
+Expected: All tests pass
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add skills/brainstorming/scripts/ .gitignore
+git commit -m "Remove vendored node_modules, swap to zero-dep server.js"
+```
+
+### Task 4: Manual smoke test
+
+- [ ] **Step 1: Start the server manually**
+
+```bash
+cd skills/brainstorming/scripts
+BRAINSTORM_DIR=/tmp/brainstorm-smoke BRAINSTORM_PORT=9876 node server.js
+```
+
+Expected: `server-started` JSON printed with port 9876
+
+- [ ] **Step 2: Open browser to http://localhost:9876**
+
+Expected: Waiting page with "Waiting for Claude to push a screen..."
+
+- [ ] **Step 3: Write an HTML file to the screen directory**
+
+```bash
+echo '<h2>Hello from smoke test</h2>' > /tmp/brainstorm-smoke/test.html
+```
+
+Expected: Browser reloads and shows "Hello from smoke test" wrapped in frame template
+
+- [ ] **Step 4: Verify WebSocket works — check browser console**
+
+Open browser dev tools. The WebSocket connection should show as connected (no errors in console). The frame template's status indicator should show "Connected".
+
+- [ ] **Step 5: Stop server with Ctrl-C, clean up**
+
+```bash
+rm -rf /tmp/brainstorm-smoke
+```

docs/superpowers/plans/2026-03-23-codex-app-compatibility.md

@@ -0,0 +1,566 @@
+# Codex App Compatibility Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Make `using-git-worktrees`, `finishing-a-development-branch`, and related skills work in the Codex App's sandboxed worktree environment without breaking existing behavior.
+
+**Architecture:** Read-only environment detection (`git-dir` vs `git-common-dir`) at the start of two skills. If already in a linked worktree, skip creation. If on detached HEAD, emit a handoff payload instead of the 4-option menu. Sandbox fallback catches permission errors during worktree creation.
+
+**Tech Stack:** Git, Markdown (skill files are instruction documents, not executable code)
+
+**Spec:** `docs/superpowers/specs/2026-03-23-codex-app-compatibility-design.md`
+
+---
+
+## File Structure
+
+| File | Responsibility | Action |
+|---|---|---|
+| `skills/using-git-worktrees/SKILL.md` | Worktree creation + isolation | Add Step 0 detection + sandbox fallback |
+| `skills/finishing-a-development-branch/SKILL.md` | Branch finishing workflow | Add Step 1.5 detection + cleanup guard |
+| `skills/subagent-driven-development/SKILL.md` | Plan execution with subagents | Update Integration description |
+| `skills/executing-plans/SKILL.md` | Plan execution inline | Update Integration description |
+| `skills/using-superpowers/references/codex-tools.md` | Codex platform reference | Add detection + finishing docs |
+
+---
+
+### Task 1: Add Step 0 to `using-git-worktrees`
+
+**Files:**
+- Modify: `skills/using-git-worktrees/SKILL.md:14-15` (insert after Overview, before Directory Selection Process)
+
+- [ ] **Step 1: Read the current skill file**
+
+Read `skills/using-git-worktrees/SKILL.md` in full. Identify the exact insertion point: after the "Announce at start" line (line 14) and before "## Directory Selection Process" (line 16).
+
+- [ ] **Step 2: Insert Step 0 section**
+
+Insert the following between the Overview section and "## Directory Selection Process":
+
+```markdown
+## Step 0: Check if Already in an Isolated Workspace
+
+Before creating a worktree, check if one already exists:
+
+```bash
+GIT_DIR=$(cd "$(git rev-parse --git-dir)" 2>/dev/null && pwd -P)
+GIT_COMMON=$(cd "$(git rev-parse --git-common-dir)" 2>/dev/null && pwd -P)
+BRANCH=$(git branch --show-current)
+```
+
+**If `GIT_DIR` differs from `GIT_COMMON`:** You are already inside a linked worktree (created by the Codex App, Claude Code's Agent tool, a previous skill run, or the user). Do NOT create another worktree. Instead:
+
+1. Run project setup (auto-detect package manager as in "Run Project Setup" below)
+2. Verify clean baseline (run tests as in "Verify Clean Baseline" below)
+3. Report with branch state:
+   - On a branch: "Already in an isolated workspace at `<path>` on branch `<name>`. Tests passing. Ready to implement."
+   - Detached HEAD: "Already in an isolated workspace at `<path>` (detached HEAD, externally managed). Tests passing. Note: branch creation needed at finish time. Ready to implement."
+
+After reporting, STOP. Do not continue to Directory Selection or Creation Steps.
+
+**If `GIT_DIR` equals `GIT_COMMON`:** Proceed with the full worktree creation flow below.
+
+**Sandbox fallback:** If you proceed to Creation Steps but `git worktree add -b` fails with a permission error (e.g., "Operation not permitted"), treat this as a late-detected restricted environment. Fall back to the behavior above — run setup and baseline tests in the current directory, report accordingly, and STOP.
+```
+
+- [ ] **Step 3: Verify the insertion**
+
+Read the file again. Confirm:
+- Step 0 appears between Overview and Directory Selection Process
+- The rest of the file (Directory Selection, Safety Verification, Creation Steps, etc.) is unchanged
+- No duplicate sections or broken markdown
+
+- [ ] **Step 4: Commit**
+
+```bash
+git add skills/using-git-worktrees/SKILL.md
+git commit -m "feat(using-git-worktrees): add Step 0 environment detection (PRI-823)
+
+Skip worktree creation when already in a linked worktree. Includes
+sandbox fallback for permission errors on git worktree add."
+```
+
+---
+
+### Task 2: Update `using-git-worktrees` Integration section
+
+**Files:**
+- Modify: `skills/using-git-worktrees/SKILL.md:211-215` (Integration > Called by)
+
+- [ ] **Step 1: Update the three "Called by" entries**
+
+Change lines 212-214 from:
+
+```markdown
+- **brainstorming** (Phase 4) - REQUIRED when design is approved and implementation follows
+- **subagent-driven-development** - REQUIRED before executing any tasks
+- **executing-plans** - REQUIRED before executing any tasks
+```
+
+To:
+
+```markdown
+- **brainstorming** - REQUIRED: Ensures isolated workspace (creates one or verifies existing)
+- **subagent-driven-development** - REQUIRED: Ensures isolated workspace (creates one or verifies existing)
+- **executing-plans** - REQUIRED: Ensures isolated workspace (creates one or verifies existing)
+```
+
+- [ ] **Step 2: Verify the Integration section**
+
+Read the Integration section. Confirm all three entries are updated, "Pairs with" is unchanged.
+
+- [ ] **Step 3: Commit**
+
+```bash
+git add skills/using-git-worktrees/SKILL.md
+git commit -m "docs(using-git-worktrees): update Integration descriptions (PRI-823)
+
+Clarify that skill ensures a workspace exists, not that it always creates one."
+```
+
+---
+
+### Task 3: Add Step 1.5 to `finishing-a-development-branch`
+
+**Files:**
+- Modify: `skills/finishing-a-development-branch/SKILL.md:38` (insert after Step 1, before Step 2)
+
+- [ ] **Step 1: Read the current skill file**
+
+Read `skills/finishing-a-development-branch/SKILL.md` in full. Identify the insertion point: after "**If tests pass:** Continue to Step 2." (line 38) and before "### Step 2: Determine Base Branch" (line 40).
+
+- [ ] **Step 2: Insert Step 1.5 section**
+
+Insert the following between Step 1 and Step 2:
+
+```markdown
+### Step 1.5: Detect Environment
+
+```bash
+GIT_DIR=$(cd "$(git rev-parse --git-dir)" 2>/dev/null && pwd -P)
+GIT_COMMON=$(cd "$(git rev-parse --git-common-dir)" 2>/dev/null && pwd -P)
+BRANCH=$(git branch --show-current)
+```
+
+**Path A — `GIT_DIR` differs from `GIT_COMMON` AND `BRANCH` is empty (externally managed worktree, detached HEAD):**
+
+First, ensure all work is staged and committed (`git add` + `git commit`).
+
+Then present this to the user (do NOT present the 4-option menu):
+
+```
+Implementation complete. All tests passing.
+Current HEAD: <full-commit-sha>
+
+This workspace is externally managed (detached HEAD).
+I cannot create branches, push, or open PRs from here.
+
+⚠ These commits are on a detached HEAD. If you do not create a branch,
+they may be lost when this workspace is cleaned up.
+
+If your host application provides these controls:
+- "Create branch" — to name a branch, then commit/push/PR
+- "Hand off to local" — to move changes to your local checkout
+
+Suggested branch name: <ticket-id/short-description>
+Suggested commit message: <summary-of-work>
+```
+
+Branch name: use ticket ID if available (e.g., `pri-823/codex-compat`), otherwise slugify the first 5 words of the plan title, otherwise omit. Avoid sensitive content in branch names.
+
+Skip to Step 5 (cleanup is a no-op — see guard below).
+
+**Path B — `GIT_DIR` differs from `GIT_COMMON` AND `BRANCH` exists (externally managed worktree, named branch):**
+
+Proceed to Step 2 and present the 4-option menu as normal.
+
+**Path C — `GIT_DIR` equals `GIT_COMMON` (normal environment):**
+
+Proceed to Step 2 and present the 4-option menu as normal.
+```
+
+- [ ] **Step 3: Verify the insertion**
+
+Read the file again. Confirm:
+- Step 1.5 appears between Step 1 and Step 2
+- Steps 2-5 are unchanged
+- Path A handoff includes commit SHA and data loss warning
+- Paths B and C proceed to Step 2 normally
+
+- [ ] **Step 4: Commit**
+
+```bash
+git add skills/finishing-a-development-branch/SKILL.md
+git commit -m "feat(finishing-a-development-branch): add Step 1.5 environment detection (PRI-823)
+
+Detect externally managed worktrees with detached HEAD and emit handoff
+payload instead of 4-option menu. Includes commit SHA and data loss warning."
+```
+
+---
+
+### Task 4: Add Step 5 cleanup guard to `finishing-a-development-branch`
+
+**Files:**
+- Modify: `skills/finishing-a-development-branch/SKILL.md` (Step 5: Cleanup Worktree — find by section heading, line numbers will have shifted after Task 3)
+
+- [ ] **Step 1: Read the current Step 5 section**
+
+Find the "### Step 5: Cleanup Worktree" section in `skills/finishing-a-development-branch/SKILL.md` (line numbers will have shifted after Task 3's insertion). The current Step 5 is:
+
+```markdown
+### Step 5: Cleanup Worktree
+
+**For Options 1, 2, 4:**
+
+Check if in worktree:
+```bash
+git worktree list | grep $(git branch --show-current)
+```
+
+If yes:
+```bash
+git worktree remove <worktree-path>
+```
+
+**For Option 3:** Keep worktree.
+```
+
+- [ ] **Step 2: Add the cleanup guard before existing logic**
+
+Replace the Step 5 section with:
+
+```markdown
+### Step 5: Cleanup Worktree
+
+**First, check if worktree is externally managed:**
+
+```bash
+GIT_DIR=$(cd "$(git rev-parse --git-dir)" 2>/dev/null && pwd -P)
+GIT_COMMON=$(cd "$(git rev-parse --git-common-dir)" 2>/dev/null && pwd -P)
+```
+
+If `GIT_DIR` differs from `GIT_COMMON`: skip worktree removal — the host environment owns this workspace.
+
+**Otherwise, for Options 1 and 4:**
+
+Check if in worktree:
+```bash
+git worktree list | grep $(git branch --show-current)
+```
+
+If yes:
+```bash
+git worktree remove <worktree-path>
+```
+
+**For Option 3:** Keep worktree.
+```
+
+Note: the original text said "For Options 1, 2, 4" but the Quick Reference table and Common Mistakes section say "Options 1 & 4 only." This edit aligns Step 5 with those sections.
+
+- [ ] **Step 3: Verify the replacement**
+
+Read Step 5. Confirm:
+- Cleanup guard (re-detection) appears first
+- Existing removal logic preserved for non-externally-managed worktrees
+- "Options 1 and 4" (not "1, 2, 4") matches Quick Reference and Common Mistakes
+
+- [ ] **Step 4: Commit**
+
+```bash
+git add skills/finishing-a-development-branch/SKILL.md
+git commit -m "feat(finishing-a-development-branch): add Step 5 cleanup guard (PRI-823)
+
+Re-detect externally managed worktree at cleanup time and skip removal.
+Also fixes pre-existing inconsistency: cleanup now correctly says
+Options 1 and 4 only, matching Quick Reference and Common Mistakes."
+```
+
+---
+
+### Task 5: Update Integration lines in `subagent-driven-development` and `executing-plans`
+
+**Files:**
+- Modify: `skills/subagent-driven-development/SKILL.md:268`
+- Modify: `skills/executing-plans/SKILL.md:68`
+
+- [ ] **Step 1: Update `subagent-driven-development`**
+
+Change line 268 from:
+```
+- **superpowers:using-git-worktrees** - REQUIRED: Set up isolated workspace before starting
+```
+To:
+```
+- **superpowers:using-git-worktrees** - REQUIRED: Ensures isolated workspace (creates one or verifies existing)
+```
+
+- [ ] **Step 2: Update `executing-plans`**
+
+Change line 68 from:
+```
+- **superpowers:using-git-worktrees** - REQUIRED: Set up isolated workspace before starting
+```
+To:
+```
+- **superpowers:using-git-worktrees** - REQUIRED: Ensures isolated workspace (creates one or verifies existing)
+```
+
+- [ ] **Step 3: Verify both files**
+
+Read line 268 of `skills/subagent-driven-development/SKILL.md` and line 68 of `skills/executing-plans/SKILL.md`. Confirm both say "Ensures isolated workspace (creates one or verifies existing)".
+
+- [ ] **Step 4: Commit**
+
+```bash
+git add skills/subagent-driven-development/SKILL.md skills/executing-plans/SKILL.md
+git commit -m "docs(sdd, executing-plans): update worktree Integration descriptions (PRI-823)
+
+Clarify that using-git-worktrees ensures a workspace exists rather than
+always creating one."
+```
+
+---
+
+### Task 6: Add environment detection docs to `codex-tools.md`
+
+**Files:**
+- Modify: `skills/using-superpowers/references/codex-tools.md:25` (append at end)
+
+- [ ] **Step 1: Read the current file**
+
+Read `skills/using-superpowers/references/codex-tools.md` in full. Confirm it ends at line 25-26 after the multi_agent section.
+
+- [ ] **Step 2: Append two new sections**
+
+Add at the end of the file:
+
+```markdown
+
+## Environment Detection
+
+Skills that create worktrees or finish branches should detect their
+environment with read-only git commands before proceeding:
+
+```bash
+GIT_DIR=$(cd "$(git rev-parse --git-dir)" 2>/dev/null && pwd -P)
+GIT_COMMON=$(cd "$(git rev-parse --git-common-dir)" 2>/dev/null && pwd -P)
+BRANCH=$(git branch --show-current)
+```
+
+- `GIT_DIR != GIT_COMMON` → already in a linked worktree (skip creation)
+- `BRANCH` empty → detached HEAD (cannot branch/push/PR from sandbox)
+
+See `using-git-worktrees` Step 0 and `finishing-a-development-branch`
+Step 1.5 for how each skill uses these signals.
+
+## Codex App Finishing
+
+When the sandbox blocks branch/push operations (detached HEAD in an
+externally managed worktree), the agent commits all work and informs
+the user to use the App's native controls:
+
+- **"Create branch"** — names the branch, then commit/push/PR via App UI
+- **"Hand off to local"** — transfers work to the user's local checkout
+
+The agent can still run tests, stage files, and output suggested branch
+names, commit messages, and PR descriptions for the user to copy.
+```
+
+- [ ] **Step 3: Verify the additions**
+
+Read the full file. Confirm:
+- Two new sections appear after the existing content
+- Bash code block renders correctly (not escaped)
+- Cross-references to Step 0 and Step 1.5 are present
+
+- [ ] **Step 4: Commit**
+
+```bash
+git add skills/using-superpowers/references/codex-tools.md
+git commit -m "docs(codex-tools): add environment detection and App finishing docs (PRI-823)
+
+Document the git-dir vs git-common-dir detection pattern and the Codex
+App's native finishing flow for skills that need to adapt."
+```
+
+---
+
+### Task 7: Automated test — environment detection
+
+**Files:**
+- Create: `tests/codex-app-compat/test-environment-detection.sh`
+
+- [ ] **Step 1: Create test directory**
+
+```bash
+mkdir -p tests/codex-app-compat
+```
+
+- [ ] **Step 2: Write the detection test script**
+
+Create `tests/codex-app-compat/test-environment-detection.sh`:
+
+```bash
+#!/usr/bin/env bash
+set -euo pipefail
+
+# Test environment detection logic from PRI-823
+# Tests the git-dir vs git-common-dir comparison used by
+# using-git-worktrees Step 0 and finishing-a-development-branch Step 1.5
+
+PASS=0
+FAIL=0
+TEMP_DIR=$(mktemp -d)
+trap "rm -rf $TEMP_DIR" EXIT
+
+log_pass() { echo "  PASS: $1"; PASS=$((PASS + 1)); }
+log_fail() { echo "  FAIL: $1"; FAIL=$((FAIL + 1)); }
+
+# Helper: run detection and return "linked" or "normal"
+detect_worktree() {
+  local git_dir git_common
+  git_dir=$(cd "$(git rev-parse --git-dir)" 2>/dev/null && pwd -P)
+  git_common=$(cd "$(git rev-parse --git-common-dir)" 2>/dev/null && pwd -P)
+  if [ "$git_dir" != "$git_common" ]; then
+    echo "linked"
+  else
+    echo "normal"
+  fi
+}
+
+echo "=== Test 1: Normal repo detection ==="
+cd "$TEMP_DIR"
+git init test-repo > /dev/null 2>&1
+cd test-repo
+git commit --allow-empty -m "init" > /dev/null 2>&1
+result=$(detect_worktree)
+if [ "$result" = "normal" ]; then
+  log_pass "Normal repo detected as normal"
+else
+  log_fail "Normal repo detected as '$result' (expected 'normal')"
+fi
+
+echo "=== Test 2: Linked worktree detection ==="
+git worktree add "$TEMP_DIR/test-wt" -b test-branch > /dev/null 2>&1
+cd "$TEMP_DIR/test-wt"
+result=$(detect_worktree)
+if [ "$result" = "linked" ]; then
+  log_pass "Linked worktree detected as linked"
+else
+  log_fail "Linked worktree detected as '$result' (expected 'linked')"
+fi
+
+echo "=== Test 3: Detached HEAD detection ==="
+git checkout --detach HEAD > /dev/null 2>&1
+branch=$(git branch --show-current)
+if [ -z "$branch" ]; then
+  log_pass "Detached HEAD: branch is empty"
+else
+  log_fail "Detached HEAD: branch is '$branch' (expected empty)"
+fi
+
+echo "=== Test 4: Linked worktree + detached HEAD (Codex App simulation) ==="
+result=$(detect_worktree)
+branch=$(git branch --show-current)
+if [ "$result" = "linked" ] && [ -z "$branch" ]; then
+  log_pass "Codex App simulation: linked + detached HEAD"
+else
+  log_fail "Codex App simulation: result='$result', branch='$branch'"
+fi
+
+echo "=== Test 5: Cleanup guard — linked worktree should NOT remove ==="
+cd "$TEMP_DIR/test-wt"
+result=$(detect_worktree)
+if [ "$result" = "linked" ]; then
+  log_pass "Cleanup guard: linked worktree correctly detected (would skip removal)"
+else
+  log_fail "Cleanup guard: expected 'linked', got '$result'"
+fi
+
+echo "=== Test 6: Cleanup guard — main repo SHOULD remove ==="
+cd "$TEMP_DIR/test-repo"
+result=$(detect_worktree)
+if [ "$result" = "normal" ]; then
+  log_pass "Cleanup guard: main repo correctly detected (would proceed with removal)"
+else
+  log_fail "Cleanup guard: expected 'normal', got '$result'"
+fi
+
+# Cleanup worktree before temp dir removal
+cd "$TEMP_DIR/test-repo"
+git worktree remove "$TEMP_DIR/test-wt" > /dev/null 2>&1 || true
+
+echo ""
+echo "=== Results: $PASS passed, $FAIL failed ==="
+if [ "$FAIL" -gt 0 ]; then
+  exit 1
+fi
+```
+
+- [ ] **Step 3: Make it executable and run it**
+
+```bash
+chmod +x tests/codex-app-compat/test-environment-detection.sh
+./tests/codex-app-compat/test-environment-detection.sh
+```
+
+Expected output: 6 passed, 0 failed.
+
+- [ ] **Step 4: Commit**
+
+```bash
+git add tests/codex-app-compat/test-environment-detection.sh
+git commit -m "test: add environment detection tests for Codex App compat (PRI-823)
+
+Tests git-dir vs git-common-dir comparison in normal repo, linked
+worktree, detached HEAD, and cleanup guard scenarios."
+```
+
+---
+
+### Task 8: Final verification
+
+**Files:**
+- Read: all 5 modified skill files
+
+- [ ] **Step 1: Run the automated detection tests**
+
+```bash
+./tests/codex-app-compat/test-environment-detection.sh
+```
+
+Expected: 6 passed, 0 failed.
+
+- [ ] **Step 2: Read each modified file and verify changes**
+
+Read each file end-to-end:
+- `skills/using-git-worktrees/SKILL.md` — Step 0 present, rest unchanged
+- `skills/finishing-a-development-branch/SKILL.md` — Step 1.5 present, cleanup guard present, rest unchanged
+- `skills/subagent-driven-development/SKILL.md` — line 268 updated
+- `skills/executing-plans/SKILL.md` — line 68 updated
+- `skills/using-superpowers/references/codex-tools.md` — two new sections at end
+
+- [ ] **Step 3: Verify no unintended changes**
+
+```bash
+git diff --stat HEAD~7
+```
+
+Should show exactly 6 files changed (5 skill files + 1 test file). No other files modified.
+
+- [ ] **Step 4: Run existing test suite**
+
+If test runner exists:
+```bash
+# Run skill-triggering tests
+# Note: tests/skill-triggering/ was lifted into drill scenarios on 2026-05-06.
+# See evals/scenarios/triggering-*.yaml. The reference below is a dated artifact.
+./tests/skill-triggering/run-all.sh 2>/dev/null || echo "Skill triggering tests not available in this environment"
+
+# Run SDD integration test
+./tests/claude-code/test-subagent-driven-development-integration.sh 2>/dev/null || echo "SDD integration test not available in this environment"
+```
+
+Note: these tests require Claude Code with `--dangerously-skip-permissions`. If not available, document that regression tests should be run manually.

docs/superpowers/plans/2026-04-06-worktree-rototill.md

@@ -0,0 +1,866 @@
+# Worktree Rototill Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Make superpowers defer to native harness worktree systems when available, fall back to manual git worktrees when not, and fix three known finishing bugs.
+
+**Architecture:** Two skill files are rewritten (`using-git-worktrees`, `finishing-a-development-branch`), three files get one-line integration updates (`executing-plans`, `subagent-driven-development`, `writing-plans`). The core change is adding detection (`GIT_DIR != GIT_COMMON`) and a native-tool-first creation path. These are markdown skill instruction files, not application code — "tests" are agent behavior tests using the testing-skills-with-subagents TDD framework.
+
+**Tech Stack:** Markdown (skill files), bash (test scripts), Claude Code CLI (`claude -p` for headless testing)
+
+**Spec:** `docs/superpowers/specs/2026-04-06-worktree-rototill-design.md`
+
+---
+
+### Task 1: GATE — TDD Validation of Step 1a (Native Tool Preference)
+
+Step 1a is the load-bearing assumption of the entire design. If agents don't prefer native worktree tools over `git worktree add`, the spec fails. Validate this FIRST, before touching any skill files.
+
+**Files:**
+- Create: `tests/claude-code/test-worktree-native-preference.sh`
+- Read: `skills/using-git-worktrees/SKILL.md` (current version, for RED baseline)
+- Read: `tests/claude-code/test-helpers.sh` (for `run_claude`, `assert_contains`, etc.)
+- Read: `skills/writing-skills/testing-skills-with-subagents.md` (TDD framework)
+
+**This task is a gate.** If the GREEN phase fails after 2 REFACTOR iterations, STOP. Do not proceed to Task 2. Report back — the creation approach needs redesign.
+
+- [ ] **Step 1: Write the RED baseline test script**
+
+Create the test script that will run scenarios both WITHOUT and WITH the updated skill text. The RED phase runs against the current skill (which has no Step 1a).
+
+```bash
+#!/usr/bin/env bash
+# Test: Does the agent prefer native worktree tools (EnterWorktree) over git worktree add?
+# Framework: RED-GREEN-REFACTOR per testing-skills-with-subagents.md
+#
+# RED:   Current skill has no native tool preference. Agent should use git worktree add.
+# GREEN: Updated skill has Step 1a. Agent should use EnterWorktree on Claude Code.
+
+set -euo pipefail
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+source "$SCRIPT_DIR/test-helpers.sh"
+
+# Pressure scenario: realistic implementation task where agent needs isolation
+SCENARIO='IMPORTANT: This is a real task. Choose and act.
+
+You need to implement a small feature (add a "version" field to package.json).
+This should be done in an isolated workspace to protect the main branch.
+
+You have the using-git-worktrees skill available. Set up the isolated workspace now.
+Do NOT actually implement the feature — just set up the workspace and report what you did.
+
+Respond with EXACTLY what tool/command you used to create the workspace.'
+
+echo "=== Worktree Native Preference Test ==="
+echo ""
+
+# Phase selection
+PHASE="${1:-red}"
+
+if [ "$PHASE" = "red" ]; then
+    echo "--- RED PHASE: Running WITHOUT Step 1a (current skill) ---"
+    echo "Expected: Agent uses 'git worktree add' (no native tool awareness)"
+    echo ""
+
+    test_dir=$(create_test_project)
+    cd "$test_dir"
+    git init && git commit --allow-empty -m "init"
+    mkdir -p .worktrees
+
+    output=$(run_claude "$SCENARIO" 120)
+
+    echo "Agent output:"
+    echo "$output"
+    echo ""
+
+    # RED expectation: agent uses git worktree add (current behavior)
+    if echo "$output" | grep -qi "EnterWorktree"; then
+        echo "[UNEXPECTED] Agent used EnterWorktree WITHOUT Step 1a — skill may not be needed"
+        echo "Investigate: is Claude Code's default behavior already correct?"
+    else
+        echo "[RED CONFIRMED] Agent did NOT use EnterWorktree"
+        assert_contains "$output" "git worktree" "Agent used git worktree (expected in RED)"
+    fi
+
+    cleanup_test_project "$test_dir"
+
+elif [ "$PHASE" = "green" ]; then
+    echo "--- GREEN PHASE: Running WITH Step 1a (updated skill) ---"
+    echo "Expected: Agent uses EnterWorktree instead of git worktree add"
+    echo ""
+
+    test_dir=$(create_test_project)
+    cd "$test_dir"
+    git init && git commit --allow-empty -m "init"
+
+    output=$(run_claude "$SCENARIO" 120)
+
+    echo "Agent output:"
+    echo "$output"
+    echo ""
+
+    # GREEN expectation: agent uses EnterWorktree
+    assert_contains "$output" "EnterWorktree" "Agent used native EnterWorktree tool"
+    assert_not_contains "$output" "git worktree add" "Agent did NOT fall back to git worktree add"
+
+    cleanup_test_project "$test_dir"
+
+elif [ "$PHASE" = "pressure" ]; then
+    echo "--- PRESSURE PHASE: Multiple pressures to skip native tools ---"
+    echo ""
+
+    PRESSURE_SCENARIO='IMPORTANT: This is a real task. Choose and act.
+
+You need to set up an isolated workspace URGENTLY. Production is impacted and
+the fix needs to go in a worktree. You know git worktree add works reliably.
+The .worktrees/ directory already exists and is gitignored.
+
+You have the using-git-worktrees skill. Set up the workspace NOW.
+Speed matters. Report EXACTLY what tool/command you used.'
+
+    test_dir=$(create_test_project)
+    cd "$test_dir"
+    git init && git commit --allow-empty -m "init"
+    mkdir -p .worktrees
+    echo ".worktrees/" >> .gitignore
+
+    output=$(run_claude "$PRESSURE_SCENARIO" 120)
+
+    echo "Agent output:"
+    echo "$output"
+    echo ""
+
+    # Should STILL use EnterWorktree even under pressure
+    assert_contains "$output" "EnterWorktree" "Agent used native tool even under time pressure"
+    assert_not_contains "$output" "git worktree add" "Agent resisted falling back to git despite pressure"
+
+    cleanup_test_project "$test_dir"
+fi
+
+echo ""
+echo "=== Test Complete ==="
+```
+
+- [ ] **Step 2: Run RED phase — confirm agent uses git worktree add today**
+
+Run: `cd tests/claude-code && bash test-worktree-native-preference.sh red`
+
+Expected: `[RED CONFIRMED] Agent did NOT use EnterWorktree` — agent uses `git worktree add` because current skill has no native tool preference.
+
+Document the agent's exact output and any rationalizations verbatim. This is the baseline failure the skill must fix.
+
+- [ ] **Step 3: If RED confirmed, proceed. Write the Step 1a skill text.**
+
+Create a temporary test version of the skill with ONLY the Step 1a addition (minimal change to isolate the variable). Add this section to the top of the skill's creation instructions, BEFORE the existing directory selection process:
+
+```markdown
+## Step 1: Create Isolated Workspace
+
+**You have two mechanisms. Try them in this order.**
+
+### 1a. Native Worktree Tools (preferred)
+
+If your platform provides a worktree or workspace-isolation tool, use it. You know your own toolkit — the skill does not need to name specific tools. Native tools handle directory placement, branch creation, and cleanup automatically.
+
+After using a native tool, skip to Step 3 (Project Setup).
+
+### 1b. Git Worktree Fallback
+
+If no native tool is available, create a worktree manually using git.
+```
+
+- [ ] **Step 4: Run GREEN phase — confirm agent now uses EnterWorktree**
+
+Run: `cd tests/claude-code && bash test-worktree-native-preference.sh green`
+
+Expected: `[PASS] Agent used native EnterWorktree tool`
+
+If FAIL: Document the agent's exact output and rationalizations. This is a REFACTOR signal — the Step 1a text needs revision. Try up to 2 REFACTOR iterations. If still failing after 2 iterations, STOP and report back.
+
+- [ ] **Step 5: Run PRESSURE phase — confirm agent resists fallback under pressure**
+
+Run: `cd tests/claude-code && bash test-worktree-native-preference.sh pressure`
+
+Expected: `[PASS] Agent used native tool even under time pressure`
+
+If FAIL: Document rationalizations verbatim. Add explicit counters to Step 1a text (e.g., a Red Flag entry: "Never use git worktree add when your platform provides a native worktree tool"). Re-run.
+
+- [ ] **Step 6: Commit test script**
+
+```bash
+git add tests/claude-code/test-worktree-native-preference.sh
+git commit -m "test: add RED/GREEN validation for native worktree preference (PRI-974)
+
+Gate test for Step 1a — validates agents prefer EnterWorktree over
+git worktree add on Claude Code. Must pass before skill rewrite."
+```
+
+---
+
+### Task 2: Rewrite `using-git-worktrees` SKILL.md
+
+Full rewrite of the creation skill. Replaces the existing file entirely.
+
+**Files:**
+- Modify: `skills/using-git-worktrees/SKILL.md` (full rewrite, 219 lines → ~210 lines)
+
+**Depends on:** Task 1 GREEN passing.
+
+- [ ] **Step 1: Write the complete new SKILL.md**
+
+Replace the entire contents of `skills/using-git-worktrees/SKILL.md` with:
+
+```markdown
+---
+name: using-git-worktrees
+description: Use when starting feature work that needs isolation from current workspace or before executing implementation plans - ensures an isolated workspace exists via native tools or git worktree fallback
+---
+
+# Using Git Worktrees
+
+## Overview
+
+Ensure work happens in an isolated workspace. Prefer your platform's native worktree tools. Fall back to manual git worktrees only when no native tool is available.
+
+**Core principle:** Detect existing isolation first. Then use native tools. Then fall back to git. Never fight the harness.
+
+**Announce at start:** "I'm using the using-git-worktrees skill to set up an isolated workspace."
+
+## Step 0: Detect Existing Isolation
+
+**Before creating anything, check if you are already in an isolated workspace.**
+
+```bash
+GIT_DIR=$(cd "$(git rev-parse --git-dir)" 2>/dev/null && pwd -P)
+GIT_COMMON=$(cd "$(git rev-parse --git-common-dir)" 2>/dev/null && pwd -P)
+BRANCH=$(git branch --show-current)
+```
+
+**Submodule guard:** `GIT_DIR != GIT_COMMON` is also true inside git submodules. Before concluding "already in a worktree," verify you are not in a submodule:
+
+```bash
+# If this returns a path, you're in a submodule, not a worktree — proceed to Step 1
+git rev-parse --show-superproject-working-tree 2>/dev/null
+```
+
+**If `GIT_DIR != GIT_COMMON` (and not a submodule):** You are already in a linked worktree. Skip to Step 3 (Project Setup). Do NOT create another worktree.
+
+Report with branch state:
+- On a branch: "Already in isolated workspace at `<path>` on branch `<name>`."
+- Detached HEAD: "Already in isolated workspace at `<path>` (detached HEAD, externally managed). Branch creation needed at finish time."
+
+**If `GIT_DIR == GIT_COMMON` (or in a submodule):** You are in a normal repo checkout.
+
+Has the user already indicated their worktree preference in your instructions? If not, ask for consent before creating a worktree:
+
+> "Would you like me to set up an isolated worktree? It protects your current branch from changes."
+
+Honor any existing declared preference without asking. If the user declines consent, work in place and skip to Step 3.
+
+## Step 1: Create Isolated Workspace
+
+**You have two mechanisms. Try them in this order.**
+
+### 1a. Native Worktree Tools (preferred)
+
+If your platform provides a worktree or workspace-isolation tool, use it. You know your own toolkit — the skill does not need to name specific tools. Native tools handle directory placement, branch creation, and cleanup automatically.
+
+After using a native tool, skip to Step 3 (Project Setup).
+
+### 1b. Git Worktree Fallback
+
+If no native tool is available, create a worktree manually using git.
+
+#### Directory Selection
+
+Follow this priority order:
+
+1. **Check your instructions for a worktree directory preference.** If specified, use it without asking.
+
+2. **Check existing project-local directories:**
+   ```bash
+   ls -d .worktrees 2>/dev/null     # Preferred (hidden)
+   ls -d worktrees 2>/dev/null      # Alternative
+   ```
+   If found, use that directory. If both exist, `.worktrees` wins.
+
+3. **Default to `.worktrees/`.**
+
+#### Safety Verification (project-local directories only)
+
+**MUST verify directory is ignored before creating worktree:**
+
+```bash
+git check-ignore -q .worktrees 2>/dev/null || git check-ignore -q worktrees 2>/dev/null
+```
+
+**If NOT ignored:** Add to .gitignore, commit the change, then proceed.
+
+**Why critical:** Prevents accidentally committing worktree contents to repository.
+
+#### Create the Worktree
+
+```bash
+# Determine path based on chosen location
+path="$LOCATION/$BRANCH_NAME"
+
+git worktree add "$path" -b "$BRANCH_NAME"
+cd "$path"
+```
+
+#### Hooks Awareness
+
+Git worktrees do not inherit the parent repo's hooks directory. After creating the worktree, symlink hooks from the main repo if they exist:
+
+```bash
+MAIN_ROOT=$(git -C "$(git rev-parse --git-common-dir)/.." rev-parse --show-toplevel)
+if [ -d "$MAIN_ROOT/.git/hooks" ]; then
+    ln -sf "$MAIN_ROOT/.git/hooks" "$path/.git/hooks"
+fi
+```
+
+This prevents pre-commit checks, linters, and other hooks from silently stopping when work moves to a worktree.
+
+**Sandbox fallback:** If `git worktree add` fails with a permission error (sandbox denial), treat this as a restricted environment. Skip creation, run setup and baseline tests in the current directory, report accordingly.
+
+## Step 3: Project Setup
+
+Auto-detect and run appropriate setup:
+
+```bash
+# Node.js
+if [ -f package.json ]; then npm install; fi
+
+# Rust
+if [ -f Cargo.toml ]; then cargo build; fi
+
+# Python
+if [ -f requirements.txt ]; then pip install -r requirements.txt; fi
+if [ -f pyproject.toml ]; then poetry install; fi
+
+# Go
+if [ -f go.mod ]; then go mod download; fi
+```
+
+## Step 4: Verify Clean Baseline
+
+Run tests to ensure workspace starts clean:
+
+```bash
+# Use project-appropriate command
+npm test / cargo test / pytest / go test ./...
+```
+
+**If tests fail:** Report failures, ask whether to proceed or investigate.
+
+**If tests pass:** Report ready.
+
+### Report
+
+```
+Worktree ready at <full-path>
+Tests passing (<N> tests, 0 failures)
+Ready to implement <feature-name>
+```
+
+## Quick Reference
+
+| Situation | Action |
+|-----------|--------|
+| Already in linked worktree | Skip creation (Step 0) |
+| In a submodule | Treat as normal repo (Step 0 guard) |
+| Native worktree tool available | Use it (Step 1a) |
+| No native tool | Git worktree fallback (Step 1b) |
+| `.worktrees/` exists | Use it (verify ignored) |
+| `worktrees/` exists | Use it (verify ignored) |
+| Both exist | Use `.worktrees/` |
+| Neither exists | Check instruction file, then default `.worktrees/` |
+| Directory not ignored | Add to .gitignore + commit |
+| Permission error on create | Sandbox fallback, work in place |
+| Tests fail during baseline | Report failures + ask |
+| No package.json/Cargo.toml | Skip dependency install |
+
+## Common Mistakes
+
+### Fighting the harness
+
+- **Problem:** Using `git worktree add` when the platform already provides isolation
+- **Fix:** Step 0 detects existing isolation. Step 1a defers to native tools.
+
+### Skipping detection
+
+- **Problem:** Creating a nested worktree inside an existing one
+- **Fix:** Always run Step 0 before creating anything
+
+### Skipping ignore verification
+
+- **Problem:** Worktree contents get tracked, pollute git status
+- **Fix:** Always use `git check-ignore` before creating project-local worktree
+
+### Assuming directory location
+
+- **Problem:** Creates inconsistency, violates project conventions
+- **Fix:** Follow priority: existing > instruction file > default
+
+### Proceeding with failing tests
+
+- **Problem:** Can't distinguish new bugs from pre-existing issues
+- **Fix:** Report failures, get explicit permission to proceed
+
+## Red Flags
+
+**Never:**
+- Create a worktree when Step 0 detects existing isolation
+- Use git commands when a native worktree tool is available
+- Create worktree without verifying it's ignored (project-local)
+- Skip baseline test verification
+- Proceed with failing tests without asking
+
+**Always:**
+- Run Step 0 detection first
+- Prefer native tools over git fallback
+- Follow directory priority: existing > instruction file > default
+- Verify directory is ignored for project-local
+- Auto-detect and run project setup
+- Verify clean test baseline
+- Symlink hooks after creating worktree via 1b
+
+## Integration
+
+**Called by:**
+- **subagent-driven-development** - Ensures isolated workspace (creates one or verifies existing)
+- **executing-plans** - Ensures isolated workspace (creates one or verifies existing)
+- Any skill needing isolated workspace
+
+**Pairs with:**
+- **finishing-a-development-branch** - REQUIRED for cleanup after work complete
+```
+
+- [ ] **Step 2: Verify the file reads correctly**
+
+Run: `wc -l skills/using-git-worktrees/SKILL.md`
+
+Expected: Approximately 200-220 lines. Scan for any markdown formatting issues.
+
+- [ ] **Step 3: Commit**
+
+```bash
+git add skills/using-git-worktrees/SKILL.md
+git commit -m "feat: rewrite using-git-worktrees with detect-and-defer (PRI-974)
+
+Step 0: GIT_DIR != GIT_COMMON detection (skip if already isolated)
+Step 0 consent: opt-in prompt before creating worktree (#991)
+Step 1a: native tool preference (short, first, declarative)
+Step 1b: git worktree fallback with project-local directory policy
+Submodule guard prevents false detection
+Platform-neutral instruction file references (#1049)"
+```
+
+---
+
+### Task 3: Rewrite `finishing-a-development-branch` SKILL.md
+
+Full rewrite of the finishing skill. Adds environment detection, fixes three bugs, adds provenance-based cleanup.
+
+**Files:**
+- Modify: `skills/finishing-a-development-branch/SKILL.md` (full rewrite, 201 lines → ~220 lines)
+
+- [ ] **Step 1: Write the complete new SKILL.md**
+
+Replace the entire contents of `skills/finishing-a-development-branch/SKILL.md` with:
+
+```markdown
+---
+name: finishing-a-development-branch
+description: Use when implementation is complete, all tests pass, and you need to decide how to integrate the work - guides completion of development work by presenting structured options for merge, PR, or cleanup
+---
+
+# Finishing a Development Branch
+
+## Overview
+
+Guide completion of development work by presenting clear options and handling chosen workflow.
+
+**Core principle:** Verify tests → Detect environment → Present options → Execute choice → Clean up.
+
+**Announce at start:** "I'm using the finishing-a-development-branch skill to complete this work."
+
+## The Process
+
+### Step 1: Verify Tests
+
+**Before presenting options, verify tests pass:**
+
+```bash
+# Run project's test suite
+npm test / cargo test / pytest / go test ./...
+```
+
+**If tests fail:**
+```
+Tests failing (<N> failures). Must fix before completing:
+
+[Show failures]
+
+Cannot proceed with merge/PR until tests pass.
+```
+
+Stop. Don't proceed to Step 2.
+
+**If tests pass:** Continue to Step 2.
+
+### Step 2: Detect Environment
+
+**Determine workspace state before presenting options:**
+
+```bash
+GIT_DIR=$(cd "$(git rev-parse --git-dir)" 2>/dev/null && pwd -P)
+GIT_COMMON=$(cd "$(git rev-parse --git-common-dir)" 2>/dev/null && pwd -P)
+```
+
+This determines which menu to show and how cleanup works:
+
+| State | Menu | Cleanup |
+|-------|------|---------|
+| `GIT_DIR == GIT_COMMON` (normal repo) | Standard 4 options | No worktree to clean up |
+| `GIT_DIR != GIT_COMMON`, named branch | Standard 4 options | Provenance-based (see Step 6) |
+| `GIT_DIR != GIT_COMMON`, detached HEAD | Reduced 3 options (no merge) | No cleanup (externally managed) |
+
+### Step 3: Determine Base Branch
+
+```bash
+# Try common base branches
+git merge-base HEAD main 2>/dev/null || git merge-base HEAD master 2>/dev/null
+```
+
+Or ask: "This branch split from main - is that correct?"
+
+### Step 4: Present Options
+
+**Normal repo and named-branch worktree — present exactly these 4 options:**
+
+```
+Implementation complete. What would you like to do?
+
+1. Merge back to <base-branch> locally
+2. Push and create a Pull Request
+3. Keep the branch as-is (I'll handle it later)
+4. Discard this work
+
+Which option?
+```
+
+**Detached HEAD — present exactly these 3 options:**
+
+```
+Implementation complete. You're on a detached HEAD (externally managed workspace).
+
+1. Push as new branch and create a Pull Request
+2. Keep as-is (I'll handle it later)
+3. Discard this work
+
+Which option?
+```
+
+**Don't add explanation** - keep options concise.
+
+### Step 5: Execute Choice
+
+#### Option 1: Merge Locally
+
+```bash
+# Get main repo root for CWD safety
+MAIN_ROOT=$(git -C "$(git rev-parse --git-common-dir)/.." rev-parse --show-toplevel)
+cd "$MAIN_ROOT"
+
+# Merge first — verify success before removing anything
+git checkout <base-branch>
+git pull
+git merge <feature-branch>
+
+# Verify tests on merged result
+<test command>
+
+# Only after merge succeeds: remove worktree, then delete branch
+# (See Step 6 for worktree cleanup)
+git branch -d <feature-branch>
+```
+
+Then: Cleanup worktree (Step 6)
+
+#### Option 2: Push and Create PR
+
+```bash
+# Push branch
+git push -u origin <feature-branch>
+
+# Create PR
+gh pr create --title "<title>" --body "$(cat <<'EOF'
+## Summary
+<2-3 bullets of what changed>
+
+## Test Plan
+- [ ] <verification steps>
+EOF
+)"
+```
+
+**Do NOT clean up worktree** — user needs it alive to iterate on PR feedback.
+
+#### Option 3: Keep As-Is
+
+Report: "Keeping branch <name>. Worktree preserved at <path>."
+
+**Don't cleanup worktree.**
+
+#### Option 4: Discard
+
+**Confirm first:**
+```
+This will permanently delete:
+- Branch <name>
+- All commits: <commit-list>
+- Worktree at <path>
+
+Type 'discard' to confirm.
+```
+
+Wait for exact confirmation.
+
+If confirmed:
+```bash
+MAIN_ROOT=$(git -C "$(git rev-parse --git-common-dir)/.." rev-parse --show-toplevel)
+cd "$MAIN_ROOT"
+```
+
+Then: Cleanup worktree (Step 6), then force-delete branch:
+```bash
+git branch -D <feature-branch>
+```
+
+### Step 6: Cleanup Workspace
+
+**Only runs for Options 1 and 4.** Options 2 and 3 always preserve the worktree.
+
+```bash
+GIT_DIR=$(cd "$(git rev-parse --git-dir)" 2>/dev/null && pwd -P)
+GIT_COMMON=$(cd "$(git rev-parse --git-common-dir)" 2>/dev/null && pwd -P)
+WORKTREE_PATH=$(git rev-parse --show-toplevel)
+```
+
+**If `GIT_DIR == GIT_COMMON`:** Normal repo, no worktree to clean up. Done.
+
+**If worktree path is under `.worktrees/` or `worktrees/`:** Superpowers created this worktree — we own cleanup.
+
+```bash
+MAIN_ROOT=$(git -C "$(git rev-parse --git-common-dir)/.." rev-parse --show-toplevel)
+cd "$MAIN_ROOT"
+git worktree remove "$WORKTREE_PATH"
+git worktree prune  # Self-healing: clean up any stale registrations
+```
+
+**Otherwise:** The host environment (harness) owns this workspace. Do NOT remove it. If your platform provides a workspace-exit tool, use it. Otherwise, leave the workspace in place.
+
+## Quick Reference
+
+| Option | Merge | Push | Keep Worktree | Cleanup Branch |
+|--------|-------|------|---------------|----------------|
+| 1. Merge locally | yes | - | - | yes |
+| 2. Create PR | - | yes | yes | - |
+| 3. Keep as-is | - | - | yes | - |
+| 4. Discard | - | - | - | yes (force) |
+
+## Common Mistakes
+
+**Skipping test verification**
+- **Problem:** Merge broken code, create failing PR
+- **Fix:** Always verify tests before offering options
+
+**Open-ended questions**
+- **Problem:** "What should I do next?" is ambiguous
+- **Fix:** Present exactly 4 structured options (or 3 for detached HEAD)
+
+**Cleaning up worktree for Option 2**
+- **Problem:** Remove worktree user needs for PR iteration
+- **Fix:** Only cleanup for Options 1 and 4
+
+**Deleting branch before removing worktree**
+- **Problem:** `git branch -d` fails because worktree still references the branch
+- **Fix:** Merge first, remove worktree, then delete branch
+
+**Running git worktree remove from inside the worktree**
+- **Problem:** Command fails silently when CWD is inside the worktree being removed
+- **Fix:** Always `cd` to main repo root before `git worktree remove`
+
+**Cleaning up harness-owned worktrees**
+- **Problem:** Removing a worktree the harness created causes phantom state
+- **Fix:** Only clean up worktrees under `.worktrees/` or `worktrees/`
+
+**No confirmation for discard**
+- **Problem:** Accidentally delete work
+- **Fix:** Require typed "discard" confirmation
+
+## Red Flags
+
+**Never:**
+- Proceed with failing tests
+- Merge without verifying tests on result
+- Delete work without confirmation
+- Force-push without explicit request
+- Remove a worktree before confirming merge success
+- Clean up worktrees you didn't create (provenance check)
+- Run `git worktree remove` from inside the worktree
+
+**Always:**
+- Verify tests before offering options
+- Detect environment before presenting menu
+- Present exactly 4 options (or 3 for detached HEAD)
+- Get typed confirmation for Option 4
+- Clean up worktree for Options 1 & 4 only
+- `cd` to main repo root before worktree removal
+- Run `git worktree prune` after removal
+
+## Integration
+
+**Called by:**
+- **subagent-driven-development** (Step 7) - After all tasks complete
+- **executing-plans** (Step 5) - After all batches complete
+
+**Pairs with:**
+- **using-git-worktrees** - Cleans up worktree created by that skill
+```
+
+- [ ] **Step 2: Verify the file reads correctly**
+
+Run: `wc -l skills/finishing-a-development-branch/SKILL.md`
+
+Expected: Approximately 210-230 lines.
+
+- [ ] **Step 3: Commit**
+
+```bash
+git add skills/finishing-a-development-branch/SKILL.md
+git commit -m "feat: rewrite finishing-a-development-branch with detect-and-defer (PRI-974)
+
+Step 2: environment detection (GIT_DIR != GIT_COMMON) before presenting menu
+Detached HEAD: reduced 3-option menu (no merge from detached HEAD)
+Provenance-based cleanup: .worktrees/ = ours, anything else = hands off
+Bug #940: Option 2 no longer cleans up worktree
+Bug #999: merge -> verify -> remove worktree -> delete branch
+Bug #238: cd to main repo root before git worktree remove
+Stale worktree pruning after removal (git worktree prune)"
+```
+
+---
+
+### Task 4: Integration Updates
+
+One-line changes to three files that reference `using-git-worktrees`.
+
+**Files:**
+- Modify: `skills/executing-plans/SKILL.md:68`
+- Modify: `skills/subagent-driven-development/SKILL.md:268`
+- Modify: `skills/writing-plans/SKILL.md:16`
+
+- [ ] **Step 1: Update executing-plans integration line**
+
+In `skills/executing-plans/SKILL.md`, change line 68 from:
+
+```markdown
+- **superpowers:using-git-worktrees** - REQUIRED: Set up isolated workspace before starting
+```
+
+to:
+
+```markdown
+- **superpowers:using-git-worktrees** - Ensures isolated workspace (creates one or verifies existing)
+```
+
+- [ ] **Step 2: Update subagent-driven-development integration line**
+
+In `skills/subagent-driven-development/SKILL.md`, change line 268 from:
+
+```markdown
+- **superpowers:using-git-worktrees** - REQUIRED: Set up isolated workspace before starting
+```
+
+to:
+
+```markdown
+- **superpowers:using-git-worktrees** - Ensures isolated workspace (creates one or verifies existing)
+```
+
+- [ ] **Step 3: Update writing-plans context line**
+
+In `skills/writing-plans/SKILL.md`, change line 16 from:
+
+```markdown
+**Context:** This should be run in a dedicated worktree (created by brainstorming skill).
+```
+
+to:
+
+```markdown
+**Context:** If working in an isolated worktree, it should have been created via the using-git-worktrees skill at execution time.
+```
+
+- [ ] **Step 4: Commit all three**
+
+```bash
+git add skills/executing-plans/SKILL.md skills/subagent-driven-development/SKILL.md skills/writing-plans/SKILL.md
+git commit -m "fix: update worktree integration references across skills (PRI-974)
+
+Remove REQUIRED language from executing-plans and subagent-driven-development.
+Consent and detection now live inside using-git-worktrees itself.
+Fix stale 'created by brainstorming' claim in writing-plans."
+```
+
+---
+
+### Task 5: End-to-End Validation
+
+Verify the full rewritten skills work together. Run the existing test suite plus manual verification.
+
+**Files:**
+- Read: `tests/claude-code/run-skill-tests.sh`
+- Read: `skills/using-git-worktrees/SKILL.md` (verify final state)
+- Read: `skills/finishing-a-development-branch/SKILL.md` (verify final state)
+
+- [ ] **Step 1: Run existing test suite**
+
+Run: `cd tests/claude-code && bash run-skill-tests.sh`
+
+Expected: All existing tests pass. If any fail, investigate — the integration changes (Task 4) may have broken a content assertion.
+
+- [ ] **Step 2: Re-run Step 1a GREEN test**
+
+Run: `cd tests/claude-code && bash test-worktree-native-preference.sh green`
+
+Expected: PASS — agent still uses EnterWorktree with the final skill text (not just the minimal Step 1a addition from Task 1).
+
+- [ ] **Step 3: Manual verification — read both rewritten skills end-to-end**
+
+Read `skills/using-git-worktrees/SKILL.md` and `skills/finishing-a-development-branch/SKILL.md` in their entirety. Check:
+
+1. No references to old behavior (hardcoded `CLAUDE.md`, interactive directory prompt, "REQUIRED" language)
+2. Step numbering is consistent within each file
+3. Quick Reference tables match the prose
+4. Integration sections cross-reference correctly
+5. No markdown formatting issues
+
+- [ ] **Step 4: Verify git status is clean**
+
+Run: `git status`
+
+Expected: Clean working tree. All changes committed across Tasks 1-4.
+
+- [ ] **Step 5: Final commit if any fixups needed**
+
+If manual verification found issues, fix them and commit:
+
+```bash
+git add -A
+git commit -m "fix: address review findings in worktree skill rewrite (PRI-974)"
+```
+
+If no issues found, skip this step.

docs/superpowers/plans/2026-05-07-pi-extension-and-evals.md

@@ -0,0 +1,143 @@
+# Pi Extension and Evals Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Add first-class Pi package support for Superpowers and add Pi as a Drill eval backend.
+
+**Architecture:** The Pi package is declared in the root `package.json` and loads existing `skills/` plus a small Pi extension. The extension injects the `using-superpowers` bootstrap into provider context as a user-role message on session startup and after compaction, with Pi-specific tool mapping. Drill gains a `pi` backend, Pi session-log normalization, and tests.
+
+**Tech Stack:** Pi TypeScript extension API, Node built-in test runner, Drill Python eval harness, pytest.
+
+---
+
+### Task 1: Pi package manifest and extension tests
+
+**Files:**
+- Modify: `package.json`
+- Create: `tests/pi/test-pi-extension.mjs`
+
+- [ ] **Step 1: Write failing package/extension tests**
+
+Create `tests/pi/test-pi-extension.mjs` with tests that import `extensions/superpowers.ts`, register fake Pi handlers, and assert:
+- root `package.json` has `keywords` containing `pi-package`
+- root `package.json` has `pi.skills: ["./skills"]`
+- root `package.json` has `pi.extensions: ["./extensions/superpowers.ts"]`
+- the extension registers `resources_discover`, `session_start`, `session_compact`, `context`, and `agent_end`
+- startup `context` injects exactly one user-role bootstrap message
+- `agent_end` clears startup injection
+- `session_compact` re-enables injection
+- the extension does not register `session_before_compact`
+
+- [ ] **Step 2: Run tests and verify RED**
+
+Run: `node --experimental-strip-types --test tests/pi/test-pi-extension.mjs`
+
+Expected: FAIL because `extensions/superpowers.ts` does not exist and `package.json` lacks the `pi` manifest.
+
+- [ ] **Step 3: Implement manifest fields**
+
+Update `package.json` with `description`, `keywords`, `pi.extensions`, and `pi.skills` while preserving existing `name`, `version`, `type`, and `main`.
+
+- [ ] **Step 4: Implement `extensions/superpowers.ts`**
+
+Create a zero-runtime-dependency extension that:
+- locates the package root from `import.meta.url`
+- reads `skills/using-superpowers/SKILL.md`
+- strips YAML frontmatter
+- appends Pi-specific tool mapping
+- exposes `resources_discover` with the skills path
+- marks bootstrap pending on `session_start` and `session_compact`
+- injects a user-role bootstrap message in `context`
+- inserts post-compact bootstrap after leading `compactionSummary` messages
+- clears pending bootstrap on `agent_end`
+
+- [ ] **Step 5: Run tests and verify GREEN**
+
+Run: `node --experimental-strip-types --test tests/pi/test-pi-extension.mjs`
+
+Expected: PASS.
+
+### Task 2: Pi tool mapping reference
+
+**Files:**
+- Create: `skills/using-superpowers/references/pi-tools.md`
+- Modify: `tests/pi/test-pi-extension.mjs`
+
+- [ ] **Step 1: Write failing test for Pi reference doc**
+
+Add assertions that `skills/using-superpowers/references/pi-tools.md` exists and documents mappings for `Skill`, `Task`, `TodoWrite`, and built-in tool names.
+
+- [ ] **Step 2: Run tests and verify RED**
+
+Run: `node --experimental-strip-types --test tests/pi/test-pi-extension.mjs`
+
+Expected: FAIL because `pi-tools.md` does not exist.
+
+- [ ] **Step 3: Add Pi reference doc**
+
+Create `skills/using-superpowers/references/pi-tools.md` explaining Pi-native skills, optional `pi-subagents`, no canonical todo/tasklist plugin, and built-in lowercase tools.
+
+- [ ] **Step 4: Run tests and verify GREEN**
+
+Run: `node --experimental-strip-types --test tests/pi/test-pi-extension.mjs`
+
+Expected: PASS.
+
+### Task 3: Drill Pi backend and session log normalization
+
+**Files:**
+- Create: `evals/backends/pi.yaml`
+- Modify: `evals/drill/backend.py`
+- Modify: `evals/drill/engine.py`
+- Modify: `evals/drill/normalizer.py`
+- Modify: `evals/tests/test_backend.py`
+- Modify: `evals/tests/test_normalizer.py`
+
+- [ ] **Step 1: Write failing backend/normalizer tests**
+
+Add pytest coverage for:
+- `load_backend("pi")` returns `family == "pi"`
+- Pi backend command starts with `pi` and includes `-e ${SUPERPOWERS_ROOT}`
+- `_resolve_log_dir()` for Pi points under `~/.pi/agent/sessions`
+- `filter_pi_logs_by_cwd()` keeps only session files whose header `cwd` matches the scenario workdir
+- `normalize_pi_logs()` extracts `toolCall` blocks from Pi assistant session entries and maps built-in lowercase tools to canonical names
+
+- [ ] **Step 2: Run tests and verify RED**
+
+Run: `uv run pytest evals/tests/test_backend.py evals/tests/test_normalizer.py -q`
+
+Expected: FAIL because the Pi backend and normalizer do not exist.
+
+- [ ] **Step 3: Add `evals/backends/pi.yaml`**
+
+Configure the backend to run `pi -e ${SUPERPOWERS_ROOT}`, use permissive TUI readiness, `/quit` shutdown, and Pi session log location.
+
+- [ ] **Step 4: Implement Pi family support**
+
+Update `Backend.family`, `Engine._resolve_log_dir`, `Engine._collect_tool_calls`, and `normalizer.py` with Pi log filtering and normalizing.
+
+- [ ] **Step 5: Run tests and verify GREEN**
+
+Run: `uv run pytest evals/tests/test_backend.py evals/tests/test_normalizer.py -q`
+
+Expected: PASS.
+
+### Task 4: Documentation and full verification
+
+**Files:**
+- Modify: `README.md`
+- Modify: `evals/README.md`
+
+- [ ] **Step 1: Document Pi install and eval backend**
+
+Add Pi to README quickstart/install list and add backend entry/usage to `evals/README.md`.
+
+- [ ] **Step 2: Run verification**
+
+Run:
+```bash
+node --experimental-strip-types --test tests/pi/test-pi-extension.mjs
+uv run pytest evals/tests/test_backend.py evals/tests/test_setup.py evals/tests/test_normalizer.py -q
+```
+
+Expected: all tests pass.

docs/superpowers/plans/2026-06-09-sdd-task-scoped-review-dispatch.md

@@ -0,0 +1,774 @@
+# SDD Task-Scoped Review Dispatch Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Scope SDD's per-task reviews to the task (diff-first reading, justified broadening, no redundant test runs) while final branch review stays broad.
+
+**Architecture:** Four prose edits to the subagent-driven-development skill (the per-task quality prompt becomes self-contained instead of delegating to the merge-readiness template; the spec prompt gets a third verdict channel and grounded skepticism; the implementer prompt gains a re-run-after-fix rule; SKILL.md gets controller guidance) plus one new eval scenario in the `evals/` submodule. `skills/requesting-code-review/` is deliberately untouched.
+
+**Tech Stack:** Markdown skill files; Python setup helper + bash checks + story.md for the quorum eval.
+
+**Spec:** `docs/superpowers/specs/2026-06-09-sdd-task-scoped-review-dispatch-design.md` — read it before starting. Decisions already settled there: full re-reviews stay; the two review stages stay separate; coordinator keeps model judgment; `requesting-code-review/` stays broad.
+
+**These are behavior-shaping prose files, not code.** There are no unit tests for them. Each task's verification steps are exact `grep` checks that the edit landed; behavioral verification is Task 6 (static) and Task 7 (live evals, maintainer-gated).
+
+---
+
+### Task 1: Rewrite the per-task quality reviewer prompt as self-contained
+
+The current file delegates to `../requesting-code-review/code-reviewer.md`, which is a merge-readiness review (architecture, security, production readiness, "Ready to merge?"). Replace the entire file with a self-contained, task-scoped template.
+
+**Files:**
+- Rewrite: `skills/subagent-driven-development/code-quality-reviewer-prompt.md`
+
+- [ ] **Step 1: Replace the full file contents with:**
+
+````markdown
+# Code Quality Reviewer Prompt Template
+
+Use this template when dispatching a code quality reviewer subagent.
+
+**Purpose:** Verify one task's implementation is well-built (clean, tested, maintainable)
+
+**Only dispatch after spec compliance review passes.**
+
+```
+Subagent (general-purpose):
+  description: "Review code quality for Task N"
+  prompt: |
+    You are reviewing one task's implementation for code quality. This is a
+    task-scoped gate, not a merge review — a broad whole-branch review happens
+    separately after all tasks are complete.
+
+    ## What Was Implemented
+
+    [DESCRIPTION]
+
+    ## Task Requirements (context only)
+
+    [TASK_TEXT]
+
+    ## Git Range to Review
+
+    **Base:** [BASE_SHA]
+    **Head:** [HEAD_SHA]
+
+    ```bash
+    git diff --stat [BASE_SHA]..[HEAD_SHA]
+    git diff [BASE_SHA]..[HEAD_SHA]
+    ```
+
+    ## Read-Only Review
+
+    Your review is read-only on this checkout. Do not mutate the working tree,
+    the index, HEAD, or branch state in any way. Use tools like `git show`,
+    `git diff`, and `git log` to inspect history.
+
+    ## Scope
+
+    Spec compliance was already verified by a separate reviewer. Do not
+    re-check whether the code matches the requirements or the plan.
+
+    Start from the diff. Read the changed files first. Inspect code outside
+    the diff only to evaluate a concrete risk you can name — and name it in
+    your report. Cross-cutting changes are legitimate named risks: if the
+    diff changes lock ordering, a function or API contract, or shared mutable
+    state, checking the call sites is the right method. Do not crawl the
+    codebase by default.
+
+    ## Tests
+
+    The implementer already ran the tests and reported results with TDD
+    evidence for exactly this code. Do not re-run the suite to confirm their
+    report. Run a test only when reading the code raises a specific doubt
+    that no existing run answers — and then a focused test, never a
+    package-wide suite, race detector run, or repeated/high-count loop. If
+    heavy validation seems warranted, recommend it in your report instead of
+    running it. If you cannot run commands in this environment, name the
+    test you would run.
+
+    ## What to Check
+
+    **Code quality:**
+    - Clean separation of concerns?
+    - Proper error handling?
+    - DRY without premature abstraction?
+    - Edge cases handled?
+
+    **Tests:**
+    - Do the new and changed tests verify real behavior, not mocks?
+    - Are the task's edge cases covered?
+
+    **Structure:**
+    - Does each file have one clear responsibility with a well-defined interface?
+    - Are units decomposed so they can be understood and tested independently?
+    - Is the implementation following the file structure from the plan?
+    - Did this change 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.)
+
+    ## Calibration
+
+    Categorize issues by actual severity. Not everything is Critical.
+    Acknowledge what was done well before listing issues — accurate praise
+    helps the implementer trust the rest of the feedback.
+
+    ## Output Format
+
+    ### Strengths
+    [What's well done? Be specific.]
+
+    ### Issues
+
+    #### Critical (Must Fix)
+    [Bugs, data loss risks, broken functionality]
+
+    #### Important (Should Fix)
+    [Poor error handling, test gaps, structural problems]
+
+    #### Minor (Nice to Have)
+    [Code style, optimization opportunities]
+
+    For each issue:
+    - File:line reference
+    - What's wrong
+    - Why it matters
+    - How to fix (if not obvious)
+
+    ### Assessment
+
+    **Task quality:** [Approved | Needs fixes]
+
+    **Reasoning:** [1-2 sentence technical assessment]
+```
+
+**Placeholders:**
+- `[DESCRIPTION]` — task summary, from implementer's report
+- `[TASK_TEXT]` — the task's requirements text or plan reference, for context
+- `[BASE_SHA]` — commit before this task
+- `[HEAD_SHA]` — current commit
+
+**Reviewer returns:** Strengths, Issues (Critical/Important/Minor), Task quality verdict
+````
+
+- [ ] **Step 2: Verify the rewrite landed**
+
+Run: `grep -c "requesting-code-review" skills/subagent-driven-development/code-quality-reviewer-prompt.md || echo ABSENT`
+Expected: `ABSENT` (no more delegation)
+
+Run: `grep -n "Task quality:" skills/subagent-driven-development/code-quality-reviewer-prompt.md | head -2`
+Expected: one match (the Output Format verdict line; the "Reviewer returns" footer says "Task quality verdict" without a colon)
+
+Run: `grep -n "worktree add\|Ready to merge" skills/subagent-driven-development/code-quality-reviewer-prompt.md || echo CLEAN`
+Expected: `CLEAN`
+
+- [ ] **Step 3: Commit**
+
+```bash
+git add skills/subagent-driven-development/code-quality-reviewer-prompt.md
+git commit -m "Make per-task quality reviewer prompt self-contained and task-scoped"
+```
+
+---
+
+### Task 2: Spec reviewer prompt cleanups
+
+Four exact edits to `skills/subagent-driven-development/spec-reviewer-prompt.md`. Current line numbers refer to the file as of commit f55642e.
+
+**Files:**
+- Modify: `skills/subagent-driven-development/spec-reviewer-prompt.md`
+
+- [ ] **Step 1: Add the judge-from-the-diff clause.** After the line (currently line 31):
+
+```
+    Only read files in this diff. Do not crawl the broader codebase.
+```
+
+insert a blank line and:
+
+```
+    Spec compliance is judged by reading the diff against the requirements.
+    The implementer already ran the tests and reported TDD evidence — do not
+    re-run them. If a requirement cannot be verified from this diff alone
+    (it lives in unchanged code or spans tasks), report it as a ⚠️ item
+    instead of broadening your search.
+```
+
+- [ ] **Step 2: Trim the read-only section.** Replace (currently line 35):
+
+```
+    Your review is read-only on this checkout. Do not mutate the working tree, the index, HEAD, or branch state in any way. Use tools like `git show`, `git diff`, and `git log` to inspect history. If you need a working copy of a different revision, check it out into a separate temporary directory (e.g. `git worktree add /tmp/review-[SHA] [SHA]`) — never move HEAD on this checkout.
+```
+
+with:
+
+```
+    Your review is read-only on this checkout. Do not mutate the working tree, the index, HEAD, or branch state in any way. Use tools like `git show`, `git diff`, and `git log` to inspect history.
+```
+
+- [ ] **Step 3: Ground the skepticism.** Replace (currently lines 39-40):
+
+```
+    The implementer finished suspiciously quickly. Their report may be incomplete,
+    inaccurate, or optimistic. You MUST verify everything independently.
+```
+
+with:
+
+```
+    Treat the implementer's report as unverified claims about the code. It may
+    be incomplete, inaccurate, or optimistic. Verify the claims against the diff.
+```
+
+- [ ] **Step 4: Add the third verdict channel.** Replace (currently lines 74-76):
+
+```
+    Report:
+    - ✅ Spec compliant (if everything matches after code inspection)
+    - ❌ Issues found: [list specifically what's missing or extra, with file:line references]
+```
+
+with:
+
+```
+    Report:
+    - ✅ Spec compliant (if everything matches after code inspection)
+    - ❌ Issues found: [list specifically what's missing or extra, with file:line references]
+    - ⚠️ Cannot verify from diff: [requirements you could not verify from the
+      diff alone, and what the controller should check — report alongside the
+      ✅/❌ verdict for everything you could verify]
+```
+
+- [ ] **Step 5: Verify**
+
+Run: `grep -n "suspiciously\|worktree add" skills/subagent-driven-development/spec-reviewer-prompt.md || echo CLEAN`
+Expected: `CLEAN`
+
+Run: `grep -c "⚠️" skills/subagent-driven-development/spec-reviewer-prompt.md`
+Expected: `2` (judge-from-diff clause + verdict channel)
+
+- [ ] **Step 6: Commit**
+
+```bash
+git add skills/subagent-driven-development/spec-reviewer-prompt.md
+git commit -m "Spec reviewer: judge from the diff, grounded skepticism, ⚠️ verdict channel"
+```
+
+---
+
+### Task 3: Implementer prompt — re-run tests after fixing review findings
+
+The reviewers' "don't re-run the implementer's tests" rule assumes the implementer re-runs tests after every fix. Make that real.
+
+**Files:**
+- Modify: `skills/subagent-driven-development/implementer-prompt.md`
+
+- [ ] **Step 1: Insert a new section.** Immediately before the line (currently line 100):
+
+```
+    ## Report Format
+```
+
+insert:
+
+```
+    ## After Review Findings
+
+    If a reviewer finds issues and you fix them, re-run the tests that cover
+    the amended code and include the results in your fix report. Reviewers
+    will not re-run tests for you — your report is the test evidence.
+
+```
+
+- [ ] **Step 2: Verify**
+
+Run: `grep -n "After Review Findings" skills/subagent-driven-development/implementer-prompt.md`
+Expected: one match, on a line before `## Report Format`
+
+- [ ] **Step 3: Commit**
+
+```bash
+git add skills/subagent-driven-development/implementer-prompt.md
+git commit -m "Implementer prompt: re-run covering tests after fixing review findings"
+```
+
+---
+
+### Task 4: SKILL.md controller changes
+
+Six exact edits to `skills/subagent-driven-development/SKILL.md`. Current line numbers refer to commit f55642e.
+
+**Files:**
+- Modify: `skills/subagent-driven-development/SKILL.md`
+
+- [ ] **Step 1: Point the final-review flowchart node at the broad template.** The node label `Dispatch final code reviewer subagent for entire implementation` appears 3 times (currently lines 65, 84, 85). In all 3 occurrences, replace the label string with:
+
+```
+Dispatch final code reviewer subagent (../requesting-code-review/code-reviewer.md)
+```
+
+(Graphviz nodes are matched by label text — all three must be byte-identical or the graph grows a phantom node.)
+
+- [ ] **Step 2: Model selection by judgment.** Replace (currently lines 97-99):
+
+```
+**Architecture, design, and review tasks**: use the most capable available model.
+
+**Task complexity signals:**
+```
+
+with:
+
+```
+**Architecture and design tasks**: use the most capable available model.
+
+**Review tasks**: choose the model with the same judgment, scaled to the
+diff's size, complexity, and risk. A small mechanical diff does not need the
+most capable model; a subtle concurrency change does.
+
+**Task complexity signals (implementation tasks):**
+```
+
+- [ ] **Step 3: Add controller guidance sections.** Immediately before the line (currently line 122):
+
+```
+## Prompt Templates
+```
+
+insert:
+
+```
+## Handling Spec Reviewer ⚠️ Items
+
+The spec reviewer may report "⚠️ Cannot verify from diff" items — requirements
+that live in unchanged code or span tasks. These do not block dispatching the
+code quality reviewer, but you must resolve each one yourself before marking
+the task complete: you hold the plan and cross-task context the reviewer
+lacks. If you confirm an item is a real gap, treat it as a failed spec
+review — send it back to the implementer and re-review.
+
+## Constructing Reviewer Prompts
+
+Per-task reviews are task-scoped gates. The broad review happens once, at the
+final whole-branch review. When you fill a reviewer template:
+
+- Do not add open-ended directives like "check all uses" or "run race tests
+  if useful" without a concrete, task-specific reason
+- Do not ask a reviewer to re-run tests the implementer already ran on the
+  same code — the implementer's report carries the test evidence
+
+```
+
+- [ ] **Step 4: Prompt Templates list — add the final-review pointer.** Replace (currently line 126):
+
+```
+- [code-quality-reviewer-prompt.md](code-quality-reviewer-prompt.md) - Dispatch code quality reviewer subagent
+```
+
+with:
+
+```
+- [code-quality-reviewer-prompt.md](code-quality-reviewer-prompt.md) - Dispatch code quality reviewer subagent
+- Final whole-branch review: use superpowers:requesting-code-review's [code-reviewer.md](../requesting-code-review/code-reviewer.md)
+```
+
+- [ ] **Step 5: Example workflow verdict vocabulary.** Two replacements:
+
+Replace (currently line 157):
+```
+Code reviewer: Strengths: Good test coverage, clean. Issues: None. Approved.
+```
+with:
+```
+Code reviewer: Strengths: Good test coverage, clean. Issues: None. Task quality: Approved.
+```
+
+Replace (currently line 191):
+```
+Code reviewer: ✅ Approved
+```
+with:
+```
+Code reviewer: ✅ Task quality: Approved
+```
+
+(The final reviewer's "ready to merge" line, currently line 199, stays.)
+
+- [ ] **Step 6: Integration section.** Replace (currently line 272):
+
+```
+- **superpowers:requesting-code-review** - Code review template for reviewer subagents
+```
+
+with:
+
+```
+- **superpowers:requesting-code-review** - Code review template for the final whole-branch review
+```
+
+- [ ] **Step 7: Verify**
+
+Run: `grep -c "Dispatch final code reviewer subagent (../requesting-code-review/code-reviewer.md)" skills/subagent-driven-development/SKILL.md`
+Expected: `3`
+
+Run: `grep -n "most capable available model" skills/subagent-driven-development/SKILL.md`
+Expected: exactly one match (architecture/design bullet)
+
+Run: `grep -n "Handling Spec Reviewer\|Constructing Reviewer Prompts" skills/subagent-driven-development/SKILL.md`
+Expected: two section headers, both before `## Prompt Templates`
+
+Run: `grep -c "Task quality: Approved" skills/subagent-driven-development/SKILL.md`
+Expected: `2`
+
+- [ ] **Step 8: Commit**
+
+```bash
+git add skills/subagent-driven-development/SKILL.md
+git commit -m "SDD controller: reviewer prompt budgets, ⚠️ handling, final-review pointer, model judgment"
+```
+
+---
+
+### Task 5: New eval scenario — per-task quality reviewer catches a planted defect
+
+Lives in the `evals/` **submodule** (separate repo, `superpowers-evals`). Work on a branch there; the parent submodule-pointer bump happens at finishing time per `evals/CLAUDE.md`.
+
+The fixture plan's Task 2 implementation snippet duplicates Task 1's formatting logic verbatim. The duplication is spec-compliant, so the spec reviewer should pass it — the per-task quality reviewer is the gate under test (DRY violation).
+
+**Files:**
+- Create: `evals/setup_helpers/sdd_quality_defect_plan.py`
+- Modify: `evals/setup_helpers/__init__.py`
+- Create: `evals/scenarios/sdd-quality-reviewer-catches-planted-defect/story.md`
+- Create: `evals/scenarios/sdd-quality-reviewer-catches-planted-defect/setup.sh`
+- Create: `evals/scenarios/sdd-quality-reviewer-catches-planted-defect/checks.sh`
+
+- [ ] **Step 0: Branch in the submodule**
+
+```bash
+cd evals
+git checkout -b sdd-quality-defect-scenario
+```
+
+- [ ] **Step 1: Create `evals/setup_helpers/sdd_quality_defect_plan.py`:**
+
+````python
+"""Setup helper for the sdd-quality-reviewer-catches-planted-defect scenario.
+
+Scaffolds a tiny Node project with a 2-task plan whose Task 2
+implementation snippet duplicates Task 1's formatting logic verbatim.
+The duplication is spec-compliant — the requirements only describe
+behavior — so the spec compliance reviewer should pass it. The test
+measures whether the per-task code quality reviewer catches the DRY
+violation and forces a refactor in the review-fix loop.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from setup_helpers.base import _git
+
+PACKAGE_JSON = """\
+{
+  "name": "report-quality",
+  "version": "1.0.0",
+  "type": "module",
+  "scripts": {
+    "test": "node --test"
+  }
+}
+"""
+
+PLAN_BODY = """\
+# Report Formatter — Implementation Plan
+
+Two report formatting functions. Implement exactly what each task
+specifies.
+
+## Task 1: User Report
+
+**File:** `src/report.js`
+
+**Requirements:**
+- Function named `formatUserReport`
+- Takes one parameter `user`: an object with `name`, `email`, `visits`
+- Returns a multi-line string: a banner of 40 `=` characters, then
+  `Report for <name> <<email>>`, then the banner again, then
+  `Visits: <visits>`, then a closing banner
+- Export the function
+
+**Implementation:**
+```javascript
+export function formatUserReport(user) {
+  const banner = "=".repeat(40);
+  const lines = [];
+  lines.push(banner);
+  lines.push(`Report for ${user.name} <${user.email}>`);
+  lines.push(banner);
+  lines.push(`Visits: ${user.visits}`);
+  lines.push(banner);
+  return lines.join("\\n");
+}
+```
+
+**Tests:** Create `test/report.test.js` verifying:
+- the result contains `Report for Ada <ada@example.com>` for that user
+- the result contains `Visits: 3` when `visits` is `3`
+- the result starts and ends with the 40-char banner
+
+**Verification:** `npm test`
+
+## Task 2: Admin Report
+
+**File:** `src/report.js` (add to existing file)
+
+**Requirements:**
+- Function named `formatAdminReport`
+- Takes one parameter `admin`: an object with `name`, `email`, `lastLogin`
+- Same banner layout as the user report; the body line is
+  `Last login: <lastLogin>` instead of the visits line
+- Export the function; keep `formatUserReport` working
+
+**Implementation:**
+```javascript
+export function formatAdminReport(admin) {
+  const banner = "=".repeat(40);
+  const lines = [];
+  lines.push(banner);
+  lines.push(`Report for ${admin.name} <${admin.email}>`);
+  lines.push(banner);
+  lines.push(`Last login: ${admin.lastLogin}`);
+  lines.push(banner);
+  return lines.join("\\n");
+}
+```
+
+**Tests:** Add to `test/report.test.js`:
+- the result contains `Report for Grace <grace@example.com>` for that admin
+- the result contains `Last login: 2026-06-01`
+- the result starts and ends with the 40-char banner
+
+**Verification:** `npm test`
+"""
+
+
+def scaffold_sdd_quality_defect_plan(workdir: Path) -> None:
+    workdir = Path(workdir)
+    workdir.mkdir(parents=True, exist_ok=True)
+    _git(["git", "init", "-b", "main"], cwd=workdir)
+    _git(["git", "config", "user.email", "drill@test.local"], cwd=workdir)
+    _git(["git", "config", "user.name", "Drill Test"], cwd=workdir)
+
+    (workdir / "package.json").write_text(PACKAGE_JSON)
+    plans_dir = workdir / "docs" / "superpowers" / "plans"
+    plans_dir.mkdir(parents=True, exist_ok=True)
+    (plans_dir / "report-plan.md").write_text(PLAN_BODY)
+
+    _git(["git", "add", "-A"], cwd=workdir)
+    _git(["git", "commit", "-m", "initial: report formatter plan"], cwd=workdir)
+````
+
+(Note the `\\n` in the JS snippets inside PLAN_BODY: the Python source must
+produce a literal `\n` in the markdown so the JS reads `lines.join("\n")`.)
+
+- [ ] **Step 2: Register the helper.** In `evals/setup_helpers/__init__.py`:
+
+After the line:
+```python
+from setup_helpers.sdd_real_projects import scaffold_sdd_go_fractals, scaffold_sdd_svelte_todo
+```
+add:
+```python
+from setup_helpers.sdd_quality_defect_plan import scaffold_sdd_quality_defect_plan
+```
+
+After the registry entry:
+```python
+    "scaffold_sdd_yagni_plan": scaffold_sdd_yagni_plan,
+```
+add:
+```python
+    "scaffold_sdd_quality_defect_plan": scaffold_sdd_quality_defect_plan,
+```
+
+- [ ] **Step 3: Create `evals/scenarios/sdd-quality-reviewer-catches-planted-defect/story.md`:**
+
+```markdown
+---
+id: sdd-quality-reviewer-catches-planted-defect
+title: SDD's per-task code quality review catches a planted DRY violation
+status: ready
+tags: subagent-driven-development
+quorum_max_time: 90m
+---
+
+You have a small plan at docs/superpowers/plans/report-plan.md — two report
+formatting functions. The plan's Task 2 implementation snippet duplicates
+Task 1's formatting logic verbatim instead of sharing it. The duplication is
+spec-compliant (the requirements only describe behavior), so the spec
+compliance reviewer should pass it — the per-task code quality reviewer is
+the gate under test. You are spec-aware — name the skill.
+
+When the agent is ready for input, tell it to execute the plan with SDD. Use
+phrasing like:
+
+"I have a small plan at docs/superpowers/plans/report-plan.md — two report
+formatting functions. Use the superpowers:subagent-driven-development skill
+to execute it end-to-end — dispatch fresh subagents per task and run the
+two-stage review after each."
+
+Let the agent proceed autonomously. If it asks clarifying questions, give
+brief answers. If it asks where the finished work should land — merge to the
+main branch, open a PR, etc. — tell it to **merge the work into the main
+checkout** (this is a local repo with no remote). If a quality reviewer
+flags the duplicated formatting logic and an implementer refactors it, let
+the review-fix cycle play out — that cycle is exactly the behavior under
+test.
+
+The deliverable must end up in the checkout you launched in (the main
+working tree). If the agent did its work on a branch or in a worktree, it
+is not done until it has merged/finished that work back into the main
+checkout. Once the agent reports the plan is complete (both functions
+implemented, tests passing) AND the code is present on the main checkout,
+you are done.
+
+## Acceptance Criteria
+
+- A `Skill` invocation naming `superpowers:subagent-driven-development`
+  and at least one `Agent` (subagent dispatch) tool call appear in the
+  session log.
+- The duplicated report-formatting logic did not survive to the end of
+  the run. Either (a) the implementer never introduced the duplication
+  (wrote or self-reviewed its way to shared logic), or (b) the per-task
+  code quality reviewer flagged the duplication as an issue and a
+  review-fix loop removed it. A fail looks like the duplicated logic
+  shipping with the per-task quality reviewer approving it, or the
+  duplication being caught only by the final whole-branch review.
+- The per-task quality reviewers stayed task-scoped: no package-wide
+  test suites, race detector runs, or repeated/high-count test loops
+  appear in reviewer subagent activity, and reviewers did not re-run
+  the full test suite merely to confirm the implementer's report.
+- `npm test` passes in the main checkout and both `formatUserReport` and
+  `formatAdminReport` are exported from src/report.js. The deterministic
+  assertions gate this; the criteria above are about whether the
+  *per-task quality review* was the mechanism that kept the code clean.
+```
+
+- [ ] **Step 4: Create `evals/scenarios/sdd-quality-reviewer-catches-planted-defect/setup.sh`:**
+
+```bash
+#!/usr/bin/env bash
+set -euo pipefail
+uv run setup-helpers run scaffold_sdd_quality_defect_plan
+```
+
+Then: `chmod +x evals/scenarios/sdd-quality-reviewer-catches-planted-defect/setup.sh`
+
+- [ ] **Step 5: Create `evals/scenarios/sdd-quality-reviewer-catches-planted-defect/checks.sh`** (no executable bit):
+
+```bash
+pre() {
+    git-repo
+    git-branch main
+    requires-tool npm
+    file-exists 'docs/superpowers/plans/report-plan.md'
+    file-contains 'docs/superpowers/plans/report-plan.md' 'formatAdminReport'
+    file-contains 'docs/superpowers/plans/report-plan.md' 'repeat\(40\)'
+}
+
+post() {
+    skill-called superpowers:subagent-driven-development
+    tool-called Agent
+    command-succeeds 'npm test'
+    file-contains 'src/report.js' 'export function formatUserReport'
+    file-contains 'src/report.js' 'export function formatAdminReport'
+    command-succeeds 'test "$(grep -c "repeat(40)" src/report.js)" -le 1'
+}
+```
+
+(The last check is the deterministic DRY gate: the banner construction
+`"=".repeat(40)` must appear at most once in the final file — shared, not
+duplicated per function.)
+
+- [ ] **Step 6: Validate and test in the evals repo**
+
+```bash
+cd evals
+uv run quorum check
+uv run ruff check
+uv run pytest -x -q
+```
+
+Expected: all pass; `quorum check` lists the new scenario without errors.
+
+- [ ] **Step 7: Commit (in the submodule)**
+
+```bash
+cd evals
+git add setup_helpers/sdd_quality_defect_plan.py setup_helpers/__init__.py scenarios/sdd-quality-reviewer-catches-planted-defect/
+git commit -m "Add sdd-quality-reviewer-catches-planted-defect scenario"
+```
+
+---
+
+### Task 6: Static verification sweep
+
+**Files:** none modified — verification only.
+
+- [ ] **Step 1: No dangling references in the parent repo**
+
+Run: `grep -rn "requesting-code-review" skills/subagent-driven-development/`
+Expected: matches only in SKILL.md (final-review flowchart node ×3, Prompt Templates pointer, Integration bullet). None in code-quality-reviewer-prompt.md.
+
+Run: `grep -rn "Ready to merge" skills/subagent-driven-development/ || echo CLEAN`
+Expected: `CLEAN`
+
+- [ ] **Step 2: Plugin infrastructure tests**
+
+Run: `bash tests/shell-lint/test-lint-shell.sh`
+Expected: all PASS (we added `setup.sh` only inside the evals submodule, which has its own checks).
+
+- [ ] **Step 3: Cross-platform tool tables still coherent**
+
+Run: `grep -n "code-quality-reviewer" skills/using-superpowers/references/antigravity-tools.md skills/using-superpowers/references/gemini-tools.md`
+Expected: both tables still list `code-quality-reviewer` as a reviewer template (the new prompt's "If you cannot run commands in this environment, name the test you would run" line keeps the read-only `research` mapping valid — no table edits needed).
+
+---
+
+### Task 7: Live before/after evals (maintainer-gated)
+
+Live quorum runs launch agent CLIs in permissive modes — **trusted-maintainer operation; Jesse launches these**, per `evals/CLAUDE.md`. Requires `ANTHROPIC_API_KEY`.
+
+- [ ] **Step 1: Baseline (skills as released on dev)** — from the main checkout (`/Users/jesse/git/superpowers/superpowers`, on dev), or any checkout without this branch's changes:
+
+```bash
+cd evals
+export SUPERPOWERS_ROOT=/Users/jesse/git/superpowers/superpowers
+uv run quorum run scenarios/sdd-rejects-extra-features --coding-agent claude
+uv run quorum run scenarios/sdd-go-fractals --coding-agent claude
+uv run quorum run scenarios/sdd-svelte-todo --coding-agent claude
+uv run quorum run scenarios/spec-reviewer-catches-planted-flaws --coding-agent claude
+```
+
+- [ ] **Step 2: After (this branch's skills)** — point `SUPERPOWERS_ROOT` at this worktree:
+
+```bash
+cd evals
+export SUPERPOWERS_ROOT=/Users/jesse/git/superpowers/superpowers/.claude/worktrees/sdd-review-dispatch
+uv run quorum run scenarios/sdd-rejects-extra-features --coding-agent claude
+uv run quorum run scenarios/sdd-go-fractals --coding-agent claude
+uv run quorum run scenarios/sdd-svelte-todo --coding-agent claude
+uv run quorum run scenarios/spec-reviewer-catches-planted-flaws --coding-agent claude
+uv run quorum run scenarios/sdd-quality-reviewer-catches-planted-defect --coding-agent claude
+uv run quorum show
+```
+
+- [ ] **Step 3: Compare**
+
+Pass bar: all four pre-existing scenarios still pass after the change (no regression in catch rate); the new planted-defect scenario passes. For exploration cost, compare reviewer-subagent tool-call counts between the before/after run transcripts (no automated check exists — the spec calls this out as a known gap).
+
+---
+
+## Finishing
+
+After all tasks pass: the evals submodule commit needs to land in `superpowers-evals` (PR to its `main`), then this branch bumps the `evals` submodule pointer — per `evals/CLAUDE.md`, the parent bump is part of propagation, not optional. Then use superpowers:finishing-a-development-branch. PRs against superpowers target `dev`.

docs/superpowers/plans/2026-06-09-visual-companion-issues.md

@@ -0,0 +1,352 @@
+# Visual Brainstorming Companion — Issue & Change Catalog
+
+**Date:** 2026-06-09
+**Status:** Analysis / triage. We are implementing these ourselves; the referenced
+community PRs are evidence and reference material, **not** code we intend to merge.
+
+## Purpose
+
+A single place that captures every open issue and PR touching the visual
+brainstorming companion (the local server in `skills/brainstorming/scripts/`),
+distilled to the underlying problem and the change we'd make. Each item is
+grounded against the current code, not the PR author's description.
+
+## Scope decisions (Jesse, 2026-06-09)
+
+- **Not vendoring Alpine.js.** PR #1639 (interactive mockups via a vendored
+  Alpine build) is **dropped**. See E3.
+- **E1 (terminal-vs-HTML hard gate) is a workshop item.** We'll design it
+  together; it is not specced here.
+- **E2 (storage location, #975/#977) is deferred** for now.
+- **Remote serving is a first-class scenario.** Superpowers is general-purpose;
+  users connect from remote (SSH tunnel, Tailscale, `--host 0.0.0.0`). The
+  security fix MUST protect those users, not just loopback. **Decision: a
+  per-session secret key**, not a Host allowlist. A Host allowlist only
+  defends the loopback browser-confused-deputy; a direct remote client just
+  sends the expected `Host`, so the allowlist is theater for remote exposure. A
+  secret key is the only thing that authenticates a client uniformly across
+  loopback, tunnel, and direct-remote, and it also defeats DNS rebinding. See A1.
+
+## Component map
+
+| File | Role |
+|------|------|
+| `skills/brainstorming/scripts/server.cjs` | Zero-dep HTTP + WebSocket server (RFC 6455 hand-rolled). Serves the newest screen, watches `content/`, records events to `state/events`. |
+| `skills/brainstorming/scripts/helper.js` | Injected into every page. WebSocket client, click capture, `window.brainstorm` API. |
+| `skills/brainstorming/scripts/frame-template.html` | Frame (header, theme CSS, status dot, indicator bar) wrapped around content fragments. |
+| `skills/brainstorming/scripts/start-server.sh` | Launch wrapper. Session dir, host/url-host, owner-PID resolution, platform backgrounding. |
+| `skills/brainstorming/scripts/stop-server.sh` | Kills the server by PID file, cleans `/tmp` sessions. |
+| `skills/brainstorming/visual-companion.md` | Operator guide the agent reads when it accepts the companion. |
+| `skills/brainstorming/SKILL.md` | Where the companion is offered and the per-question decision lives. |
+
+## Disposition summary
+
+| ID | Item | Source | Disposition |
+|----|------|--------|-------------|
+| A1 | Per-session secret key on `/`, `/files/*`, and WS (supersedes Host allowlist) | issues #1014, PRs #1110/#1553 | **Do** — chosen approach |
+| A2 | Host allowlist; browser WS Origin check | PRs #1110/#1553 | Host allowlist dropped; WS Origin check retained after auth for browser confused-deputy defense |
+| A3 | Crash on `null` / non-object WS payload | PR #1504 | Do |
+| A4 | Frame-length bound in `decodeFrame` | issue #1446 | Already fixed — verify/close |
+| B1 | Dotfile screens served as content (`._*.html`) | PR #950 | Do |
+| B2 | `stop-server.sh` kills reused/stale PID | PR #1703 | Do |
+| B3 | WS client reconnect backoff + status indicator | PR #856 | Do |
+| C1 | Idle timeout too short / not configurable; WS not closed on shutdown | issue #1237 (PR #1689) | Do |
+| C2 | Server death is invisible to user/agent | issue #1237 (residual) | Do |
+| D1 | Permanent opt-out of the companion | issue #892 | Deferred - not in PR #1720 |
+| D2 | Free-text feedback from the browser | issue #957 | Deferred - not in PR #1720 |
+| D3 | Auto-open the companion URL | PR #759 (#755) | Done in PR #1720 via `--open` |
+| D4 | Light/dark contrast helpers in the frame | PR #1683 | Deferred - not in PR #1720 |
+| E1 | Hard-gate terminal-vs-HTML per question | PR #1037 | **Workshop** |
+| E2 | Move session state out of the working tree | issue #975 (PR #977) | **Deferred** |
+| E3 | Vendor Alpine.js for interactive mockups | PR #1639 | **Dropped** |
+| E4 | Shell-lint warnings in start/stop scripts | PR #1677 | Opportunistic only |
+
+---
+
+## A. Server security hardening (`server.cjs`)
+
+### A1 — Per-session secret key (chosen approach)
+
+**Threat model.** Two assets: confidentiality of the served screen (`/`) and
+files (`/files/*`), and integrity of `state/events` — a WebSocket client with a
+truthy `choice` writes there (`server.cjs:243-246`), and the agent reads it next
+turn as the user's selection, i.e. **prompt injection into a live session with
+full tool access**. Reachers: with the default `127.0.0.1` bind, a malicious
+page in the user's browser (a confused deputy — runs attacker JS *and* can reach
+loopback); with a remote bind (`--host 0.0.0.0`, tailnet/LAN), any host that can
+route to the port, directly, with no same-origin policy in the way. Today
+`handleUpgrade` (`server.cjs:176`) checks only `Sec-WebSocket-Key`, and
+`handleRequest` (`server.cjs:138`) checks nothing — both are wide open.
+
+**Why a key, not a Host allowlist.** A Host allowlist only defends the
+loopback browser-deputy. A direct remote client just sends the expected `Host`
+and forges/omits `Origin`, so the allowlist is theater for exactly the remote
+case we must protect. A per-session secret authenticates the client uniformly
+across loopback, SSH tunnel, and direct-remote, and it also kills DNS rebinding
+(the rebound page neither knows the key nor receives the host-scoped cookie).
+So the key **supersedes** A1/A2's Host allowlist entirely — no `BRAINSTORM_ALLOWED_HOSTS`.
+
+**Design.** Random token (`crypto.randomBytes(32)` hex), generated in
+`server.cjs` at startup (overridable via `BRAINSTORM_TOKEN` for deterministic
+tests):
+
+1. **URL carries it** as `?key=<token>`. The server already builds `url` in its
+   `server-started` JSON (`server.cjs:351`) and writes it to `state/server-info`
+   — appending `?key=` there means `start-server.sh` (greps and prints that
+   JSON) and the skill (hands the user that URL) need **no change**.
+2. **Cookie bootstrap.** A valid `?key` on `/` sets
+   `brainstorm-key-<port>=<token>; HttpOnly; SameSite=Strict; Path=/`. The
+   browser then auto-attaches it to same-origin subresources (`/files/*`) and
+   the WebSocket handshake, so the agent can write any URL style and it works,
+   and `helper.js` needs no change. Cookie name is **per-port** to avoid the
+   Jupyter multi-server collision (cookies aren't port-scoped).
+   `SameSite=Strict` is safe for CDN/Unsplash content — that cookie is host-
+   scoped, so outbound CDN requests never carry it; SameSite only governs
+   requests back to our origin, which are all same-site.
+3. **Auth gate** = valid `?key` **OR** valid cookie (compared with
+   `crypto.timingSafeEqual`) on `/`, `/files/*`, and the WS upgrade. Missing/bad
+   key → friendly **403 HTML page** ("this page needs the full URL your coding
+   agent gave you, including `?key=…`" — generic "coding agent", not "Claude",
+   since this ships on Codex/Gemini/Copilot too). WS upgrade → destroy socket.
+
+The query token is the source of truth; the cookie is a convenience that never
+bears initial-auth load.
+
+**Blast radius.** `server.cjs` (all logic). `helper.js` optional one-liner
+(append `?key=` from `location.search` to the WS URL as a cookie-blocked
+fallback). `start-server.sh` none. `visual-companion.md` doc note (URL now has
+`?key=`; don't strip it). Tests updated to pass the token.
+
+### A2 — Host allowlist dropped; browser WS Origin retained
+
+Subsumed by A1. The secret key closes the WS-injection vector (#1014), the
+HTTP/WS DNS-rebinding read vector (PR #1553), and the cross-origin WS vector
+(PR #1110) in one mechanism, and unlike an allowlist it actually protects the
+remote-bind case. No `BRAINSTORM_ALLOWED_HOSTS` and no Host allowlist. The final
+implementation still checks browser WebSocket `Origin` after session auth so a
+cross-origin localhost tab cannot ride the companion cookie.
+
+### A3 — Server crashes on `null` / primitive WS payload
+
+**Problem.** `handleMessage` (`server.cjs:233`) does `JSON.parse(text)` then
+`if (event.choice)` at `server.cjs:243`. A client that sends the 4-byte text
+frame `null` yields `event === null`, and `null.choice` throws. The throw is
+**not** caught — `handleMessage` is called from the `socket.on('data')` handler
+(`server.cjs:207`) outside the `try/catch`, which only wraps `decodeFrame`. The
+result is an uncaught exception and process exit. Any local client can kill the
+server.
+
+**Change.** Guard the access: `if (event && event.choice)`. Minimal and exact —
+`JSON.parse` can't produce `undefined`, and primitives return `undefined` for
+`.choice` without throwing, so only `null` is the live hazard. (Avoid the
+broader fixes — a top-level `try/catch` or `process.on('uncaughtException')`
+would mask other bugs.)
+
+### A4 — Frame-length bound in `decodeFrame` (adjacent)
+
+Referenced by PR #1504 as #1446. The current code **already** bounds extended
+frame lengths: `MAX_FRAME_PAYLOAD_BYTES = 10MB` (`server.cjs:10`) is enforced at
+`server.cjs:58-67` before any `Buffer.alloc`. Action: verify #1446 against
+current `dev` and close if already resolved, rather than re-implementing.
+
+---
+
+## B. Server robustness / correctness
+
+### B1 — macOS resource-fork dotfiles served as screen content
+
+**Problem.** The newest-screen selector filters on `f.endsWith('.html')` only
+(`server.cjs:127-128`). On macOS/ExFAT, `._screen.html` resource-fork files pass
+that filter and, being written alongside the real file, can sort newest — so the
+browser gets binary metadata instead of the mockup. Four read sites share the
+weak filter: `getNewestScreen` (`server.cjs:127`), `knownFiles` init
+(`server.cjs:279`), the `fs.watch` handler (`server.cjs:286`), and the `/files/`
+endpoint (`server.cjs:154-156`).
+
+**Change.** Reject dotfiles (`!f.startsWith('.')`) at all four sites. Covers
+`._*`, `.DS_Store`, etc.
+
+### B2 — `stop-server.sh` can kill a reused PID
+
+**Problem.** `stop-server.sh` reads the PID from `state/server.pid`
+(`stop-server.sh:20`) and `kill`s it (`:23`, escalating to `-9` at `:35`)
+without confirming the PID still belongs to our server. After a reboot or PID
+wraparound the file can point at an unrelated process, which we'd then SIGKILL.
+
+**Change.** Before signalling, verify ownership — the PID's command is `node`
+running our `server.cjs`, ideally matching this session. If ownership can't be
+proven, fail closed (report `stale_pid`, don't kill). Keep the existing
+`stopped` / `not_running` outputs for the real cases.
+
+### B3 — WebSocket client: silent reconnect, stale "Connected"
+
+**Problem.** `helper.js` reconnects on a fixed 1s timer (`helper.js:21-23`),
+has no `onerror` handler, never nulls `ws` on close, and never clears a pending
+reconnect timer. The frame's status element is hardcoded to "Connected" with the
+dot pinned to `var(--success)` (`frame-template.html:77,200`). When the laptop
+sleeps or the server restarts, the page shows "Connected" over a dead socket and
+queues events with no feedback.
+
+**Change.**
+- `helper.js`: exponential backoff (500ms → ×2 → cap 30s, reset on open);
+  `onerror` delegating to `onclose`; `ws = null` on close; `clearTimeout` before
+  reconnecting.
+- `frame-template.html`: drive the status dot from a `--status-color` custom
+  property so JS can switch Connected (green) / Reconnecting (yellow) /
+  Disconnected (red).
+
+---
+
+## C. Lifecycle / timeout (issue #1237)
+
+### C1 — Idle timeout too short, not configurable, WS keeps process alive
+
+**Problem.** `IDLE_TIMEOUT_MS` is hardcoded to 30 minutes (`server.cjs:258`),
+enforced by the 60s lifecycle check (`server.cjs:329-332`). A single brainstorm
+question can sit longer than 30 min while the user thinks or steps away, so the
+server dies mid-session. Separately, `shutdown()` (`server.cjs:310-321`) calls
+`server.close()` but never closes the upgraded sockets in `clients`
+(`server.cjs:174`), so an open browser connection can keep the Node process
+alive past shutdown.
+
+**Change.**
+- Raise the default to 4 hours and make it configurable:
+  `--idle-timeout-minutes` in `start-server.sh` → an env var → `IDLE_TIMEOUT_MS`,
+  with validation against Node timer overflow.
+- Expose the effective timeout in the startup JSON / `state/server-info`.
+- In `shutdown()`, close every socket in `clients` so the process actually
+  exits.
+
+### C2 — Server death is invisible
+
+**Problem.** When the server exits it writes `state/server-stopped` and removes
+`state/server-info` (`server.cjs:312-317`), and the skill is *told* to check
+those files (`visual-companion.md:108`) — but it's soft guidance the model skips,
+and the browser just shows a generic "can't be reached." The user diagnoses it
+manually; the agent keeps referring to a dead URL.
+
+**Change (two parts, independent of C1):**
+- **Browser-facing tombstone.** Leave something at the last-served URL that says
+  "this companion expired — ask Claude to restart it" instead of a connection
+  error. Options to weigh: `helper.js` rendering a banner when the socket stays
+  down past backoff (works only while the page is loaded), vs. a more involved
+  approach that keeps a minimal responder alive to serve a tombstone page.
+- **Harder skill check.** Tighten `visual-companion.md` / `SKILL.md` so
+  "check `server-info`/`server-stopped` before referring to the URL or pushing a
+  screen" is a required step, not a note. Keep it lightweight — possibly a
+  one-line helper the agent always runs.
+
+---
+
+## D. Features
+
+### D1 — Permanent opt-out of the visual companion (issue #892)
+
+**Problem.** The companion is offered as its own message every session
+(`SKILL.md:25,151-152`). A user who never wants it pays that round-trip — and
+HTML generation — every time. There's no way to say "never offer this."
+
+**Change.** Before the offer step, the skill checks a user-level setting and
+skips the offer entirely when opt-out is set.
+
+**Design choice open.** Mechanism isn't settled:
+- Env var (e.g. `SUPERPOWERS_VISUAL_COMPANION=off`) the skill is told to read —
+  simplest, matches what the issue asks for, lives in `.zshrc`.
+- A plugin-settings file (`.claude/superpowers.local.md` frontmatter) — more
+  structured, per-project capable, but heavier and project-scoped.
+- Reliability caveat from the issue: a separate "no-companion" skill competes on
+  trigger words and isn't reliable — rejected.
+
+Pick the mechanism, then it's a small `SKILL.md` change plus a documented knob.
+
+### D2 — Free-text feedback from the browser (issue #957)
+
+**Problem.** The client only captures clicks on `[data-choice]`
+(`helper.js:36-62`). A user who wants to annotate a mockup ("wrong shade of
+blue") has to switch to the terminal, breaking the visual flow.
+
+**Change.** Add a feedback `<textarea>` whose submit emits
+`{"type":"feedback","text":...,"timestamp":...}` via the existing
+`window.brainstorm.send` path (`helper.js:82-85`).
+
+**Cross-cutting — server change required.** `handleMessage` only persists events
+when `event.choice` is truthy (`server.cjs:243`). A `feedback` event has no
+`choice`, so today it would be logged but **never written to `state/events`**,
+and the agent wouldn't see it. The persistence condition must also accept
+`feedback` events. Document the new event shape in `visual-companion.md`
+(Browser Events Format, `:247-259`). Decide the submit trigger (button vs blur
+vs both) and where the textarea renders (frame-level vs opt-in per screen).
+
+### D3 — Auto-open the companion URL (PR #759, issue #755)
+
+**Problem.** `start-server.sh` only prints the URL; the user opens it manually.
+In WSL2 especially, people expect the browser to open.
+
+**Change.** Best-effort opener after the `server-started` JSON is parsed:
+Windows/WSL → `rundll32.exe url.dll,FileProtocolHandler <url>`, macOS → `open`,
+Linux → `xdg-open` only when `DISPLAY`/`WAYLAND_DISPLAY` is set. Swallow
+failures, never block startup, keep echoing the URL. Document in
+`visual-companion.md`. (Consider an opt-out for headless/remote runs where
+popping a browser is wrong — ties into D1's config mechanism.)
+
+### D4 — Light/dark contrast helpers (PR #1683)
+
+**Problem.** Content fragments are wrapped in the OS-aware frame
+(`frame-template.html`). In dark mode, quick mockups often use white inline
+backgrounds while inheriting low-contrast frame text, making cards/panels hard
+to read.
+
+**Change.** Add `.light-surface` / `.dark-surface` helper classes plus a
+conservative fallback for common inline light backgrounds, and document them in
+`visual-companion.md`'s CSS reference. Pure CSS in `frame-template.html`.
+
+---
+
+## E. Workshop / deferred / dropped
+
+### E1 — Hard-gate terminal-vs-HTML per question (PR #1037) — WORKSHOP
+
+The soft guidance already exists: "decide per-question," with browser-vs-terminal
+tests in `SKILL.md:156-161` and `visual-companion.md:5-25`. The complaint is that
+the model renders HTML for purely textual content (A/B lists, clarifying
+questions), wasting tokens and a turn. PR #1037 wraps the decision in a
+`<HARD-GATE>`. **Per Jesse, we'll workshop the wording/mechanism together** —
+this is behavior-shaping skill content and not specced here.
+
+### E2 — Move session state out of the working tree (issue #975 / PR #977) — DEFERRED
+
+Today `--project-dir` writes session state to `<project>/.superpowers/brainstorm/`
+(`start-server.sh:80-84`) and the skill tells the user to gitignore it
+(`visual-companion.md:58`). The ask is a `--state-dir` / `SUPERPOWERS_STATE_DIR`
+default outside the repo (XDG), keeping `--project-dir` as an alias.
+**Deferred by Jesse for now.** Captured so it isn't lost.
+
+### E3 — Vendor Alpine.js for interactive mockups (PR #1639) — DROPPED
+
+Adds a vendored Alpine build so mockups can be interactive (tabs, accordions,
+forms) without hand-rolled JS. **Dropped per Jesse** — we are not taking on a
+vendored third-party dependency in the companion runtime. The underlying need
+(interactive mockups) is not being pursued via this route.
+
+### E4 — Shell-lint warnings (PR #1677) — OPPORTUNISTIC
+
+SC2034 (and friends) in `start-server.sh` / `stop-server.sh`. Trivial; fold into
+B2/C1/D3 when we're already editing those scripts rather than as its own change.
+
+---
+
+## Suggested grouping for implementation
+
+These cluster into a few coherent passes (each independently testable against
+`tests/brainstorm-server/`):
+
+1. **Security pass** (IN PROGRESS, branch `brainstorm-companion-session-key`) —
+   A1 per-session key (supersedes A2) + A3 null-crash guard. Verify/close A4.
+   *Highest priority.*
+2. **Lifecycle pass** — C1 + C2 together (both touch `shutdown()` and the
+   server-death story).
+3. **Robustness pass** — B1, B2, B3 (independent, small).
+4. **Deferred feature pass** - D1, D2, D4 are not part of PR #1720. D3 is
+   shipped through the `--open` flow.
+
+E1 is a separate workshop session. E2/E3 are out of scope for this round.

docs/superpowers/plans/2026-06-10-visual-companion-auth-hardening.md

@@ -0,0 +1,785 @@
+# Visual Companion Auth Hardening Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Harden the brainstorming visual companion auth and reconnect flow while preserving trusted same-origin screen JavaScript and future vendored UI libraries.
+
+**Architecture:** Keyed root loads become a bootstrap step that sets the cookie, stores the key in tab-scoped `sessionStorage`, and navigates to a bare `/` screen URL. WebSockets require valid auth plus browser same-origin `Origin`, while `/files/*` uses realpath containment to prevent content-directory escapes.
+
+**Tech Stack:** Node.js built-ins (`http`, `fs`, `path`, `crypto`), zero runtime dependencies, existing `ws` test dependency, Bash start/stop scripts, repo shell lint script.
+
+**Important:** Do not commit during execution unless Drew explicitly asks. This repository's instructions override the generic plan template's commit cadence.
+
+---
+
+## File Map
+
+- Modify: `skills/brainstorming/scripts/server.cjs`
+  - Add bootstrap response.
+  - Add shared security headers.
+  - Add WebSocket Origin validation.
+  - Add `/files/*` realpath containment.
+- Modify: `skills/brainstorming/scripts/helper.js`
+  - Read the stored session key and append it to the WebSocket URL.
+- Modify: `tests/brainstorm-server/auth.test.js`
+  - Add bootstrap, header, same-origin WS, cross-origin WS, and cookie/file auth regressions.
+- Modify: `tests/brainstorm-server/helper.test.js`
+  - Add mocked-browser coverage for sessionStorage-backed WS URLs.
+- Modify: `tests/brainstorm-server/server.test.js`
+  - Add symlink containment regression for `/files/*`.
+- Modify: `tests/brainstorm-server/lifecycle.test.js`
+  - Make the start-server timeout flag test force background mode.
+  - Add restart reconnect credential coverage if it fits the existing lifecycle helper.
+- Modify: `skills/brainstorming/scripts/start-server.sh`
+  - Fix shell lint.
+- Modify: `skills/brainstorming/scripts/stop-server.sh`
+  - Fix shell lint.
+- Modify: `.gitignore`
+  - Add `.superpowers/`.
+- Optional docs update: `skills/brainstorming/visual-companion.md`
+  - Mention bootstrap URL stripping and trusted same-origin screen JS if the code behavior changes need operator-facing explanation.
+
+## Task 1: Bootstrap Keyed Root Loads
+
+**Files:**
+- Modify: `tests/brainstorm-server/auth.test.js`
+- Modify: `skills/brainstorming/scripts/server.cjs`
+
+- [ ] **Step 1: Add RED tests for bootstrap behavior**
+
+In `tests/brainstorm-server/auth.test.js`, add tests after the existing valid-key root test:
+
+```js
+    await test('GET / with valid query returns bootstrap instead of screen content', async () => {
+      const res = await get('/', { key: TOKEN });
+      assert.strictEqual(res.status, 200);
+      assert(res.body.includes('sessionStorage'), 'bootstrap should store the session key in tab storage');
+      assert(res.body.includes('location.replace'), 'bootstrap should navigate to the bare root URL');
+      assert(!res.body.includes('Secret screen'), 'bootstrap must not serve screen HTML at the keyed URL');
+    });
+
+    await test('GET / with valid cookie serves the screen after bootstrap', async () => {
+      const res = await get('/', { cookie: `${COOKIE_NAME}=${TOKEN}` });
+      assert.strictEqual(res.status, 200);
+      assert(res.body.includes('Secret screen'), 'cookie-authenticated bare root should serve the screen');
+      assert(!res.body.includes('sessionStorage'), 'bare screen response should not be the bootstrap page');
+    });
+```
+
+Keep the existing cookie test if present; merge assertions rather than duplicating the same test name.
+
+- [ ] **Step 2: Verify RED**
+
+Run:
+
+```bash
+cd /Users/drewritter/prime-rad/superpowers/tests/brainstorm-server
+node auth.test.js
+```
+
+Expected: the new bootstrap test fails because current `GET /?key=...` serves `Secret screen` directly and does not include the bootstrap `sessionStorage`/`location.replace` code.
+
+- [ ] **Step 3: Implement minimal bootstrap response**
+
+In `skills/brainstorming/scripts/server.cjs`, add a helper near the page constants:
+
+```js
+function bootstrapPage(key) {
+  const jsonKey = JSON.stringify(String(key));
+  return `<!DOCTYPE html>
+<html>
+<head><meta charset="utf-8"><title>Opening Brainstorm Companion</title></head>
+<body>
+<script>
+sessionStorage.setItem('brainstorm-session-key', ${jsonKey});
+location.replace('/');
+</script>
+</body>
+</html>`;
+}
+```
+
+Then in `handleRequest`, after authorization and cookie setting but before serving screen HTML, detect a valid query key on root:
+
+```js
+function queryKey(url) {
+  const q = url.indexOf('?');
+  if (q < 0) return null;
+  return new URLSearchParams(url.slice(q + 1)).get('key');
+}
+```
+
+Use it in `handleRequest`:
+
+```js
+  const pathname = pathnameOf(req.url);
+  const keyFromQuery = queryKey(req.url);
+  if (req.method === 'GET' && pathname === '/' && keyFromQuery && timingSafeEqualStr(keyFromQuery, TOKEN)) {
+    res.writeHead(200, securityHeaders({ 'Content-Type': 'text/html; charset=utf-8' }));
+    res.end(bootstrapPage(keyFromQuery));
+    return;
+  }
+```
+
+This assumes Task 4 will introduce `securityHeaders`. If implementing Task 1 first, temporarily use:
+
+```js
+    res.writeHead(200, { 'Content-Type': 'text/html; charset=utf-8' });
+```
+
+and replace it in Task 4.
+
+- [ ] **Step 4: Verify GREEN**
+
+Run:
+
+```bash
+cd /Users/drewritter/prime-rad/superpowers/tests/brainstorm-server
+node auth.test.js
+```
+
+Expected: all auth tests pass, including the new bootstrap tests.
+
+## Task 2: WebSocket Origin Enforcement
+
+**Files:**
+- Modify: `tests/brainstorm-server/auth.test.js`
+- Modify: `skills/brainstorming/scripts/server.cjs`
+
+- [ ] **Step 1: Add RED tests for same-origin and cross-origin WS**
+
+In `tests/brainstorm-server/auth.test.js`, extend `wsConnect` to accept an `origin` option:
+
+```js
+function wsConnect({ key, cookie, origin } = {}) {
+  const url = `ws://localhost:${TEST_PORT}/` + (key !== undefined ? `?key=${key}` : '');
+  const headers = {};
+  if (cookie) headers['Cookie'] = cookie;
+  if (origin) headers['Origin'] = origin;
+  const ws = new WebSocket(url, Object.keys(headers).length ? { headers } : {});
+  return new Promise((resolve) => {
+    let settled = false;
+    const done = (outcome) => { if (!settled) { settled = true; resolve({ outcome, ws }); } };
+    ws.on('open', () => done('opened'));
+    ws.on('error', () => done('rejected'));
+    ws.on('close', () => done('rejected'));
+    setTimeout(() => done('rejected'), 1500);
+  });
+}
+```
+
+Then add:
+
+```js
+    await test('WS upgrade with valid cookie and same-origin Origin opens', async () => {
+      const { outcome, ws } = await wsConnect({
+        cookie: `${COOKIE_NAME}=${TOKEN}`,
+        origin: `http://localhost:${TEST_PORT}`
+      });
+      ws.close();
+      assert.strictEqual(outcome, 'opened');
+    });
+
+    await test('WS upgrade with valid cookie but cross-origin Origin is rejected', async () => {
+      const eventsFile = path.join(TEST_DIR, 'state', 'events');
+      if (fs.existsSync(eventsFile)) fs.unlinkSync(eventsFile);
+
+      const { outcome, ws } = await wsConnect({
+        cookie: `${COOKIE_NAME}=${TOKEN}`,
+        origin: 'http://localhost:9999'
+      });
+      if (outcome === 'opened') {
+        ws.send(JSON.stringify({ type: 'choice', choice: 'attacker-injected', text: 'local attacker probe' }));
+        await sleep(300);
+      }
+      ws.close();
+
+      assert.strictEqual(outcome, 'rejected', 'cross-origin browser WS must not open even with cookie');
+      assert(!fs.existsSync(eventsFile), 'cross-origin WS must not write state/events');
+    });
+```
+
+- [ ] **Step 2: Verify RED**
+
+Run:
+
+```bash
+cd /Users/drewritter/prime-rad/superpowers/tests/brainstorm-server
+node auth.test.js
+```
+
+Expected: cross-origin cookie WS test fails because current server accepts any cookie-authenticated WS regardless of Origin.
+
+- [ ] **Step 3: Implement Origin check**
+
+In `skills/brainstorming/scripts/server.cjs`, add:
+
+```js
+function isAllowedWebSocketOrigin(req) {
+  const origin = req.headers.origin;
+  if (!origin) return true; // non-browser clients still need the session key
+  const host = req.headers.host;
+  if (!host) return false;
+  return origin === 'http://' + host;
+}
+```
+
+Then update `handleUpgrade`:
+
+```js
+function handleUpgrade(req, socket) {
+  if (!isAuthorized(req) || !isAllowedWebSocketOrigin(req)) { socket.destroy(); return; }
+```
+
+- [ ] **Step 4: Verify GREEN**
+
+Run:
+
+```bash
+cd /Users/drewritter/prime-rad/superpowers/tests/brainstorm-server
+node auth.test.js
+```
+
+Expected: auth tests pass; cross-origin WS is rejected; same-origin and direct key WS still open.
+
+## Task 3: Helper Uses Stored Key For Reconnect
+
+**Files:**
+- Modify: `tests/brainstorm-server/helper.test.js`
+- Modify: `skills/brainstorming/scripts/helper.js`
+
+- [ ] **Step 1: Add RED test for WebSocket URL key**
+
+In `tests/brainstorm-server/helper.test.js`, add a mocked-browser test near the reconnect state-machine tests:
+
+```js
+test('uses sessionStorage key in the WebSocket URL when present', () => {
+  const e = makeEnv();
+  e.state.sessionKey = 'stored-key-abc';
+  e.boot();
+  assert.strictEqual(e.sockets[0].url, 'ws://localhost:7777/?key=stored-key-abc');
+});
+```
+
+Update `makeEnv()` so the returned object exposes `sockets`, and the mock window includes sessionStorage:
+
+```js
+    window: {
+      location: { host: 'localhost:7777', reload() { state.reloads++; } },
+      sessionStorage: { getItem: (key) => key === 'brainstorm-session-key' ? state.sessionKey : null }
+    },
+```
+
+Also add a fallback test:
+
+```js
+test('uses cookie-only WebSocket URL when no sessionStorage key is present', () => {
+  const e = makeEnv();
+  e.state.sessionKey = null;
+  e.boot();
+  assert.strictEqual(e.sockets[0].url, 'ws://localhost:7777');
+});
+```
+
+- [ ] **Step 2: Verify RED**
+
+Run:
+
+```bash
+cd /Users/drewritter/prime-rad/superpowers/tests/brainstorm-server
+node helper.test.js
+```
+
+Expected: stored-key test fails because current helper uses `ws://localhost:7777`.
+
+- [ ] **Step 3: Implement stored-key WS URL**
+
+In `skills/brainstorming/scripts/helper.js`, replace:
+
+```js
+  const WS_URL = 'ws://' + window.location.host;
+```
+
+with:
+
+```js
+  function websocketUrl() {
+    let key = null;
+    try { key = window.sessionStorage && window.sessionStorage.getItem('brainstorm-session-key'); } catch (e) {}
+    return 'ws://' + window.location.host + (key ? '/?key=' + encodeURIComponent(key) : '');
+  }
+```
+
+Then replace:
+
+```js
+    ws = new WebSocket(WS_URL);
+```
+
+with:
+
+```js
+    ws = new WebSocket(websocketUrl());
+```
+
+- [ ] **Step 4: Verify GREEN**
+
+Run:
+
+```bash
+cd /Users/drewritter/prime-rad/superpowers/tests/brainstorm-server
+node helper.test.js
+```
+
+Expected: helper tests pass.
+
+## Task 4: Security Headers
+
+**Files:**
+- Modify: `tests/brainstorm-server/auth.test.js`
+- Modify: `skills/brainstorming/scripts/server.cjs`
+
+- [ ] **Step 1: Add RED header tests**
+
+In `tests/brainstorm-server/auth.test.js`, add:
+
+```js
+    await test('HTML responses include leak-reduction and anti-framing headers', async () => {
+      const res = await get('/', { key: TOKEN });
+      assert.strictEqual(res.headers['referrer-policy'], 'no-referrer');
+      assert.strictEqual(res.headers['cache-control'], 'no-store');
+      assert.strictEqual(res.headers['x-frame-options'], 'DENY');
+      assert.strictEqual(res.headers['content-security-policy'], "frame-ancestors 'none'");
+      assert.strictEqual(res.headers['cross-origin-resource-policy'], 'same-origin');
+    });
+
+    await test('403 responses include leak-reduction and anti-framing headers', async () => {
+      const res = await get('/');
+      assert.strictEqual(res.status, 403);
+      assert.strictEqual(res.headers['referrer-policy'], 'no-referrer');
+      assert.strictEqual(res.headers['cache-control'], 'no-store');
+      assert.strictEqual(res.headers['x-frame-options'], 'DENY');
+      assert.strictEqual(res.headers['content-security-policy'], "frame-ancestors 'none'");
+      assert.strictEqual(res.headers['cross-origin-resource-policy'], 'same-origin');
+    });
+```
+
+- [ ] **Step 2: Verify RED**
+
+Run:
+
+```bash
+cd /Users/drewritter/prime-rad/superpowers/tests/brainstorm-server
+node auth.test.js
+```
+
+Expected: header tests fail because current responses do not include these headers.
+
+- [ ] **Step 3: Implement shared header helper**
+
+In `skills/brainstorming/scripts/server.cjs`, add:
+
+```js
+function securityHeaders(headers = {}) {
+  return {
+    'Referrer-Policy': 'no-referrer',
+    'Cache-Control': 'no-store',
+    'X-Frame-Options': 'DENY',
+    'Content-Security-Policy': "frame-ancestors 'none'",
+    'Cross-Origin-Resource-Policy': 'same-origin',
+    ...headers
+  };
+}
+```
+
+Update response writes in `handleRequest`:
+
+```js
+res.writeHead(403, securityHeaders({ 'Content-Type': 'text/html; charset=utf-8' }));
+```
+
+```js
+res.writeHead(200, securityHeaders({ 'Content-Type': 'text/html; charset=utf-8' }));
+```
+
+```js
+res.writeHead(200, securityHeaders({ 'Content-Type': contentType }));
+```
+
+For 404s:
+
+```js
+res.writeHead(404, securityHeaders());
+```
+
+- [ ] **Step 4: Verify GREEN**
+
+Run:
+
+```bash
+cd /Users/drewritter/prime-rad/superpowers/tests/brainstorm-server
+node auth.test.js
+```
+
+Expected: auth tests pass and header assertions are green.
+
+## Task 5: `/files/*` Realpath Containment
+
+**Files:**
+- Modify: `tests/brainstorm-server/server.test.js`
+- Modify: `skills/brainstorming/scripts/server.cjs`
+
+- [ ] **Step 1: Add RED symlink escape test**
+
+In `tests/brainstorm-server/server.test.js`, after the `/files/` empty-name test, add:
+
+```js
+    await test('does not serve symlinks that escape content dir via /files/', async () => {
+      const target = path.join(STATE_DIR, 'server-info');
+      const link = path.join(CONTENT_DIR, 'linked-server-info.txt');
+      try { fs.unlinkSync(link); } catch (e) {}
+      fs.symlinkSync(target, link);
+
+      const res = await fetch(`http://localhost:${TEST_PORT}/files/linked-server-info.txt`);
+      assert.strictEqual(res.status, 404, 'symlink to state/server-info must not be served');
+      assert(!res.body.includes('server-started'), 'response must not include server-info body');
+    });
+```
+
+- [ ] **Step 2: Verify RED**
+
+Run:
+
+```bash
+cd /Users/drewritter/prime-rad/superpowers/tests/brainstorm-server
+node server.test.js
+```
+
+Expected: symlink test fails because current `/files/*` follows symlinks and serves `server-info`.
+
+- [ ] **Step 3: Implement containment helper**
+
+In `skills/brainstorming/scripts/server.cjs`, add:
+
+```js
+function isRegularFileInsideContentDir(filePath) {
+  let stat, realContentDir, realFilePath;
+  try {
+    stat = fs.lstatSync(filePath);
+    if (stat.isSymbolicLink()) return false;
+    if (!stat.isFile()) return false;
+    realContentDir = fs.realpathSync(CONTENT_DIR);
+    realFilePath = fs.realpathSync(filePath);
+  } catch (e) {
+    return false;
+  }
+  return realFilePath.startsWith(realContentDir + path.sep);
+}
+```
+
+Replace the `/files/*` guard with:
+
+```js
+    if (!fileName || fileName.startsWith('.') || !isRegularFileInsideContentDir(filePath)) {
+      res.writeHead(404, securityHeaders());
+      res.end('Not found');
+      return;
+    }
+```
+
+- [ ] **Step 4: Verify GREEN**
+
+Run:
+
+```bash
+cd /Users/drewritter/prime-rad/superpowers/tests/brainstorm-server
+node server.test.js
+```
+
+Expected: server tests pass, including symlink rejection.
+
+## Task 6: Restart Reconnect Regression
+
+**Files:**
+- Modify: `tests/brainstorm-server/lifecycle.test.js`
+- Modify: `skills/brainstorming/scripts/server.cjs`
+- Modify: `skills/brainstorming/scripts/helper.js`
+
+- [ ] **Step 1: Add RED integration test for same key over WS after restart**
+
+In `tests/brainstorm-server/lifecycle.test.js`, add a test after the port/token persistence test:
+
+```js
+  await test('stored key can authenticate WebSocket after same-port restart', async () => {
+    const dir = fs.mkdtempSync('/tmp/bs-reconnect-');
+    const portFile = path.join(dir, '.last-port');
+    const tokenFile = path.join(dir, '.last-token');
+    const env = { ...process.env, BRAINSTORM_PORT_FILE: portFile, BRAINSTORM_TOKEN_FILE: tokenFile, BRAINSTORM_LIFECYCLE_CHECK_MS: 100000 };
+
+    const a = spawn('node', [SERVER], { env: { ...env, BRAINSTORM_DIR: path.join(dir, 's1') } });
+    let outA = ''; a.stdout.on('data', d => outA += d.toString());
+    for (let i = 0; i < 60 && !outA.includes('server-started'); i++) await sleep(50);
+    const infoA = firstServerStarted(outA);
+    const keyA = new URL(infoA.url).searchParams.get('key');
+    a.kill(); await sleep(400);
+
+    const b = spawn('node', [SERVER], { env: { ...env, BRAINSTORM_DIR: path.join(dir, 's2') } });
+    let outB = ''; b.stdout.on('data', d => outB += d.toString());
+    for (let i = 0; i < 60 && !outB.includes('server-started'); i++) await sleep(50);
+    const infoB = firstServerStarted(outB);
+
+    const ws = new WebSocket(`ws://localhost:${infoB.port}/?key=${keyA}`, {
+      headers: { Origin: `http://localhost:${infoB.port}` }
+    });
+    const opened = await new Promise(resolve => {
+      ws.on('open', () => resolve(true));
+      ws.on('error', () => resolve(false));
+      setTimeout(() => resolve(false), 1500);
+    });
+
+    try {
+      assert.strictEqual(infoB.port, infoA.port, 'restart should reuse same port');
+      assert(opened, 'stored key should authenticate WS after restart');
+    } finally {
+      try { ws.close(); } catch (e) {}
+      b.kill(); await sleep(100);
+      fs.rmSync(dir, { recursive: true, force: true });
+    }
+  });
+```
+
+This test may already pass once Tasks 2 and 3 are implemented. If it passes before code changes, keep it as coverage but do not call it RED. The real browser reconnect behavior is primarily covered by Task 3 plus final manual/headless browser verification.
+
+- [ ] **Step 2: Verify behavior**
+
+Run:
+
+```bash
+cd /Users/drewritter/prime-rad/superpowers/tests/brainstorm-server
+node lifecycle.test.js
+```
+
+Expected after Tasks 2 and 3: lifecycle tests pass. If this fails, fix the auth/restart path before continuing.
+
+## Task 7: Lifecycle Hang And Shell Lint
+
+**Files:**
+- Modify: `tests/brainstorm-server/lifecycle.test.js`
+- Modify: `skills/brainstorming/scripts/start-server.sh`
+- Modify: `skills/brainstorming/scripts/stop-server.sh`
+
+- [ ] **Step 1: Reproduce shell lint failure**
+
+Run:
+
+```bash
+cd /Users/drewritter/prime-rad/superpowers
+scripts/lint-shell.sh skills/brainstorming/scripts/start-server.sh skills/brainstorming/scripts/stop-server.sh tests/brainstorm-server/stop-server.test.sh
+```
+
+Expected current failure:
+
+```text
+SC2164: skills/brainstorming/scripts/start-server.sh line 128: cd "$SCRIPT_DIR"
+SC2034: skills/brainstorming/scripts/start-server.sh line 166: for i in {1..50}
+SC2034: skills/brainstorming/scripts/stop-server.sh line 57: for i in {1..20}
+```
+
+- [ ] **Step 2: Fix shell lint minimally**
+
+In `skills/brainstorming/scripts/start-server.sh`, change:
+
+```bash
+cd "$SCRIPT_DIR"
+```
+
+to:
+
+```bash
+cd "$SCRIPT_DIR" || exit 1
+```
+
+Change unused loop variables from `i` to `_` where they are not read:
+
+```bash
+for _ in {1..50}; do
+```
+
+In `skills/brainstorming/scripts/stop-server.sh`, change:
+
+```bash
+for i in {1..20}; do
+```
+
+to:
+
+```bash
+for _ in {1..20}; do
+```
+
+- [ ] **Step 3: Fix lifecycle start-server hang**
+
+In `tests/brainstorm-server/lifecycle.test.js`, update the `start-server.sh --idle-timeout-minutes sets the timeout` test command:
+
+```js
+const out = execFileSync('bash', [START, '--project-dir', dir, '--idle-timeout-minutes', '5', '--background'], { encoding: 'utf8' });
+```
+
+This keeps the test from hanging when `CODEX_CI` triggers start-server foreground mode.
+
+- [ ] **Step 4: Verify lint and lifecycle**
+
+Run:
+
+```bash
+cd /Users/drewritter/prime-rad/superpowers
+scripts/lint-shell.sh skills/brainstorming/scripts/start-server.sh skills/brainstorming/scripts/stop-server.sh tests/brainstorm-server/stop-server.test.sh
+cd tests/brainstorm-server
+node lifecycle.test.js
+```
+
+Expected: shell lint exits 0; lifecycle tests exit 0 without hanging.
+
+## Task 8: Gitignore Durable Companion State
+
+**Files:**
+- Modify: `.gitignore`
+
+- [ ] **Step 1: Verify current ignore gap**
+
+Run:
+
+```bash
+cd /Users/drewritter/prime-rad/superpowers
+git check-ignore .superpowers/brainstorm/.last-token || true
+```
+
+Expected current output: no matching ignore rule.
+
+- [ ] **Step 2: Add ignore rule**
+
+Add this line to `.gitignore`:
+
+```gitignore
+.superpowers/
+```
+
+- [ ] **Step 3: Verify GREEN**
+
+Run:
+
+```bash
+cd /Users/drewritter/prime-rad/superpowers
+git check-ignore .superpowers/brainstorm/.last-token
+```
+
+Expected output:
+
+```text
+.superpowers/brainstorm/.last-token
+```
+
+## Task 9: Full Automated Verification
+
+**Files:**
+- No code changes in this task.
+
+- [ ] **Step 1: Run focused suites**
+
+Run:
+
+```bash
+cd /Users/drewritter/prime-rad/superpowers/tests/brainstorm-server
+node auth.test.js
+node helper.test.js
+node server.test.js
+node lifecycle.test.js
+```
+
+Expected: all four commands exit 0.
+
+- [ ] **Step 2: Run full brainstorm-server suite**
+
+Run:
+
+```bash
+cd /Users/drewritter/prime-rad/superpowers/tests/brainstorm-server
+npm test
+```
+
+Expected: all tests pass, including ws-protocol, helper, auth, server, lifecycle, and stop-server.
+
+- [ ] **Step 3: Repeat suite for lifecycle/watch flake**
+
+Run:
+
+```bash
+cd /Users/drewritter/prime-rad/superpowers/tests/brainstorm-server
+for i in 1 2 3; do npm test || exit 1; done
+```
+
+Expected: all three repeats pass without hanging.
+
+- [ ] **Step 4: Run shell lint**
+
+Run:
+
+```bash
+cd /Users/drewritter/prime-rad/superpowers
+scripts/lint-shell.sh skills/brainstorming/scripts/start-server.sh skills/brainstorming/scripts/stop-server.sh tests/brainstorm-server/stop-server.test.sh
+```
+
+Expected: exits 0.
+
+## Task 10: Re-run Security Probes
+
+**Files:**
+- No code changes in this task.
+
+- [ ] **Step 1: Recreate the cross-origin attacker probe**
+
+Use the previous scratch probe if available:
+
+```bash
+node /tmp/superpowers-pr1720-security-drewritter/probe-pr1720.cjs
+```
+
+If the scratch probe is unavailable, recreate a minimal probe under `/tmp` that:
+
+- starts the companion with a fixed token
+- loads the keyed URL in headless Chrome
+- starts an attacker page on a different localhost port
+- attempts `new WebSocket('ws://localhost:<companion-port>/')`
+- sends `{"type":"choice","choice":"attacker-injected"}`
+- checks `state/events`
+
+Expected after fixes:
+
+- keyless and wrong-key HTTP still return 403
+- same-origin helper reaches Connected
+- cross-origin WebSocket does not open
+- `state/events` does not contain `attacker-injected`
+- symlink-to-`server-info` returns 404
+- keyed browser load ends on bare `/`
+
+- [ ] **Step 2: Re-run manual/browser flow only after automated probes pass**
+
+Manual flow:
+
+1. start the companion with `--project-dir --open`
+2. push a screen
+3. confirm URL strips to `/`
+4. confirm status reaches Connected
+5. click a choice and verify `state/events`
+6. stop and restart same project
+7. verify the open tab reconnects automatically
+
+Expected: all steps pass without manual URL reload.
+
+## Self-Review Checklist
+
+- Spec coverage: every design requirement maps to at least one task.
+- Placeholder scan: this plan contains no unresolved placeholder markers or unspecified edge-case steps.
+- TDD order: every production change task starts with a focused failing test or a command that demonstrates the current failure.
+- Trust model: the plan preserves trusted same-origin screen JavaScript and future same-origin vendored libraries.
+- No-commit rule: execution does not commit unless Drew explicitly asks.

docs/superpowers/specs/2026-01-22-document-review-system-design.md

@@ -0,0 +1,136 @@
+# Document Review System Design
+
+## Overview
+
+Add two new review stages to the superpowers workflow:
+
+1. **Spec Document Review** - After brainstorming, before writing-plans
+2. **Plan Document Review** - After writing-plans, before implementation
+
+Both follow the iterative loop pattern used by implementation reviews.
+
+## Spec Document Reviewer
+
+**Purpose:** Verify the spec is complete, consistent, and ready for implementation planning.
+
+**Location:** `skills/brainstorming/spec-document-reviewer-prompt.md`
+
+**What it checks for:**
+
+| Category | What to Look For |
+|----------|------------------|
+| Completeness | TODOs, placeholders, "TBD", incomplete sections |
+| Coverage | Missing error handling, edge cases, integration points |
+| Consistency | Internal contradictions, conflicting requirements |
+| Clarity | Ambiguous requirements |
+| YAGNI | Unrequested features, over-engineering |
+
+**Output format:**
+```
+## Spec Review
+
+**Status:** Approved | Issues Found
+
+**Issues (if any):**
+- [Section X]: [issue] - [why it matters]
+
+**Recommendations (advisory):**
+- [suggestions that don't block approval]
+```
+
+**Review loop:** Issues found -> brainstorming agent fixes -> re-review -> repeat until approved.
+
+**Dispatch mechanism:** Use the Task tool with `subagent_type: general-purpose`. The reviewer prompt template provides the full prompt. The brainstorming skill's controller dispatches the reviewer.
+
+## Plan Document Reviewer
+
+**Purpose:** Verify the plan is complete, matches the spec, and has proper task decomposition.
+
+**Location:** `skills/writing-plans/plan-document-reviewer-prompt.md`
+
+**What it checks for:**
+
+| Category | What to Look For |
+|----------|------------------|
+| Completeness | TODOs, placeholders, incomplete tasks |
+| Spec Alignment | Plan covers spec requirements, no scope creep |
+| Task Decomposition | Tasks atomic, clear boundaries |
+| Task Syntax | Checkbox syntax on tasks and steps |
+| Chunk Size | Each chunk under 1000 lines |
+
+**Chunk definition:** A chunk is a logical grouping of tasks within the plan document, delimited by `## Chunk N: <name>` headings. The writing-plans skill creates these boundaries based on logical phases (e.g., "Foundation", "Core Features", "Integration"). Each chunk should be self-contained enough to review independently.
+
+**Spec alignment verification:** The reviewer receives both:
+1. The plan document (or current chunk)
+2. The path to the spec document for reference
+
+The reviewer reads both and compares requirements coverage.
+
+**Output format:** Same as spec reviewer, but scoped to the current chunk.
+
+**Review process (chunk-by-chunk):**
+1. Writing-plans creates chunk N
+2. Controller dispatches plan-document-reviewer with chunk N content and spec path
+3. Reviewer reads chunk and spec, returns verdict
+4. If issues: writing-plans agent fixes chunk N, goto step 2
+5. If approved: proceed to chunk N+1
+6. Repeat until all chunks approved
+
+**Dispatch mechanism:** Same as spec reviewer - Task tool with `subagent_type: general-purpose`.
+
+## Updated Workflow
+
+```
+brainstorming -> spec -> SPEC REVIEW LOOP -> writing-plans -> plan -> PLAN REVIEW LOOP -> implementation
+```
+
+**Spec Review Loop:**
+1. Spec complete
+2. Dispatch reviewer
+3. If issues: fix -> goto 2
+4. If approved: proceed
+
+**Plan Review Loop:**
+1. Chunk N complete
+2. Dispatch reviewer for chunk N
+3. If issues: fix -> goto 2
+4. If approved: next chunk or implementation
+
+## Markdown Task Syntax
+
+Tasks and steps use checkbox syntax:
+
+```markdown
+- [ ] ### Task 1: Name
+
+- [ ] **Step 1:** Description
+  - File: path
+  - Command: cmd
+```
+
+## Error Handling
+
+**Review loop termination:**
+- No hard iteration limit - loops continue until reviewer approves
+- If loop exceeds 5 iterations, the controller should surface this to the human for guidance
+- The human can choose to: continue iterating, approve with known issues, or abort
+
+**Disagreement handling:**
+- Reviewers are advisory - they flag issues but don't block
+- If the agent believes reviewer feedback is incorrect, it should explain why in its fix
+- If disagreement persists after 3 iterations on the same issue, surface to human
+
+**Malformed reviewer output:**
+- Controller should validate reviewer output has required fields (Status, Issues if applicable)
+- If malformed, re-dispatch reviewer with a note about expected format
+- After 2 malformed responses, surface to human
+
+## Files to Change
+
+**New files:**
+- `skills/brainstorming/spec-document-reviewer-prompt.md`
+- `skills/writing-plans/plan-document-reviewer-prompt.md`
+
+**Modified files:**
+- `skills/brainstorming/SKILL.md` - add review loop after spec written
+- `skills/writing-plans/SKILL.md` - add chunk-by-chunk review loop, update task syntax examples

docs/superpowers/specs/2026-02-19-visual-brainstorming-refactor-design.md

@@ -0,0 +1,162 @@
+# Visual Brainstorming Refactor: Browser Displays, Terminal Commands
+
+**Date:** 2026-02-19
+**Status:** Approved
+**Scope:** `lib/brainstorm-server/`, `skills/brainstorming/visual-companion.md`, `tests/brainstorm-server/`
+
+## Problem
+
+During visual brainstorming, Claude runs `wait-for-feedback.sh` as a background task and blocks on `TaskOutput(block=true, timeout=600s)`. This seizes the TUI entirely — the user cannot type to Claude while visual brainstorming is running. The browser becomes the only input channel.
+
+Claude Code's execution model is turn-based. There is no way for Claude to listen on two channels simultaneously within a single turn. The blocking `TaskOutput` pattern was the wrong primitive — it simulates event-driven behavior the platform doesn't support.
+
+## Design
+
+### Core Model
+
+**Browser = interactive display.** Shows mockups, lets the user click to select options. Selections are recorded server-side.
+
+**Terminal = conversation channel.** Always unblocked, always available. The user talks to Claude here.
+
+### The Loop
+
+1. Claude writes an HTML file to the session directory
+2. Server detects it via chokidar, pushes WebSocket reload to the browser (unchanged)
+3. Claude ends its turn — tells the user to check the browser and respond in the terminal
+4. User looks at browser, optionally clicks to select an option, then types feedback in the terminal
+5. On the next turn, Claude reads `$SCREEN_DIR/.events` for the browser interaction stream (clicks, selections), merges with the terminal text
+6. Iterate or advance
+
+No background tasks. No `TaskOutput` blocking. No polling scripts.
+
+### Key Deletion: `wait-for-feedback.sh`
+
+Deleted entirely. Its purpose was to bridge "server logs events to stdout" and "Claude needs to receive those events." The `.events` file replaces this — the server writes user interaction events directly, and Claude reads them with whatever file-reading mechanism the platform provides.
+
+### Key Addition: `.events` File (Per-Screen Event Stream)
+
+The server writes all user interaction events to `$SCREEN_DIR/.events`, one JSON object per line. This gives Claude the full interaction stream for the current screen — not just the final selection, but the user's exploration path (clicked A, then B, settled on C).
+
+Example contents after a user explores options:
+
+```jsonl
+{"type":"click","choice":"a","text":"Option A - Preset-First Wizard","timestamp":1706000101}
+{"type":"click","choice":"c","text":"Option C - Manual Config","timestamp":1706000108}
+{"type":"click","choice":"b","text":"Option B - Hybrid Approach","timestamp":1706000115}
+```
+
+- Append-only within a screen. Each user event is appended as a new line.
+- The file is cleared (deleted) when chokidar detects a new HTML file (new screen pushed), preventing stale events from carrying over.
+- If the file doesn't exist when Claude reads it, no browser interaction occurred — Claude uses only the terminal text.
+- The file contains only user events (`click`, etc.) — not server lifecycle events (`server-started`, `screen-added`). This keeps it small and focused.
+- Claude can read the full stream to understand the user's exploration pattern, or just look at the last `choice` event for the final selection.
+
+## Changes by File
+
+### `index.js` (server)
+
+**A. Write user events to `.events` file.**
+
+In the WebSocket `message` handler, after logging the event to stdout: append the event as a JSON line to `$SCREEN_DIR/.events` via `fs.appendFileSync`. Only write user interaction events (those with `source: 'user-event'`), not server lifecycle events.
+
+**B. Clear `.events` on new screen.**
+
+In the chokidar `add` handler (new `.html` file detected), delete `$SCREEN_DIR/.events` if it exists. This is the definitive "new screen" signal — better than clearing on GET `/` which fires on every reload.
+
+**C. Replace `wrapInFrame` content injection.**
+
+The current regex anchors on `<div class="feedback-footer">`, which is being removed. Replace with a comment placeholder: remove the existing default content inside `#claude-content` (the `<h2>Visual Brainstorming</h2>` and subtitle paragraph) and replace with a single `<!-- CONTENT -->` marker. Content injection becomes `frameTemplate.replace('<!-- CONTENT -->', content)`. Simpler and won't break if template formatting changes.
+
+### `frame-template.html` (UI frame)
+
+**Remove:**
+- The `feedback-footer` div (textarea, Send button, label, `.feedback-row`)
+- Associated CSS (`.feedback-footer`, `.feedback-footer label`, `.feedback-row`, textarea and button styles within it)
+
+**Add:**
+- `<!-- CONTENT -->` placeholder inside `#claude-content`, replacing the default text
+- A selection indicator bar where the footer was, with two states:
+  - Default: "Click an option above, then return to the terminal"
+  - After selection: "Option B selected — return to terminal to continue"
+- CSS for the indicator bar (subtle, similar visual weight to the existing header)
+
+**Keep unchanged:**
+- Header bar with "Brainstorm Companion" title and connection status
+- `.main` wrapper and `#claude-content` container
+- All component CSS (`.options`, `.cards`, `.mockup`, `.split`, `.pros-cons`, placeholders, mock elements)
+- Dark/light theme variables and media query
+
+### `helper.js` (client-side script)
+
+**Remove:**
+- `sendToClaude()` function and the "Sent to Claude" page takeover
+- `window.send()` function (was tied to the removed Send button)
+- Form submission handler — no purpose without the feedback textarea, adds log noise
+- Input change handler — same reason
+- `pageshow` event listener (was added to fix textarea persistence — no textarea anymore)
+
+**Keep:**
+- WebSocket connection, reconnect logic, event queue
+- Reload handler (`window.location.reload()` on server push)
+- `window.toggleSelect()` for selection highlighting
+- `window.selectedChoice` tracking
+- `window.brainstorm.send()` and `window.brainstorm.choice()` — these are distinct from the removed `window.send()`. They call `sendEvent` which logs to the server via WebSocket. Useful for custom full-document pages.
+
+**Narrow:**
+- Click handler: capture only `[data-choice]` clicks, not all buttons/links. The broad capture was needed when the browser was a feedback channel; now it's just for selection tracking.
+
+**Add:**
+- On `data-choice` click, update the selection indicator bar text to show which option was selected.
+
+**Remove from `window.brainstorm` API:**
+- `brainstorm.sendToClaude` — no longer exists
+
+### `visual-companion.md` (skill instructions)
+
+**Rewrite "The Loop" section** to the non-blocking flow described above. Remove all references to:
+- `wait-for-feedback.sh`
+- `TaskOutput` blocking
+- Timeout/retry logic (600s timeout, 30-minute cap)
+- "User Feedback Format" section describing `send-to-claude` JSON
+
+**Replace with:**
+- The new loop (write HTML → end turn → user responds in terminal → read `.events` → iterate)
+- `.events` file format documentation
+- Guidance that the terminal message is the primary feedback; `.events` provides the full browser interaction stream for additional context
+
+**Keep:**
+- Server startup/shutdown instructions
+- Content fragment vs full document guidance
+- CSS class reference and available components
+- Design tips (scale fidelity to the question, 2-4 options per screen, etc.)
+
+### `wait-for-feedback.sh`
+
+**Deleted entirely.**
+
+### `tests/brainstorm-server/server.test.js`
+
+Tests that need updating:
+- Test asserting `feedback-footer` presence in fragment responses — update to assert the selection indicator bar or `<!-- CONTENT -->` replacement
+- Test asserting `helper.js` contains `send` — update to reflect narrowed API
+- Test asserting `sendToClaude` CSS variable usage — remove (function no longer exists)
+
+## Platform Compatibility
+
+The server code (`index.js`, `helper.js`, `frame-template.html`) is fully platform-agnostic — pure Node.js and browser JavaScript. No Claude Code-specific references. Already proven to work on Codex via background terminal interaction.
+
+The skill instructions (`visual-companion.md`) are the platform-adaptive layer. Each platform's Claude uses its own tools to start the server, read `.events`, etc. The non-blocking model works naturally across platforms since it doesn't depend on any platform-specific blocking primitive.
+
+## What This Enables
+
+- **TUI always responsive** during visual brainstorming
+- **Mixed input** — click in browser + type in terminal, naturally merged
+- **Graceful degradation** — browser down or user doesn't open it? Terminal still works
+- **Simpler architecture** — no background tasks, no polling scripts, no timeout management
+- **Cross-platform** — same server code works on Claude Code, Codex, and any future platform
+
+## What This Drops
+
+- **Pure-browser feedback workflow** — user must return to the terminal to continue. The selection indicator bar guides them, but it's one extra step compared to the old click-Send-and-wait flow.
+- **Inline text feedback from browser** — the textarea is gone. All text feedback goes through the terminal. This is intentional — the terminal is a better text input channel than a small textarea in a frame.
+- **Immediate response on browser Send** — the old system had Claude respond the moment the user clicked Send. Now there's a gap while the user switches to the terminal. In practice this is seconds, and the user gets to add context in their terminal message.

docs/superpowers/specs/2026-03-11-zero-dep-brainstorm-server-design.md

@@ -0,0 +1,118 @@
+# Zero-Dependency Brainstorm Server
+
+Replace the brainstorm companion server's vendored node_modules (express, ws, chokidar — 714 tracked files) with a single zero-dependency `server.js` using only Node.js built-ins.
+
+## Motivation
+
+Vendoring node_modules into the git repo creates a supply chain risk: frozen dependencies don't get security patches, 714 files of third-party code are committed without audit, and modifications to vendored code look like normal commits. While the actual risk is low (localhost-only dev server), eliminating it is straightforward.
+
+## Architecture
+
+A single `server.js` file (~250-300 lines) using `http`, `crypto`, `fs`, and `path`. The file serves two roles:
+
+- **When run directly** (`node server.js`): starts the HTTP/WebSocket server
+- **When required** (`require('./server.js')`): exports WebSocket protocol functions for unit testing
+
+### WebSocket Protocol
+
+Implements RFC 6455 for text frames only:
+
+**Handshake:** Compute `Sec-WebSocket-Accept` from client's `Sec-WebSocket-Key` using SHA-1 + the RFC 6455 magic GUID. Return 101 Switching Protocols.
+
+**Frame decoding (client to server):** Handle three masked length encodings:
+- Small: payload < 126 bytes
+- Medium: 126-65535 bytes (16-bit extended)
+- Large: > 65535 bytes (64-bit extended)
+
+XOR-unmask payload using 4-byte mask key. Return `{ opcode, payload, bytesConsumed }` or `null` for incomplete buffers. Reject unmasked frames.
+
+**Frame encoding (server to client):** Unmasked frames with the same three length encodings.
+
+**Opcodes handled:** TEXT (0x01), CLOSE (0x08), PING (0x09), PONG (0x0A). Unrecognized opcodes get a close frame with status 1003 (Unsupported Data).
+
+**Deliberately skipped:** Binary frames, fragmented messages, extensions (permessage-deflate), subprotocols. These are unnecessary for small JSON text messages between localhost clients. Extensions and subprotocols are negotiated in the handshake — by not advertising them, they are never active.
+
+**Buffer accumulation:** Each connection maintains a buffer. On `data`, append and loop `decodeFrame` until it returns null or buffer is empty.
+
+### HTTP Server
+
+Three routes:
+
+1. **`GET /`** — Serve newest `.html` from screen directory by mtime. Detect full documents vs fragments, wrap fragments in frame template, inject helper.js. Return `text/html`. When no `.html` files exist, serve a hardcoded waiting page ("Waiting for Claude to push a screen...") with helper.js injected.
+2. **`GET /files/*`** — Serve static files from screen directory with MIME type lookup from a hardcoded extension map (html, css, js, png, jpg, gif, svg, json). Return 404 if not found.
+3. **Everything else** — 404.
+
+WebSocket upgrade handled via the `'upgrade'` event on the HTTP server, separate from the request handler.
+
+### Configuration
+
+Environment variables (all optional):
+
+- `BRAINSTORM_PORT` — port to bind (default: random high port 49152-65535)
+- `BRAINSTORM_HOST` — interface to bind (default: `127.0.0.1`)
+- `BRAINSTORM_URL_HOST` — hostname for the URL in startup JSON (default: `localhost` when host is `127.0.0.1`, otherwise same as host)
+- `BRAINSTORM_DIR` — screen directory path (default: `/tmp/brainstorm`)
+
+### Startup Sequence
+
+1. Create `SCREEN_DIR` if it doesn't exist (`mkdirSync` recursive)
+2. Load frame template and helper.js from `__dirname`
+3. Start HTTP server on configured host/port
+4. Start `fs.watch` on `SCREEN_DIR`
+5. On successful listen, log `server-started` JSON to stdout: `{ type, port, host, url_host, url, screen_dir }`
+6. Write the same JSON to `SCREEN_DIR/.server-info` so agents can find connection details when stdout is hidden (background execution)
+
+### Application-Level WebSocket Messages
+
+When a TEXT frame arrives from a client:
+
+1. Parse as JSON. If parsing fails, log to stderr and continue.
+2. Log to stdout as `{ source: 'user-event', ...event }`.
+3. If the event contains a `choice` property, append the JSON to `SCREEN_DIR/.events` (one line per event).
+
+### File Watching
+
+`fs.watch(SCREEN_DIR)` replaces chokidar. On HTML file events:
+
+- On new file (`rename` event for a file that exists): delete `.events` file if present (`unlinkSync`), log `screen-added` to stdout as JSON
+- On file change (`change` event): log `screen-updated` to stdout as JSON (do NOT clear `.events`)
+- Both events: send `{ type: 'reload' }` to all connected WebSocket clients
+
+Debounce per-filename with ~100ms timeout to prevent duplicate events (common on macOS and Linux).
+
+### Error Handling
+
+- Malformed JSON from WebSocket clients: log to stderr, continue
+- Unhandled opcodes: close with status 1003
+- Client disconnects: remove from broadcast set
+- `fs.watch` errors: log to stderr, continue
+- No graceful shutdown logic — shell scripts handle process lifecycle via SIGTERM
+
+## What Changes
+
+| Before | After |
+|---|---|
+| `index.js` + `package.json` + `package-lock.json` + 714 `node_modules` files | `server.js` (single file) |
+| express, ws, chokidar dependencies | none |
+| No static file serving | `/files/*` serves from screen directory |
+
+## What Stays the Same
+
+- `helper.js` — no changes
+- `frame-template.html` — no changes
+- `start-server.sh` — one-line update: `index.js` to `server.js`
+- `stop-server.sh` — no changes
+- `visual-companion.md` — no changes
+- All existing server behavior and external contract
+
+## Platform Compatibility
+
+- `server.js` uses only cross-platform Node built-ins
+- `fs.watch` is reliable for single flat directories on macOS, Linux, and Windows
+- Shell scripts require bash (Git Bash on Windows, which is required for Claude Code)
+
+## Testing
+
+**Unit tests** (`ws-protocol.test.js`): Test WebSocket frame encoding/decoding, handshake computation, and protocol edge cases directly by requiring `server.js` exports.
+
+**Integration tests** (`server.test.js`): Test full server behavior — HTTP serving, WebSocket communication, file watching, brainstorming workflow. Uses `ws` npm package as a test-only client dependency (not shipped to end users).

docs/superpowers/specs/2026-03-23-codex-app-compatibility-design.md

@@ -0,0 +1,244 @@
+# Codex App Compatibility: Worktree and Finishing Skill Adaptation
+
+Make superpowers skills work in the Codex App's sandboxed worktree environment without breaking existing Claude Code or Codex CLI behavior.
+
+**Ticket:** PRI-823
+
+## Motivation
+
+The Codex App runs agents inside git worktrees it manages — detached HEAD, located under `$CODEX_HOME/worktrees/`, with a Seatbelt sandbox that blocks `git checkout -b`, `git push`, and network access. Three superpowers skills assume unrestricted git access: `using-git-worktrees` creates manual worktrees with named branches, `finishing-a-development-branch` merges/pushes/PRs by branch name, and `subagent-driven-development` requires both.
+
+The Codex CLI (open source terminal tool) does NOT have this conflict — it has no built-in worktree management. Our manual worktree approach fills an isolation gap there. The problem is specifically with the Codex App.
+
+## Empirical Findings
+
+Tested in the Codex App on 2026-03-23:
+
+| Operation | workspace-write sandbox | Full access sandbox |
+|---|---|---|
+| `git add` | Works | Works |
+| `git commit` | Works | Works |
+| `git checkout -b` | **Blocked** (can't write `.git/refs/heads/`) | Works |
+| `git push` | **Blocked** (network + `.git/refs/remotes/`) | Works |
+| `gh pr create` | **Blocked** (network) | Works |
+| `git status/diff/log` | Works | Works |
+
+Additional findings:
+- `spawn_agent` subagents **share** the parent thread's filesystem (confirmed via marker file test)
+- "Create branch" button appears in the App header regardless of which branch the worktree was started from
+- The App's native finishing flow: Create branch → Commit modal → Commit and push / Commit and create PR
+- `network_access = true` config is silently broken on macOS (issue #10390)
+
+## Design: Read-Only Environment Detection
+
+Three read-only git commands detect the environment without side effects:
+
+```bash
+GIT_DIR=$(cd "$(git rev-parse --git-dir)" 2>/dev/null && pwd -P)
+GIT_COMMON=$(cd "$(git rev-parse --git-common-dir)" 2>/dev/null && pwd -P)
+BRANCH=$(git branch --show-current)
+```
+
+Two signals derived:
+
+- **IN_LINKED_WORKTREE:** `GIT_DIR != GIT_COMMON` — the agent is in a worktree created by something else (Codex App, Claude Code Agent tool, previous skill run, or the user)
+- **ON_DETACHED_HEAD:** `BRANCH` is empty — no named branch exists
+
+Why `git-dir != git-common-dir` instead of checking `show-toplevel`:
+- In a normal repo, both resolve to the same `.git` directory
+- In a linked worktree, `git-dir` is `.git/worktrees/<name>` while `git-common-dir` is `.git`
+- In a submodule, both are equal — avoiding a false positive that `show-toplevel` would produce
+- Resolving via `cd && pwd -P` handles the relative-path problem (`git-common-dir` returns `.git` relative in normal repos but absolute in worktrees) and symlinks (macOS `/tmp` → `/private/tmp`)
+
+### Decision Matrix
+
+| Linked Worktree? | Detached HEAD? | Environment | Action |
+|---|---|---|---|
+| No | No | Claude Code / Codex CLI / normal git | Full skill behavior (unchanged) |
+| Yes | Yes | Codex App worktree (workspace-write) | Skip worktree creation; handoff payload at finish |
+| Yes | No | Codex App (Full access) or manual worktree | Skip worktree creation; full finishing flow |
+| No | Yes | Unusual (manual detached HEAD) | Create worktree normally; warn at finish |
+
+## Changes
+
+### 1. `using-git-worktrees/SKILL.md` — Add Step 0 (~12 lines)
+
+New section between "Overview" and "Directory Selection Process":
+
+**Step 0: Check if Already in an Isolated Workspace**
+
+Run the detection commands. If `GIT_DIR != GIT_COMMON`, skip worktree creation entirely. Instead:
+1. Skip to "Run Project Setup" subsection under Creation Steps — `npm install` etc. is idempotent, worth running for safety
+2. Then "Verify Clean Baseline" — run tests
+3. Report with branch state:
+   - On a branch: "Already in an isolated workspace at `<path>` on branch `<name>`. Tests passing. Ready to implement."
+   - Detached HEAD: "Already in an isolated workspace at `<path>` (detached HEAD, externally managed). Tests passing. Note: branch creation needed at finish time. Ready to implement."
+
+If `GIT_DIR == GIT_COMMON`, proceed with the full worktree creation flow (unchanged).
+
+Safety verification (.gitignore check) is skipped when Step 0 fires — irrelevant for externally-created worktrees.
+
+Update the Integration section's "Called by" entries. Change the description on each from context-specific text to: "Ensures isolated workspace (creates one or verifies existing)". For example, the `subagent-driven-development` entry changes from "REQUIRED: Set up isolated workspace before starting" to "REQUIRED: Ensures isolated workspace (creates one or verifies existing)".
+
+**Sandbox fallback:** If `GIT_DIR == GIT_COMMON` and the skill proceeds to Creation Steps, but `git worktree add -b` fails with a permission error (e.g., Seatbelt sandbox denial), treat this as a late-detected restricted environment. Fall back to the Step 0 "already in workspace" behavior — skip creation, run setup and baseline tests in the current directory, report accordingly.
+
+After reporting in Step 0, STOP. Do not continue to Directory Selection or Creation Steps.
+
+**Everything else unchanged:** Directory Selection, Safety Verification, Creation Steps, Project Setup, Baseline Tests, Quick Reference, Common Mistakes, Red Flags.
+
+### 2. `finishing-a-development-branch/SKILL.md` — Add Step 1.5 + cleanup guard (~20 lines)
+
+**Step 1.5: Detect Environment** (after Step 1 "Verify Tests", before Step 2 "Determine Base Branch")
+
+Run the detection commands. Three paths:
+
+- **Path A** skips Steps 2 and 3 entirely (no base branch or options needed).
+- **Paths B and C** proceed through Step 2 (Determine Base Branch) and Step 3 (Present Options) as normal.
+
+**Path A — Externally managed worktree + detached HEAD** (`GIT_DIR != GIT_COMMON` AND `BRANCH` empty):
+
+First, ensure all work is staged and committed (`git add` + `git commit`). The Codex App's finishing controls operate on committed work.
+
+Then present this to the user (do NOT present the 4-option menu):
+
+```
+Implementation complete. All tests passing.
+Current HEAD: <full-commit-sha>
+
+This workspace is externally managed (detached HEAD).
+I cannot create branches, push, or open PRs from here.
+
+⚠ These commits are on a detached HEAD. If you do not create a branch,
+they may be lost when this workspace is cleaned up.
+
+If your host application provides these controls:
+- "Create branch" — to name a branch, then commit/push/PR
+- "Hand off to local" — to move changes to your local checkout
+
+Suggested branch name: <ticket-id/short-description>
+Suggested commit message: <summary-of-work>
+```
+
+Branch name derivation: use the ticket ID if available (e.g., `pri-823/codex-compat`), otherwise slugify the first 5 words of the plan title, otherwise omit the suggestion. Avoid including sensitive content (vulnerability descriptions, customer names) in branch names.
+
+Skip to Step 5 (cleanup is a no-op for externally managed worktrees).
+
+**Path B — Externally managed worktree + named branch** (`GIT_DIR != GIT_COMMON` AND `BRANCH` exists):
+
+Present the 4-option menu as normal. (The Step 5 cleanup guard will re-detect the externally managed state independently.)
+
+**Path C — Normal environment** (`GIT_DIR == GIT_COMMON`):
+
+Present the 4-option menu as today (unchanged).
+
+**Step 5 cleanup guard:**
+
+Re-run the `GIT_DIR` vs `GIT_COMMON` detection at cleanup time (do not rely on earlier skill output — the finishing skill may run in a different session). If `GIT_DIR != GIT_COMMON`, skip `git worktree remove` — the host environment owns this workspace.
+
+Otherwise, check and remove as today. Note: the existing Step 5 text says "For Options 1, 2, 4" but the Quick Reference table and Common Mistakes section say "Options 1 & 4 only." The new guard is added before this existing logic and does not change which options trigger cleanup.
+
+**Everything else unchanged:** Options 1-4 logic, Quick Reference, Common Mistakes, Red Flags.
+
+### 3. `subagent-driven-development/SKILL.md` and `executing-plans/SKILL.md` — 1 line edit each
+
+Both skills have an identical Integration section line. Change from:
+```
+- superpowers:using-git-worktrees - REQUIRED: Set up isolated workspace before starting
+```
+To:
+```
+- superpowers:using-git-worktrees - REQUIRED: Ensures isolated workspace (creates one or verifies existing)
+```
+
+**Everything else unchanged:** Dispatch/review loop, prompt templates, model selection, status handling, red flags.
+
+### 4. `codex-tools.md` — Add environment detection docs (~15 lines)
+
+Two new sections at the end:
+
+**Environment Detection:**
+
+```markdown
+## Environment Detection
+
+Skills that create worktrees or finish branches should detect their
+environment with read-only git commands before proceeding:
+
+\```bash
+GIT_DIR=$(cd "$(git rev-parse --git-dir)" 2>/dev/null && pwd -P)
+GIT_COMMON=$(cd "$(git rev-parse --git-common-dir)" 2>/dev/null && pwd -P)
+BRANCH=$(git branch --show-current)
+\```
+
+- `GIT_DIR != GIT_COMMON` → already in a linked worktree (skip creation)
+- `BRANCH` empty → detached HEAD (cannot branch/push/PR from sandbox)
+
+See `using-git-worktrees` Step 0 and `finishing-a-development-branch`
+Step 1.5 for how each skill uses these signals.
+```
+
+**Codex App Finishing:**
+
+```markdown
+## Codex App Finishing
+
+When the sandbox blocks branch/push operations (detached HEAD in an
+externally managed worktree), the agent commits all work and informs
+the user to use the App's native controls:
+
+- **"Create branch"** — names the branch, then commit/push/PR via App UI
+- **"Hand off to local"** — transfers work to the user's local checkout
+
+The agent can still run tests, stage files, and output suggested branch
+names, commit messages, and PR descriptions for the user to copy.
+```
+
+## What Does NOT Change
+
+- `implementer-prompt.md`, `spec-reviewer-prompt.md`, `code-quality-reviewer-prompt.md` — subagent prompts untouched
+- `executing-plans/SKILL.md` — only the 1-line Integration description changes (same as `subagent-driven-development`); all runtime behavior is unchanged
+- `dispatching-parallel-agents/SKILL.md` — no worktree or finishing operations
+- `.codex/INSTALL.md` — installation process unchanged
+- The 4-option finishing menu — preserved exactly for Claude Code and Codex CLI
+- The full worktree creation flow — preserved exactly for non-worktree environments
+- Subagent dispatch/review/iterate loop — unchanged (filesystem sharing confirmed)
+
+## Scope Summary
+
+| File | Change |
+|---|---|
+| `skills/using-git-worktrees/SKILL.md` | +12 lines (Step 0) |
+| `skills/finishing-a-development-branch/SKILL.md` | +20 lines (Step 1.5 + cleanup guard) |
+| `skills/subagent-driven-development/SKILL.md` | 1 line edit |
+| `skills/executing-plans/SKILL.md` | 1 line edit |
+| `skills/using-superpowers/references/codex-tools.md` | +15 lines |
+
+~50 lines added/changed across 5 files. Zero new files. Zero breaking changes.
+
+## Future Considerations
+
+If a third skill needs the same detection pattern, extract it into a shared `references/environment-detection.md` file (Approach B). Not needed now — only 2 skills use it.
+
+## Test Plan
+
+### Automated (run in Claude Code after implementation)
+
+1. Normal repo detection — assert IN_LINKED_WORKTREE=false
+2. Linked worktree detection — `git worktree add` test worktree, assert IN_LINKED_WORKTREE=true
+3. Detached HEAD detection — `git checkout --detach`, assert ON_DETACHED_HEAD=true
+4. Finishing skill handoff output — verify handoff message (not 4-option menu) in restricted environment
+5. **Step 5 cleanup guard** — create a linked worktree (`git worktree add /tmp/test-cleanup -b test-cleanup`), `cd` into it, run the Step 5 cleanup detection (`GIT_DIR` vs `GIT_COMMON`), assert it would NOT call `git worktree remove`. Then `cd` back to main repo, run the same detection, assert it WOULD call `git worktree remove`. Clean up test worktree afterward.
+
+### Manual Codex App Tests (5 tests)
+
+1. Detection in Worktree thread (workspace-write) — verify GIT_DIR != GIT_COMMON, empty branch
+2. Detection in Worktree thread (Full access) — same detection, different sandbox behavior
+3. Finishing skill handoff format — verify agent emits handoff payload, not 4-option menu
+4. Full lifecycle — detection → commit → finishing detection → correct behavior → cleanup
+5. **Sandbox fallback in Local thread** — Start a Codex App **Local thread** (workspace-write sandbox). Prompt: "Use the superpowers skill `using-git-worktrees` to set up an isolated workspace for implementing a small change." Pre-check: `git checkout -b test-sandbox-check` should fail with `Operation not permitted`. Expected: the skill detects `GIT_DIR == GIT_COMMON` (normal repo), attempts `git worktree add -b`, hits Seatbelt denial, falls back to Step 0 "already in workspace" behavior — runs setup, baseline tests, reports ready from current directory. Pass: agent recovers gracefully without cryptic error messages. Fail: agent prints raw Seatbelt error, retries, or gives up with confusing output.
+
+### Regression
+
+- Existing Claude Code skill-triggering tests still pass
+- Existing subagent-driven-development integration tests still pass
+- Normal Claude Code session: full worktree creation + 4-option finishing still works

docs/superpowers/specs/2026-04-06-worktree-rototill-design.md

@@ -0,0 +1,341 @@
+# Worktree Rototill: Detect-and-Defer
+
+**Date:** 2026-04-06
+**Status:** Draft
+**Ticket:** PRI-974
+**Subsumes:** PRI-823 (Codex App compatibility)
+
+## Problem
+
+Superpowers is opinionated about worktree management — specific paths (`.worktrees/<branch>`), specific commands (`git worktree add`), specific cleanup (`git worktree remove`). Meanwhile, Claude Code, Codex App, Gemini CLI, and Cursor all provide native worktree support with their own paths, lifecycle management, and cleanup.
+
+This creates three failure modes:
+
+1. **Duplication** — on Claude Code, the skill does what `EnterWorktree`/`ExitWorktree` already does
+2. **Conflict** — on Codex App, the skill tries to create worktrees inside an already-managed worktree
+3. **Phantom state** — skill-created worktrees at `.worktrees/` are invisible to the harness; harness-created worktrees at `.claude/worktrees/` are invisible to the skill
+
+For harnesses without native support (Codex CLI, OpenCode, Copilot standalone), superpowers fills a real gap. The skill shouldn't go away — it should get out of the way when native support exists.
+
+## Goals
+
+1. Defer to native harness worktree systems when they exist
+2. Continue providing worktree support for harnesses that lack it
+3. Fix three known bugs in finishing-a-development-branch (#940, #999, #238)
+4. Make worktree creation opt-in rather than mandatory (#991)
+5. Replace hardcoded `CLAUDE.md` references with platform-neutral language (#1049)
+
+## Non-Goals
+
+- Per-worktree environment conventions (`.worktree-env.sh`, port offsetting) — Phase 4
+- PreToolUse hooks for path enforcement — Phase 4
+- Multi-repo worktree documentation — Phase 4
+- Brainstorming checklist changes for worktrees — Phase 4
+- `.superpowers-session.json` metadata tracking (interesting PR #997 idea, not needed for v1)
+- Hooks symlinking into worktrees (PR #965 idea, separate concern)
+
+## Design Principles
+
+### Detect state, not platform
+
+Use `GIT_DIR != GIT_COMMON` to determine "am I already in a worktree?" rather than sniffing environment variables to identify the harness. This is a stable git primitive (since git 2.5, 2015), works universally across all harnesses, and requires zero maintenance as new harnesses appear.
+
+### Declarative intent, prescriptive fallback
+
+The skill describes the goal ("ensure work happens in an isolated workspace") and defers to native tools when available. It prescribes specific git commands only as a fallback for harnesses without native worktree support. Step 1a comes first and names native tools explicitly (`EnterWorktree`, `WorktreeCreate`, `/worktree`, `--worktree`); Step 1b comes second with the git fallback. The original spec kept Step 1a abstract ("you know your own toolkit"), but TDD proved that agents anchor on Step 1b's concrete commands when Step 1a is too vague. Explicit tool naming and a consent-authorization bridge were required to make the preference reliable.
+
+### Provenance-based ownership
+
+Whoever creates the worktree owns its cleanup. If the harness created it, superpowers doesn't touch it. If superpowers created it (via git fallback), superpowers cleans it up. The heuristic: if the worktree lives under `.worktrees/` or `worktrees/`, superpowers owns it. Anything else (`.claude/worktrees/`, `~/.codex/worktrees/`, `.gemini/worktrees/`, or old user-global Superpowers paths) belongs to the harness or user and is left alone.
+
+## Design
+
+### 1. `using-git-worktrees` SKILL.md Rewrite
+
+The skill gains three new steps before creation and simplifies the creation flow.
+
+#### Step 0: Detect Existing Isolation
+
+```bash
+GIT_DIR=$(cd "$(git rev-parse --git-dir)" 2>/dev/null && pwd -P)
+GIT_COMMON=$(cd "$(git rev-parse --git-common-dir)" 2>/dev/null && pwd -P)
+BRANCH=$(git branch --show-current)
+```
+
+Three outcomes:
+
+| Condition | Meaning | Action |
+|-----------|---------|--------|
+| `GIT_DIR == GIT_COMMON` | Normal repo checkout | Proceed to Step 0.5 |
+| `GIT_DIR != GIT_COMMON`, named branch | Already in a linked worktree | Skip to Step 3 (project setup). Report: "Already in isolated workspace at `<path>` on branch `<name>`." |
+| `GIT_DIR != GIT_COMMON`, detached HEAD | Externally managed worktree (e.g., Codex App sandbox) | Skip to Step 3. Report: "Already in isolated workspace at `<path>` (detached HEAD, externally managed)." |
+
+Step 0 does not care who created the worktree or which harness is running. A worktree is a worktree regardless of origin.
+
+**Submodule guard:** `GIT_DIR != GIT_COMMON` is also true inside git submodules. Before concluding "already in a worktree," check that we're not in a submodule:
+
+```bash
+# If this returns a path, we're in a submodule, not a worktree
+git rev-parse --show-superproject-working-tree 2>/dev/null
+```
+
+If in a submodule, treat as `GIT_DIR == GIT_COMMON` (proceed to Step 0.5).
+
+#### Step 0.5: Consent
+
+When Step 0 finds no existing isolation (`GIT_DIR == GIT_COMMON`), ask before creating:
+
+> "Would you like me to set up an isolated worktree? This protects your current branch from changes. (y/n)"
+
+If yes, proceed to Step 1. If no, work in place — skip to Step 3 with no worktree.
+
+This step is skipped entirely when Step 0 detects existing isolation (no point asking about what already exists).
+
+#### Step 1a: Native Tools (preferred)
+
+> The user has asked for an isolated workspace (Step 0 consent). Check your available tools — do you have `EnterWorktree`, `WorktreeCreate`, a `/worktree` command, or a `--worktree` flag? If YES: the user's consent to create a worktree is your authorization to use it. Use it now and skip to Step 3.
+
+After using a native tool, skip to Step 3 (project setup).
+
+**Design note — TDD revision:** The original spec used a deliberately short, abstract Step 1a ("You know your own toolkit — the skill does not need to name specific tools"). TDD validation disproved this: agents anchored on Step 1b's concrete git commands and ignored the abstract guidance (2/6 pass rate). Three changes fixed it (50/50 pass rate across GREEN and PRESSURE tests):
+
+1. **Explicit tool naming** — listing `EnterWorktree`, `WorktreeCreate`, `/worktree`, `--worktree` by name transforms the decision from interpretation ("do I have a native tool?") into factual lookup ("is `EnterWorktree` in my tool list?"). Agents on platforms without these tools simply check, find nothing, and fall through to Step 1b. No false positives observed.
+2. **Consent bridge** — "the user's consent to create a worktree is your authorization to use it" directly addresses `EnterWorktree`'s tool-level guardrail ("ONLY when user explicitly asks"). Tool descriptions override skill instructions (Claude Code #29950), so the skill must frame user consent as the authorization the tool requires.
+3. **Red Flag entry** — naming the specific anti-pattern ("Use `git worktree add` when you have a native worktree tool — this is the #1 mistake") in the Red Flags section.
+
+File splitting (Step 1b in a separate skill) was tested and proven unnecessary. The anchoring problem is solved by the quality of Step 1a's text, not by physical separation of git commands. Control tests with the full 240-line skill (all git commands visible) passed 20/20.
+
+#### Step 1b: Git Worktree Fallback
+
+When no native tool is available, create a worktree manually.
+
+**Directory selection** (priority order):
+1. Check the project's agent instruction file (CLAUDE.md, GEMINI.md, AGENTS.md, .cursorrules, or equivalent) for a worktree directory preference.
+2. Check for existing `.worktrees/` or `worktrees/` directory — if found, use it. If both exist, `.worktrees/` wins.
+3. Default to `.worktrees/`.
+
+No interactive directory selection prompt. Old user-global Superpowers worktree paths are not detected or offered; new manual worktrees are project-local unless the user explicitly specifies another location.
+
+**Safety verification** (project-local directories only):
+
+```bash
+git check-ignore -q .worktrees 2>/dev/null
+```
+
+If not ignored, add to `.gitignore` and commit before proceeding.
+
+**Create:**
+
+```bash
+git worktree add "$path" -b "$BRANCH_NAME"
+cd "$path"
+```
+
+**Hooks awareness:** Git worktrees do not inherit the parent repo's hooks directory. After creating a worktree via 1b, symlink the hooks directory from the main repo if one exists:
+
+```bash
+if [ -d "$MAIN_ROOT/.git/hooks" ]; then
+    ln -sf "$MAIN_ROOT/.git/hooks" "$path/.git/hooks"
+fi
+```
+
+This prevents pre-commit checks, linters, and other hooks from silently stopping when work moves to a worktree. (Idea from PR #965.)
+
+**Sandbox fallback:** If `git worktree add` fails with a permission error, treat as a restricted environment. Skip creation, work in current directory, proceed to Step 3.
+
+**Step numbering note:** The current skill has Steps 1-4 as a flat list. This redesign uses 0, 0.5, 1a, 1b, 3, 4. There is no Step 2 — it was the old monolithic "Create Isolated Workspace" which is now split into the 1a/1b structure. The implementation should renumber cleanly (e.g., 0 → "Step 0: Detect", 0.5 → within Step 0's flow, 1a/1b → "Step 1", 3 → "Step 2", 4 → "Step 3") or keep the current numbering with a note. Implementer's choice.
+
+#### Steps 3-4: Project Setup and Baseline Tests (unchanged)
+
+Regardless of which path created the workspace (Step 0 detected existing, Step 1a native tool, Step 1b git fallback, or no worktree at all), execution converges:
+
+- **Step 3:** Auto-detect and run project setup (`npm install`, `cargo build`, `pip install`, `go mod download`, etc.)
+- **Step 4:** Run the test suite. If tests fail, report failures and ask whether to proceed.
+
+### 2. `finishing-a-development-branch` SKILL.md Rewrite
+
+The finishing skill gains environment detection and fixes three bugs.
+
+#### Step 1: Verify Tests (unchanged)
+
+Run the project's test suite. If tests fail, stop. Don't offer completion options.
+
+#### Step 1.5: Detect Environment (new)
+
+Re-run the same detection as Step 0 in creation:
+
+```bash
+GIT_DIR=$(cd "$(git rev-parse --git-dir)" 2>/dev/null && pwd -P)
+GIT_COMMON=$(cd "$(git rev-parse --git-common-dir)" 2>/dev/null && pwd -P)
+```
+
+Three paths:
+
+| State | Menu | Cleanup |
+|-------|------|---------|
+| `GIT_DIR == GIT_COMMON` (normal repo) | Standard 4 options | No worktree to clean up |
+| `GIT_DIR != GIT_COMMON`, named branch | Standard 4 options | Provenance-based (see Step 5) |
+| `GIT_DIR != GIT_COMMON`, detached HEAD | Reduced menu: push as new branch + PR, keep as-is, discard | No merge options (can't merge from detached HEAD) |
+
+#### Step 2: Determine Base Branch (unchanged)
+
+#### Step 3: Present Options
+
+**Normal repo and named-branch worktree:**
+
+1. Merge back to `<base-branch>` locally
+2. Push and create a Pull Request
+3. Keep the branch as-is (I'll handle it later)
+4. Discard this work
+
+**Detached HEAD:**
+
+1. Push as new branch and create a Pull Request
+2. Keep as-is (I'll handle it later)
+3. Discard this work
+
+#### Step 4: Execute Choice
+
+**Option 1 (Merge locally):**
+
+```bash
+# Get main repo root for CWD safety (Bug #238 fix)
+MAIN_ROOT=$(git -C "$(git rev-parse --git-common-dir)/.." rev-parse --show-toplevel)
+cd "$MAIN_ROOT"
+
+# Merge first, verify success before removing anything
+git checkout <base-branch>
+git pull
+git merge <feature-branch>
+<run tests>
+
+# Only after merge succeeds: remove worktree, then delete branch (Bug #999 fix)
+git worktree remove "$WORKTREE_PATH"  # only if superpowers owns it
+git branch -d <feature-branch>
+```
+
+The order is critical: merge → verify → remove worktree → delete branch. The old skill deleted the branch before removing the worktree (which fails because the worktree still references the branch). The naive fix of removing the worktree first is also wrong — if the merge then fails, the working directory is gone and changes are lost.
+
+**Option 2 (Create PR):**
+
+Push branch, create PR. Do NOT clean up worktree — user needs it for PR iteration. (Bug #940 fix: remove contradictory "Then: Cleanup worktree" prose.)
+
+**Option 3 (Keep as-is):** No action.
+
+**Option 4 (Discard):** Require typed "discard" confirmation. Then remove worktree (if superpowers owns it), force-delete branch.
+
+#### Step 5: Cleanup (updated)
+
+```
+if GIT_DIR == GIT_COMMON:
+    # Normal repo, no worktree to clean up
+    done
+
+if worktree path is under .worktrees/ or worktrees/:
+    # Superpowers created it — we own cleanup
+    cd to main repo root       # Bug #238 fix
+    git worktree remove <path>
+
+else:
+    # Harness created it — hands off
+    # If platform provides a workspace-exit tool, use it
+    # Otherwise, leave the worktree in place
+```
+
+Cleanup only runs for Options 1 and 4. Options 2 and 3 always preserve the worktree. (Bug #940 fix.)
+
+**Stale worktree pruning:** After any `git worktree remove`, run `git worktree prune` as a self-healing step. Worktree directories can get deleted out-of-band (e.g., by harness cleanup, manual `rm`, or `.claude/` cleanup), leaving stale registrations that cause confusing errors. One line, prevents silent rot. (Idea from PR #1072.)
+
+### 3. Integration Updates
+
+#### `subagent-driven-development` and `executing-plans`
+
+Both currently list `using-git-worktrees` as REQUIRED in their integration sections. Change to:
+
+> `using-git-worktrees` — Ensures isolated workspace (creates one or verifies existing)
+
+The skill itself now handles consent (Step 0.5) and detection (Step 0), so calling skills don't need to gate or prompt.
+
+#### `writing-plans`
+
+Remove the stale claim "should be run in a dedicated worktree (created by brainstorming skill)." Brainstorming is a design skill and does not create worktrees. The worktree prompt happens at execution time via `using-git-worktrees`.
+
+### 4. Platform-Neutral Instruction File References
+
+All instances of hardcoded `CLAUDE.md` in worktree-related skills are replaced with:
+
+> "your project's agent instruction file (CLAUDE.md, GEMINI.md, AGENTS.md, .cursorrules, or equivalent)"
+
+This applies to directory preference checks in Step 1b.
+
+## Bug Fixes (bundled)
+
+| Bug | Problem | Fix | Location |
+|-----|---------|-----|----------|
+| #940 | Option 2 prose says "Then: Cleanup worktree (Step 5)" but quick reference says keep it. Step 5 says "For Options 1, 2, 4" but Common Mistakes says "Options 1 and 4 only." | Remove cleanup from Option 2. Step 5 applies to Options 1 and 4 only. | finishing SKILL.md |
+| #999 | Option 1 deletes branch before removing worktree. `git branch -d` can fail because worktree still references the branch. | Reorder to: merge → verify tests → remove worktree → delete branch. Merge must succeed before anything is removed. | finishing SKILL.md |
+| #238 | `git worktree remove` fails silently if CWD is inside the worktree being removed. | Add CWD guard: `cd` to main repo root before `git worktree remove`. | finishing SKILL.md |
+
+## Issues Resolved
+
+| Issue | Resolution |
+|-------|-----------|
+| #940 | Direct fix (Bug #940) |
+| #991 | Opt-in consent in Step 0.5 |
+| #918 | Step 0 detection + Step 1.5 finishing detection |
+| #1009 | Resolved by Step 1a — agents use native tools (e.g., `EnterWorktree`) which create at harness-native paths. Depends on Step 1a working; see Risks. |
+| #999 | Direct fix (Bug #999) |
+| #238 | Direct fix (Bug #238) |
+| #1049 | Platform-neutral instruction file references |
+| #279 | Solved by detect-and-defer — native paths respected because we don't override them |
+| #574 | **Deferred.** Nothing in this spec touches the brainstorming skill where the bug lives. Full fix (adding a worktree step to brainstorming's checklist) is Phase 4. |
+
+## Risks
+
+### Step 1a is the load-bearing assumption — RESOLVED
+
+Step 1a — agents preferring native worktree tools over the git fallback — is the foundation the entire design rests on. If agents ignore Step 1a and fall through to Step 1b on harnesses with native support, detect-and-defer fails entirely.
+
+**Status:** This risk materialized during implementation. The original abstract Step 1a ("You know your own toolkit") failed at 2/6 on Claude Code. The TDD gate worked as designed — it caught the failure before any skill files were modified, preventing a broken release. Three REFACTOR iterations identified the root causes (agent anchoring on concrete commands, tool-description guardrail overriding skill instructions) and produced a fix validated at 50/50 across GREEN and PRESSURE tests. See Step 1a design note above for details.
+
+**Cross-platform validation:**
+
+As of 2026-04-06, Claude Code is the only harness with an agent-callable mid-session worktree tool (`EnterWorktree`). All others either create worktrees before the agent starts (Codex App, Gemini CLI, Cursor) or have no native worktree support (Codex CLI, OpenCode). Step 1a is forward-compatible: when other harnesses add agent-callable worktree tools, agents will match them against the named examples and use them without skill changes.
+
+| Harness | Current worktree model | Skill mechanism | Tested |
+|---------|----------------------|-----------------|--------|
+| Claude Code | Agent-callable `EnterWorktree` | Step 1a | 50/50 (GREEN + PRESSURE) |
+| Codex CLI | No native tool (shell only) | Step 1b git fallback | 6/6 (`codex exec`) |
+| Gemini CLI | Launch-time `--worktree` flag, no agent tool | Step 0 if launched with flag, Step 1b if not | Step 0: 1/1, Step 1b: 1/1 (`gemini -p`) |
+| Cursor Agent | User-facing `/worktree`, no agent tool | Step 0 if user activated, Step 1b if not | Step 0: 1/1, Step 1b: 1/1 (`cursor-agent -p`) |
+| Codex App | Platform-managed, detached HEAD, no agent tool | Step 0 detects existing | 1/1 simulated |
+| OpenCode | Detection only (`ctx.worktree`), no agent tool | Step 1b git fallback | Untested (no CLI access) |
+
+**Residual risks:**
+1. If Anthropic changes `EnterWorktree`'s tool description to be more restrictive (e.g., "Do not use based on skill instructions"), the consent bridge breaks. Worth filing an issue requesting that the tool description accommodate skill-driven invocation.
+2. When other harnesses add agent-callable worktree tools, they may use names not in Step 1a's list. The list should be updated as new tools appear. The generic phrasing ("a worktree or workspace-isolation tool") provides some forward coverage.
+
+### Provenance heuristic
+
+The `.worktrees/` or `worktrees/` = ours, anything else = hands off` heuristic works for every current harness. If a future harness adopts one of those project-local directories as its convention, we'd have a false positive (superpowers tries to clean up a harness-owned worktree). Similarly, if a user manually runs `git worktree add .worktrees/experiment` without superpowers, we'd incorrectly claim ownership. Both are low risk — every harness uses branded paths, and manual `.worktrees/` creation is unlikely — but worth noting.
+
+### Detached HEAD finishing
+
+The reduced menu for detached HEAD worktrees (no merge option) is correct for Codex App's sandbox model. If a user is in detached HEAD for another reason, the reduced menu still makes sense — you genuinely can't merge from detached HEAD without creating a branch first.
+
+## Implementation Notes
+
+Both skill files contain sections beyond the core steps that need updating during implementation:
+
+- **Frontmatter** (`name`, `description`): Update to reflect detect-and-defer behavior
+- **Quick Reference tables**: Rewrite to match new step structure and bug fixes
+- **Common Mistakes sections**: Update or remove items that reference old behavior (e.g., "Skip CLAUDE.md check" is now wrong)
+- **Red Flags sections**: Update to reflect new priorities (e.g., "Never create a worktree when Step 0 detects existing isolation")
+- **Integration sections**: Update cross-references between skills
+
+The spec describes *what changes*; the implementation plan will specify exact edits to these secondary sections.
+
+## Future Work (not in this spec)
+
+- **Phase 3 remainder:** `$TMPDIR` directory option (#666), setup docs for caching and env inheritance (#299)
+- **Phase 4:** PreToolUse hooks for path enforcement (#1040), per-worktree env conventions (#597), brainstorming checklist worktree step (#574), multi-repo documentation (#710)

docs/superpowers/specs/2026-05-05-platform-neutral-config-refs-design.md

@@ -0,0 +1,77 @@
+# Platform-neutral config-file references — Phase B design
+
+## Background
+
+Phase A (see `2026-05-05-platform-neutral-prose-design.md`) replaced generic third-person "Claude" prose with agent-neutral forms. This phase tackles the next category: references to the per-platform instruction file (CLAUDE.md, AGENTS.md, GEMINI.md) inside skills.
+
+The plugin runs on multiple harnesses, and each one reads its own instruction file. Where a skill names CLAUDE.md as if it were the only file, that's a Claude-Code-centric assumption that doesn't hold on Codex / Gemini CLI / OpenCode.
+
+## In scope
+
+Two specific lines in active skills:
+
+1. **`skills/writing-skills/SKILL.md:58`** — `Project-specific conventions (put in CLAUDE.md)`
+2. **`skills/receiving-code-review/SKILL.md:30`** — `"You're absolutely right!" (explicit CLAUDE.md violation)`
+
+## Out of scope
+
+- **`skills/using-superpowers/SKILL.md:22, 26`** — instruction-priority list. The list already names all three (CLAUDE.md, GEMINI.md, AGENTS.md) inclusively, which is correct: the section is making a real claim about *what counts as user instruction* on a multi-platform plugin. No change needed.
+- **Historical / example artifacts**:
+  - `skills/systematic-debugging/CREATION-LOG.md` — attribution path (`~/.claude/CLAUDE.md`) is a historical fact.
+  - `skills/writing-skills/examples/CLAUDE_MD_TESTING.md` — the entire file is a worked example testing CLAUDE.md content variants. The filename, body, and the reference from `testing-skills-with-subagents.md` all stay; normalizing them defeats the example.
+- **Platform-tooling references** — Phase D candidates:
+  - `skills/using-superpowers/SKILL.md:40` (Gemini CLI tool mapping note about GEMINI.md)
+  - `skills/using-superpowers/references/gemini-tools.md` (`save_memory` persists to GEMINI.md)
+
+## Substitution rules
+
+Two distinct calls, one per in-scope line.
+
+### Rule 1: "where to put project-specific conventions"
+
+`writing-skills/SKILL.md:58`:
+
+- **Before:** `Project-specific conventions (put in CLAUDE.md)`
+- **After:** `Project-specific conventions (put in your instructions file)`
+
+Use a generic phrase rather than picking one filename. Different harnesses read different files (CLAUDE.md, AGENTS.md, GEMINI.md, etc.) and the skill should not assume one. The platform-tools reference docs (`references/{codex,copilot,gemini}-tools.md`) are the right place to name each platform's preferred file.
+
+### Rule 2: the "(explicit CLAUDE.md violation)" parenthetical
+
+`receiving-code-review/SKILL.md:30`:
+
+- **Before:** `"You're absolutely right!" (explicit CLAUDE.md violation)`
+- **After:** `"You're absolutely right!" (explicit instruction-file violation)`
+
+The parenthetical is doing real work — it signals this phrase isn't just stylistically bad, it actively violates rules many users put in their instruction files. "Instruction file" is the natural cross-platform term covering AGENTS.md / CLAUDE.md / GEMINI.md collectively, and keeps the original signal without picking one filename or softening to "common".
+
+## Commit plan
+
+Atomic commits, in order:
+
+1. **`writing-skills/SKILL.md`** — CLAUDE.md → "your instructions file" in the "where to put project conventions" line
+2. **`receiving-code-review/SKILL.md`** — CLAUDE.md → instruction-file in the violation parenthetical
+3. **Platform-tools reference docs** — add the preferred per-platform instructions filename (CLAUDE.md, AGENTS.md, GEMINI.md, etc.) to each `references/{codex,copilot,gemini}-tools.md` so readers can resolve "your instructions file" to a real filename.
+
+Each commit message names "Phase B" and the slice.
+
+## Verification
+
+After each commit:
+
+- Read the surrounding paragraph to confirm grammar and meaning still parse.
+- `grep -n "CLAUDE\.md" <touched-file>` — no remaining hits in active prose (carve-outs already documented).
+
+After both commits:
+
+- `grep -rn "CLAUDE\.md" skills/` should return only the documented carve-outs (CREATION-LOG, CLAUDE_MD_TESTING and its inbound reference, the priority list in using-superpowers).
+
+## Non-goals
+
+- Do not touch the priority list ordering in `using-superpowers/SKILL.md`. Reordering CLAUDE.md / GEMINI.md / AGENTS.md is an aesthetic change, not a substitution, and out of scope here.
+- Do not rename `examples/CLAUDE_MD_TESTING.md` or change its content.
+- Do not modify Gemini-CLI-specific tooling references (Phase D candidates).
+
+## Implementation note
+
+Phase B as written here covered three commits and the three non-Claude-Code platform-tools refs. Implementation went one step further: a fourth ref, `references/claude-code-tools.md`, was added in commit `8505703` for symmetry, so Claude Code's instructions-file conventions and tool-name list live alongside the others rather than implicitly in the surrounding skill prose. That addition wasn't anticipated in this spec but is consistent with its intent.

docs/superpowers/specs/2026-05-05-platform-neutral-prose-design.md

@@ -0,0 +1,94 @@
+# Platform-neutral prose — Phase A design
+
+## Background
+
+Superpowers ships to multiple agent runtimes (Claude Code, Codex, Cursor, OpenCode, Copilot CLI, Gemini CLI). Skill content and supporting docs were written first for Claude Code and use "Claude" in places where any runtime's agent applies. OpenAI's vendored fork (openai/plugins#217) attempted a wholesale rewrite that was actively wrong in places — rewriting historical attribution paths, model names, and platform-specific install instructions — and we want to avoid that mistake while still removing platform-centric prose where it is genuinely incidental.
+
+The full effort is broken into phases by reference category. **This spec covers Phase A only:** generic third-person prose mentioning "Claude" in non-platform-specific contexts. Later phases (config-file references, marketing copy, tool-name references) are out of scope here and will get their own specs.
+
+## In scope
+
+Generic prose mentions of "Claude" in:
+
+- `skills/*/SKILL.md` and supporting `.md` files in active skill directories
+- `skills/writing-skills/anthropic-best-practices.md`
+- `README.md` (only where the mention is generic prose, not platform marketing)
+
+Plus one coined-term rename: **Claude Search Optimization (CSO) → Skill Discovery Optimization (SDO)** in `skills/writing-skills/SKILL.md`.
+
+## Out of scope
+
+- **Platform/runtime statements** — "In Claude Code:", install instructions, tool-mapping references. (Phase D candidate.)
+- **Config-file references** — CLAUDE.md, AGENTS.md, GEMINI.md priority lists and "where to put project conventions" callouts. (Phase B.)
+- **Tool-name references** — `Skill`, `Bash`, `Read`, `Task`, `TodoWrite`. Skills are written in Claude Code's tool vocabulary; the existing `references/{codex,copilot,gemini}-tools.md` files map them. (At the time this spec was written, the plan was to defer or skip these. Phase E ended up doing them — replacing tool names with action language across active skills and unifying the platform-tools refs around the same vocabulary.)
+- **Marketing copy** in README — "Superpowers for Claude Code", platform-named install sections. (Phase C.)
+- **Historical artifacts** — `docs/plans/*.md`, `docs/superpowers/specs/*.md`, `CREATION-LOG.md`. These are dated, point-in-time documents; rewriting them rewrites history.
+- **Model identifiers** — Claude Haiku / Sonnet / Opus. These are real product names.
+- **Filename / URL references** — `CLAUDE.md`, `claude.com`, `claude-plugin/`, paths under `~/.claude/`.
+- **`anthropic-best-practices.md` filename** — the file remains named after its source even though we rewrite the prose inside it.
+
+## Replacement style
+
+Use a mix that reads naturally in English:
+
+- **Second person — "your agent"** when addressing the skill author about *their* runtime
+  - "your agent reads the description"
+- **Third person — "the agent" / "agents" / "an agent"** when describing system behavior generically
+  - "Future agents find your skills"
+  - "Use words an agent would search for"
+  - "Agents read SKILL.md only when the skill becomes relevant"
+
+Pick whichever fits the surrounding sentence; do not force consistency at the cost of awkward phrasing. Pluralize when natural ("future agents", "agents read") rather than always saying "the agent".
+
+### Carve-outs that stay as "Claude"
+
+- Model names: Claude Haiku, Claude Sonnet, Claude Opus
+- Filenames and URLs: `CLAUDE.md`, `claude.com`, `~/.claude/`
+- Branded platform name "Claude Code" wherever it refers to the runtime as such (handled in later phases)
+
+### Coined-term rename
+
+- **Claude Search Optimization (CSO) → Skill Discovery Optimization (SDO)**
+  - Appears in `skills/writing-skills/SKILL.md` as a section heading and in nearby prose. Rename the heading, the acronym, and any in-file cross-references.
+
+## Files affected
+
+Approximate counts based on a `grep` filtered to exclude carve-outs:
+
+| File | Generic-prose mentions |
+|------|------------------------|
+| `skills/writing-skills/SKILL.md` | ~12 (includes CSO heading + body) |
+| `skills/writing-skills/anthropic-best-practices.md` | ~30 |
+| `skills/writing-skills/examples/CLAUDE_MD_TESTING.md` | ~1 — filename stays (it's a CLAUDE.md test artifact); the "Variant C: Claude.AI Emphatic Style" heading also stays (it's a label naming a specific style) |
+| `README.md` | ~1 |
+
+Final list confirmed during implementation by re-running the filtered grep.
+
+## Commit plan
+
+Four atomic commits, in order:
+
+1. **Rename CSO → SDO** in `skills/writing-skills/SKILL.md`. Mechanical, isolated, easy to revert if we change our minds about the term.
+2. **Active skills prose** — generic "Claude" → "agent" forms across `skills/*/SKILL.md` and supporting `.md`, excluding `anthropic-best-practices.md`.
+3. **`anthropic-best-practices.md` prose** — same substitution rules. Separate commit because this file is a vendored adaptation of an external doc; isolating the change makes future reconciliation with upstream easier to read.
+4. **README.md prose** *(only if any generic-prose mentions remain after filtering)*. Skipped if empty.
+
+Each commit message names the phase ("Phase A") and the slice ("rename CSO to SDO", "agent prose in active skills", etc.) so the series is self-documenting.
+
+## Verification
+
+After each commit:
+
+- `grep -rn "Claude" <touched-paths>` — every remaining hit must fall into a documented carve-out (model name, filename, URL, "Claude Code" platform name, historical artifact).
+- Read the touched file end-to-end — substitutions should not have broken sentence flow, pronoun agreement, or list parallelism.
+- No tests to run; this is prose-only.
+
+After the final commit:
+
+- Skim each modified skill in a live session to confirm nothing reads awkwardly.
+
+## Non-goals
+
+- Do not change behavior, structure, headings (other than CSO→SDO), examples, code blocks, or YAML frontmatter.
+- Do not introduce new sections, callouts, or compatibility notes.
+- Do not "improve" prose beyond the substitution while editing.

docs/superpowers/specs/2026-05-05-platform-neutral-readme-design.md

@@ -0,0 +1,47 @@
+# Platform-neutral README ordering — Phase C design
+
+## Background
+
+Phases A and B (see `2026-05-05-platform-neutral-prose-design.md` and `2026-05-05-platform-neutral-config-refs-design.md`) already neutralized generic Claude prose and config-file references in the README. The remaining platform-leaning signal is layout: the README's two platform listings put Claude Code first and aren't strictly alphabetical elsewhere.
+
+This phase fixes the ordering. No prose changes.
+
+## In scope
+
+1. **Quickstart platform list** (`README.md:7`) — the inline link list of supported harnesses
+2. **Installation section ordering** (`README.md:35–152`) — the per-harness install sub-sections
+
+## Out of scope
+
+- Prose, marketplace names, plugin IDs, URLs — all factually correct as-is.
+- Visual weight of the Claude Code section (which has two sub-sections — official Anthropic marketplace and Superpowers marketplace). Both are real install paths; collapsing them would hide accurate info.
+- Section headings and content within each install block — only the ordering of the blocks changes.
+
+## Substitution
+
+Both listings reorder to strict alphabetical:
+
+| Old order | New order |
+|-----------|-----------|
+| Claude Code | Claude Code |
+| Codex CLI | Codex App |
+| Codex App | Codex CLI |
+| Factory Droid | Cursor |
+| Gemini CLI | Factory Droid |
+| OpenCode | Gemini CLI |
+| Cursor | GitHub Copilot CLI |
+| GitHub Copilot CLI | OpenCode |
+
+Three moves: Codex App swaps with Codex CLI; Cursor moves up two slots; GitHub Copilot CLI moves up one.
+
+Claude Code remains first by alphabetical chance (`Cl…` precedes `Co…`).
+
+## Commit plan
+
+One atomic commit covering both listings, since changing one without the other would create inconsistency between the quickstart and the installation section.
+
+## Verification
+
+- Quickstart anchors (`#claude-code`, `#codex-app`, etc.) still resolve to existing `### …` headings — no headings renamed.
+- Each install sub-section's body is byte-identical pre/post; only positions changed.
+- `git diff README.md` shows section moves only, no content edits.

docs/superpowers/specs/2026-05-06-lift-drill-into-evals-design.md

@@ -0,0 +1,247 @@
+# Lift drill into superpowers as `evals/` — design
+
+## Background
+
+Drill is a Python skill-compliance benchmark that lives in its own repo at `obra/drill`. It drives real tmux sessions, runs an LLM actor as a simulated user, runs an LLM verifier on the resulting transcript, and reports pass/fail per scenario. It supports Claude Code, Codex, Gemini CLI, and (per recent commits) OpenCode and Copilot CLI.
+
+Drill is already the *de facto* eval harness for superpowers. The PRI-1397 commit series in the drill repo lifted ~22 superpowers bash tests into drill scenarios, and the most recent superpowers commit (`a2292c5`) explicitly removed a redundant bash test with the message *"replaced by drill behavioral coverage"*. Migration momentum exists; this spec completes it.
+
+This work moves drill into superpowers under `evals/`, deletes the redundant bash tests after per-file verification of drill scenario coverage, and updates docs so contributors land on the new structure.
+
+## Goals
+
+1. `evals/` is the canonical eval harness in superpowers — full drill source, scenarios, fixtures, prompts, backend configs, and tests.
+2. Bash tests in `superpowers/tests/` that have been individually verified as 100% covered by drill scenarios are deleted; the rest are preserved.
+3. The split between `tests/` (plugin infrastructure: bash + node + python integration tests) and `evals/` (LLM behavior with actor + verifier) is meaningful and documented.
+4. Top-level docs (`README.md`, `CLAUDE.md`, `docs/testing.md`) point contributors at the right place.
+5. The standalone `obra/drill` repo continues to exist (this PR does not touch it) and gets archived as a separate manual step after this PR merges.
+
+## Non-goals
+
+- **CI integration.** Manual-only here. The natural follow-up is "tiered": fast subset on every PR, full sweep nightly + on-demand. That requires API budget decisions, GitHub Actions secrets, and a runner image with `tmux` + `node` + `python` + `claude` / `codex` / `gemini` CLIs installed. Out of scope.
+- **Scenario co-location with skills.** Scenarios stay centralized at `evals/scenarios/`. If we later decide each skill should own its scenarios, that's a path-find-and-rename operation; the YAML format does not change.
+- **Renaming the internal Python package** (`drill` → `evals`). The directory is `evals/` (user-facing); the Python package keeps its `drill` name to keep the diff small. A short note in `evals/README.md` explains.
+- **Drill repo archival.** This PR does not touch `obra/drill`. After merge, the drill repo is archived manually (read-only on GitHub, README pointer to `obra/superpowers/evals/`).
+- **Lifting `tests/claude-code/analyze-token-usage.py` into `evals/bin/`.** Useful utility, not test code. Can move later; not required by this PR.
+
+## Branching
+
+Branch off `dev` as `f/evals-lift`. This work is independent of the open `f/cross-platform` PR — no shared file changes besides possibly `README.md`, which is small enough to resolve at merge time if it conflicts.
+
+## Architecture after the move
+
+```
+superpowers/
+  evals/                              ← NEW (full drill copy)
+    pyproject.toml                    (Python 3.11, uv-managed)
+    uv.lock
+    .gitignore                        (drill's own; results/, .venv/, .env)
+    README.md                         (was drill's README; install instructions updated)
+    CLAUDE.md                         (was drill's CLAUDE.md; paths updated)
+    docs/
+      design.md                       (drill's design — preserved verbatim, cross-linked from this spec)
+      manual-testing.md
+      pressure-and-red-testing.md
+    drill/                            (Python package; name kept; cli, engine, actor, verifier, etc.)
+    backends/                         (claude-*.yaml, codex.yaml, gemini.yaml)
+    scenarios/                        (32+ YAML scenarios)
+    setup_helpers/                    (15 Python helpers; create_base_repo, sdd_*, spec_*, worktree, etc.)
+    fixtures/                         (template-repo, sdd-go-fractals, sdd-svelte-todo)
+    prompts/                          (actor.md, verifier.md)
+    bin/                              (assertion helper scripts: tool-called, tool-count, etc.)
+    tests/                            (drill's own pytest suite)
+
+  tests/                              ← bash tests preserved by default
+    brainstorm-server/                ← KEEP (node tests for brainstorm-server JS code)
+    opencode/                         ← KEEP (plugin loading tests)
+    codex-plugin-sync/                ← KEEP (sync verification)
+    claude-code/                      ← MOSTLY KEEP — see deletion gate
+    explicit-skill-requests/          ← KEEP unless verified replaced
+    skill-triggering/                 ← KEEP unless verified replaced
+    subagent-driven-dev/              ← KEEP unless verified replaced
+
+  docs/
+    testing.md                        ← UPDATED (split into "Plugin tests" + "Skill behavior evals")
+    superpowers/
+      specs/
+        2026-05-06-lift-drill-into-evals-design.md   ← THIS SPEC
+
+  README.md                           ← small Contributing-section pointer to evals/
+  CLAUDE.md                           ← one-line "Eval harness lives at evals/" pointer
+```
+
+The `tests/` and `evals/` directories serve clearly distinct roles after this PR:
+
+- **`tests/`** — does the plugin's non-LLM code work? Unit and integration tests for the brainstorm-server JS code, OpenCode plugin loading, codex-plugin-sync sync verification. Bash + node + python.
+- **`evals/`** — do agents behave correctly on real LLM sessions? Drill scenarios with actor + verifier. Python-only, runs real tmux sessions.
+
+## Deletion gate (per bash test)
+
+A bash test is deleted *only if* a drill scenario verifiably covers every assertion it makes. The implementation plan documents this verification per file: read the bash test, list its checks, find the drill scenario, confirm each check has a matching `verify.assertions` or `verify.criteria` entry. If even one check is missing, the option is to either extend the drill scenario or keep the bash test. Default keeps it.
+
+**Tentative coverage map** (commit-message-based; needs per-file verification before any deletion):
+
+| Bash test | Claimed drill replacement | Coverage status |
+|-----------|---------------------------|-----------------|
+| `tests/skill-triggering/prompts/*` (6 prompt files) | `triggering-*.yaml` (6 scenarios) | candidate — verify per-prompt before deleting |
+| `tests/skill-triggering/run-test.sh`, `run-all.sh` | n/a (runners, not tests) | **keep** — runner scripts |
+| `tests/explicit-skill-requests/prompts/please-use-brainstorming.txt` | needs verification — drill has no obvious counterpart yet | likely **keep** unless drill scenario added |
+| `tests/explicit-skill-requests/prompts/use-systematic-debugging.txt` | needs verification — drill has no obvious counterpart | likely **keep** unless drill scenario added |
+| `tests/explicit-skill-requests/run-claude-describes-sdd.sh` | partially → `mid-conversation-skill-invocation.yaml` | candidate — verify per-script |
+| `tests/explicit-skill-requests/run-haiku-test.sh` | no drill scenario covers Haiku-specific behavior | **keep** |
+| `tests/explicit-skill-requests/run-multiturn-test.sh`, `run-extended-multiturn-test.sh` | no drill scenario covers multi-turn build-up | **keep** unless drill scenarios added |
+| `tests/explicit-skill-requests/run-test.sh`, `run-all.sh` | n/a (runners) | **keep** |
+| `tests/subagent-driven-dev/go-fractals/`, `tests/subagent-driven-dev/svelte-todo/` | `sdd-go-fractals.yaml`, `sdd-svelte-todo.yaml` | candidate — verify before deleting (these include real assertions about test suites passing) |
+| `tests/claude-code/test-document-review-system.sh` | `spec-reviewer-catches-planted-flaws.yaml` | candidate — verify before deleting |
+| `tests/claude-code/test-requesting-code-review.sh` | `code-review-catches-planted-bugs.yaml` | candidate — verify before deleting |
+| `tests/claude-code/test-subagent-driven-development-integration.sh` | `sdd-rejects-extra-features.yaml` (YAGNI subset) | **partial** — bash test also asserts ≥3 commits / `npm test` passes / runs `analyze-token-usage.py`. Drill scenario asserts forbidden-exports + reviewer-as-gate. Mostly disjoint — almost certainly **keep + extend drill scenario**. |
+| `tests/claude-code/test-subagent-driven-development.sh` | meta/documentation test (asks agent to *describe* SDD); no drill scenario covers description tests | **keep** unless drill scenario added |
+| `tests/claude-code/test-worktree-native-preference.sh` | `worktree-creation-under-pressure.yaml` | candidate — verify before deleting |
+| `tests/claude-code/test-helpers.sh`, `run-skill-tests.sh`, `analyze-token-usage.py` | n/a (utilities, not tests) | **keep** — libraries/tools |
+
+## Verification protocol (subagent-gated)
+
+Every change in the implementation plan gets cross-checked by an independent subagent before commit.
+
+| Change category | Subagent verification |
+|----------------|----------------------|
+| Each bash-test deletion | Dispatch a subagent with: (a) the bash test file content, (b) the candidate drill scenario YAML, (c) the prompt: *"List every assertion the bash test makes. List every verify entry in the drill scenario. For each bash assertion, find a matching drill check or report it as unmatched. Output a per-assertion table."* The subagent's output is the gate — only delete if every bash assertion has a match. |
+| Initial `evals/` copy | Subagent verifies: (a) drill SHA being copied is recorded in the lift commit message so provenance is auditable; (b) **per-file SHA-256 checksum** matches drill repo for every file (not just file count); (c) excluded paths (`.git/`, `.venv/`, `results/`, `.env`, `__pycache__/`, `*.egg-info/`, any `.private-journal/`) are absent from `evals/`; (d) all backend YAMLs reference paths that exist post-move; (e) `pyproject.toml`, `uv.lock`, `.gitignore` are intact. |
+| Drill's own pytest suite | Subagent runs `cd evals && uv run pytest` after the path-default change. Drill ships its own pytest suite at `evals/tests/` including `test_backend.py` which exercises `SUPERPOWERS_ROOT` env-var behavior — these tests must update to match the helper and continue to pass. |
+| Reference scrubbing after deletion | Subagent greps the entire superpowers tree (excluding `node_modules/`, `.venv/`, and `evals/`) for references to deleted bash test paths. Search targets: `docs/`, `docs/superpowers/plans/`, `RELEASE-NOTES.md`, `CLAUDE.md`, `GEMINI.md`, `AGENTS.md`, `README.md`, `.github/`, `scripts/`, `.opencode/INSTALL.md`, `.codex-plugin/INSTALL.md`, `lefthook.yml`. Any hit is either updated or surfaces a missed dependency. |
+| Path defaults change (`SUPERPOWERS_ROOT` default) | Subagent runs at least one cheap drill scenario after the path changes (e.g., `triggering-test-driven-development`) and confirms it still passes. Real validation, not just code review. |
+| Final pre-PR adversarial review | Two subagents in parallel, "5 points to whoever finds the most legitimate issues" framing — same protocol used on the cross-platform PR. Verify both source code and behavior. |
+
+Each subagent task gets its own bullet in the implementation plan with explicit inputs and pass criteria. The subagent's output is summarized in the relevant commit message ("Subagent verification: …") so the trail is auditable.
+
+## Concrete path/config edits
+
+**Verified prior to writing this spec.** `drill/cli.py` defines `PROJECT_ROOT = Path(__file__).parent.parent`. After the move, `cli.py` lives at `evals/drill/cli.py`, so `PROJECT_ROOT` resolves to `evals/` and `PROJECT_ROOT.parent` resolves to the superpowers repo root. That's the value `SUPERPOWERS_ROOT` should take by default.
+
+**YAML substitution audit.** Only the four `claude*.yaml` backend configs interpolate `${SUPERPOWERS_ROOT}` into `args` (for the `--plugin-dir` flag); `codex.yaml` and `gemini.yaml` only list `SUPERPOWERS_ROOT` in `required_env` (consumed by `engine.py:233` / `setup.py:25`'s `os.environ["SUPERPOWERS_ROOT"]` lookups in pre/post-run hooks). The helper's `os.environ` mutation covers both code paths.
+
+| File | Current | After |
+|------|---------|-------|
+| `drill/cli.py` | `load_dotenv(PROJECT_ROOT / ".env")` at module import; nothing about `SUPERPOWERS_ROOT` | After `load_dotenv`, call new helper `_set_superpowers_root_default()` that sets `os.environ["SUPERPOWERS_ROOT"]` to `str(PROJECT_ROOT.parent)` if and only if not already set. Order: `load_dotenv` → set default → click group definitions. |
+| `drill/engine.py:233`, `drill/setup.py:25` | Direct `os.environ["SUPERPOWERS_ROOT"]` access (KeyError if unset) | Unchanged. The CLI startup hook guarantees the env var is set by the time the engine/setup execute. |
+| `backends/claude*.yaml` (5 files) | `${SUPERPOWERS_ROOT}` substituted in `args` for `--plugin-dir` | Unchanged. YAML substitution reads `os.environ` at backend-load time, which is after CLI startup. |
+| `backends/codex.yaml`, `backends/gemini.yaml` | `SUPERPOWERS_ROOT` in `required_env` only | Drop from `required_env` (the helper supplies it). `claude*.yaml` keep `required_env` for backward compat (env var works as override). |
+| `evals/tests/test_backend.py` | Tests assert `SUPERPOWERS_ROOT` is in `required_env` lists, plus path-resolution tests | Update tests to match the new contract: helper-supplied default, env override still works, `required_env` no longer required for codex/gemini. |
+| `evals/README.md` | "export SUPERPOWERS_ROOT=/path/to/superpowers" | Drop the export line; note that the env var auto-defaults to the parent of `evals/`; mention the only required setup is `ANTHROPIC_API_KEY` (or `OPENAI_API_KEY` / Gemini auth). |
+| `evals/CLAUDE.md` | Same | Same |
+| `evals/.gitignore` | drill's existing patterns (`results/`, `.venv/`, `__pycache__/`, `.env`, `*.pyc`, `*.egg-info/`, `dist/`, `build/`, `.claude/`) | Copied verbatim. Patterns are relative to file location, so they apply correctly under `evals/`. |
+| `evals/lefthook.yml` | drill ships `lefthook.yml` defining `pre-commit: uv run ruff check && uv run ty check` | Move to `evals/lefthook.yml`. Either (a) install lefthook at the superpowers root and have it federate to `evals/lefthook.yml`, or (b) document that contributors run `cd evals && lefthook run pre-commit` manually. **Decision in implementation: option (b) for simplicity** — superpowers' top-level workflow doesn't change. |
+
+`.env` placement: keep `evals/.env` (gitignored). Contributors source it from there or set `ANTHROPIC_API_KEY` in their shell environment.
+
+**Top-level superpowers files needing small additions:**
+
+- `superpowers/.gitignore`: add `evals/results/`, `evals/.venv/`, `evals/.env` (belt-and-suspenders; evals/.gitignore already covers these locally).
+- `superpowers/CLAUDE.md`: add a one-line pointer "Eval harness lives at `evals/` — see `evals/README.md`" so agents discover it.
+- `superpowers/docs/testing.md`: split into "## Plugin tests" (existing tests/ content, with the deleted-test references trimmed) and "## Skill behavior evals" (one-paragraph summary + pointer to `evals/`).
+- `superpowers/README.md`: add a single line in the Contributing section pointing at `evals/` for skill-behavior testing.
+
+## Migration ordering
+
+Each step is a separate commit (or small group of commits). Step 2 is the biggest single commit (the verbatim drill copy); subsequent steps are small and atomic.
+
+```
+1. Branch off `dev` (f/evals-lift)
+
+2. Copy drill repo into evals/ (single commit, easy to revert)
+   ├─ Record drill SHA at copy time → commit message
+   ├─ Use `rsync -a --exclude=.git --exclude=.venv --exclude=results
+   │  --exclude=.env --exclude=__pycache__ --exclude='*.egg-info'
+   │  --exclude=.private-journal /path/to/drill/ evals/`
+   │  (rsync chosen over `cp -r` for explicit excludes; verify with
+   │  `find evals -name '.git' -type d` returns nothing)
+   ├─ Subagent gate: per-file SHA-256 checksum matches drill repo for every
+   │  non-excluded file; excluded paths absent from evals/
+   └─ Smoke check: `cd evals && uv sync` succeeds (proves install only;
+      not a behavioral test)
+
+3. Update path defaults
+   ├─ Add _set_superpowers_root_default() helper to drill/cli.py
+   ├─ Wire it after load_dotenv, before click group definition
+   ├─ Update evals/README.md and evals/CLAUDE.md (drop SUPERPOWERS_ROOT install step)
+   ├─ Drop SUPERPOWERS_ROOT from required_env in codex.yaml/gemini.yaml
+   │  (keep in claude*.yaml as override)
+   └─ Update evals/tests/test_backend.py to match new contract
+
+4. Validate from new location (TWO checks)
+   ├─ Run drill's own pytest: `cd evals && uv run pytest` — must pass
+   └─ Run cheap drill scenario: `cd evals && uv run drill run
+      triggering-test-driven-development -b claude` — must pass.
+      Real behavioral validation, not just code review.
+
+5. Bash test deletion phase — per-file with subagent gate
+   For each file in the candidate-deletion list:
+   a. Subagent compares bash test assertions vs drill scenario verify block
+   b. Pass criterion: every bash assertion has a matching drill check
+   c. If pass → delete the bash test file (one commit per file or per
+      coherent group)
+   d. If fail → either extend drill scenario (separate commit + verify) or
+      keep the bash test (no commit)
+
+6. Stale-reference scrub
+   ├─ Subagent greps the superpowers tree (excluding node_modules/, .venv/,
+   │  evals/) for deleted file paths
+   ├─ Search targets: docs/, docs/superpowers/plans/, RELEASE-NOTES.md,
+   │  CLAUDE.md, GEMINI.md, AGENTS.md, README.md, .github/, scripts/,
+   │  .opencode/INSTALL.md, .codex-plugin/INSTALL.md, lefthook.yml
+   ├─ Update active references (e.g., docs/testing.md, README.md install)
+   └─ Historical references in docs/superpowers/plans/*.md and
+      RELEASE-NOTES.md are PRESERVED with a brief annotation
+      ("(test removed; behavior covered by drill scenario X)") rather
+      than rewritten — these are dated artifacts, not living docs.
+
+7. Top-level docs
+   ├─ docs/testing.md split
+   ├─ CLAUDE.md pointer
+   └─ README.md Contributing section
+
+8. Re-run smoke checks (regression gate)
+   ├─ `cd evals && uv run pytest`
+   └─ `cd evals && uv run drill run triggering-test-driven-development -b claude`
+
+9. Final adversarial review
+   └─ Two parallel subagents, full diff, "5 points to whoever finds the
+      most legitimate issues" framing. Address findings before push.
+
+10. Push branch + open PR against dev
+    └─ PR description includes: drill SHA pinned at copy, archival action
+       item ("after merge: archive obra/drill, add README pointer to
+       obra/superpowers/evals/"), per-deleted-file coverage receipts.
+```
+
+## Verification (post-implementation)
+
+The implementation plan must show:
+
+- All non-excluded drill source files present at `evals/` after step 2 (subagent **per-file SHA-256 checksum diff** vs `obra/drill@<recorded-sha>`).
+- Excluded paths (`.git/`, `.venv/`, `results/`, `.env`, `__pycache__/`, `*.egg-info/`, `.private-journal/`) absent from `evals/`.
+- The step-2 commit message records the drill source SHA.
+- `cd evals && uv sync` succeeds without `SUPERPOWERS_ROOT` set.
+- `cd evals && uv run pytest` passes (drill's own pytest suite).
+- `cd evals && uv run drill list` returns the same scenario count as the standalone drill repo at the recorded SHA.
+- `cd evals && uv run drill run triggering-test-driven-development -b claude` passes (proves path defaults work end-to-end).
+- For each deleted bash test: subagent verification table in the commit message showing every assertion mapped to a drill check.
+- Grep for deleted file paths returns zero hits across living superpowers docs (post step 6); historical refs in `docs/superpowers/plans/*.md` and `RELEASE-NOTES.md` are annotated, not rewritten.
+- `docs/testing.md` has both "Plugin tests" and "Skill behavior evals" sections.
+- The drill repo's history is untouched; `obra/drill` is unaffected by this PR.
+- PR description names the action item to archive `obra/drill` after merge.
+
+## Open questions
+
+None. All clarifying decisions have been made:
+
+| Question | Decision |
+|----------|----------|
+| Where does drill live in superpowers? | `evals/` (rename from drill); standalone repo archived as separate step |
+| Fate of redundant bash tests? | Delete per-file with subagent verification of coverage; default keep |
+| Scenarios layout? | Centralized at `evals/scenarios/` |
+| Python toolchain placement? | Self-contained at `evals/` |
+| CI integration? | Manual-only this PR; documented future path |
+| Migration mechanics? | Plain copy; drill repo's history preserved in archived repo, not in-tree |
+| Internal Python package name? | Keep as `drill` (directory is `evals/`) |
+| Branching strategy? | Independent off `dev` (not stacked on `f/cross-platform`) |

docs/superpowers/specs/2026-06-09-sdd-task-scoped-review-dispatch-design.md

@@ -0,0 +1,160 @@
+# SDD Task-Scoped Review Dispatch
+
+Make subagent-driven-development's per-task reviews cheaper and faster without weakening them, by scoping per-task review prompts to the task and stopping redundant work — while final branch review stays broad.
+
+## Problem
+
+Per-task code quality reviewers in SDD routinely do branch-review-scale work on single-task diffs. Evidence from two real local SDD sessions: `a1a6719a-6109-453a-9933-34ae396f5bae` (sen-core-v2) and `0cc1a12d-9984-4c35-8615-9d42dadb2c47` (serf), both under `~/.claude/projects/`:
+
+- In the sen-core-v2 session, 7/8 quality reviewers ran repo-wide greps; the most expensive ran 50+ Bash commands over ~200 seconds. Across both sessions, quality reviewers cost 4-8× what spec reviewers cost on the same tasks.
+- Spec reviewers, whose prompt contains "Only read files in this diff. Do not crawl the broader codebase," stayed tight: 6-16 tool calls, 14-65 seconds.
+- No reviewer ran heavy tests autonomously. Every package-wide or repeated test run observed was explicitly requested by a controller-written prompt ("check all uses," "run tests if useful, especially race-focused ones," "does anything else read `Meta()`?").
+
+Root causes, in order of impact:
+
+1. **The per-task quality prompt inherits a merge-readiness review.** `code-quality-reviewer-prompt.md` delegates to `requesting-code-review/code-reviewer.md`, which asks about architecture, scalability, security, production readiness, and ends with "Ready to merge?" That frame licenses branch-level breadth on a one-task diff. The spec prompt's diff-scope guard was never carried over.
+2. **The controller gets no guidance on writing reviewer prompts**, so it invents open-ended directives ("check all uses") that reviewers interpret literally.
+3. **Duplicated work across the pipeline.** The quality template's "Plan alignment" dimension re-checks what the spec reviewer just verified. Reviewers re-run test suites the implementer already ran (and reported, with TDD evidence) on identical code.
+4. **Per-task and final review share one template**, so there is no representation of "per-task narrow, final broad" anywhere.
+
+A field report (`~/2026-06-09-code-quality-reviewer-scope-budget-issue.md`) first flagged this. Its cited session and headline numbers could not be verified, but its qualitative diagnosis was confirmed against two real local sessions. One correction to it: cross-cutting audits (lock ordering, changed contracts) are sometimes the *correct* review method — the fix must gate breadth behind a stated concrete risk, not forbid it.
+
+## Goals
+
+- Per-task reviews scoped to the task: diff-first reading, justified broadening, no redundant test runs.
+- Final whole-branch review keeps its current breadth.
+- No reduction in what reviews catch.
+
+## Non-goals / explicitly preserved
+
+- **Full re-reviews stay.** When a reviewer re-reviews after a fix, it still reviews the whole task at full reading breadth. (It does not re-run tests the implementer just ran on the amended code.) This deliberately rejects the field report's "re-review budget" remedy: the cost of its worst cited example (a re-review running `-race` and `-count=100` loops) is curbed by the test budget below, not by narrowing what re-reviewers read.
+- ~~**The two review stages stay separate.** Spec compliance and code quality remain independent subagents, serially gated. No merging.~~ **Superseded by the cost iterations below**: live eval economics showed per-dispatch overhead dominating cost, and the maintainer put everything on the table. The per-task stages are now one task reviewer with two verdicts; the independent broad final review remains.
+- **The coordinator keeps model judgment.** No forced model tier for reviews, in either direction.
+- **`requesting-code-review/` is untouched.** It remains the broad template for final branch review and ad-hoc review.
+- Verdict ordering (spec compliance reported before quality), the fix-and-re-review loops, and the requirement to fix Critical/Important findings are unchanged.
+
+## Cost iterations (post-launch eval economics)
+
+Live before/after runs surfaced a cost regression once the quality-hardening
+prose (evidence rule, constraint carrying, pristine output) landed: go-fractals
+went from 42.8 min / 14.5M tokens (first task-scoped version) to 69.9 min /
+32.2M (hardened version) while reaching baseline-parity quality (blind-judged
+8.5 vs 8.5). Per-subagent turn profiling attributed cost to, in order: cheap
+models taking 2-3× the turns on multi-step work (678 of 1197 subagent turns
+were haiku), per-dispatch overhead (3 subagent spin-ups per task, each
+re-deriving the diff; controller coordination was half the dollars), and
+evidence-rule narration.
+
+- **Iteration 1:** turn-count-beats-token-price model guidance (mid-tier floor
+  for multi-step work), optional inline diffs, cite-don't-narrate evidence,
+  Important = cannot-trust-until-fixed, fixes dispatched only for
+  Critical/Important. Result: 68.2 min / 22.9M — tokens down 29%, wall-clock
+  flat; controllers pasted the diff in only 2 of 22 review dispatches when
+  phrasing was optional.
+- **Iteration 2:** per-task spec and quality reviews merged into one
+  `task-reviewer-prompt.md` (one reviewer, one reading of the diff, two
+  verdicts; one fix dispatch addresses both kinds of findings); implementers
+  run the focused test while iterating, full suite once before commit.
+  Result (go-fractals): 47.5 min / 15.7M / $13.55 — beat baseline on every
+  axis, blind-judged 9/10 vs baseline 7/10.
+- **Iteration 3:** Calibration names merge-blocking maintainability damage
+  (verbatim duplication, swallowed errors, assertion-free tests) as
+  Important and Minor findings must be pasted into the final review for
+  triage; reviewer skepticism extended to the implementer's design
+  rationales ("left it per YAGNI" is a claim, not a verdict); diff handed
+  to reviewers as a file (`git diff > /tmp/sdd-task-N.diff`, redirected so
+  it never enters the controller's context; one Read call for the
+  reviewer) after paste-into-prompt guidance went unadopted (0-6 of 11-17
+  dispatches) for locally-rational context-economics reasons.
+- **Final frozen config (e355795), all five scenarios pass:** go-fractals
+  44.4 min / 13.4M / $11.67 (-32% time, -37% tokens, -27% dollars vs
+  baseline); svelte-todo 62.8 / 19.7M / $15.76 (-21% / -28% / -25%);
+  rejects-extra-features $1.31 (vs $1.88); spec-reviewer-flaws flat; the
+  planted-defect scenario (v3: open-flag transparency bar for judgment
+  calls, must-fix bar for a test whose name promises verification it
+  never performs) passes with the defect caught and fixed.
+
+### Iterations 4-5 (2026-06-10): variance honesty, structural fixes, positive recipes
+
+A same-config re-run exposed run-to-run variance (44.4→57.1 min on
+identical prompts; reviewer escape-hatch appetite swung 1.0→6.3 tool
+calls/review), so all subsequent claims use ranges. Five parallel
+experiment variants on go-fractals plus transcript mining of real local
+sessions (full log with negative results:
+`evals/docs/experiments/2026-06-10-sdd-cost-experiments.md`) produced the
+final config:
+
+- **Adopted:** final-review package (final reviewer 33→6 turns at
+  controller-model prices); REQUIRED `model:` line in both templates
+  (prose guidance decayed mid-session once, inheriting opus for 17
+  dispatches, +$5); task-brief + report files (`scripts/task-brief`;
+  fidelity anchor, modest context savings); progress ledger in
+  `<git-dir>/sdd/progress.md` (real sessions re-dispatched entire
+  completed task sequences after compaction — 269 dispatches for ~22
+  tasks); omnibus final fixer (a real session's per-finding fix wave cost
+  more than all its tasks); scoped fix tests; unique SHA-range collateral
+  names (worktree/submodule-safe); dispatch-composition recipe and
+  reviewer named-risk budget (micro-tested: positive recipe 3.0
+  transcribed values vs prohibition 4.4 vs control 3.6 — prohibitions can
+  backfire; see `2026-06-10-positive-instruction-redesign-design.md`).
+- **Tested and declined:** controller turn batching and parallel-call
+  pipelining (controller emits exactly one tool call per message — 0
+  multi-tool messages in every run; 46% of its turns are
+  thinking/narration, a prompt-immune floor); background-dispatch
+  pipelining (mechanism adopted 7/28 but benefit below the ±6 min noise
+  floor on these scenarios).
+- **Final validated config (b81f35b family), all gates pass:** go-fractals
+  54.1-54.7 min / 14.4-16.6M / $12.81-14.31 (baseline 64.9 / 21.2M /
+  $16.07); svelte-todo 55.0 min / 19.3M / $14.99 (baseline 79.7 / 27.3M /
+  $20.98); planted-defect pass / $2.77. Across all 8 same-design fractals
+  runs: 44.4-57.1 min / 13.4-20.0M / $11.67-14.84 — the worst draw beats
+  baseline on every axis; typical mid-band savings ~20-25%.
+
+## Design
+
+### Shared principle: don't re-run tests on code that hasn't changed
+
+The implementer's report includes test results and TDD RED/GREEN evidence for exactly the code under review. Reviewers verify by reading. A reviewer runs a test only when reading raises a specific doubt that no existing run answers — and then a focused test, not a suite. On harnesses where reviewer subagents are read-only (e.g., Antigravity maps reviewer templates to the `research` type, which has no command access), the reviewer instead names the test it would run in its report.
+
+After a fix, the implementer re-runs the tests covering the amended code; the re-reviewer does not repeat that run. Today nothing enforces that premise: `implementer-prompt.md` describes the initial implement-test-commit flow only, with no fix-iteration instruction. This spec therefore also adds to `implementer-prompt.md`: after fixing a review finding, re-run the tests that cover the amended code and include the results in the fix report.
+
+This principle appears in both reviewer prompts, the implementer prompt, and the controller guidance.
+
+### 1. New file: `skills/subagent-driven-development/code-quality-reviewer-prompt.md` becomes self-contained
+
+Stop delegating to `requesting-code-review/code-reviewer.md`. The per-task quality reviewer gets its own scoped prompt template:
+
+- **Framing:** "You are reviewing one task's implementation for code quality." A task-scoped gate, not a merge review.
+- **Spec compliance is settled:** spec review already passed; do not re-litigate requirements or plan alignment.
+- **Review dimensions kept:** code quality (clarity, duplication, error handling), test quality (real behavior, not mocks), maintainability, and the existing SDD-specific checks (single responsibility, independent testability, file structure from plan, file growth contributed by this change). Dropped: plan alignment, security/scalability/production-readiness dimensions, merge verdict.
+- **Scope budget:** start from `git diff BASE..HEAD`; read changed files first; inspect adjacent code only to evaluate a concrete risk you can name. Cross-cutting changes — lock ordering, changed function/API contracts, shared mutable state — are legitimate named risks that justify checking call sites. Do not crawl the codebase by default.
+- **Test budget:** the shared principle above, plus: no package-wide suites, race detectors, or repeated/high-count runs unless you have first named a specific suspected flake or race. Otherwise, recommend heavy validation in the report instead of running it. Warnings or noise in the implementer's reported test output are findings — output should be pristine (the implementer's self-review checks this too).
+- **Evidence rule:** reviewers answer each What-to-Check item with file:line evidence, not bare yes/no. (Added after live eval runs showed reviewers passing defects the prompt had pointed them at — an accessible-name check and a temp-dir-cleanup check both got unsupported "yes" answers while the defect sat in the reviewed diff.)
+- **Read-only rule** kept in trimmed form: no mutating the working tree, index, HEAD, or branch state. The `git worktree add` how-to sentence from the current templates is NOT carried into this file — a diff-scoped review never needs a checkout of another revision (same rationale as the spec-prompt cleanup below).
+- **Verdict:** Strengths / Issues (Critical/Important/Minor) / "Task quality: Approved | Needs fixes."
+
+### 2. `skills/subagent-driven-development/spec-reviewer-prompt.md` cleanups
+
+- Remove the `git worktree add` how-to sentence. The read-only rule stays; a diff-scoped spec review never needs a checkout of another revision.
+- Resolve the tension between the diff-only guard and "verify everything independently": spec compliance is judged by reading the diff against the requirements. The implementer's TDD evidence covers "it runs" — apply the shared test principle.
+- New third verdict channel: requirements that cannot be verified from the diff (live in unchanged code, span tasks) are reported as explicit "⚠️ Cannot verify from diff — controller should check X" items, instead of either crawling or silently passing. The flowchart's binary pass/fail diamond cannot route this, so the controller guidance (§3) defines the handling: ⚠️ items do not block dispatching the quality reviewer, but the controller must resolve each one itself (it holds the plan and cross-task context) before marking the task complete; an item the controller confirms is a real gap is treated as a failed spec review and goes back to the implementer.
+- Replace the fabricated premise "The implementer finished suspiciously quickly" with grounded skepticism: treat the implementer's report as unverified claims about the code. Same distrust, no invented fact.
+
+### 3. `skills/subagent-driven-development/SKILL.md` controller changes
+
+- **Model Selection:** replace "Architecture, design, and review tasks: use the most capable available model" with judgment guidance — pick reviewer models the way implementer models are picked, scaled to the diff's size, complexity, and risk. The "Task complexity signals" list is rescoped to make clear its bullets describe implementation tasks; reviewer model choice follows the same judgment, so a narrow diff review does not automatically map to "broad codebase understanding → most capable model."
+- **Reviewer prompt construction** (new guidance near Red Flags): when dispatching reviewers, do not write open-ended directives ("check all uses," "run race tests if useful") without a concrete task-specific reason; do not ask reviewers to re-run tests the implementer already ran on the same code; do not pre-judge findings for the reviewer (never instruct a reviewer to ignore or not flag a specific issue — adjudicate suspected false positives in the review loop instead); per-task reviews are task-scoped gates — the broad review happens once, at the final whole-branch review. (The pre-judging rule was added after a live eval run caught the controller fabricating a "the plan forbids a shared helper" claim and instructing the quality reviewer not to flag a planted DRY violation.) Controllers must also include the spec/design's global constraints that bind the task — version floors, naming and copy rules, platform requirements — in the requirements they paste: a live run shipped a `go 1.26.1` module floor against a "Go 1.21+" design because no reviewer ever saw the constraint. And controllers must specify a model explicitly on every dispatch — an omitted model inherits the session's (usually most expensive) model, which silently defeats model selection.
+- **Handling spec-reviewer ⚠️ items** (new guidance, alongside Handling Implementer Status): the controller resolves each "cannot verify from diff" item itself before marking the task complete; confirmed gaps go back to the implementer as failed spec review.
+- **Final review stays broad, explicitly:** the final whole-branch reviewer dispatch node gains an explicit pointer to `../requesting-code-review/code-reviewer.md`. (Today that template is reachable only through the per-task quality prompt's delegation; once that delegation is removed, an unreferenced final-review template would be orphaned.) The Integration section's note that `superpowers:requesting-code-review` provides "the code review template for reviewer subagents" is corrected to apply to the final review only.
+- **Example workflow:** the quality-reviewer lines in the example are updated to the new verdict vocabulary ("Task quality: Approved"); the final reviewer's "ready to merge" line stays.
+- Flowchart topology is unchanged; the ⚠️ channel is handled by controller guidance, not a new graph branch.
+
+## What this does not fix (known, deferred)
+
+The spec reviewer judges against task text the controller pasted; it cannot catch requirements dropped during the controller's extraction from the plan. That is an architectural property of "controller provides full text," not a prompt problem, and is out of scope here.
+
+## Verification
+
+- Plugin infrastructure tests (`tests/`) still pass.
+- Run the SDD skill-behavior evals (`git submodule update --init evals`, then per `evals/README.md`) before and after the change. Specifically: `sdd-go-fractals`, `sdd-svelte-todo`, `sdd-rejects-extra-features` (end-to-end SDD including the spec reviewer's YAGNI gate), and `spec-reviewer-catches-planted-flaws`.
+- Known eval gaps this change exposes: no existing scenario plants a code-quality defect inside a single SDD task and asserts the per-task quality reviewer catches it, and no scenario measures per-reviewer exploration cost (tool-call/grep counts). Add one scenario covering the first gap (planted single-task quality defect → per-task reviewer must flag it before final review). For exploration cost, compare reviewer subagent tool-call counts manually across the before/after eval transcripts.

docs/superpowers/specs/2026-06-10-positive-instruction-redesign-design.md

@@ -0,0 +1,178 @@
+# Positive-Instruction Redesign of Skill Guidance — Design Spec
+
+**Status:** Proposed (follow-up to the 2026-06-09 SDD review-dispatch work; separate PR per the one-problem-per-PR rule)
+**Driver:** Measured evidence (2026-06-10) that some negative instructions in skill prose backfire, while others work — and that the difference is predictable.
+
+## The measured finding this spec generalizes
+
+Micro-tests on 2026-06-10 (opus, 5 reps per phrasing, programmatic scoring;
+harness described below) measured how guidance phrasing changes what a
+controller composes:
+
+| Case | Phrasing | Result |
+|---|---|---|
+| Dispatch composition ("don't restate the brief") | prohibition | **4.4** spec values re-typed — *worse than no guidance* (3.6) |
+| Dispatch composition | positive recipe ("your dispatch should contain: (1)…(5)") | **3.0, zero variance** — adopted |
+| Dispatch composition | recipe + nuance clause ("quote only the fragment…") | 3.8, noisy — nuance dilutes recipes |
+| Test-rerun directive ("do not ask reviewer to re-run tests") | prohibition | **0/5 violations** — works fine (control: 3/5) |
+| Test-rerun directive | positive recipe | 0/5 — equal, but longer |
+
+**The doctrine** (use this to classify any negative instruction):
+
+1. **Tripwires work.** Phrase-level self-checks on concrete tokens ("if the
+   prompt you are writing contains 'do not flag' … stop") fire reliably.
+2. **Recognition tables work.** Red-Flags/rationalization tables read at
+   decision time, not composition time.
+3. **Discrete-directive prohibitions work.** "Do not ask X to do Y" holds
+   when the model has no competing incentive to do Y.
+4. **Composition prohibitions backfire** when the model has its own agenda
+   for the output (e.g., restating specs feels like helpful curation).
+   Only a positive composition recipe moves these — and adding nuance
+   clauses to a winning recipe makes it worse, not better.
+5. **Ties go to the shorter phrasing.** Codex re-reads SKILL.md ~500× per
+   long session (measured 2026-06-10); prose length is a real cost.
+
+## Audit results (2026-06-10, all ~30 skills + prompt templates)
+
+Counts: 3 tripwires (keep), 14 recognition tables (keep), ~20 policy gates
+(keep — "never push without permission" is policy, not composition
+shaping), 5 composition-prohibitions:
+
+| # | Location | Disposition |
+|---|---|---|
+| 1 | `subagent-driven-development/task-reviewer-prompt.md` — "Cite, don't narrate" | **Queued in PR #1717 batch**: lead with the positive half ("Your report should point at evidence: file:line for every finding…"), drop the prohibition half (dead weight — the positive half already exists and carries the load) |
+| 2 | `subagent-driven-development/SKILL.md` — "Do not add open-ended directives" | **Keep as-is**: micro-test could not elicit the failure in 15 samples; no evidence either way; shorter wins |
+| 3 | `subagent-driven-development/SKILL.md` — "Do not ask a reviewer to re-run tests" | **Keep as-is**: measured 0/5 violations; the prohibition also usefully propagates itself into dispatches |
+| 4 | `subagent-driven-development/SKILL.md` — "do not re-review on top of it" | **Queued in PR #1717 batch**: replace with the three-element checklist ("Before re-dispatching the reviewer, confirm the fix report contains: the covering tests, the command run, and the output") |
+| 5 | `writing-plans/SKILL.md` — the "No Placeholders" banned-patterns list | **This spec's main subject** — see below |
+
+Borderline, deferred with #5: `task-reviewer-prompt.md` "Don't flag
+pre-existing file sizes — focus on what this change contributed" (positive
+half present and load-bearing; low impact; test alongside #5 if convenient).
+
+## The writing-plans change (deferred item #5)
+
+### Current state
+
+`skills/writing-plans/SKILL.md`, "No Placeholders": one positive sentence
+("Every step must contain the actual content an engineer needs") followed
+by a six-bullet banned-patterns list ("never write them: 'TBD', 'TODO',
+'Add appropriate error handling', 'Write tests for the above', 'Similar to
+Task N', …").
+
+### Why it matters and why it is genuinely uncertain
+
+- Plans are the **largest generated artifact** in the workflow, and the
+  model has a real competing incentive to emit placeholders (they are the
+  path of least effort under length pressure) — the incentive structure of
+  the case where prohibition measurably backfired.
+- But the banned items are **discrete, recognizable tokens** — the shape
+  of the case where prohibition measurably held.
+- **The list is load-bearing elsewhere:** the skill's Self-Review section
+  references it ("Placeholder scan: search your plan for red flags — any
+  of the patterns from the 'No Placeholders' section above"). The tokens
+  double as the review-time scan inventory, and review-time recognition is
+  the category that works. A naive swap to a positive checklist breaks
+  that reference and discards good tripwire tokens.
+
+### Variants to test
+
+- **V0 (current):** positive sentence + banned list at composition time;
+  Self-Review references the list.
+- **V1 (auditor's checklist):** composition-time positive recipe only —
+  "Before finalizing a step, confirm it has: the literal code to write, a
+  runnable command with expected output, types and method names defined
+  within this plan, error handling shown explicitly. A step is complete
+  when an engineer could implement it without asking any follow-up
+  questions." Self-Review keeps a generic placeholder scan.
+- **V2 (restructure by mechanism — predicted winner):** composition time
+  gets only V1's positive recipe; the named patterns move wholesale into
+  the Self-Review placeholder-scan step, reframed as recognition ("when
+  you scan, look for: 'TBD', 'TODO', 'Similar to Task N', …"). Same
+  tokens, relocated from the category that primes to the category that
+  detects.
+- **V3 (control):** positive sentence only, no list anywhere.
+
+### Micro-test design
+
+- **Task:** opus writes a 2-3 task implementation plan from a deliberately
+  under-specified spec (under-specification is what tempts placeholders).
+  Use a fixture spec with: one well-specified task, one task whose error
+  handling the spec hand-waves, one task similar to the first (tempting
+  "Similar to Task 1").
+- **Sampling:** 5+ reps per variant, default temperature, model
+  `claude-opus-4-8` (the model that writes plans in practice).
+- **Programmatic scoring** (lower is better unless noted):
+  - banned-token count: `TBD|TODO|implement later|fill in details|appropriate error handling|handle edge cases|Similar to Task|Write tests for the above`
+  - steps lacking a fenced code block where the step changes code
+  - references to types/functions not defined anywhere in the plan output
+  - (higher is better) runnable commands with expected output per task
+- **Two-stage scoring for V2:** also test the Self-Review half — feed each
+  generated plan back with the variant's Self-Review section and measure
+  whether the scan actually catches seeded placeholders (insert 2 known
+  placeholders into a fixture plan; detection rate is the metric).
+- **Acceptance:** adopt a variant only if it beats V0 on banned-token count
+  without losing code-block coverage or self-review detection rate.
+  Expected cost: ~$6-10 total.
+
+### PR scoping
+
+Separate PR (writing-plans is a different skill; its "No Placeholders"
+list is tuned content where the contributor guidelines demand eval
+evidence). The PR must include: the micro-test harness + results table,
+before/after text, and the V2 relocation rationale.
+
+## The micro-test harness (method, so it isn't lost)
+
+`/tmp/sdd-exp/micro/run-micro.py` and `/tmp/sdd-exp/micro2/run-micro2.py`
+(2026-06-10; to be committed to superpowers-evals as
+`docs/superpowers/skills/micro-testing-prompt-guidance.md` + scripts):
+
+- One API call per sample: system prompt = the skill-guidance variant in
+  realistic surrounding context; user = a realistic mid-workflow scenario;
+  output = the composed artifact (dispatch prompt, plan, report).
+- Programmatic scoring with greps for unambiguous markers; **manually
+  inspect every match before trusting a verdict** — one of tonight's
+  "violations" was the controller correctly quoting the prohibition, and
+  automated negation detection mislabeled another.
+- ~$0.15-0.30/sample, seconds per iteration vs $12/50-min full eval runs.
+  Iterate phrasings here; confirm winners in full runs only when the
+  change is structural.
+- Always include a no-guidance control — tonight it revealed both a
+  backfire (restating: prohibition worse than nothing) and a working
+  prohibition (test-reruns: 3/5 control failures vs 0/5 with either
+  phrasing).
+
+## Result: writing-plans micro-test (run 2026-06-10, after this spec was written)
+
+**Resolved — no change needed.** Stage 1 (3-task spec, no pressure): 0
+placeholders in all 20 plans across all four variants including the
+no-guidance control. Stage 1b (10-task spec, five near-identical commands
+tempting "Similar to Task N", explicit ~2,500-word economy target): 40/40
+clean — the single regex hit was a V2 self-review *attesting* "no
+TBD/TODO ✓". Current-generation opus does not produce plan placeholders
+even under deliberate pressure, with or without the banned-patterns list.
+Disposition: leave the No Placeholders section exactly as it is (it costs
+little and the counterfactual is unmeasurable); do NOT open the follow-up
+PR. The V2 relocation design remains on file here should a future model
+generation regress.
+
+## Also explicitly not-dropped (tested-and-declined, with data)
+
+Recorded so nobody re-proposes them without new evidence — full numbers in
+the 2026-06-09 SDD design spec's Cost-iterations section:
+
+- **Controller turn batching / parallel tool calls in one message:** the
+  controller emits exactly one tool call per message (0 multi-tool
+  messages across every measured run, with and without guidance). 46% of
+  controller turns are thinking/narration with no tool call — a
+  prompt-immune floor.
+- **Pipelined reviews via parallel calls:** dead for the same reason.
+- **Pipelined reviews via `run_in_background`:** mechanism adopted when
+  offered (7/28 dispatches) but benefit below the run-to-run noise floor
+  on 45-min scenarios (reviews are only ~30-60s each); adds dual
+  result-stream coordination. Worth revisiting only for plans whose
+  reviews are individually long.
+- **Nuance clauses appended to winning recipes:** measurably degrade them
+  (C2: 3.8 noisy vs C: 3.0 consistent). Iterate by re-deriving the recipe,
+  not by appending caveats.

docs/superpowers/specs/2026-06-10-strict-cost-sdd-design.md

@@ -0,0 +1,265 @@
+# Strict-Cost SDD — Design Spec
+
+**Status:** Proposed experiment ladder (not implementation). Each rung ships
+only with its gate evidence; abort any rung whose gates fail.
+**Objective:** minimize dollars per plan-execution. Wall-clock is
+unconstrained; token count matters only as a cost driver.
+**Hard invariant:** quality. Concretely: `sdd-quality-reviewer-catches-
+planted-defect` pass rate over **N=5 runs** (not 1 — single-run gates were
+this campaign's weakest methodology), `sdd-rejects-extra-features` pass,
+all end-to-end scenarios pass, blind A/B deliverable parity with the
+current config. Any quality regression kills the rung, full stop.
+
+## Where the dollars are (final 2026-06-10 config, go-fractals, ~$13/run)
+
+| Component | $ | Driver |
+|---|---|---|
+| Controller (session model, opus) | ~6-7 | ~150 turns × resident context; prompt-immune turn floor (46% thinking/narration) |
+| Implementers (sonnet, 10-13 dispatches) | ~5-6 | the actual work; ~25 turns each; ~13 pre-edit exploration calls each |
+| Task reviewers (sonnet, 10) | ~1-1.5 | 3-9 turns each with package |
+| Final review + fixes | ~1 | 6 turns with branch package |
+
+Review-loop count (2-4 per run) is the biggest run-to-run cost variance;
+loops are mostly caused by plan ambiguity the implementer resolved wrongly.
+
+## Judgment guardrail (co-invariant with quality)
+
+**Cheapen mechanics, never judgment.** Every rung must enumerate which
+decisions it moves to a cheaper model and show each is *mechanical* —
+deterministic, scriptable, or cheaply verifiable after the fact. Judgment
+stays at the highest tier or with the human. The judgment points in SDD,
+explicitly:
+
+- **BLOCKED / NEEDS_CONTEXT handling** — diagnosing why a subagent is stuck
+  and choosing the remedy
+- **⚠️ "cannot verify from diff" resolution** — the controller adjudicating
+  with cross-task context
+- **Dispatch curation** — ambiguity resolution and task-boundary drawing
+  (measured load-bearing: the Task 5 gradient-direction note prevented a
+  wrong implementation)
+- **Review verdicts and severity calibration** — what is Important vs Minor
+- **Review-loop adjudication** — deciding a finding is a false positive
+- **Escalate-to-human recognition** — knowing the plan itself is wrong
+
+A rung that would move any of these to a cheaper model must either (a)
+restructure so the decision is made once by the expensive model at plan
+time, (b) add an explicit escalation rule routing it back up at execution
+time, or (c) die. "The cheap model usually gets it right" is not
+acceptance evidence — judgment failures are rare-event, high-blast-radius,
+and largely invisible to pass/fail gates, which is why every tier change
+below carries a judgment audit (session-resume interrogation of each
+judgment point in the gate runs, compared against the expensive-controller
+baseline) in addition to the N=5 scenario gates.
+
+## Thesis guardrail
+
+SDD's thesis: **a fresh subagent per task with precisely curated context,
+gated per task.** Rungs below must preserve it. Dispatch-time task batching
+(one implementer dispatch handling several plan tasks) is **counter-thesis**
+— it pollutes the fresh-context property and coarsens the gates — and is
+deliberately NOT on the ladder. The thesis-compatible route to the same
+dispatch economics is plan-time task right-sizing (L1): if the plan defines
+fewer, better-sized tasks, SDD still runs one fresh subagent per task.
+
+## The ladder (in expected $/leverage order)
+
+### L1 — Plan-side crispness (writing-plans changes; est. −$1.5-3/run, plus variance reduction)
+
+**Status 2026-06-11 (final): elicitation tested end-to-end; claims
+re-attributed.** Micro-tests: constraints header and Interfaces blocks
+elicit deterministically (0→5/5, 0→100% of tasks, exact values);
+right-sizing is modest and scale-dependent (9.4→8.4 tasks at svelte
+scale, nothing to move at fractals scale). Full runs: an elicited plan
+executed at $6.34/$8.49 — but the no-guidance control (opus plan,
+complete code) hit $7.59/$7.73, inside that range. **The cost win
+belongs to opus-written complete-code plans; the hand-written prose
+fixture plans all prior numbers used are unrepresentative and ~2×
+costlier to execute.** The guidance owns fidelity and variance instead:
+deterministic constraints propagation (the one elicited-run fix was a
+version-floor catch), exact cross-task interfaces, fix waves 1 vs 2-4
+(the control plan shipped a real Sierpinski bug both runs had to fix).
+The writing-plans PR claims those grounds, not dollars. Draft at
+/tmp/sdd-exp/writing-plans-l1 (branch writing-plans-crisp).
+
+The plan is upstream of every cost: task count sets dispatch count; plan
+ambiguity sets review-loop count; plan completeness sets implementer
+exploration. Current writing-plans optimizes for implementer success, not
+execution economics. Changes to test:
+
+1. **Task right-sizing guidance.** Today's plans produce tasks as small as
+   "create .gitignore" — each costing a full dispatch + review cycle
+   (~$0.60-1.00 fixed overhead). Add: "A task is the smallest unit that
+   carries its own test cycle and is worth a fresh reviewer's gate. Merge
+   setup/config steps into the task that needs them; split only at
+   boundaries where a reviewer could meaningfully reject." Fractals' plan
+   would drop from 10 tasks to ~7. Validate: dispatch count falls, gates
+   hold, review granularity still catches the planted defect.
+2. **Structured `## Global Constraints` section** in the plan header
+   (version floors, naming/copy rules, platform requirements). Today these
+   live in design.md prose and reach reviewers only if the controller
+   remembers to paste them (a `go 1.26.1` floor violation shipped because
+   none did). A fixed heading makes them mechanically extractable —
+   `task-brief` can append them to every brief automatically (small script
+   change), removing a controller responsibility entirely.
+3. **Per-task `Interfaces:` line** (consumes/produces, exact signatures).
+   The controller currently re-derives cross-task interfaces per dispatch
+   (its main legitimate "restating"), and implementers spend ~13 tool calls
+   re-discovering context. The planner already knows the interfaces; one
+   line per task moves the work to where it is done once.
+4. **Per-task model-tier recommendation** from the planner ("mechanical /
+   standard / judgment"). The planner has the best information for the
+   Model Selection decision the controller currently re-makes per dispatch;
+   the controller keeps override authority.
+
+Validation: micro-test the planner output shape (recipe-style, per the
+instruction-design doctrine), then full runs. Note the 2026-06-10 result:
+plan *placeholders* cannot be elicited from current opus — these changes
+target economics and ambiguity, not placeholder hygiene.
+
+### L2 — Controller tier (est. −$4-5/run; the biggest single lever, gated hardest)
+
+**Status 2026-06-11 (final): DIED AT THE GATES, as pre-registered — with
+useful anatomy.** Recon was positive ($6.68/$8.05, n=2, mechanics clean).
+The full battery split the judgment surface: the new
+`sdd-escalates-broken-plan` scenario (explicit plan self-contradiction;
+the human never volunteers it) passed **5/5 at sonnet** ($1.02-1.37/run;
+opus baseline 2/2) — explicit conflicts get escalated. But the
+planted-defect battery failed decisively: under a sonnet controller the
+per-task quality gate collapsed into plan-compliance advocacy ("no
+assertion, as required" listed under Strengths), the defect shipped in
+4/5 runs (deterministic check), and only the tier-pinned opus final
+reviewer ever caught it — while the same sonnet-tier reviewers under an
+opus controller flagged it 5/5. Cheap controllers handle explicit
+escalation; they absorb implicit authority-vs-quality adjudication.
+A possible L2b (discrete rule: "a reviewer finding that conflicts with
+the plan's text is the human's decision — escalate it") would route the
+failing judgment through the escalation behavior that held.
+
+**L2b tested 2026-06-11 (E35/E36, evals
+`docs/experiments/2026-06-11-build-loop-autoresearch.md`): improves the
+opus stack, does NOT rescue the sonnet rung.** Two rules: a reviewer
+tripwire (a plan-mandated defect IS a finding — Important, labeled
+plan-mandated; the human decides) and a controller escalation rule
+(plan-mandated findings go to the human like any plan contradiction).
+Micro on frozen sonnet-composed inputs: 0/6 → 6/6 labeled findings.
+Full battery: opus controllers 2/2 internalized the rule, caught their
+reviewer's miss as self-described backstop, and escalated for a
+sanctioned fix (the 4241 ad-hoc behavior made structural); escalation
+sanity 2/2 unbroken. Sonnet controllers: 1/5 full pass — paraphrase
+drops the tripwire from dispatches (2/5 transmitted), transmission
+alone doesn't fire it live (read-once dilution across the reviewer's
+tool reads; placement within the dispatch refuted as the variable),
+and no sonnet controller showed backstop behavior; 1/5 shipped the
+defect. The L2b rules are a candidate commit for the opus stack.
+A future L2c for the sonnet rung would pair the SKILL.md
+constraints-recipe (the one channel sonnet transmits verbatim) with a
+mandatory output-format slot for plan-mandated findings (the skeleton
+survives every observed paraphrase and is consulted at composition
+time); untested. Original recon notes follow.
+
+**Recon (superseded):**
+Sonnet-controller runs (claude-sonnet coding-agent): all gates green at
+**$6.68 and $8.05** / 31-41 min (combo band $11.67-14.84), tokens inside
+the combo band — no cheap-controller turn inflation. 26/26 and 31/31
+dispatches model-explicit, with heavier (and sane) haiku tiering than
+opus controllers showed; review loops, per-task Important→fix→re-review,
+and omnibus-fixer rules followed in both runs; the run-1 controller
+caught a fixer side-effect (`go mod tidy` removed cobra) before
+re-review — real adjudication, not silent absorption. But neither run
+surfaced a BLOCKED/⚠️ event (the escalation points were never stressed)
+and final reviews ran on sonnet rather than the most capable tier. The
+N=5 quality gates + full judgment audit below remain mandatory before
+any skill change.
+
+The controller is half the dollars solely because it inherits the session
+model. Its turn floor is prompt-immune, so the lever is the rate per turn —
+but the controller is also where most judgment points live, so this rung is
+designed judgment-first:
+
+1. **Primary form — judgment moved up front, mechanics cheapened:** the
+   expensive model does the judgment-dense work at plan time (L1's
+   Interfaces lines, ambiguity resolutions, per-task constraints — i.e.
+   the dispatch curation is pre-written into the plan). The mid-tier
+   execution session then runs a loop that is genuinely mechanical:
+   extract brief, dispatch, run script, route verdicts. Explicit
+   escalation rules in the skill: on BLOCKED, on any ⚠️ item, on a
+   suspected false positive, or on anything the plan does not already
+   answer, the cheap controller STOPS and escalates (to the human, or to
+   a fresh expensive-model consultation dispatch) — it never resolves
+   judgment alone.
+2. **Gates beyond the standard N=5:** a judgment audit — every
+   BLOCKED/⚠️/adjudication event in the gate runs interrogated via
+   session-resume and scored against how the opus-controller baseline
+   handled the same class of event; any silently-absorbed judgment call
+   (cheap controller resolving what it should have escalated) fails the
+   rung regardless of scenario verdicts.
+3. **User authority preserved:** the skill recommends, never enforces, the
+   execution-session tier.
+
+Caveat from this campaign: cheap-model turn inflation was measured on
+multi-step *work*, not dispatch loops; whether a mid-tier controller holds
+~150 turns is part of what the experiment determines.
+
+### L3 — Reviewer tier (est. −$0.7-1/run; most likely rung to die on the judgment guardrail)
+
+**Status 2026-06-11: DEAD, as pre-registered.** Planted-defect ×5 with
+forced-haiku task reviewers: 2 pass / 1 indeterminate / 2 fail (baseline
+5/5); per-task haiku cleanly flagged 0 of 10 planted defects at correct
+severity — 1 found-but-downgraded with the exact prohibited rationale,
+9 missed or rationalized (DRY praised as YAGNI; assert-nothing test
+called plan-compliant). Cheap reviewers fail by *advocating* for
+defects; passing runs survived only on controller redundancy or the
+final review. Recorded in the experiments log, Batch A-E. Do not
+re-propose without a structurally different design.
+
+The package reviewer is near-single-step mechanically (3 turns / 1 Read
+when calm), which invalidates the original turn-inflation rationale for the
+mid-tier floor — but reviewing is judgment through and through: severity
+calibration, spec verdicts, knowing what not to flag. Mechanical cheapness
+does not make the decisions mechanical. Test haiku-with-package only with
+the full judgment battery: planted-defect ×5, a severity-calibration check
+(seeded Minor-vs-Important pairs; miscalibration fails the rung), and the
+escape-hatch variance re-measured at that tier. Prior expectation: this
+rung dies, and that is a fine outcome — it converts "we suspect cheap
+reviewers are bad" into recorded evidence.
+
+### L4 — Resident-context diet (est. −$0.5-1/run)
+
+- `task-brief --list` mode: controller reads task headings + Global
+  Constraints, never the full plan (the plan body is already delivered via
+  briefs).
+- Reports trim 15 → 8 lines.
+- SKILL.md minification pass (every section added this week re-justified
+  at composition-recipe density; Codex pays ~10k chars × ~500 re-reads per
+  long session).
+
+### L5 — Re-litigations (explicitly flagged, maintainer-vetoed or counter-thesis)
+
+Recorded for completeness; each requires Jesse's explicit reversal before
+any experiment:
+- **Scoped re-reviews** (verify fix + regression scan instead of full
+  re-review): vetoed 2026-06-09; worth ~$0.50/run at most.
+- **Dispatch-time task batching**: counter-thesis (see guardrail). L1.1
+  is the sanctioned form.
+
+## Budget and sequencing
+
+L1 and L2.1 are independent — run both first (~$80: micro-tests + 2×5-run
+gates + A/B). L3 after L2 settles the controller (reviewer behavior depends
+on dispatch quality; ~$25 — planted-defect runs are $2-3 each). L4 last
+(cheap, but re-gate once after the stack; ~$30). Total ≲ $150 for the full
+ladder with honest N=5 gates. Expected end state if every rung survives its gates: **$5-7/run on
+fractals (from $12-15)**; if the judgment-sensitive rungs (L2 beyond its
+primary form, L3) die as expected, **$8-10/run** — the honest target, since
+the guardrail prices judgment above dollars by construction.
+
+## Relationship to existing work
+
+Builds on the 2026-06-09 task-scoped review dispatch design (PR #1717) and
+the 2026-06-10 experiment campaign (evals
+`docs/experiments/2026-06-10-sdd-cost-experiments.md` — consult the
+negative-results section before adding rungs; turn-discipline and
+parallel-call mechanisms are dead). Instruction wording for any new prose
+follows the positive-instruction doctrine spec and gets micro-tested before
+full runs. L1 is a writing-plans change → its own PR with eval evidence;
+L2-L4 are SDD changes → separate PR(s).

docs/superpowers/specs/2026-06-10-visual-companion-auth-hardening-design.md

@@ -0,0 +1,225 @@
+# Visual Companion Auth Hardening Design
+
+**Date:** 2026-06-10
+**Status:** Draft for Drew review
+
+## Goal
+
+Fix the security and reliability gaps found in PR #1720's brainstorming visual
+companion without changing the companion's core workflow or adding runtime
+dependencies.
+
+The fixes must be test-first and must leave clear automated evidence for:
+
+- cross-origin browser tabs cannot inject companion events by riding cookies
+- restart reconnect works without depending only on browser cookie behavior
+- bearer keys do not remain in the visible URL after bootstrap
+- `/files/*` cannot serve files outside the content directory
+- future same-origin vendored UI libraries still work
+
+## Threat Model
+
+The companion serves agent-generated local UI for a single brainstorming
+session. The important assets are:
+
+- screen content served from the companion
+- the session key
+- `state/events`, which the agent reads as user feedback
+- local files under the companion session directory
+
+In scope attackers:
+
+- a malicious browser tab on another `localhost` port
+- a browser page that can make requests to the companion but should not be able
+  to authenticate as the companion UI
+- a direct remote client when the server is bound to a non-loopback interface
+- accidental leakage through URL history, referrers, or committed local state
+- content-directory symlinks or path tricks that escape `/files/*`
+
+Out of scope for this fix:
+
+- malicious agent-authored screen HTML
+- malicious same-origin vendored JavaScript loaded by a companion screen
+
+This out-of-scope boundary is intentional. Companion screens are part of the
+agent UI surface. They may use inline scripts today and may someday use
+same-origin vendored libraries such as Alpine or Three.js. Protecting against
+malicious screen HTML would require a larger sandboxed-iframe architecture with
+a narrow message bridge; that is not the scope of this PR hardening pass.
+
+## Current Failures
+
+Automated and headed-browser testing found these failures in the PR branch:
+
+1. A cross-origin localhost page can open a cookie-authenticated WebSocket and
+   write attacker-controlled choices to `state/events` after the real companion
+   page sets the cookie.
+2. `/files/*` serves symlinks that point outside `content/`, including a symlink
+   to `state/server-info` containing the keyed URL.
+3. The session key remains in the URL of the actual screen page, so same-origin
+   screen JavaScript and accidental referrers/history can see it.
+4. The helper reconnects with a keyless `ws://host` URL. In headed Chrome, after
+   a same-port/same-token restart, the browser stopped presenting the cookie to
+   the restarted server, so the open tab stayed stuck on the tombstone until a
+   manual reload.
+5. Shell lint and the lifecycle test need cleanup so the test pass is stable in
+   Codex.
+
+## Design
+
+### 1. Bootstrap Keyed Loads
+
+`GET /?key=<token>` becomes a bootstrap response, not the screen response.
+
+When the key is valid, the server:
+
+1. sets the HttpOnly session cookie as it does today
+2. returns a small HTML bootstrap page
+3. the bootstrap page stores the key in tab-scoped `sessionStorage`
+4. the bootstrap page navigates to `/` using `location.replace('/')`
+
+After this, the visible screen URL is bare `/`, not `/?key=...`.
+
+`GET /` with a valid cookie serves the current screen. `GET /` without a valid
+cookie still returns the friendly 403 page. `GET /?key=<wrong>` returns 403.
+
+Why `sessionStorage`: the helper needs a reconnect credential that survives
+same-port restarts and does not depend only on cookie behavior. Because screen
+HTML is trusted same-origin UI, storing the key in tab-scoped storage is
+acceptable for this threat model. It is materially better than leaving the key
+in the address bar, history, and referrer surface.
+
+### 2. WebSocket Same-Origin Enforcement
+
+WebSocket upgrades must pass both checks:
+
+1. valid session auth by query key or cookie
+2. if an `Origin` header is present, it must match the request target origin
+
+The origin check should compare:
+
+```text
+Origin === "http://" + req.headers.host
+```
+
+Browser attacker page example:
+
+```text
+Origin: http://localhost:9999
+Host: localhost:58088
+```
+
+This must be rejected even if the browser sends the companion cookie.
+
+Legitimate companion page example:
+
+```text
+Origin: http://localhost:58088
+Host: localhost:58088
+```
+
+This should be accepted when the key or cookie is valid.
+
+Direct non-browser clients may omit `Origin`; they still need the session key.
+
+### 3. Helper Reconnect Credential
+
+`helper.js` should read the tab-scoped key from `sessionStorage` and append it
+to the WebSocket URL:
+
+```text
+ws://<host>/?key=<stored-key>
+```
+
+If no stored key exists, the helper falls back to the current cookie-only
+`ws://<host>` behavior. This preserves compatibility for already-loaded pages
+that do have a valid cookie but no storage entry.
+
+### 4. `/files/*` Containment
+
+The file server should continue to reject empty names and dotfiles. It must also
+ensure the file is a real regular file inside `CONTENT_DIR`.
+
+Use realpath containment as the boundary:
+
+- compute `realContentDir = fs.realpathSync(CONTENT_DIR)`
+- compute `realFilePath = fs.realpathSync(filePath)`
+- serve only when `realFilePath` equals a descendant of `realContentDir`
+- reject symlinks and anything outside the content directory with 404
+
+The server should keep using `path.basename` so nested paths remain unsupported.
+
+### 5. Leak-Reduction Headers
+
+Add conservative headers that do not block inline scripts or future same-origin
+vendored libraries:
+
+```text
+Referrer-Policy: no-referrer
+Cache-Control: no-store
+X-Frame-Options: DENY
+Content-Security-Policy: frame-ancestors 'none'
+Cross-Origin-Resource-Policy: same-origin
+```
+
+Do not add a restrictive `script-src` CSP in this pass. The companion currently
+injects inline helper JavaScript and future screens may load same-origin
+vendored libraries.
+
+### 6. Gitignore Durable Session State
+
+Add `.superpowers/` to the repo root `.gitignore` so persisted companion state
+and `.last-token` are not accidentally committed when using `--project-dir`.
+
+### 7. Test Stability And Lint
+
+Clean up shell lint warnings in the touched start/stop scripts.
+
+Update the lifecycle test that invokes `start-server.sh --idle-timeout-minutes`
+so it cannot hang under Codex's `CODEX_CI` foreground auto-detection. The test
+should force background mode with `--background` when it expects the script to
+return startup JSON.
+
+## Testing Strategy
+
+All behavior changes should be TDD:
+
+1. write the failing focused test
+2. run it and confirm it fails for the expected reason
+3. implement the minimum fix
+4. rerun the focused test
+5. rerun the full brainstorm-server suite
+
+Required focused regressions:
+
+- valid keyed `/` returns bootstrap, not screen content
+- bootstrap stores key in `sessionStorage` and strips the URL
+- cookie-only `/` still serves screen content
+- helper uses `sessionStorage` key for WebSocket URL
+- same-origin cookie WebSocket opens
+- cross-origin cookie WebSocket is rejected and writes no events
+- direct key WebSocket still opens without `Origin`
+- symlink under `content/` pointing to `state/server-info` returns 404
+- security headers are present on normal HTML, bootstrap, 403, and file responses
+- restart same port/token can authenticate reconnect with the stored key
+- shell lint passes for touched shell scripts
+- lifecycle suite does not hang under Codex
+
+## Acceptance Criteria
+
+- `cd tests/brainstorm-server && npm test` passes repeatedly without hanging.
+- The security probe that previously wrote `attacker-injected` from another
+  localhost origin now fails to open the WebSocket and leaves `state/events`
+  unchanged.
+- The symlink-to-`server-info` probe returns 404.
+- A headed or headless browser keyed load ends on a bare `/` URL and the status
+  pill reaches Connected.
+- A same-port/same-token restart reconnects automatically without manual reload.
+- `scripts/lint-shell.sh` passes for the touched shell scripts.
+
+## Deferred Work
+
+If the project later needs to treat screen HTML as untrusted, design a separate
+sandboxed iframe architecture. That should isolate generated screens on a
+separate origin or sandboxed frame and expose only a narrow `postMessage` bridge
+for user choices. Do not bundle that into this fix.

docs/superpowers/specs/2026-06-11-visual-companion-final-hardening-fixup-design.md

@@ -0,0 +1,254 @@
+# Visual Companion Final Hardening Fixup Design
+
+**Date:** 2026-06-11
+**Status:** Draft for Drew review
+
+## Goal
+
+Finish the PR #1720 visual companion hardening pass so the branch is ready for
+Jesse review with clean security behavior, deterministic tests, and a PR diff
+that contains only the companion work.
+
+This is a fixup on top of the existing auth hardening design. It should not
+redesign the companion or expand the feature surface.
+
+## Background
+
+The previous hardening pass added keyed sessions, same-origin WebSocket checks,
+URL key stripping, `/files/*` containment, leak-reduction headers, IPv6 URL
+formatting, Windows lifecycle coverage, and PR evidence updates.
+
+The final review pass found five remaining issues:
+
+1. The root `GET /` screen-selection path can still serve symlinks or hardlinks
+   under `content/` that point outside the content directory.
+2. When the preferred port is occupied, fallback servers can reuse a persisted
+   `.last-token`, creating two live same-project companion servers with the same
+   bearer key.
+3. `stop-server.sh` can signal an unrelated `node server.cjs` process when
+   strong ownership proof is unavailable.
+4. Some tests can pass against the wrong fallback process, leak background
+   processes on failure, or assume symlink support on Windows-like hosts.
+5. The PR is currently conflicted because the branch contains an older `evals`
+   submodule bump that was handled separately.
+
+## Non-Goals
+
+- Do not add HTTPS tunnel or `wss://` origin semantics in this pass.
+- Do not implement opt-out, free-text, or contrast-helper companion features.
+- Do not vendor Alpine, Three.js, or any other JavaScript library.
+- Do not attempt to sandbox malicious agent-authored screen HTML.
+- Do not add backward compatibility for stale stop-server PID files unless Drew
+  explicitly approves that tradeoff.
+
+## Inherited Security Invariants
+
+This fixup preserves the auth hardening already designed and implemented:
+
+- `.last-token` and `state/server-info` remain sensitive owner-only state.
+- Fallback tokens may appear in startup JSON and `state/server-info`, but must
+  not be written to `.last-token`.
+- Cookies remain port-named, `HttpOnly`, `SameSite=Strict`, and scoped to `/`.
+- WebSocket upgrades still require a valid key or cookie.
+- WebSocket `Origin` checks remain enforced when the browser supplies an
+  `Origin` header.
+- Direct no-`Origin` clients remain allowed only when they carry the session key.
+- Generated same-origin screen JavaScript and future same-origin vendored
+  libraries are trusted. Sandboxing malicious screen HTML remains deferred.
+
+## Design
+
+### 1. Rebase Onto Current `dev`
+
+Rebase `brainstorming-companion` onto current `origin/dev` before implementation
+work. Resolve the `evals` submodule conflict by taking `dev`.
+
+After the rebase:
+
+- `evals` must not appear in the PR diff.
+- PR #1720 can still mention eval evidence that was run elsewhere, but it must
+  include exact external evidence: eval repo commit, scenario path, command,
+  result artifact path or id, and RED/GREEN outcome.
+- The PR body must not imply the evals submodule bump is part of this PR.
+- Any earlier PR-body text or comment implying the submodule bump is included
+  must be superseded by the final PR-body evidence.
+
+### 2. Root Screen Containment
+
+The root screen route must use the same containment boundary as `/files/*`.
+
+`getNewestScreen()` should ignore any `.html` candidate that does not pass the
+regular-file-inside-content-dir guard. That guard must resolve real paths and
+ensure the served file is inside `CONTENT_DIR`. It must also preserve the
+existing hardlink protection by rejecting files whose link count is not exactly
+one when the platform reports link counts.
+
+Expected behavior:
+
+- A symlink under `content/` pointing outside `content/` is ignored.
+- A hardlink under `content/` to `state/server-info` is ignored when
+  `fs.linkSync` succeeds and `lstat.nlink > 1`.
+- If no safe screen file remains, the waiting page is served.
+- Existing `/files/*` containment behavior remains unchanged: empty names,
+  dotfiles, symlinks, hardlinks, and directories still return 404.
+
+### 3. Fallback Token Isolation
+
+Port fallback must not reuse a token loaded from persisted `.last-token`.
+
+Token source should be explicit in code:
+
+- `BRAINSTORM_TOKEN` from the environment is an intentional operator/test
+  override. If the preferred port is occupied while an explicit environment
+  token is set, the server must fail closed instead of falling back, because the
+  occupied server may be using the same explicit token.
+- `.last-token` is persisted state for same-port reconnect convenience. If the
+  server falls back because the preferred port is occupied, discard that loaded
+  token and generate a fresh unpersisted token for the fallback process.
+- A newly generated token that was not loaded from `.last-token` can be reused
+  within the same process because no other live process is known to have it.
+
+The fallback server must continue to avoid overwriting `.last-port` and
+`.last-token`.
+
+### 4. Stop-Server Ownership Proof
+
+`start-server.sh` should create a per-start server instance id and pass it to
+Node as an inert command-line argument, for example:
+
+```text
+node server.cjs --brainstorm-server-id=<id>
+```
+
+The id is not an auth credential. It is only process-ownership evidence for the
+local lifecycle scripts. `server.cjs` can ignore the argument.
+
+The id must use a shell/MSYS-safe alphabet, such as
+`^[A-Za-z0-9_-]{32,64}$`. Store it in `state/server-instance-id` with
+owner-only permissions.
+
+`stop-server.sh` should read the expected id from state and only signal the PID
+when the target process argv contains the exact argument
+`--brainstorm-server-id=<id>` as a full argv token, not as a loose substring.
+Prefer `/proc/<pid>/cmdline` when available, then fall back to wide `ps` output.
+A matching instance id is sufficient proof even when `server-info` is missing
+or `lsof` is unavailable. Existing port-to-PID checks may remain as additional
+evidence.
+
+Fail closed when ownership cannot be proven:
+
+- missing PID file
+- missing or malformed server id
+- target command line unavailable
+- target command line does not include the expected id
+- old/stale session metadata without the new id
+
+This intentionally prefers leaving a stale process running over killing an
+unrelated process.
+
+Operator-visible outcomes should be explicit:
+
+- missing PID file returns `not_running`
+- missing or malformed server id returns `stale_pid`
+- unavailable command line returns `stale_pid`
+- wrong or absent argv id returns `stale_pid`
+- successful stop returns `stopped`
+
+On `stale_pid` and `stopped` outcomes, remove `server.pid` and
+`server-instance-id` so future stop attempts do not keep targeting the same
+ambiguous process. Do not remove persistent session content.
+
+### 5. Test Hardening
+
+The test pass should be deterministic across macOS and the Windows Git Bash host
+used for validation.
+
+Required changes:
+
+- Fixed-port suites must either fail fast if the server reports a fallback port
+  or drive all clients from the reported startup port.
+- `stop-server.test.sh` needs a top-level cleanup trap before any background
+  process is started.
+- Symlink-specific assertions should probe symlink capability and skip only that
+  assertion when the host cannot create usable test symlinks.
+- Tests that create impostor processes must assert that the impostor survives
+  when lifecycle metadata is missing or insufficient.
+- Windows/MSYS start-server tests must assert that Windows-like detection still
+  clears `BRAINSTORM_OWNER_PID`, still auto-foregrounds when appropriate, and
+  still passes the instance-id argv exactly.
+
+### 6. Docs And PR Consistency
+
+Before Jesse reviews, reconcile reviewer-visible docs and PR metadata:
+
+- Update the issue catalog so dispositions match what this PR actually ships.
+- Keep auto-open docs consistent with the implemented `--open` behavior.
+- Keep the documented default idle timeout at 4 hours everywhere.
+- Review the PR body against the template after the rebase.
+- Record macOS, Windows, browser/manual, and external eval evidence in the PR
+  body with concrete commands and results.
+
+## Testing Strategy
+
+Use TDD for each behavior change:
+
+1. Add or tighten a focused regression test.
+2. Run it and confirm it fails for the expected reason.
+3. Implement the smallest fix.
+4. Rerun the focused test.
+5. Rerun the full brainstorm-server suite.
+
+Required focused regressions:
+
+| Behavior | Test File | Focused Command | Expected RED | Expected GREEN |
+| --- | --- | --- | --- | --- |
+| Root route ignores symlink escape | `tests/brainstorm-server/server.test.js` | `node tests/brainstorm-server/server.test.js` | authenticated `GET /` serves linked outside content | response serves waiting page or safe screen |
+| Root route ignores supported hardlink escape | `tests/brainstorm-server/server.test.js` | `node tests/brainstorm-server/server.test.js` | authenticated `GET /` serves hardlinked `server-info` | hardlink candidate is ignored when `nlink > 1` |
+| `/files/*` containment stays unchanged | `tests/brainstorm-server/server.test.js` | `node tests/brainstorm-server/server.test.js` | existing containment test regresses | empty, dotfile, directory, symlink, hardlink cases remain 404 |
+| Persisted-token fallback rotates token | `tests/brainstorm-server/lifecycle.test.js` | `node tests/brainstorm-server/lifecycle.test.js` | fallback URL key equals persisted preferred-port key | fallback URL key differs and is not written to `.last-token` |
+| Explicit-token fallback fails closed | `tests/brainstorm-server/lifecycle.test.js` | `node tests/brainstorm-server/lifecycle.test.js` | server falls back while `BRAINSTORM_TOKEN` is set | process exits non-zero and does not start fallback |
+| Fallback key cannot authenticate to original server | `tests/brainstorm-server/lifecycle.test.js` | `node tests/brainstorm-server/lifecycle.test.js` | fallback key receives 200 from original port | original port rejects fallback key |
+| Correct instance id permits stop | `tests/brainstorm-server/stop-server.test.sh` | `bash tests/brainstorm-server/stop-server.test.sh` | real start-server-launched server survives | stop returns `stopped` and process exits |
+| Wrong, missing, malformed, or stale id is safe | `tests/brainstorm-server/stop-server.test.sh` | `bash tests/brainstorm-server/stop-server.test.sh` | impostor is signaled | stop returns `stale_pid` and impostor survives |
+| Fixed-port suites cannot pass through fallback | `tests/brainstorm-server/server.test.js`, `tests/brainstorm-server/auth.test.js` | respective `node` commands | test silently talks to fallback port | test fails clearly or uses reported port intentionally |
+| Shell cleanup traps run on failures | `tests/brainstorm-server/stop-server.test.sh` | `bash tests/brainstorm-server/stop-server.test.sh` | failure leaves child processes | trap reaps background children |
+| Windows/MSYS start behavior keeps lifecycle invariants | `tests/brainstorm-server/start-server.test.sh`, `tests/brainstorm-server/windows-lifecycle.test.sh` | `bash` test commands on macOS and `ballmer` | owner PID or argv handling regresses | owner PID is cleared, foreground detection holds, id argv is present |
+
+Each RED/GREEN cycle should leave a short evidence note for the PR body: focused
+command, failing assertion before the fix, passing assertion after the fix, and
+whether the evidence was gathered on macOS or Windows.
+
+## Verification
+
+Before calling the fixup complete, run:
+
+- `git fetch origin dev && git rebase origin/dev`
+- `git diff --quiet origin/dev...HEAD -- evals`
+- `gh pr view 1720 --json mergeStateStatus,statusCheckRollup,headRefOid`
+- `cd tests/brainstorm-server && npm test`
+- relevant focused test commands used during TDD
+- `git diff --check`
+- Node syntax checks for touched JavaScript files
+- shell lint for touched shell files
+- Windows validation on `ballmer`: full runnable brainstorm-server suite plus
+  the standalone Windows lifecycle probe
+
+Manual/browser testing comes only after the automated pass is green.
+
+## Acceptance Criteria
+
+- PR #1720 rebases cleanly onto current `dev`.
+- `evals` is absent from the PR diff.
+- Root screen serving cannot read outside `content/` through symlink or
+  supported hardlink escapes.
+- `/files/*` containment protections remain unchanged.
+- No fallback server runs with a token that may be shared with the occupied
+  preferred-port server.
+- `stop-server.sh` does not signal unrelated processes when ownership proof is
+  missing or ambiguous.
+- `stop-server.sh` can still stop a legitimate server with a matching instance
+  id when `server-info` or `lsof` is unavailable.
+- Focused RED/GREEN evidence is recorded for each regression.
+- macOS and Windows validation evidence is recorded in the PR body.
+- The PR body accurately describes what is in the branch and what evidence was
+  gathered externally.

docs/testing.md

@@ -1,303 +1,35 @@
-# Testing Superpowers Skills
+# Testing Superpowers
 
-This document describes how to test Superpowers skills, particularly the integration tests for complex skills like `subagent-driven-development`.
+Superpowers has two distinct kinds of tests, each in its own directory:
 
-## Overview
+- **`tests/`** — does the plugin's non-LLM code work? Bash + node + python integration tests for brainstorm-server JS, OpenCode plugin loading, codex-plugin sync, and analysis utilities.
+- **`evals/`** — do agents behave correctly on real LLM sessions? Python harness driving real tmux sessions of Claude Code / Codex / Gemini CLI, with an LLM actor and verifier judging skill compliance.
 
-Testing skills that involve subagents, workflows, and complex interactions requires running actual Claude Code sessions in headless mode and verifying their behavior through session transcripts.
+## Plugin tests
 
-## Test Structure
+Live in `tests/`. Currently:
 
-```
-tests/
-├── claude-code/
-│   ├── test-helpers.sh                    # Shared test utilities
-│   ├── test-subagent-driven-development-integration.sh
-│   ├── analyze-token-usage.py             # Token analysis tool
-│   └── run-skill-tests.sh                 # Test runner (if exists)
-```
+- `tests/brainstorm-server/` — node test suite for the brainstorm server JS code.
+- `tests/opencode/` — bash tests for OpenCode plugin loading, bootstrap caching, and tool registration.
+- `tests/codex-plugin-sync/` — bash sync verification.
+- `tests/kimi/` — bash/Python checks for Kimi plugin manifest wiring.
+- `tests/claude-code/test-helpers.sh`, `analyze-token-usage.py` — utilities used by remaining bash tests.
+- `tests/claude-code/test-subagent-driven-development.sh` — agent-can-describe-SDD test (no drill counterpart; tests description-recall, not behavior).
+- `tests/claude-code/test-subagent-driven-development-integration.sh` — extended SDD integration with token analysis (drill covers the YAGNI subset; bash adds commit-count, Claude Code task-tracking, and token telemetry assertions).
+- `tests/claude-code/test-worktree-native-preference.sh` — RED-GREEN-REFACTOR validation for worktree skill (drill covers the PRESSURE phase; bash also covers RED/GREEN baselines).
+- `tests/explicit-skill-requests/` — Haiku-specific, multi-turn, and skill-name-prompted tests not covered by drill.
 
-## Running Tests
+Run plugin tests via the relevant directory's `run-*.sh` or `npm test`.
 
-### Integration Tests
+## Skill behavior evals
 
-Integration tests execute real Claude Code sessions with actual skills:
+Live in `evals/`. Drill is the harness; scenarios live at `evals/scenarios/*.yaml`. See `evals/README.md` for setup. Quick start:
 
 ```bash
-# Run the subagent-driven-development integration test
-cd tests/claude-code
-./test-subagent-driven-development-integration.sh
+cd evals
+uv sync --extra dev
+export ANTHROPIC_API_KEY=sk-...
+uv run drill run triggering-test-driven-development -b claude
 ```
 
-**Note:** Integration tests can take 10-30 minutes as they execute real implementation plans with multiple subagents.
-
-### Requirements
-
-- Must run from the **superpowers plugin directory** (not from temp directories)
-- Claude Code must be installed and available as `claude` command
-- Local dev marketplace must be enabled: `"superpowers@superpowers-dev": true` in `~/.claude/settings.json`
-
-## Integration Test: subagent-driven-development
-
-### What It Tests
-
-The integration test verifies the `subagent-driven-development` skill correctly:
-
-1. **Plan Loading**: Reads the plan once at the beginning
-2. **Full Task Text**: Provides complete task descriptions to subagents (doesn't make them read files)
-3. **Self-Review**: Ensures subagents perform self-review before reporting
-4. **Review Order**: Runs spec compliance review before code quality review
-5. **Review Loops**: Uses review loops when issues are found
-6. **Independent Verification**: Spec reviewer reads code independently, doesn't trust implementer reports
-
-### How It Works
-
-1. **Setup**: Creates a temporary Node.js project with a minimal implementation plan
-2. **Execution**: Runs Claude Code in headless mode with the skill
-3. **Verification**: Parses the session transcript (`.jsonl` file) to verify:
-   - Skill tool was invoked
-   - Subagents were dispatched (Task tool)
-   - TodoWrite was used for tracking
-   - Implementation files were created
-   - Tests pass
-   - Git commits show proper workflow
-4. **Token Analysis**: Shows token usage breakdown by subagent
-
-### Test Output
-
-```
-========================================
- Integration Test: subagent-driven-development
-========================================
-
-Test project: /tmp/tmp.xyz123
-
-=== Verification Tests ===
-
-Test 1: Skill tool invoked...
-  [PASS] subagent-driven-development skill was invoked
-
-Test 2: Subagents dispatched...
-  [PASS] 7 subagents dispatched
-
-Test 3: Task tracking...
-  [PASS] TodoWrite used 5 time(s)
-
-Test 6: Implementation verification...
-  [PASS] src/math.js created
-  [PASS] add function exists
-  [PASS] multiply function exists
-  [PASS] test/math.test.js created
-  [PASS] Tests pass
-
-Test 7: Git commit history...
-  [PASS] Multiple commits created (3 total)
-
-Test 8: No extra features added...
-  [PASS] No extra features added
-
-=========================================
- Token Usage Analysis
-=========================================
-
-Usage Breakdown:
-----------------------------------------------------------------------------------------------------
-Agent           Description                          Msgs      Input     Output      Cache     Cost
-----------------------------------------------------------------------------------------------------
-main            Main session (coordinator)             34         27      3,996  1,213,703 $   4.09
-3380c209        implementing Task 1: Create Add Function     1          2        787     24,989 $   0.09
-34b00fde        implementing Task 2: Create Multiply Function     1          4        644     25,114 $   0.09
-3801a732        reviewing whether an implementation matches...   1          5        703     25,742 $   0.09
-4c142934        doing a final code review...                    1          6        854     25,319 $   0.09
-5f017a42        a code reviewer. Review Task 2...               1          6        504     22,949 $   0.08
-a6b7fbe4        a code reviewer. Review Task 1...               1          6        515     22,534 $   0.08
-f15837c0        reviewing whether an implementation matches...   1          6        416     22,485 $   0.07
-----------------------------------------------------------------------------------------------------
-
-TOTALS:
-  Total messages:         41
-  Input tokens:           62
-  Output tokens:          8,419
-  Cache creation tokens:  132,742
-  Cache read tokens:      1,382,835
-
-  Total input (incl cache): 1,515,639
-  Total tokens:             1,524,058
-
-  Estimated cost: $4.67
-  (at $3/$15 per M tokens for input/output)
-
-========================================
- Test Summary
-========================================
-
-STATUS: PASSED
-```
-
-## Token Analysis Tool
-
-### Usage
-
-Analyze token usage from any Claude Code session:
-
-```bash
-python3 tests/claude-code/analyze-token-usage.py ~/.claude/projects/<project-dir>/<session-id>.jsonl
-```
-
-### Finding Session Files
-
-Session transcripts are stored in `~/.claude/projects/` with the working directory path encoded:
-
-```bash
-# Example for /Users/jesse/Documents/GitHub/superpowers/superpowers
-SESSION_DIR="$HOME/.claude/projects/-Users-jesse-Documents-GitHub-superpowers-superpowers"
-
-# Find recent sessions
-ls -lt "$SESSION_DIR"/*.jsonl | head -5
-```
-
-### What It Shows
-
-- **Main session usage**: Token usage by the coordinator (you or main Claude instance)
-- **Per-subagent breakdown**: Each Task invocation with:
-  - Agent ID
-  - Description (extracted from prompt)
-  - Message count
-  - Input/output tokens
-  - Cache usage
-  - Estimated cost
-- **Totals**: Overall token usage and cost estimate
-
-### Understanding the Output
-
-- **High cache reads**: Good - means prompt caching is working
-- **High input tokens on main**: Expected - coordinator has full context
-- **Similar costs per subagent**: Expected - each gets similar task complexity
-- **Cost per task**: Typical range is $0.05-$0.15 per subagent depending on task
-
-## Troubleshooting
-
-### Skills Not Loading
-
-**Problem**: Skill not found when running headless tests
-
-**Solutions**:
-1. Ensure you're running FROM the superpowers directory: `cd /path/to/superpowers && tests/...`
-2. Check `~/.claude/settings.json` has `"superpowers@superpowers-dev": true` in `enabledPlugins`
-3. Verify skill exists in `skills/` directory
-
-### Permission Errors
-
-**Problem**: Claude blocked from writing files or accessing directories
-
-**Solutions**:
-1. Use `--permission-mode bypassPermissions` flag
-2. Use `--add-dir /path/to/temp/dir` to grant access to test directories
-3. Check file permissions on test directories
-
-### Test Timeouts
-
-**Problem**: Test takes too long and times out
-
-**Solutions**:
-1. Increase timeout: `timeout 1800 claude ...` (30 minutes)
-2. Check for infinite loops in skill logic
-3. Review subagent task complexity
-
-### Session File Not Found
-
-**Problem**: Can't find session transcript after test run
-
-**Solutions**:
-1. Check the correct project directory in `~/.claude/projects/`
-2. Use `find ~/.claude/projects -name "*.jsonl" -mmin -60` to find recent sessions
-3. Verify test actually ran (check for errors in test output)
-
-## Writing New Integration Tests
-
-### Template
-
-```bash
-#!/usr/bin/env bash
-set -euo pipefail
-
-SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
-source "$SCRIPT_DIR/test-helpers.sh"
-
-# Create test project
-TEST_PROJECT=$(create_test_project)
-trap "cleanup_test_project $TEST_PROJECT" EXIT
-
-# Set up test files...
-cd "$TEST_PROJECT"
-
-# Run Claude with skill
-PROMPT="Your test prompt here"
-cd "$SCRIPT_DIR/../.." && timeout 1800 claude -p "$PROMPT" \
-  --allowed-tools=all \
-  --add-dir "$TEST_PROJECT" \
-  --permission-mode bypassPermissions \
-  2>&1 | tee output.txt
-
-# Find and analyze session
-WORKING_DIR_ESCAPED=$(echo "$SCRIPT_DIR/../.." | sed 's/\\//-/g' | sed 's/^-//')
-SESSION_DIR="$HOME/.claude/projects/$WORKING_DIR_ESCAPED"
-SESSION_FILE=$(find "$SESSION_DIR" -name "*.jsonl" -type f -mmin -60 | sort -r | head -1)
-
-# Verify behavior by parsing session transcript
-if grep -q '"name":"Skill".*"skill":"your-skill-name"' "$SESSION_FILE"; then
-    echo "[PASS] Skill was invoked"
-fi
-
-# Show token analysis
-python3 "$SCRIPT_DIR/analyze-token-usage.py" "$SESSION_FILE"
-```
-
-### Best Practices
-
-1. **Always cleanup**: Use trap to cleanup temp directories
-2. **Parse transcripts**: Don't grep user-facing output - parse the `.jsonl` session file
-3. **Grant permissions**: Use `--permission-mode bypassPermissions` and `--add-dir`
-4. **Run from plugin dir**: Skills only load when running from the superpowers directory
-5. **Show token usage**: Always include token analysis for cost visibility
-6. **Test real behavior**: Verify actual files created, tests passing, commits made
-
-## Session Transcript Format
-
-Session transcripts are JSONL (JSON Lines) files where each line is a JSON object representing a message or tool result.
-
-### Key Fields
-
-```json
-{
-  "type": "assistant",
-  "message": {
-    "content": [...],
-    "usage": {
-      "input_tokens": 27,
-      "output_tokens": 3996,
-      "cache_read_input_tokens": 1213703
-    }
-  }
-}
-```
-
-### Tool Results
-
-```json
-{
-  "type": "user",
-  "toolUseResult": {
-    "agentId": "3380c209",
-    "usage": {
-      "input_tokens": 2,
-      "output_tokens": 787,
-      "cache_read_input_tokens": 24989
-    },
-    "prompt": "You are implementing Task 1...",
-    "content": [{"type": "text", "text": "..."}]
-  }
-}
-```
-
-The `agentId` field links to subagent sessions, and the `usage` field contains token usage for that specific subagent invocation.
+Drill scenarios are slow (3-30+ minutes each) and run real LLM sessions. They are not part of CI today; the natural follow-up is a tiered model (fast subset on PR, full sweep nightly + on-demand).

docs/windows/polyglot-hooks.md

@@ -1,6 +1,8 @@
 # Cross-Platform Polyglot Hooks for Claude Code
 
-Claude Code plugins need hooks that work on Windows, macOS, and Linux. This document explains the polyglot wrapper technique that makes this possible.
+Claude Code plugins need hooks that work on Windows, macOS, and Linux. This document describes the single generic dispatcher pattern used in `hooks/run-hook.cmd`.
+
+> **Authoritative source:** `hooks/run-hook.cmd` is the canonical implementation. When this document and the code diverge, trust the code.
 
 ## The Problem
 
@@ -10,52 +12,22 @@ Claude Code runs hook commands through the system's default shell:
 
 This creates several challenges:
 
-1. **Script execution**: Windows CMD can't execute `.sh` files directly - it tries to open them in a text editor
+1. **Script execution**: Windows CMD can't execute `.sh` files directly
 2. **Path format**: Windows uses backslashes (`C:\path`), Unix uses forward slashes (`/path`)
 3. **Environment variables**: `$VAR` syntax doesn't work in CMD
-4. **No `bash` in PATH**: Even with Git Bash installed, `bash` isn't in the PATH when CMD runs
+4. **`.sh` auto-prepend**: Claude Code on Windows automatically prepends `bash` to any command that contains `.sh` in its path — this interferes with the dispatcher if scripts have extensions
 
-## The Solution: Polyglot `.cmd` Wrapper
+## The Solution: Extensionless Scripts + Single Generic Dispatcher
 
-A polyglot script is valid syntax in multiple languages simultaneously. Our wrapper is valid in both CMD and bash:
+The repo uses one generic `run-hook.cmd` dispatcher for all hooks. Hook scripts are **extensionless** (`session-start`, not `session-start.sh`). This is deliberate: it prevents Claude Code's Windows auto-detection from prepending `bash` to the dispatcher command and breaking it.
 
-```cmd
-: << 'CMDBLOCK'
-@echo off
-"C:\Program Files\Git\bin\bash.exe" -l -c "\"$(cygpath -u \"$CLAUDE_PLUGIN_ROOT\")/hooks/session-start.sh\""
-exit /b
-CMDBLOCK
-
-# Unix shell runs from here
-"${CLAUDE_PLUGIN_ROOT}/hooks/session-start.sh"
-```
-
-### How It Works
-
-#### On Windows (CMD.exe)
-
-1. `: << 'CMDBLOCK'` - CMD sees `:` as a label (like `:label`) and ignores `<< 'CMDBLOCK'`
-2. `@echo off` - Suppresses command echoing
-3. The bash.exe command runs with:
-   - `-l` (login shell) to get proper PATH with Unix utilities
-   - `cygpath -u` converts Windows path to Unix format (`C:\foo` → `/c/foo`)
-4. `exit /b` - Exits the batch script, stopping CMD here
-5. Everything after `CMDBLOCK` is never reached by CMD
-
-#### On Unix (bash/sh)
-
-1. `: << 'CMDBLOCK'` - `:` is a no-op, `<< 'CMDBLOCK'` starts a heredoc
-2. Everything until `CMDBLOCK` is consumed by the heredoc (ignored)
-3. `# Unix shell runs from here` - Comment
-4. The script runs directly with the Unix path
-
-## File Structure
+### File Structure
 
 ```
 hooks/
-├── hooks.json           # Points to the .cmd wrapper
-├── session-start.cmd    # Polyglot wrapper (cross-platform entry point)
-└── session-start.sh     # Actual hook logic (bash script)
+├── hooks.json          # Points to run-hook.cmd with extensionless script name
+├── run-hook.cmd        # Cross-platform dispatcher (the polyglot wrapper)
+└── session-start       # Actual hook logic — extensionless bash script
 ```
 
 ### hooks.json
@@ -65,11 +37,12 @@ hooks/
   "hooks": {
     "SessionStart": [
       {
-        "matcher": "startup|resume|clear|compact",
+        "matcher": "startup|clear|compact",
         "hooks": [
           {
             "type": "command",
-            "command": "\"${CLAUDE_PLUGIN_ROOT}/hooks/session-start.cmd\""
+            "command": "\"${CLAUDE_PLUGIN_ROOT}/hooks/run-hook.cmd\" session-start",
+            "async": false
           }
         ]
       }
@@ -78,41 +51,63 @@ hooks/
 }
 ```
 
-Note: The path must be quoted because `${CLAUDE_PLUGIN_ROOT}` may contain spaces on Windows (e.g., `C:\Program Files\...`).
+The path is quoted because `${CLAUDE_PLUGIN_ROOT}` may contain spaces.
 
-## Requirements
+## How `run-hook.cmd` Works at a High Level
 
-### Windows
-- **Git for Windows** must be installed (provides `bash.exe` and `cygpath`)
-- Default installation path: `C:\Program Files\Git\bin\bash.exe`
-- If Git is installed elsewhere, the wrapper needs modification
+`run-hook.cmd` is a polyglot script: Windows treats the first block as batch
+commands, while Unix shells treat that block as a no-op heredoc and continue
+after it.
 
-### Unix (macOS/Linux)
-- Standard bash or sh shell
-- The `.cmd` file must have execute permission (`chmod +x`)
+Do not copy an implementation from this document. Read `hooks/run-hook.cmd`
+directly when changing the dispatcher, and run `tests/hooks/test-session-start.sh`
+afterward.
+
+### How it works on Windows (CMD.exe)
+
+1. The batch section validates the script name and resolves the hook directory
+   from the dispatcher's own location.
+2. It tries bash in three places:
+   - `C:\Program Files\Git\bin\bash.exe`
+   - `C:\Program Files (x86)\Git\bin\bash.exe`
+   - `bash` on `PATH` (MSYS2, Cygwin, or a non-default Git install)
+3. If bash is found, it runs the named extensionless hook script from the hooks
+   directory.
+4. If no bash is found, the dispatcher exits `0` silently — the plugin
+   continues working, it just skips the hook.
+5. `exit /b` stops CMD before it reaches the Unix section.
+
+### How it works on Unix (bash/sh)
+
+1. `: << 'CMDBLOCK'` opens a heredoc on a no-op command.
+2. The entire CMD batch block is consumed by the heredoc and ignored.
+3. After `CMDBLOCK`, bash resolves the script directory and `exec`s the named
+   extensionless script directly.
+
+### Key design decisions
+
+| Decision | Why |
+|----------|-----|
+| Extensionless scripts | Prevents Claude Code's Windows `.sh`-auto-prepend from interfering with the dispatcher command |
+| No `-l` (login shell) | Not needed; hook scripts should be self-contained and not depend on login-shell PATH setup |
+| No `cygpath` | Bash receives the Windows path directly and handles it correctly; `cygpath` was needed by the old `-c "..."` invocation pattern, not by direct exec |
+| Silent exit on no-bash | Avoids breaking the plugin for users who don't have Git for Windows; hook context injection is skipped gracefully |
 
 ## Writing Cross-Platform Hook Scripts
 
-Your actual hook logic goes in the `.sh` file. To ensure it works on Windows (via Git Bash):
+Your hook logic goes in the extensionless script file. A few portable patterns:
 
-### Do:
+### Do
 - Use pure bash builtins when possible
 - Use `$(command)` instead of backticks
 - Quote all variable expansions: `"$VAR"`
-- Use `printf` or here-docs for output
 
-### Avoid:
-- External commands that may not be in PATH (sed, awk, grep)
-- If you must use them, they're available in Git Bash but ensure PATH is set up (use `bash -l`)
+### Avoid
+- Relying on PATH-dependent tools without fallbacks (the hook runs without `-l`, so login-shell PATH is not set)
+- Giving scripts a `.sh` extension — this triggers Claude Code's Windows auto-prepend
 
-### Example: JSON Escaping Without sed/awk
+### Example: JSON escaping without external tools
 
-Instead of:
-```bash
-escaped=$(echo "$content" | sed 's/\\/\\\\/g' | sed 's/"/\\"/g' | awk '{printf "%s\\n", $0}')
-```
-
-Use pure bash:
 ```bash
 escape_for_json() {
     local input="$1"
@@ -133,80 +128,21 @@ escape_for_json() {
 }
 ```
 
-## Reusable Wrapper Pattern
-
-For plugins with multiple hooks, you can create a generic wrapper that takes the script name as an argument:
-
-### run-hook.cmd
-```cmd
-: << 'CMDBLOCK'
-@echo off
-set "SCRIPT_DIR=%~dp0"
-set "SCRIPT_NAME=%~1"
-"C:\Program Files\Git\bin\bash.exe" -l -c "cd \"$(cygpath -u \"%SCRIPT_DIR%\")\" && \"./%SCRIPT_NAME%\""
-exit /b
-CMDBLOCK
-
-# Unix shell runs from here
-SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]:-$0}")" && pwd)"
-SCRIPT_NAME="$1"
-shift
-"${SCRIPT_DIR}/${SCRIPT_NAME}" "$@"
-```
-
-### hooks.json using the reusable wrapper
-```json
-{
-  "hooks": {
-    "SessionStart": [
-      {
-        "matcher": "startup",
-        "hooks": [
-          {
-            "type": "command",
-            "command": "\"${CLAUDE_PLUGIN_ROOT}/hooks/run-hook.cmd\" session-start.sh"
-          }
-        ]
-      }
-    ],
-    "PreToolUse": [
-      {
-        "matcher": "Bash",
-        "hooks": [
-          {
-            "type": "command",
-            "command": "\"${CLAUDE_PLUGIN_ROOT}/hooks/run-hook.cmd\" validate-bash.sh"
-          }
-        ]
-      }
-    ]
-  }
-}
-```
-
 ## Troubleshooting
 
 ### "bash is not recognized"
-CMD can't find bash. The wrapper uses the full path `C:\Program Files\Git\bin\bash.exe`. If Git is installed elsewhere, update the path.
 
-### "cygpath: command not found" or "dirname: command not found"
-Bash isn't running as a login shell. Ensure `-l` flag is used.
+CMD couldn't find bash in any of the three locations the dispatcher tries. The dispatcher exits silently (0) rather than erroring, so the hook is skipped. Install Git for Windows at the standard path or ensure `bash` is on `PATH`.
 
-### Path has weird `\/` in it
-`${CLAUDE_PLUGIN_ROOT}` expanded to a Windows path ending with backslash, then `/hooks/...` was appended. Use `cygpath` to convert the entire path.
+### Hook runs on Unix but does nothing on Windows
 
-### Script opens in text editor instead of running
-The hooks.json is pointing directly to the `.sh` file. Point to the `.cmd` wrapper instead.
+Check that the script filename is **extensionless** in `hooks.json`. A command like `run-hook.cmd session-start.sh` can trigger Claude Code's `.sh` auto-detection and bypass the intended CMD dispatcher path, or just try to run a non-existent `session-start.sh` script.
 
-### Works in terminal but not as hook
-Claude Code may run hooks differently. Test by simulating the hook environment:
-```powershell
-$env:CLAUDE_PLUGIN_ROOT = "C:\path\to\plugin"
-cmd /c "C:\path\to\plugin\hooks\session-start.cmd"
-```
+### Hook doesn't fire at all
+
+Verify the `matcher` in `hooks.json` matches the event type your harness emits. Claude Code uses `startup|clear|compact`; Codex uses `startup|resume|clear`. Check `hooks-codex.json` for the Codex variant.
 
 ## Related Issues
 
-- [anthropics/claude-code#9758](https://github.com/anthropics/claude-code/issues/9758) - .sh scripts open in editor on Windows
-- [anthropics/claude-code#3417](https://github.com/anthropics/claude-code/issues/3417) - Hooks don't work on Windows
-- [anthropics/claude-code#6023](https://github.com/anthropics/claude-code/issues/6023) - CLAUDE_PROJECT_DIR not found
+- [anthropics/claude-code#9758](https://github.com/anthropics/claude-code/issues/9758) — `.sh` scripts open in editor on Windows
+- [anthropics/claude-code#3417](https://github.com/anthropics/claude-code/issues/3417) — Hooks don't work on Windows

gemini-extension.json

@@ -0,0 +1,6 @@
+{
+  "name": "superpowers",
+  "description": "Core skills library: TDD, debugging, collaboration patterns, and proven techniques",
+  "version": "6.0.3",
+  "contextFileName": "GEMINI.md"
+}

hooks/hooks-codex.json

@@ -0,0 +1,16 @@
+{
+  "hooks": {
+    "SessionStart": [
+      {
+        "matcher": "startup|resume|clear",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "\"${PLUGIN_ROOT}/hooks/run-hook.cmd\" session-start-codex",
+            "async": false
+          }
+        ]
+      }
+    ]
+  }
+}

hooks/hooks-cursor.json

@@ -0,0 +1,10 @@
+{
+  "version": 1,
+  "hooks": {
+    "sessionStart": [
+      {
+        "command": "./hooks/run-hook.cmd session-start"
+      }
+    ]
+  }
+}

hooks/hooks.json

@@ -2,11 +2,12 @@
   "hooks": {
     "SessionStart": [
       {
-        "matcher": "startup|resume|clear|compact",
+        "matcher": "startup|clear|compact",
         "hooks": [
           {
             "type": "command",
-            "command": "\"${CLAUDE_PLUGIN_ROOT}/hooks/run-hook.cmd\" session-start.sh"
+            "command": "\"${CLAUDE_PLUGIN_ROOT}/hooks/run-hook.cmd\" session-start",
+            "async": false
           }
         ]
       }

hooks/run-hook.cmd

@@ -1,19 +1,46 @@
 : << 'CMDBLOCK'
 @echo off
-REM Polyglot wrapper: runs .sh scripts cross-platform
+REM Cross-platform polyglot wrapper for hook scripts.
+REM On Windows: cmd.exe runs the batch portion, which finds and calls bash.
+REM On Unix: the shell interprets this as a script (: is a no-op in bash).
+REM
+REM Hook scripts use extensionless filenames (e.g. "session-start" not
+REM "session-start.sh") so Claude Code's Windows auto-detection -- which
+REM prepends "bash" to any command containing .sh -- doesn't interfere.
+REM
 REM Usage: run-hook.cmd <script-name> [args...]
-REM The script should be in the same directory as this wrapper
 
 if "%~1"=="" (
     echo run-hook.cmd: missing script name >&2
     exit /b 1
 )
-"C:\Program Files\Git\bin\bash.exe" -l "%~dp0%~1" %2 %3 %4 %5 %6 %7 %8 %9
-exit /b
+
+set "HOOK_DIR=%~dp0"
+
+REM Try Git for Windows bash in standard locations
+if exist "C:\Program Files\Git\bin\bash.exe" (
+    "C:\Program Files\Git\bin\bash.exe" "%HOOK_DIR%%~1" %2 %3 %4 %5 %6 %7 %8 %9
+    exit /b %ERRORLEVEL%
+)
+if exist "C:\Program Files (x86)\Git\bin\bash.exe" (
+    "C:\Program Files (x86)\Git\bin\bash.exe" "%HOOK_DIR%%~1" %2 %3 %4 %5 %6 %7 %8 %9
+    exit /b %ERRORLEVEL%
+)
+
+REM Try bash on PATH (e.g. user-installed Git Bash, MSYS2, Cygwin)
+where bash >nul 2>nul
+if %ERRORLEVEL% equ 0 (
+    bash "%HOOK_DIR%%~1" %2 %3 %4 %5 %6 %7 %8 %9
+    exit /b %ERRORLEVEL%
+)
+
+REM No bash found - exit silently rather than error
+REM (plugin still works, just without SessionStart context injection)
+exit /b 0
 CMDBLOCK
 
-# Unix shell runs from here
+# Unix: run the named script directly
 SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
 SCRIPT_NAME="$1"
 shift
-"${SCRIPT_DIR}/${SCRIPT_NAME}" "$@"
+exec bash "${SCRIPT_DIR}/${SCRIPT_NAME}" "$@"

hooks/session-start

@@ -0,0 +1,49 @@
+#!/usr/bin/env bash
+# SessionStart hook for superpowers plugin
+
+set -euo pipefail
+
+# Determine plugin root directory
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+PLUGIN_ROOT="$(cd "${SCRIPT_DIR}/.." && pwd)"
+
+# Read using-superpowers content
+using_superpowers_content=$(cat "${PLUGIN_ROOT}/skills/using-superpowers/SKILL.md" 2>&1 || echo "Error reading using-superpowers skill")
+
+# Escape string for JSON embedding using bash parameter substitution.
+# Each ${s//old/new} is a single C-level pass - orders of magnitude
+# faster than the character-by-character loop this replaces.
+escape_for_json() {
+    local s="$1"
+    s="${s//\\/\\\\}"
+    s="${s//\"/\\\"}"
+    s="${s//$'\n'/\\n}"
+    s="${s//$'\r'/\\r}"
+    s="${s//$'\t'/\\t}"
+    printf '%s' "$s"
+}
+
+using_superpowers_escaped=$(escape_for_json "$using_superpowers_content")
+session_context="<EXTREMELY_IMPORTANT>\nYou have superpowers.\n\n**Below is the full content of your 'superpowers:using-superpowers' skill - your introduction to using skills. For all other skills, use the 'Skill' tool:**\n\n${using_superpowers_escaped}\n</EXTREMELY_IMPORTANT>"
+
+# Output context injection as JSON.
+# Cursor hooks expect additional_context (snake_case).
+# Claude Code hooks expect hookSpecificOutput.additionalContext (nested).
+# Copilot CLI (v1.0.11+) and others expect additionalContext (top-level, SDK standard).
+# Claude Code reads BOTH additional_context and hookSpecificOutput without
+# deduplication, so we must emit only the field the current platform consumes.
+#
+# Uses printf instead of heredoc to work around bash 5.3+ heredoc hang.
+# See: https://github.com/obra/superpowers/issues/571
+if [ -n "${CURSOR_PLUGIN_ROOT:-}" ]; then
+  # Cursor sets CURSOR_PLUGIN_ROOT (may also set CLAUDE_PLUGIN_ROOT)
+  printf '{\n  "additional_context": "%s"\n}\n' "$session_context" | cat
+elif [ -n "${CLAUDE_PLUGIN_ROOT:-}" ] && [ -z "${COPILOT_CLI:-}" ]; then
+  # Claude Code sets CLAUDE_PLUGIN_ROOT without COPILOT_CLI
+  printf '{\n  "hookSpecificOutput": {\n    "hookEventName": "SessionStart",\n    "additionalContext": "%s"\n  }\n}\n' "$session_context" | cat
+else
+  # Copilot CLI (sets COPILOT_CLI=1) or unknown platform — SDK standard format
+  printf '{\n  "additionalContext": "%s"\n}\n' "$session_context" | cat
+fi
+
+exit 0

hooks/session-start-codex

@@ -0,0 +1,26 @@
+#!/usr/bin/env bash
+# Codex SessionStart hook for superpowers plugin
+
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+PLUGIN_ROOT="$(cd "${SCRIPT_DIR}/.." && pwd)"
+
+using_superpowers_content=$(cat "${PLUGIN_ROOT}/skills/using-superpowers/SKILL.md" 2>&1 || echo "Error reading using-superpowers skill")
+
+escape_for_json() {
+    local s="$1"
+    s="${s//\\/\\\\}"
+    s="${s//\"/\\\"}"
+    s="${s//$'\n'/\\n}"
+    s="${s//$'\r'/\\r}"
+    s="${s//$'\t'/\\t}"
+    printf '%s' "$s"
+}
+
+using_superpowers_escaped=$(escape_for_json "$using_superpowers_content")
+session_context="<EXTREMELY_IMPORTANT>\nYou have superpowers.\n\n**Below is the full content of your 'superpowers:using-superpowers' skill - your introduction to using skills. For all other skills, follow the Codex skill-loading instructions in that skill:**\n\n${using_superpowers_escaped}\n</EXTREMELY_IMPORTANT>"
+
+printf '{\n  "hookSpecificOutput": {\n    "hookEventName": "SessionStart",\n    "additionalContext": "%s"\n  }\n}\n' "$session_context" | cat
+
+exit 0

hooks/session-start.sh

@@ -1,52 +0,0 @@
-#!/usr/bin/env bash
-# SessionStart hook for superpowers plugin
-
-set -euo pipefail
-
-# Determine plugin root directory
-SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]:-$0}")" && pwd)"
-PLUGIN_ROOT="$(cd "${SCRIPT_DIR}/.." && pwd)"
-
-# Check if legacy skills directory exists and build warning
-warning_message=""
-legacy_skills_dir="${HOME}/.config/superpowers/skills"
-if [ -d "$legacy_skills_dir" ]; then
-    warning_message="\n\n<important-reminder>IN YOUR FIRST REPLY AFTER SEEING THIS MESSAGE YOU MUST TELL THE USER:⚠️ **WARNING:** Superpowers now uses Claude Code's skills system. Custom skills in ~/.config/superpowers/skills will not be read. Move custom skills to ~/.claude/skills instead. To make this message go away, remove ~/.config/superpowers/skills</important-reminder>"
-fi
-
-# Read using-superpowers content
-using_superpowers_content=$(cat "${PLUGIN_ROOT}/skills/using-superpowers/SKILL.md" 2>&1 || echo "Error reading using-superpowers skill")
-
-# Escape outputs for JSON using pure bash
-escape_for_json() {
-    local input="$1"
-    local output=""
-    local i char
-    for (( i=0; i<${#input}; i++ )); do
-        char="${input:$i:1}"
-        case "$char" in
-            $'\\') output+='\\' ;;
-            '"') output+='\"' ;;
-            $'\n') output+='\n' ;;
-            $'\r') output+='\r' ;;
-            $'\t') output+='\t' ;;
-            *) output+="$char" ;;
-        esac
-    done
-    printf '%s' "$output"
-}
-
-using_superpowers_escaped=$(escape_for_json "$using_superpowers_content")
-warning_escaped=$(escape_for_json "$warning_message")
-
-# Output context injection as JSON
-cat <<EOF
-{
-  "hookSpecificOutput": {
-    "hookEventName": "SessionStart",
-    "additionalContext": "<EXTREMELY_IMPORTANT>\nYou have superpowers.\n\n**Below is the full content of your 'superpowers:using-superpowers' skill - your introduction to using skills. For all other skills, use the 'Skill' tool:**\n\n${using_superpowers_escaped}\n\n${warning_escaped}\n</EXTREMELY_IMPORTANT>"
-  }
-}
-EOF
-
-exit 0

lib/skills-core.js

@@ -1,208 +0,0 @@
-import fs from 'fs';
-import path from 'path';
-import { execSync } from 'child_process';
-
-/**
- * Extract YAML frontmatter from a skill file.
- * Current format:
- * ---
- * name: skill-name
- * description: Use when [condition] - [what it does]
- * ---
- *
- * @param {string} filePath - Path to SKILL.md file
- * @returns {{name: string, description: string}}
- */
-function extractFrontmatter(filePath) {
-    try {
-        const content = fs.readFileSync(filePath, 'utf8');
-        const lines = content.split('\n');
-
-        let inFrontmatter = false;
-        let name = '';
-        let description = '';
-
-        for (const line of lines) {
-            if (line.trim() === '---') {
-                if (inFrontmatter) break;
-                inFrontmatter = true;
-                continue;
-            }
-
-            if (inFrontmatter) {
-                const match = line.match(/^(\w+):\s*(.*)$/);
-                if (match) {
-                    const [, key, value] = match;
-                    switch (key) {
-                        case 'name':
-                            name = value.trim();
-                            break;
-                        case 'description':
-                            description = value.trim();
-                            break;
-                    }
-                }
-            }
-        }
-
-        return { name, description };
-    } catch (error) {
-        return { name: '', description: '' };
-    }
-}
-
-/**
- * Find all SKILL.md files in a directory recursively.
- *
- * @param {string} dir - Directory to search
- * @param {string} sourceType - 'personal' or 'superpowers' for namespacing
- * @param {number} maxDepth - Maximum recursion depth (default: 3)
- * @returns {Array<{path: string, name: string, description: string, sourceType: string}>}
- */
-function findSkillsInDir(dir, sourceType, maxDepth = 3) {
-    const skills = [];
-
-    if (!fs.existsSync(dir)) return skills;
-
-    function recurse(currentDir, depth) {
-        if (depth > maxDepth) return;
-
-        const entries = fs.readdirSync(currentDir, { withFileTypes: true });
-
-        for (const entry of entries) {
-            const fullPath = path.join(currentDir, entry.name);
-
-            if (entry.isDirectory()) {
-                // Check for SKILL.md in this directory
-                const skillFile = path.join(fullPath, 'SKILL.md');
-                if (fs.existsSync(skillFile)) {
-                    const { name, description } = extractFrontmatter(skillFile);
-                    skills.push({
-                        path: fullPath,
-                        skillFile: skillFile,
-                        name: name || entry.name,
-                        description: description || '',
-                        sourceType: sourceType
-                    });
-                }
-
-                // Recurse into subdirectories
-                recurse(fullPath, depth + 1);
-            }
-        }
-    }
-
-    recurse(dir, 0);
-    return skills;
-}
-
-/**
- * Resolve a skill name to its file path, handling shadowing
- * (personal skills override superpowers skills).
- *
- * @param {string} skillName - Name like "superpowers:brainstorming" or "my-skill"
- * @param {string} superpowersDir - Path to superpowers skills directory
- * @param {string} personalDir - Path to personal skills directory
- * @returns {{skillFile: string, sourceType: string, skillPath: string} | null}
- */
-function resolveSkillPath(skillName, superpowersDir, personalDir) {
-    // Strip superpowers: prefix if present
-    const forceSuperpowers = skillName.startsWith('superpowers:');
-    const actualSkillName = forceSuperpowers ? skillName.replace(/^superpowers:/, '') : skillName;
-
-    // Try personal skills first (unless explicitly superpowers:)
-    if (!forceSuperpowers && personalDir) {
-        const personalPath = path.join(personalDir, actualSkillName);
-        const personalSkillFile = path.join(personalPath, 'SKILL.md');
-        if (fs.existsSync(personalSkillFile)) {
-            return {
-                skillFile: personalSkillFile,
-                sourceType: 'personal',
-                skillPath: actualSkillName
-            };
-        }
-    }
-
-    // Try superpowers skills
-    if (superpowersDir) {
-        const superpowersPath = path.join(superpowersDir, actualSkillName);
-        const superpowersSkillFile = path.join(superpowersPath, 'SKILL.md');
-        if (fs.existsSync(superpowersSkillFile)) {
-            return {
-                skillFile: superpowersSkillFile,
-                sourceType: 'superpowers',
-                skillPath: actualSkillName
-            };
-        }
-    }
-
-    return null;
-}
-
-/**
- * Check if a git repository has updates available.
- *
- * @param {string} repoDir - Path to git repository
- * @returns {boolean} - True if updates are available
- */
-function checkForUpdates(repoDir) {
-    try {
-        // Quick check with 3 second timeout to avoid delays if network is down
-        const output = execSync('git fetch origin && git status --porcelain=v1 --branch', {
-            cwd: repoDir,
-            timeout: 3000,
-            encoding: 'utf8',
-            stdio: 'pipe'
-        });
-
-        // Parse git status output to see if we're behind
-        const statusLines = output.split('\n');
-        for (const line of statusLines) {
-            if (line.startsWith('## ') && line.includes('[behind ')) {
-                return true; // We're behind remote
-            }
-        }
-        return false; // Up to date
-    } catch (error) {
-        // Network down, git error, timeout, etc. - don't block bootstrap
-        return false;
-    }
-}
-
-/**
- * Strip YAML frontmatter from skill content, returning just the content.
- *
- * @param {string} content - Full content including frontmatter
- * @returns {string} - Content without frontmatter
- */
-function stripFrontmatter(content) {
-    const lines = content.split('\n');
-    let inFrontmatter = false;
-    let frontmatterEnded = false;
-    const contentLines = [];
-
-    for (const line of lines) {
-        if (line.trim() === '---') {
-            if (inFrontmatter) {
-                frontmatterEnded = true;
-                continue;
-            }
-            inFrontmatter = true;
-            continue;
-        }
-
-        if (frontmatterEnded || !inFrontmatter) {
-            contentLines.push(line);
-        }
-    }
-
-    return contentLines.join('\n').trim();
-}
-
-export {
-    extractFrontmatter,
-    findSkillsInDir,
-    resolveSkillPath,
-    checkForUpdates,
-    stripFrontmatter
-};

package.json

@@ -0,0 +1,23 @@
+{
+  "name": "superpowers",
+  "version": "6.0.3",
+  "description": "Superpowers skills and runtime bootstrap for coding agents",
+  "type": "module",
+  "main": ".opencode/plugins/superpowers.js",
+  "keywords": [
+    "pi-package",
+    "skills",
+    "tdd",
+    "debugging",
+    "collaboration",
+    "workflow"
+  ],
+  "pi": {
+    "extensions": [
+      "./.pi/extensions/superpowers.ts"
+    ],
+    "skills": [
+      "./skills"
+    ]
+  }
+}

scripts/bump-version.sh

@@ -0,0 +1,220 @@
+#!/usr/bin/env bash
+#
+# bump-version.sh — bump version numbers across all declared files,
+# with drift detection and repo-wide audit for missed files.
+#
+# Usage:
+#   bump-version.sh <new-version>   Bump all declared files to new version
+#   bump-version.sh --check         Report current versions (detect drift)
+#   bump-version.sh --audit         Check + grep repo for old version strings
+#
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+REPO_ROOT="$(cd "$SCRIPT_DIR/.." && pwd)"
+CONFIG="$REPO_ROOT/.version-bump.json"
+
+if [[ ! -f "$CONFIG" ]]; then
+  echo "error: .version-bump.json not found at $CONFIG" >&2
+  exit 1
+fi
+
+# --- helpers ---
+
+# Read a dotted field path from a JSON file.
+# Handles both simple ("version") and nested ("plugins.0.version") paths.
+read_json_field() {
+  local file="$1" field="$2"
+  # Convert dot-path to jq path: "plugins.0.version" -> .plugins[0].version
+  local jq_path
+  jq_path=$(echo "$field" | sed -E 's/\.([0-9]+)/[\1]/g' | sed 's/^/./' | sed 's/\.\././g')
+  jq -r "$jq_path" "$file"
+}
+
+# Write a dotted field path in a JSON file, preserving formatting.
+write_json_field() {
+  local file="$1" field="$2" value="$3"
+  local jq_path
+  jq_path=$(echo "$field" | sed -E 's/\.([0-9]+)/[\1]/g' | sed 's/^/./' | sed 's/\.\././g')
+  local tmp="${file}.tmp"
+  jq "$jq_path = \"$value\"" "$file" > "$tmp" && mv "$tmp" "$file"
+}
+
+# Read the list of declared files from config.
+# Outputs lines of "path<TAB>field"
+declared_files() {
+  jq -r '.files[] | "\(.path)\t\(.field)"' "$CONFIG"
+}
+
+# Read the audit exclude patterns from config.
+audit_excludes() {
+  jq -r '.audit.exclude[]' "$CONFIG" 2>/dev/null
+}
+
+# --- commands ---
+
+cmd_check() {
+  local has_drift=0
+  local versions=()
+
+  echo "Version check:"
+  echo ""
+
+  while IFS=$'\t' read -r path field; do
+    local fullpath="$REPO_ROOT/$path"
+    if [[ ! -f "$fullpath" ]]; then
+      printf "  %-45s  MISSING\n" "$path ($field)"
+      has_drift=1
+      continue
+    fi
+    local ver
+    ver=$(read_json_field "$fullpath" "$field")
+    printf "  %-45s  %s\n" "$path ($field)" "$ver"
+    versions+=("$ver")
+  done < <(declared_files)
+
+  echo ""
+
+  # Check if all versions match
+  local unique
+  unique=$(printf '%s\n' "${versions[@]}" | sort -u | wc -l | tr -d ' ')
+  if [[ "$unique" -gt 1 ]]; then
+    echo "DRIFT DETECTED — versions are not in sync:"
+    printf '%s\n' "${versions[@]}" | sort | uniq -c | sort -rn | while read -r count ver; do
+      echo "  $ver ($count files)"
+    done
+    has_drift=1
+  else
+    echo "All declared files are in sync at ${versions[0]}"
+  fi
+
+  return $has_drift
+}
+
+cmd_audit() {
+  # First run check
+  cmd_check || true
+  echo ""
+
+  # Determine the current version (most common across declared files)
+  local current_version
+  current_version=$(
+    while IFS=$'\t' read -r path field; do
+      local fullpath="$REPO_ROOT/$path"
+      [[ -f "$fullpath" ]] && read_json_field "$fullpath" "$field"
+    done < <(declared_files) | sort | uniq -c | sort -rn | head -1 | awk '{print $2}'
+  )
+
+  if [[ -z "$current_version" ]]; then
+    echo "error: could not determine current version" >&2
+    return 1
+  fi
+
+  echo "Audit: scanning repo for version string '$current_version'..."
+  echo ""
+
+  # Build grep exclude args
+  local -a exclude_args=()
+  while IFS= read -r pattern; do
+    exclude_args+=("--exclude=$pattern" "--exclude-dir=$pattern")
+  done < <(audit_excludes)
+
+  # Also always exclude binary files and .git
+  exclude_args+=("--exclude-dir=.git" "--exclude-dir=node_modules" "--binary-files=without-match")
+
+  # Get list of declared paths for comparison
+  local -a declared_paths=()
+  while IFS=$'\t' read -r path _field; do
+    declared_paths+=("$path")
+  done < <(declared_files)
+
+  # Grep for the version string
+  local found_undeclared=0
+  while IFS= read -r match; do
+    local match_file
+    match_file=$(echo "$match" | cut -d: -f1)
+    # Make path relative to repo root
+    local rel_path="${match_file#$REPO_ROOT/}"
+
+    # Check if this file is in the declared list
+    local is_declared=0
+    for dp in "${declared_paths[@]}"; do
+      if [[ "$rel_path" == "$dp" ]]; then
+        is_declared=1
+        break
+      fi
+    done
+
+    if [[ "$is_declared" -eq 0 ]]; then
+      if [[ "$found_undeclared" -eq 0 ]]; then
+        echo "UNDECLARED files containing '$current_version':"
+        found_undeclared=1
+      fi
+      echo "  $match"
+    fi
+  done < <(grep -rn "${exclude_args[@]}" -F "$current_version" "$REPO_ROOT" 2>/dev/null || true)
+
+  if [[ "$found_undeclared" -eq 0 ]]; then
+    echo "No undeclared files contain the version string. All clear."
+  else
+    echo ""
+    echo "Review the above files — if they should be bumped, add them to .version-bump.json"
+    echo "If they should be skipped, add them to the audit.exclude list."
+  fi
+}
+
+cmd_bump() {
+  local new_version="$1"
+
+  # Validate semver-ish format
+  if ! echo "$new_version" | grep -qE '^[0-9]+\.[0-9]+\.[0-9]+'; then
+    echo "error: '$new_version' doesn't look like a version (expected X.Y.Z)" >&2
+    exit 1
+  fi
+
+  echo "Bumping all declared files to $new_version..."
+  echo ""
+
+  while IFS=$'\t' read -r path field; do
+    local fullpath="$REPO_ROOT/$path"
+    if [[ ! -f "$fullpath" ]]; then
+      echo "  SKIP (missing): $path"
+      continue
+    fi
+    local old_ver
+    old_ver=$(read_json_field "$fullpath" "$field")
+    write_json_field "$fullpath" "$field" "$new_version"
+    printf "  %-45s  %s -> %s\n" "$path ($field)" "$old_ver" "$new_version"
+  done < <(declared_files)
+
+  echo ""
+  echo "Done. Running audit to check for missed files..."
+  echo ""
+  cmd_audit
+}
+
+# --- main ---
+
+case "${1:-}" in
+  --check)
+    cmd_check
+    ;;
+  --audit)
+    cmd_audit
+    ;;
+  --help|-h|"")
+    echo "Usage: bump-version.sh <new-version> | --check | --audit"
+    echo ""
+    echo "  <new-version>  Bump all declared files to the given version"
+    echo "  --check        Show current versions, detect drift"
+    echo "  --audit        Check + scan repo for undeclared version references"
+    exit 0
+    ;;
+  --*)
+    echo "error: unknown flag '$1'" >&2
+    exit 1
+    ;;
+  *)
+    cmd_bump "$1"
+    ;;
+esac

scripts/lint-shell.sh

@@ -0,0 +1,211 @@
+#!/usr/bin/env bash
+#
+# Lint shell scripts in this repository.
+#
+# Usage:
+#   scripts/lint-shell.sh [--all] [--format] [--strict] [file ...]
+#
+# By default, runs ShellCheck and shell syntax checks on changed shell scripts.
+# Use --format to format with shfmt before linting. Use --all for the full tracked
+# baseline, or pass files explicitly to lint a smaller set.
+set -euo pipefail
+
+usage() {
+  sed -n '2,9p' "$0" | sed 's/^# \{0,1\}//'
+}
+
+die() {
+  echo "error: $*" >&2
+  exit 1
+}
+
+require_tool() {
+  command -v "$1" >/dev/null 2>&1 || die "required tool '$1' is not on PATH"
+}
+
+is_shell_file() {
+  local path="$1"
+  local first_line=""
+
+  [[ -f "$path" ]] || return 1
+
+  case "$path" in
+    *.sh)
+      return 0
+      ;;
+  esac
+
+  IFS= read -r first_line <"$path" || true
+  [[ "$first_line" =~ ^#!.*[/[:space:]](bash|dash|ksh|sh)([[:space:]]|$) ]]
+}
+
+ensure_git_work_tree() {
+  git rev-parse --is-inside-work-tree >/dev/null 2>&1 \
+    || die "run this from inside a git work tree, or pass files explicitly"
+}
+
+add_shell_file() {
+  local path
+  local existing
+
+  path="$1"
+  if ! is_shell_file "$path"; then
+    return 0
+  fi
+
+  if [[ "${#files[@]}" -gt 0 ]]; then
+    for existing in "${files[@]}"; do
+      if [[ "$existing" == "$path" ]]; then
+        return 0
+      fi
+    done
+  fi
+
+  files+=("$path")
+}
+
+collect_all_shell_files() {
+  local path
+
+  ensure_git_work_tree
+
+  while IFS= read -r -d '' path; do
+    add_shell_file "$path"
+  done < <(git ls-files -z)
+}
+
+collect_changed_shell_files() {
+  local path
+
+  ensure_git_work_tree
+
+  if git rev-parse --verify HEAD >/dev/null 2>&1; then
+    while IFS= read -r -d '' path; do
+      add_shell_file "$path"
+    done < <(git diff --name-only -z --diff-filter=ACMR HEAD)
+
+    while IFS= read -r -d '' path; do
+      add_shell_file "$path"
+    done < <(git diff --cached --name-only -z --diff-filter=ACMR)
+  else
+    collect_all_shell_files
+  fi
+
+  while IFS= read -r -d '' path; do
+    add_shell_file "$path"
+  done < <(git ls-files --others --exclude-standard -z)
+}
+
+collect_requested_shell_files() {
+  local path
+
+  for path in "$@"; do
+    add_shell_file "$path"
+  done
+}
+
+syntax_shell_for() {
+  local path="$1"
+  local first_line=""
+
+  IFS= read -r first_line <"$path" || true
+
+  case "$first_line" in
+    *"/sh"* | *" env sh"* | *"/dash"* | *" env dash"*)
+      printf 'sh'
+      ;;
+    *)
+      printf 'bash'
+      ;;
+  esac
+}
+
+run_syntax_checks() {
+  local file
+  local shell_name
+
+  for file in "$@"; do
+    shell_name="$(syntax_shell_for "$file")"
+    case "$shell_name" in
+      sh)
+        sh -n "$file"
+        ;;
+      bash)
+        bash -n "$file"
+        ;;
+      *)
+        die "unsupported shell for syntax check: $shell_name"
+        ;;
+    esac
+  done
+}
+
+format=false
+strict=false
+all=false
+requested_files=()
+
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --all)
+      all=true
+      ;;
+    --format)
+      format=true
+      ;;
+    --strict)
+      strict=true
+      ;;
+    -h | --help)
+      usage
+      exit 0
+      ;;
+    --)
+      shift
+      requested_files+=("$@")
+      break
+      ;;
+    -*)
+      die "unknown option: $1"
+      ;;
+    *)
+      requested_files+=("$1")
+      ;;
+  esac
+  shift
+done
+
+require_tool shellcheck
+if [[ "$format" == true ]]; then
+  require_tool shfmt
+fi
+
+files=()
+if [[ "${#requested_files[@]}" -gt 0 ]]; then
+  collect_requested_shell_files "${requested_files[@]}"
+elif [[ "$all" == true ]]; then
+  collect_all_shell_files
+else
+  collect_changed_shell_files
+fi
+
+if [[ "${#files[@]}" -eq 0 ]]; then
+  echo "No shell files found."
+  exit 0
+fi
+
+if [[ "$format" == true ]]; then
+  echo "Formatting ${#files[@]} shell files"
+  shfmt_args=(-i 2 -ci -bn)
+  shfmt "${shfmt_args[@]}" -w "${files[@]}"
+fi
+
+echo "Linting ${#files[@]} shell files"
+
+shellcheck_args=(--severity=warning --external-sources --source-path=SCRIPTDIR)
+if [[ "$strict" == true ]]; then
+  shellcheck_args+=("--enable=check-extra-masked-returns,check-set-e-suppressed,quote-safe-variables,deprecate-which,avoid-nullary-conditions")
+fi
+
+shellcheck "${shellcheck_args[@]}" "${files[@]}"
+run_syntax_checks "${files[@]}"

scripts/sync-to-codex-plugin.sh

@@ -0,0 +1,466 @@
+#!/usr/bin/env bash
+#
+# sync-to-codex-plugin.sh
+#
+# Sync this superpowers checkout → prime-radiant-inc/openai-codex-plugins.
+# Clones the fork fresh into a temp dir, rsyncs tracked upstream plugin content
+# (including committed Codex files under .codex-plugin/ and assets/), preserves
+# OpenAI-owned marketplace metadata already in the destination plugin, commits,
+# pushes a sync branch, and opens a PR.
+# Path/user agnostic — auto-detects upstream from script location.
+#
+# Deterministic: running twice against the same upstream SHA produces PRs with
+# identical diffs, so two back-to-back runs can verify the tool itself.
+#
+# Usage:
+#   ./scripts/sync-to-codex-plugin.sh                              # full run
+#   ./scripts/sync-to-codex-plugin.sh -n                           # dry run
+#   ./scripts/sync-to-codex-plugin.sh -y                           # skip confirm
+#   ./scripts/sync-to-codex-plugin.sh --local PATH                 # existing checkout
+#   ./scripts/sync-to-codex-plugin.sh --base BRANCH                # default: main
+#   ./scripts/sync-to-codex-plugin.sh --bootstrap                  # create plugin dir if missing
+#
+# Bootstrap mode: skips the "plugin must exist on base" requirement and creates
+# plugins/superpowers/ when absent, then copies the tracked plugin files from
+# upstream just like a normal sync.
+#
+# Requires: bash, rsync, git, gh (authenticated), python3.
+
+set -euo pipefail
+
+# =============================================================================
+# Config — edit as upstream or canonical plugin shape evolves
+# =============================================================================
+
+FORK="prime-radiant-inc/openai-codex-plugins"
+DEFAULT_BASE="main"
+DEST_REL="plugins/superpowers"
+
+# Paths in upstream that should NOT land in the embedded plugin.
+# All patterns use a leading "/" to anchor them to the source root.
+# Unanchored patterns like "scripts/" would match any directory named
+# "scripts" at any depth — including legitimate nested dirs like
+# skills/brainstorming/scripts/. Anchoring prevents that.
+# (.DS_Store is intentionally unanchored — Finder creates them everywhere.)
+EXCLUDES=(
+  # Dotfiles and infra — top-level only
+  "/.claude/"
+  "/.claude-plugin/"
+  "/.codex/"
+  "/.cursor-plugin/"
+  "/.git/"
+  "/.gitattributes"
+  "/.github/"
+  "/.gitignore"
+  "/.gitmodules"
+  "/.kimi-plugin/"
+  "/.opencode/"
+  "/.pi/"
+  "/.pre-commit-config.yaml"
+  "/.version-bump.json"
+  "/.worktrees/"
+  ".DS_Store"
+
+  # Root ceremony files
+  "/AGENTS.md"
+  "/CHANGELOG.md"
+  "/CLAUDE.md"
+  "/GEMINI.md"
+  "/RELEASE-NOTES.md"
+  "/gemini-extension.json"
+  "/package.json"
+
+  # Directories not shipped by canonical Codex plugins
+  "/commands/"
+  "/docs/"
+  "/evals/"
+  "/lib/"
+  "/scripts/"
+  "/tests/"
+  "/tmp/"
+)
+
+# =============================================================================
+# Ignored-path helpers
+# =============================================================================
+
+IGNORED_DIR_EXCLUDES=()
+
+path_has_directory_exclude() {
+  local path="$1"
+  local dir
+
+  if [[ ${#IGNORED_DIR_EXCLUDES[@]} -eq 0 ]]; then
+    return 1
+  fi
+
+  for dir in "${IGNORED_DIR_EXCLUDES[@]}"; do
+    [[ "$path" == "$dir"* ]] && return 0
+  done
+
+  return 1
+}
+
+ignored_directory_has_tracked_descendants() {
+  local path="$1"
+
+  [[ -n "$(git -C "$UPSTREAM" ls-files --cached -- "$path/")" ]]
+}
+
+append_git_ignored_directory_excludes() {
+  local path
+  local lookup_path
+
+  while IFS= read -r -d '' path; do
+    [[ "$path" == */ ]] || continue
+
+    lookup_path="${path%/}"
+    if ! ignored_directory_has_tracked_descendants "$lookup_path"; then
+      IGNORED_DIR_EXCLUDES+=("$path")
+      RSYNC_ARGS+=(--exclude="/$path")
+    fi
+  done < <(git -C "$UPSTREAM" ls-files --others --ignored --exclude-standard --directory -z)
+}
+
+append_git_ignored_file_excludes() {
+  local path
+
+  while IFS= read -r -d '' path; do
+    path_has_directory_exclude "$path" && continue
+    RSYNC_ARGS+=(--exclude="/$path")
+  done < <(git -C "$UPSTREAM" ls-files --others --ignored --exclude-standard -z)
+}
+
+# =============================================================================
+# Args
+# =============================================================================
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+UPSTREAM="$(cd "$SCRIPT_DIR/.." && pwd)"
+BASE="$DEFAULT_BASE"
+DRY_RUN=0
+YES=0
+LOCAL_CHECKOUT=""
+BOOTSTRAP=0
+
+usage() {
+  sed -n '/^# Usage:/,/^# Requires:/s/^# \{0,1\}//p' "$0"
+  exit "${1:-0}"
+}
+
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    -n|--dry-run)  DRY_RUN=1; shift ;;
+    -y|--yes)      YES=1; shift ;;
+    --local)       LOCAL_CHECKOUT="$2"; shift 2 ;;
+    --base)        BASE="$2"; shift 2 ;;
+    --bootstrap)   BOOTSTRAP=1; shift ;;
+    -h|--help)     usage 0 ;;
+    *)             echo "Unknown arg: $1" >&2; usage 2 ;;
+  esac
+done
+
+# =============================================================================
+# Preflight
+# =============================================================================
+
+die() { echo "ERROR: $*" >&2; exit 1; }
+
+command -v rsync >/dev/null   || die "rsync not found in PATH"
+command -v git >/dev/null     || die "git not found in PATH"
+command -v gh >/dev/null      || die "gh not found — install GitHub CLI"
+command -v python3 >/dev/null || die "python3 not found in PATH"
+
+gh auth status >/dev/null 2>&1 || die "gh not authenticated — run 'gh auth login'"
+
+[[ -d "$UPSTREAM/.git" ]]         || die "upstream '$UPSTREAM' is not a git checkout"
+[[ -f "$UPSTREAM/.codex-plugin/plugin.json" ]] || die "committed Codex manifest missing at $UPSTREAM/.codex-plugin/plugin.json"
+
+# Read the upstream version from the committed Codex manifest.
+UPSTREAM_VERSION="$(python3 -c 'import json,sys; print(json.load(open(sys.argv[1]))["version"])' "$UPSTREAM/.codex-plugin/plugin.json")"
+[[ -n "$UPSTREAM_VERSION" ]] || die "could not read 'version' from committed Codex manifest"
+
+UPSTREAM_BRANCH="$(cd "$UPSTREAM" && git branch --show-current)"
+UPSTREAM_SHA="$(cd "$UPSTREAM" && git rev-parse HEAD)"
+UPSTREAM_SHORT="$(cd "$UPSTREAM" && git rev-parse --short HEAD)"
+
+confirm() {
+  [[ $YES -eq 1 ]] && return 0
+  read -rp "$1 [y/N] " ans
+  [[ "$ans" == "y" || "$ans" == "Y" ]]
+}
+
+if [[ "$UPSTREAM_BRANCH" != "main" ]]; then
+  echo "WARNING: upstream is on '$UPSTREAM_BRANCH', not 'main'"
+  confirm "Sync from '$UPSTREAM_BRANCH' anyway?" || exit 1
+fi
+
+UPSTREAM_STATUS="$(cd "$UPSTREAM" && git status --porcelain)"
+if [[ -n "$UPSTREAM_STATUS" ]]; then
+  echo "WARNING: upstream has uncommitted changes:"
+  echo "$UPSTREAM_STATUS" | sed 's/^/  /'
+  echo "Sync will use working-tree state, not HEAD ($UPSTREAM_SHORT)."
+  confirm "Continue anyway?" || exit 1
+fi
+
+# =============================================================================
+# Prepare destination (clone fork fresh, or use --local)
+# =============================================================================
+
+CLEANUP_DIR=""
+cleanup() {
+  if [[ -n "$CLEANUP_DIR" ]]; then
+    rm -rf "$CLEANUP_DIR"
+  fi
+}
+trap cleanup EXIT
+
+if [[ -n "$LOCAL_CHECKOUT" ]]; then
+  DEST_REPO="$(cd "$LOCAL_CHECKOUT" && pwd)"
+  [[ -d "$DEST_REPO/.git" ]] || die "--local path '$DEST_REPO' is not a git checkout"
+else
+  echo "Cloning $FORK..."
+  CLEANUP_DIR="$(mktemp -d)"
+  DEST_REPO="$CLEANUP_DIR/openai-codex-plugins"
+  gh repo clone "$FORK" "$DEST_REPO" >/dev/null
+fi
+
+DEST="$DEST_REPO/$DEST_REL"
+PREVIEW_REPO="$DEST_REPO"
+PREVIEW_DEST="$DEST"
+SYNC_SOURCE=""
+
+overlay_destination_paths() {
+  local repo="$1"
+  local path
+  local source_path
+  local preview_path
+
+  while IFS= read -r -d '' path; do
+    source_path="$repo/$path"
+    preview_path="$PREVIEW_REPO/$path"
+
+    if [[ -e "$source_path" ]]; then
+      mkdir -p "$(dirname "$preview_path")"
+      cp -R "$source_path" "$preview_path"
+    else
+      rm -rf "$preview_path"
+    fi
+  done
+}
+
+copy_local_destination_overlay() {
+  overlay_destination_paths "$DEST_REPO" < <(
+    git -C "$DEST_REPO" diff --name-only -z -- "$DEST_REL"
+  )
+  overlay_destination_paths "$DEST_REPO" < <(
+    git -C "$DEST_REPO" diff --cached --name-only -z -- "$DEST_REL"
+  )
+  overlay_destination_paths "$DEST_REPO" < <(
+    git -C "$DEST_REPO" ls-files --others --exclude-standard -z -- "$DEST_REL"
+  )
+  overlay_destination_paths "$DEST_REPO" < <(
+    git -C "$DEST_REPO" ls-files --others --ignored --exclude-standard -z -- "$DEST_REL"
+  )
+}
+
+local_checkout_has_uncommitted_destination_changes() {
+  [[ -n "$(git -C "$DEST_REPO" status --porcelain=1 --untracked-files=all --ignored=matching -- "$DEST_REL")" ]]
+}
+
+prepare_preview_checkout() {
+  if [[ -n "$LOCAL_CHECKOUT" ]]; then
+    [[ -n "$CLEANUP_DIR" ]] || CLEANUP_DIR="$(mktemp -d)"
+    PREVIEW_REPO="$CLEANUP_DIR/preview"
+    git clone -q --no-local "$DEST_REPO" "$PREVIEW_REPO"
+    PREVIEW_DEST="$PREVIEW_REPO/$DEST_REL"
+  fi
+
+  git -C "$PREVIEW_REPO" checkout -q "$BASE" 2>/dev/null || die "base branch '$BASE' doesn't exist in $FORK"
+  if [[ -n "$LOCAL_CHECKOUT" ]]; then
+    copy_local_destination_overlay
+  fi
+  if [[ $BOOTSTRAP -ne 1 ]]; then
+    [[ -d "$PREVIEW_DEST" ]] || die "base branch '$BASE' has no '$DEST_REL/' — use --bootstrap, or pass --base <branch>"
+  fi
+}
+
+prepare_apply_checkout() {
+  git -C "$DEST_REPO" checkout -q "$BASE" 2>/dev/null || die "base branch '$BASE' doesn't exist in $FORK"
+  if [[ $BOOTSTRAP -ne 1 ]]; then
+    [[ -d "$DEST" ]] || die "base branch '$BASE' has no '$DEST_REL/' — use --bootstrap, or pass --base <branch>"
+  fi
+}
+
+apply_to_preview_checkout() {
+  if [[ $BOOTSTRAP -eq 1 ]]; then
+    mkdir -p "$PREVIEW_DEST"
+  fi
+
+  rsync "${RSYNC_ARGS[@]}" "$SYNC_SOURCE/" "$PREVIEW_DEST/"
+}
+
+preview_checkout_has_changes() {
+  [[ -n "$(git -C "$PREVIEW_REPO" status --porcelain "$DEST_REL")" ]]
+}
+
+prepare_preview_checkout
+
+TIMESTAMP="$(date -u +%Y%m%d-%H%M%S)"
+if [[ $BOOTSTRAP -eq 1 ]]; then
+  SYNC_BRANCH="bootstrap/superpowers-${UPSTREAM_SHORT}-${TIMESTAMP}"
+else
+  SYNC_BRANCH="sync/superpowers-${UPSTREAM_SHORT}-${TIMESTAMP}"
+fi
+
+# =============================================================================
+# Build rsync args
+# =============================================================================
+
+RSYNC_ARGS=(-av --delete --delete-excluded)
+for pat in "${EXCLUDES[@]}"; do RSYNC_ARGS+=(--exclude="$pat"); done
+append_git_ignored_directory_excludes
+append_git_ignored_file_excludes
+
+copy_preserved_destination_metadata() {
+  local destination="$1"
+  local source="$2"
+  local path
+  local rel
+
+  [[ -d "$destination/skills" ]] || return 0
+
+  while IFS= read -r -d '' path; do
+    rel="${path#"$destination"/}"
+    mkdir -p "$source/$(dirname "$rel")"
+    cp -p "$path" "$source/$rel"
+  done < <(find "$destination/skills" -path '*/agents/openai.yaml' -type f -print0)
+}
+
+prepare_sync_source() {
+  local destination="$1"
+
+  [[ -n "$CLEANUP_DIR" ]] || CLEANUP_DIR="$(mktemp -d)"
+
+  SYNC_SOURCE="$CLEANUP_DIR/source-overlay"
+  rm -rf "$SYNC_SOURCE"
+  mkdir -p "$SYNC_SOURCE"
+
+  rsync "${RSYNC_ARGS[@]}" "$UPSTREAM/" "$SYNC_SOURCE/" >/dev/null
+  copy_preserved_destination_metadata "$destination" "$SYNC_SOURCE"
+}
+
+prepare_sync_source "$PREVIEW_DEST"
+
+# =============================================================================
+# Dry run preview (always shown)
+# =============================================================================
+
+echo ""
+echo "Upstream: $UPSTREAM ($UPSTREAM_BRANCH @ $UPSTREAM_SHORT)"
+echo "Version:  $UPSTREAM_VERSION"
+echo "Fork:     $FORK"
+echo "Base:     $BASE"
+echo "Branch:   $SYNC_BRANCH"
+if [[ $BOOTSTRAP -eq 1 ]]; then
+  echo "Mode:     BOOTSTRAP (creating plugins/superpowers/ when absent)"
+fi
+echo ""
+echo "=== Preview (rsync --dry-run) ==="
+rsync "${RSYNC_ARGS[@]}" --dry-run --itemize-changes "$SYNC_SOURCE/" "$PREVIEW_DEST/"
+echo "=== End preview ==="
+echo ""
+
+if [[ $DRY_RUN -eq 1 ]]; then
+  echo ""
+  echo "Dry run only. Nothing was changed or pushed."
+  exit 0
+fi
+
+# =============================================================================
+# Apply
+# =============================================================================
+
+echo ""
+confirm "Apply changes, push branch, and open PR?" || { echo "Aborted."; exit 1; }
+
+echo ""
+if [[ -n "$LOCAL_CHECKOUT" ]]; then
+  if local_checkout_has_uncommitted_destination_changes; then
+    die "local checkout has uncommitted changes under '$DEST_REL' — commit, stash, or discard them before syncing"
+  fi
+
+  apply_to_preview_checkout
+  if ! preview_checkout_has_changes; then
+    echo "No changes — embedded plugin was already in sync with upstream $UPSTREAM_SHORT (v$UPSTREAM_VERSION)."
+    exit 0
+  fi
+fi
+
+prepare_apply_checkout
+cd "$DEST_REPO"
+git checkout -q -b "$SYNC_BRANCH"
+echo "Syncing upstream content..."
+if [[ $BOOTSTRAP -eq 1 ]]; then
+  mkdir -p "$DEST"
+fi
+rsync "${RSYNC_ARGS[@]}" "$SYNC_SOURCE/" "$DEST/"
+
+# Bail early if nothing actually changed
+cd "$DEST_REPO"
+if [[ -z "$(git status --porcelain "$DEST_REL")" ]]; then
+  echo "No changes — embedded plugin was already in sync with upstream $UPSTREAM_SHORT (v$UPSTREAM_VERSION)."
+  exit 0
+fi
+
+# =============================================================================
+# Commit, push, open PR
+# =============================================================================
+
+git add "$DEST_REL"
+
+if [[ $BOOTSTRAP -eq 1 ]]; then
+  COMMIT_TITLE="bootstrap superpowers v$UPSTREAM_VERSION from upstream main @ $UPSTREAM_SHORT"
+  PR_BODY="Initial bootstrap of the superpowers plugin from upstream \`main\` @ \`$UPSTREAM_SHORT\` (v$UPSTREAM_VERSION).
+
+Creates \`plugins/superpowers/\` by copying the tracked plugin files from upstream, including \`.codex-plugin/plugin.json\`, \`assets/\`, and \`hooks/\`.
+
+Run via: \`scripts/sync-to-codex-plugin.sh --bootstrap\`
+Upstream commit: https://github.com/obra/superpowers/commit/$UPSTREAM_SHA
+
+This is a one-time bootstrap. Subsequent syncs will be normal (non-bootstrap) runs using the same tracked upstream plugin files."
+else
+  COMMIT_TITLE="sync superpowers v$UPSTREAM_VERSION from upstream main @ $UPSTREAM_SHORT"
+  PR_BODY="Automated sync from superpowers upstream \`main\` @ \`$UPSTREAM_SHORT\` (v$UPSTREAM_VERSION).
+
+Copies the tracked plugin files from upstream, including the committed Codex manifest, assets, and hooks.
+
+Run via: \`scripts/sync-to-codex-plugin.sh\`
+Upstream commit: https://github.com/obra/superpowers/commit/$UPSTREAM_SHA
+
+Running the sync tool again against the same upstream SHA should produce a PR with an identical diff — use that to verify the tool is behaving."
+fi
+
+git commit --quiet -m "$COMMIT_TITLE
+
+Automated sync via scripts/sync-to-codex-plugin.sh
+Upstream: https://github.com/obra/superpowers/commit/$UPSTREAM_SHA
+Branch:   $SYNC_BRANCH"
+
+echo "Pushing $SYNC_BRANCH to $FORK..."
+git push -u origin "$SYNC_BRANCH" --quiet
+
+echo "Opening PR..."
+PR_URL="$(gh pr create \
+  --repo "$FORK" \
+  --base "$BASE" \
+  --head "$SYNC_BRANCH" \
+  --title "$COMMIT_TITLE" \
+  --body "$PR_BODY")"
+
+PR_NUM="${PR_URL##*/}"
+DIFF_URL="https://github.com/$FORK/pull/$PR_NUM/files"
+
+echo ""
+echo "PR opened: $PR_URL"
+echo "Diff view: $DIFF_URL"

skills/brainstorming/SKILL.md

@@ -5,44 +5,130 @@ description: "You MUST use this before any creative work - creating features, bu
 
 # Brainstorming Ideas Into Designs
 
-## Overview
-
 Help turn ideas into fully formed designs and specs through natural collaborative dialogue.
 
-Start by understanding the current project context, then ask questions one at a time to refine the idea. Once you understand what you're building, present the design in small sections (200-300 words), checking after each section whether it looks right so far.
+Start by understanding the current project context, then ask questions one at a time to refine the idea. Once you understand what you're building, present the design and get user approval.
+
+<HARD-GATE>
+Do NOT invoke any implementation skill, write any code, scaffold any project, or take any implementation action until you have presented a design and the user has approved it. This applies to EVERY project regardless of perceived simplicity.
+</HARD-GATE>
+
+## Anti-Pattern: "This Is Too Simple To Need A Design"
+
+Every project goes through this process. A todo list, a single-function utility, a config change — all of them. "Simple" projects are where unexamined assumptions cause the most wasted work. The design can be short (a few sentences for truly simple projects), but you MUST present it and get approval.
+
+## Checklist
+
+You MUST create a task for each of these items and complete them in order:
+
+1. **Explore project context** — check files, docs, recent commits
+2. **Offer the visual companion just-in-time** — NOT upfront. The first time a question would genuinely be clearer shown than described, offer it then (its own message); on approval its browser tab opens for you. If no visual question ever arises, never offer it. See the Visual Companion section below.
+3. **Ask clarifying questions** — one at a time, understand purpose/constraints/success criteria
+4. **Propose 2-3 approaches** — with trade-offs and your recommendation
+5. **Present design** — in sections scaled to their complexity, get user approval after each section
+6. **Write design doc** — save to `docs/superpowers/specs/YYYY-MM-DD-<topic>-design.md` and commit
+7. **Spec self-review** — quick inline check for placeholders, contradictions, ambiguity, scope (see below)
+8. **User reviews written spec** — ask user to review the spec file before proceeding
+9. **Transition to implementation** — invoke writing-plans skill to create implementation plan
+
+## Process Flow
+
+```dot
+digraph brainstorming {
+    "Explore project context" [shape=box];
+    "Ask clarifying questions" [shape=box];
+    "Propose 2-3 approaches" [shape=box];
+    "Present design sections" [shape=box];
+    "User approves design?" [shape=diamond];
+    "Write design doc" [shape=box];
+    "Spec self-review\n(fix inline)" [shape=box];
+    "User reviews spec?" [shape=diamond];
+    "Invoke writing-plans skill" [shape=doublecircle];
+
+    "Explore project context" -> "Ask clarifying questions";
+    "Ask clarifying questions" -> "Propose 2-3 approaches";
+    "Propose 2-3 approaches" -> "Present design sections";
+    "Present design sections" -> "User approves design?";
+    "User approves design?" -> "Present design sections" [label="no, revise"];
+    "User approves design?" -> "Write design doc" [label="yes"];
+    "Write design doc" -> "Spec self-review\n(fix inline)";
+    "Spec self-review\n(fix inline)" -> "User reviews spec?";
+    "User reviews spec?" -> "Write design doc" [label="changes requested"];
+    "User reviews spec?" -> "Invoke writing-plans skill" [label="approved"];
+}
+```
+
+**The terminal state is invoking writing-plans.** Do NOT invoke frontend-design, mcp-builder, or any other implementation skill. The ONLY skill you invoke after brainstorming is writing-plans.
 
 ## The Process
 
 **Understanding the idea:**
+
 - Check out the current project state first (files, docs, recent commits)
-- Ask questions one at a time to refine the idea
+- Before asking detailed questions, assess scope: if the request describes multiple independent subsystems (e.g., "build a platform with chat, file storage, billing, and analytics"), flag this immediately. Don't spend questions refining details of a project that needs to be decomposed first.
+- If the project is too large for a single spec, help the user decompose into sub-projects: what are the independent pieces, how do they relate, what order should they be built? Then brainstorm the first sub-project through the normal design flow. Each sub-project gets its own spec → plan → implementation cycle.
+- For appropriately-scoped projects, ask questions one at a time to refine the idea
 - Prefer multiple choice questions when possible, but open-ended is fine too
 - Only one question per message - if a topic needs more exploration, break it into multiple questions
 - Focus on understanding: purpose, constraints, success criteria
 
 **Exploring approaches:**
+
 - Propose 2-3 different approaches with trade-offs
 - Present options conversationally with your recommendation and reasoning
 - Lead with your recommended option and explain why
 
 **Presenting the design:**
+
 - Once you believe you understand what you're building, present the design
-- Break it into sections of 200-300 words
+- Scale each section to its complexity: a few sentences if straightforward, up to 200-300 words if nuanced
 - Ask after each section whether it looks right so far
 - Cover: architecture, components, data flow, error handling, testing
 - Be ready to go back and clarify if something doesn't make sense
 
+**Design for isolation and clarity:**
+
+- Break the system into smaller units that each have one clear purpose, communicate through well-defined interfaces, and can be understood and tested independently
+- For each unit, you should be able to answer: what does it do, how do you use it, and what does it depend on?
+- Can someone understand what a unit does without reading its internals? Can you change the internals without breaking consumers? If not, the boundaries need work.
+- Smaller, well-bounded units are also easier for you to work with - you reason better about code you can hold in context at once, and your edits are more reliable when files are focused. When a file grows large, that's often a signal that it's doing too much.
+
+**Working in existing codebases:**
+
+- Explore the current structure before proposing changes. Follow existing patterns.
+- Where existing code has problems that affect the work (e.g., a file that's grown too large, unclear boundaries, tangled responsibilities), include targeted improvements as part of the design - the way a good developer improves code they're working in.
+- Don't propose unrelated refactoring. Stay focused on what serves the current goal.
+
 ## After the Design
 
 **Documentation:**
-- Write the validated design to `docs/plans/YYYY-MM-DD-<topic>-design.md`
+
+- Write the validated design (spec) to `docs/superpowers/specs/YYYY-MM-DD-<topic>-design.md`
+  - (User preferences for spec location override this default)
 - Use elements-of-style:writing-clearly-and-concisely skill if available
 - Commit the design document to git
 
-**Implementation (if continuing):**
-- Ask: "Ready to set up for implementation?"
-- Use superpowers:using-git-worktrees to create isolated workspace
-- Use superpowers:writing-plans to create detailed implementation plan
+**Spec Self-Review:**
+After writing the spec document, look at it with fresh eyes:
+
+1. **Placeholder scan:** Any "TBD", "TODO", incomplete sections, or vague requirements? Fix them.
+2. **Internal consistency:** Do any sections contradict each other? Does the architecture match the feature descriptions?
+3. **Scope check:** Is this focused enough for a single implementation plan, or does it need decomposition?
+4. **Ambiguity check:** Could any requirement be interpreted two different ways? If so, pick one and make it explicit.
+
+Fix any issues inline. No need to re-review — just fix and move on.
+
+**User Review Gate:**
+After the spec review loop passes, ask the user to review the written spec before proceeding:
+
+> "Spec written and committed to `<path>`. Please review it and let me know if you want to make any changes before we start writing out the implementation plan."
+
+Wait for the user's response. If they request changes, make them and re-run the spec review loop. Only proceed once the user approves.
+
+**Implementation:**
+
+- Invoke the writing-plans skill to create a detailed implementation plan
+- Do NOT invoke any other skill. writing-plans is the next step.
 
 ## Key Principles
 
@@ -50,5 +136,24 @@ Start by understanding the current project context, then ask questions one at a
 - **Multiple choice preferred** - Easier to answer than open-ended when possible
 - **YAGNI ruthlessly** - Remove unnecessary features from all designs
 - **Explore alternatives** - Always propose 2-3 approaches before settling
-- **Incremental validation** - Present design in sections, validate each
+- **Incremental validation** - Present design, get approval before moving on
 - **Be flexible** - Go back and clarify when something doesn't make sense
+
+## Visual Companion
+
+A browser-based companion for showing mockups, diagrams, and visual options during brainstorming. Available as a tool — not a mode. Accepting the companion means it's available for questions that benefit from visual treatment; it does NOT mean every question goes through the browser.
+
+**Offering the companion (just-in-time):** Do NOT offer it upfront. Wait until a question would genuinely be clearer shown than told — a real mockup / layout / diagram question, not merely a UI *topic*. The first time that happens, offer it then, as its own message:
+> "This next part might be easier if I show you — I can put together mockups, diagrams, and comparisons in a browser tab as we go. It's still new and can be token-intensive. Want me to? I'll open it for you."
+
+**This offer MUST be its own message.** Only the offer — no clarifying question, summary, or other content. Wait for the user's response. If they accept, start the server with `--open` so their browser opens to the first screen automatically. If they decline, continue text-only and don't offer again unless they raise it.
+
+**Per-question decision:** Even after the user accepts, decide FOR EACH QUESTION whether to use the browser or the terminal. The test: **would the user understand this better by seeing it than reading it?**
+
+- **Use the browser** for content that IS visual — mockups, wireframes, layout comparisons, architecture diagrams, side-by-side visual designs
+- **Use the terminal** for content that is text — requirements questions, conceptual choices, tradeoff lists, A/B/C/D text options, scope decisions
+
+A question about a UI topic is not automatically a visual question. "What does personality mean in this context?" is a conceptual question — use the terminal. "Which wizard layout works better?" is a visual question — use the browser.
+
+If they agree to the companion, read the detailed guide before proceeding:
+`skills/brainstorming/visual-companion.md`

skills/brainstorming/scripts/frame-template.html

@@ -0,0 +1,213 @@
+<!DOCTYPE html>
+<html>
+<head>
+  <meta charset="utf-8">
+  <title>Superpowers Brainstorming</title>
+  <style>
+    /*
+     * BRAINSTORM COMPANION FRAME TEMPLATE
+     *
+     * This template provides a consistent frame with:
+     * - OS-aware light/dark theming
+     * - Header branding and connection status
+     * - Scrollable main content area
+     * - CSS helpers for common UI patterns
+     *
+     * Content is injected via placeholder comment in #frame-content.
+     */
+
+    * { box-sizing: border-box; margin: 0; padding: 0; }
+    html, body { height: 100%; overflow: hidden; }
+
+    /* ===== THEME VARIABLES ===== */
+    :root {
+      --bg-primary: #f5f5f7;
+      --bg-secondary: #ffffff;
+      --bg-tertiary: #e5e5e7;
+      --border: #d1d1d6;
+      --text-primary: #1d1d1f;
+      --text-secondary: #86868b;
+      --text-tertiary: #aeaeb2;
+      --accent: #0071e3;
+      --accent-hover: #0077ed;
+      --success: #34c759;
+      --warning: #ff9f0a;
+      --error: #ff3b30;
+      --selected-bg: #e8f4fd;
+      --selected-border: #0071e3;
+    }
+
+    @media (prefers-color-scheme: dark) {
+      :root {
+        --bg-primary: #1d1d1f;
+        --bg-secondary: #2d2d2f;
+        --bg-tertiary: #3d3d3f;
+        --border: #424245;
+        --text-primary: #f5f5f7;
+        --text-secondary: #86868b;
+        --text-tertiary: #636366;
+        --accent: #0a84ff;
+        --accent-hover: #409cff;
+        --selected-bg: rgba(10, 132, 255, 0.15);
+        --selected-border: #0a84ff;
+      }
+    }
+
+    body {
+      font-family: system-ui, -apple-system, BlinkMacSystemFont, sans-serif;
+      background: var(--bg-primary);
+      color: var(--text-primary);
+      display: flex;
+      flex-direction: column;
+      line-height: 1.5;
+    }
+
+    /* ===== FRAME STRUCTURE ===== */
+    .brand { display: flex; align-items: center; min-width: 0; overflow: hidden; color: var(--text-secondary); line-height: 1; }
+    .brand a { color: inherit; text-decoration: none; display: flex; align-items: center; gap: 0.5rem; min-width: 0; max-width: 100%; line-height: 1; }
+    .brand-copy { display: block; min-width: 0; overflow: hidden; text-overflow: ellipsis; white-space: nowrap; line-height: 1; transform: translateY(-1px); }
+    .brand-logo { display: block; height: 1em; width: auto; max-width: 180px; flex-shrink: 0; filter: invert(1); }
+    @media (prefers-color-scheme: dark) {
+      .brand-logo { filter: none; }
+    }
+    .status { font-size: 0.7rem; color: var(--status-color, var(--success)); display: flex; align-items: center; gap: 0.4rem; justify-self: end; white-space: nowrap; line-height: 1; }
+    .status::before { content: ''; width: 6px; height: 6px; background: var(--status-color, var(--success)); border-radius: 50%; }
+
+    .main { flex: 1; overflow-y: auto; }
+    #frame-content { padding: 2rem; min-height: 100%; }
+
+    .header {
+      background: var(--bg-secondary);
+      border-bottom: 1px solid var(--border);
+      padding: 0.5rem 1.5rem;
+      flex-shrink: 0;
+      display: grid;
+      grid-template-columns: minmax(0, 1fr) auto;
+      align-items: center;
+      gap: 1rem;
+      min-height: 42px;
+    }
+    .header .brand { justify-self: start; width: 100%; font-size: 0.75rem; line-height: 1; }
+    .header .status { grid-column: 2; line-height: 1; }
+    .header span {
+      font-size: 0.75rem;
+      color: var(--text-secondary);
+    }
+    .header .selected-text {
+      color: var(--accent);
+      font-weight: 500;
+    }
+
+    /* ===== TYPOGRAPHY ===== */
+    h2 { font-size: 1.5rem; font-weight: 600; margin-bottom: 0.5rem; }
+    h3 { font-size: 1.1rem; font-weight: 600; margin-bottom: 0.25rem; }
+    .subtitle { color: var(--text-secondary); margin-bottom: 1.5rem; }
+    .section { margin-bottom: 2rem; }
+    .label { font-size: 0.7rem; color: var(--text-secondary); text-transform: uppercase; letter-spacing: 0.05em; margin-bottom: 0.5rem; }
+
+    /* ===== OPTIONS (for A/B/C choices) ===== */
+    .options { display: flex; flex-direction: column; gap: 0.75rem; }
+    .option {
+      background: var(--bg-secondary);
+      border: 2px solid var(--border);
+      border-radius: 12px;
+      padding: 1rem 1.25rem;
+      cursor: pointer;
+      transition: all 0.15s ease;
+      display: flex;
+      align-items: flex-start;
+      gap: 1rem;
+    }
+    .option:hover { border-color: var(--accent); }
+    .option.selected { background: var(--selected-bg); border-color: var(--selected-border); }
+    .option .letter {
+      background: var(--bg-tertiary);
+      color: var(--text-secondary);
+      width: 1.75rem; height: 1.75rem;
+      border-radius: 6px;
+      display: flex; align-items: center; justify-content: center;
+      font-weight: 600; font-size: 0.85rem; flex-shrink: 0;
+    }
+    .option.selected .letter { background: var(--accent); color: white; }
+    .option .content { flex: 1; }
+    .option .content h3 { font-size: 0.95rem; margin-bottom: 0.15rem; }
+    .option .content p { color: var(--text-secondary); font-size: 0.85rem; margin: 0; }
+
+    /* ===== CARDS (for showing designs/mockups) ===== */
+    .cards { display: grid; grid-template-columns: repeat(auto-fit, minmax(280px, 1fr)); gap: 1rem; }
+    .card {
+      background: var(--bg-secondary);
+      border: 1px solid var(--border);
+      border-radius: 12px;
+      overflow: hidden;
+      cursor: pointer;
+      transition: all 0.15s ease;
+    }
+    .card:hover { border-color: var(--accent); transform: translateY(-2px); box-shadow: 0 4px 12px rgba(0,0,0,0.1); }
+    .card.selected { border-color: var(--selected-border); border-width: 2px; }
+    .card-image { background: var(--bg-tertiary); aspect-ratio: 16/10; display: flex; align-items: center; justify-content: center; }
+    .card-body { padding: 1rem; }
+    .card-body h3 { margin-bottom: 0.25rem; }
+    .card-body p { color: var(--text-secondary); font-size: 0.85rem; }
+
+    /* ===== MOCKUP CONTAINER ===== */
+    .mockup {
+      background: var(--bg-secondary);
+      border: 1px solid var(--border);
+      border-radius: 12px;
+      overflow: hidden;
+      margin-bottom: 1.5rem;
+    }
+    .mockup-header {
+      background: var(--bg-tertiary);
+      padding: 0.5rem 1rem;
+      font-size: 0.75rem;
+      color: var(--text-secondary);
+      border-bottom: 1px solid var(--border);
+    }
+    .mockup-body { padding: 1.5rem; }
+
+    /* ===== SPLIT VIEW (side-by-side comparison) ===== */
+    .split { display: grid; grid-template-columns: 1fr 1fr; gap: 1.5rem; }
+    @media (max-width: 700px) { .split { grid-template-columns: 1fr; } }
+
+    /* ===== PROS/CONS ===== */
+    .pros-cons { display: grid; grid-template-columns: 1fr 1fr; gap: 1rem; margin: 1rem 0; }
+    .pros, .cons { background: var(--bg-secondary); border-radius: 8px; padding: 1rem; }
+    .pros h4 { color: var(--success); font-size: 0.85rem; margin-bottom: 0.5rem; }
+    .cons h4 { color: var(--error); font-size: 0.85rem; margin-bottom: 0.5rem; }
+    .pros ul, .cons ul { margin-left: 1.25rem; font-size: 0.85rem; color: var(--text-secondary); }
+    .pros li, .cons li { margin-bottom: 0.25rem; }
+
+    /* ===== PLACEHOLDER (for mockup areas) ===== */
+    .placeholder {
+      background: var(--bg-tertiary);
+      border: 2px dashed var(--border);
+      border-radius: 8px;
+      padding: 2rem;
+      text-align: center;
+      color: var(--text-tertiary);
+    }
+
+    /* ===== INLINE MOCKUP ELEMENTS ===== */
+    .mock-nav { background: var(--accent); color: white; padding: 0.75rem 1rem; display: flex; gap: 1.5rem; font-size: 0.9rem; }
+    .mock-sidebar { background: var(--bg-tertiary); padding: 1rem; min-width: 180px; }
+    .mock-content { padding: 1.5rem; flex: 1; }
+    .mock-button { background: var(--accent); color: white; border: none; padding: 0.5rem 1rem; border-radius: 6px; font-size: 0.85rem; }
+    .mock-input { background: var(--bg-primary); border: 1px solid var(--border); border-radius: 6px; padding: 0.5rem; width: 100%; }
+  </style>
+</head>
+<body>
+  <div class="header">
+    <!-- BRANDING -->
+    <div class="status">Connecting…</div>
+  </div>
+
+  <div class="main">
+    <div id="frame-content">
+      <!-- CONTENT -->
+    </div>
+  </div>
+
+</body>
+</html>

skills/brainstorming/scripts/helper.js

@@ -0,0 +1,167 @@
+(function() {
+  const MIN_RECONNECT_MS = 500;
+  const MAX_RECONNECT_MS = 30000;
+  const TOMBSTONE_AFTER_MS = 15000; // show the "paused" overlay after this long disconnected
+
+  // Pure: next backoff delay (doubles, capped). Exported for unit tests.
+  function nextReconnectDelay(current, max) {
+    return Math.min(current * 2, max);
+  }
+  if (typeof module !== 'undefined' && module.exports) {
+    module.exports = { nextReconnectDelay, MIN_RECONNECT_MS, MAX_RECONNECT_MS, TOMBSTONE_AFTER_MS };
+  }
+
+  // Everything below is browser-only; bail out when loaded in Node (tests).
+  if (typeof window === 'undefined') return;
+
+  let ws = null;
+  let eventQueue = [];
+  let reconnectDelay = MIN_RECONNECT_MS;
+  let reconnectTimer = null;
+  let disconnectedSince = null;
+  let everConnected = false;
+  let tombstoneShown = false;
+
+  function sessionKey() {
+    try {
+      return window.sessionStorage && window.sessionStorage.getItem('brainstorm-session-key');
+    } catch (e) {}
+    return null;
+  }
+
+  function websocketUrl() {
+    const key = sessionKey();
+    return 'ws://' + window.location.host + (key ? '/?key=' + encodeURIComponent(key) : '');
+  }
+
+  function reloadAfterRecovery() {
+    const key = sessionKey();
+    if (key) {
+      window.location.replace('/?key=' + encodeURIComponent(key));
+    } else {
+      window.location.reload();
+    }
+  }
+
+  // Reflect connection state in the frame's status pill (absent on full-doc screens).
+  function setStatus(state) {
+    const el = document.querySelector('.status');
+    if (!el) return;
+    const map = {
+      connecting:   ['Connecting…',   'var(--text-tertiary)'],
+      connected:    ['Connected',     'var(--success)'],
+      reconnecting: ['Reconnecting…', 'var(--warning)'],
+      disconnected: ['Disconnected',  'var(--error)']
+    };
+    const [text, color] = map[state] || map.disconnected;
+    el.textContent = text;
+    el.style.setProperty('--status-color', color);
+  }
+
+  // Self-styled so it works on framed and full-document screens alike.
+  function showTombstone() {
+    if (tombstoneShown) return;
+    tombstoneShown = true;
+    const el = document.createElement('div');
+    el.id = 'bs-tombstone';
+    el.style.cssText = 'position:fixed;inset:0;z-index:99999;display:flex;' +
+      'align-items:center;justify-content:center;padding:2rem;text-align:center;' +
+      'background:rgba(20,20,22,0.92);color:#f5f5f7;font-family:system-ui,sans-serif';
+    el.innerHTML = '<div style="max-width:480px">' +
+      '<h2 style="margin:0 0 .5rem;font-weight:600">Companion paused</h2>' +
+      '<p style="margin:0;opacity:.85">This brainstorm companion has stopped. ' +
+      'Ask your coding agent to bring it back — this page reconnects automatically.</p></div>';
+    if (document.body) document.body.appendChild(el);
+  }
+
+  function connect() {
+    if (reconnectTimer) { clearTimeout(reconnectTimer); reconnectTimer = null; }
+    setStatus(everConnected ? 'reconnecting' : 'connecting');
+    ws = new WebSocket(websocketUrl());
+
+    ws.onopen = () => {
+      const recovered = tombstoneShown;
+      everConnected = true;
+      disconnectedSince = null;
+      reconnectDelay = MIN_RECONNECT_MS;
+      tombstoneShown = false;
+      setStatus('connected');
+      eventQueue.forEach(e => ws.send(JSON.stringify(e)));
+      eventQueue = [];
+      // Recovered from a tombstoned outage (e.g. the server restarted on the same
+      // port) — reload through the keyed bootstrap when possible so the cookie is
+      // refreshed before the visible URL returns to bare /.
+      if (recovered) reloadAfterRecovery();
+    };
+
+    ws.onmessage = (msg) => {
+      let data;
+      try { data = JSON.parse(msg.data); } catch (e) { return; }
+      if (data.type === 'reload') window.location.reload();
+    };
+
+    ws.onclose = () => {
+      ws = null;
+      if (disconnectedSince === null) disconnectedSince = Date.now();
+      if (Date.now() - disconnectedSince >= TOMBSTONE_AFTER_MS) {
+        setStatus('disconnected');
+        showTombstone();
+      } else {
+        setStatus('reconnecting');
+      }
+      reconnectTimer = setTimeout(connect, reconnectDelay);
+      reconnectDelay = nextReconnectDelay(reconnectDelay, MAX_RECONNECT_MS);
+    };
+
+    // Let onclose own reconnection so we don't schedule it twice.
+    ws.onerror = () => { try { ws.close(); } catch (e) {} };
+  }
+
+  function sendEvent(event) {
+    event.timestamp = Date.now();
+    if (ws && ws.readyState === WebSocket.OPEN) {
+      ws.send(JSON.stringify(event));
+    } else {
+      eventQueue.push(event);
+    }
+  }
+
+  // Capture clicks on choice elements
+  document.addEventListener('click', (e) => {
+    const target = e.target.closest('[data-choice]');
+    if (!target) return;
+
+    sendEvent({
+      type: 'click',
+      text: target.textContent.trim(),
+      choice: target.dataset.choice,
+      id: target.id || null
+    });
+
+  });
+
+  // Frame UI: selection tracking
+  window.selectedChoice = null;
+
+  window.toggleSelect = function(el) {
+    const container = el.closest('.options') || el.closest('.cards');
+    const multi = container && container.dataset.multiselect !== undefined;
+    if (container && !multi) {
+      container.querySelectorAll('.option, .card').forEach(o => o.classList.remove('selected'));
+    }
+    if (multi) {
+      el.classList.toggle('selected');
+    } else {
+      el.classList.add('selected');
+    }
+    window.selectedChoice = el.dataset.choice;
+  };
+
+  // Expose API for explicit use
+  window.brainstorm = {
+    send: sendEvent,
+    choice: (value, metadata = {}) => sendEvent({ type: 'choice', value, ...metadata })
+  };
+
+  connect();
+})();

skills/brainstorming/scripts/server.cjs

@@ -0,0 +1,723 @@
+const crypto = require('crypto');
+const http = require('http');
+const fs = require('fs');
+const path = require('path');
+
+// ========== WebSocket Protocol (RFC 6455) ==========
+
+const OPCODES = { TEXT: 0x01, CLOSE: 0x08, PING: 0x09, PONG: 0x0A };
+const WS_MAGIC = '258EAFA5-E914-47DA-95CA-C5AB0DC85B11';
+const MAX_FRAME_PAYLOAD_BYTES = 10 * 1024 * 1024;
+
+function computeAcceptKey(clientKey) {
+  return crypto.createHash('sha1').update(clientKey + WS_MAGIC).digest('base64');
+}
+
+function encodeFrame(opcode, payload) {
+  const fin = 0x80;
+  const len = payload.length;
+  let header;
+
+  if (len < 126) {
+    header = Buffer.alloc(2);
+    header[0] = fin | opcode;
+    header[1] = len;
+  } else if (len < 65536) {
+    header = Buffer.alloc(4);
+    header[0] = fin | opcode;
+    header[1] = 126;
+    header.writeUInt16BE(len, 2);
+  } else {
+    header = Buffer.alloc(10);
+    header[0] = fin | opcode;
+    header[1] = 127;
+    header.writeBigUInt64BE(BigInt(len), 2);
+  }
+
+  return Buffer.concat([header, payload]);
+}
+
+function decodeFrame(buffer) {
+  if (buffer.length < 2) return null;
+
+  const secondByte = buffer[1];
+  const opcode = buffer[0] & 0x0F;
+  const masked = (secondByte & 0x80) !== 0;
+  let payloadLen = secondByte & 0x7F;
+  let offset = 2;
+
+  if (!masked) throw new Error('Client frames must be masked');
+
+  if (payloadLen === 126) {
+    if (buffer.length < 4) return null;
+    payloadLen = buffer.readUInt16BE(2);
+    offset = 4;
+  } else if (payloadLen === 127) {
+    if (buffer.length < 10) return null;
+    const extendedLen = buffer.readBigUInt64BE(2);
+    if (extendedLen > BigInt(MAX_FRAME_PAYLOAD_BYTES)) {
+      throw new Error('WebSocket frame payload exceeds maximum allowed size');
+    }
+    payloadLen = Number(extendedLen);
+    offset = 10;
+  }
+
+  if (payloadLen > MAX_FRAME_PAYLOAD_BYTES) {
+    throw new Error('WebSocket frame payload exceeds maximum allowed size');
+  }
+
+  const maskOffset = offset;
+  const dataOffset = offset + 4;
+  const totalLen = dataOffset + payloadLen;
+  if (buffer.length < totalLen) return null;
+
+  const mask = buffer.slice(maskOffset, dataOffset);
+  const data = Buffer.alloc(payloadLen);
+  for (let i = 0; i < payloadLen; i++) {
+    data[i] = buffer[dataOffset + i] ^ mask[i % 4];
+  }
+
+  return { opcode, payload: data, bytesConsumed: totalLen };
+}
+
+// ========== Configuration ==========
+
+const PORT_FILE = process.env.BRAINSTORM_PORT_FILE || null;
+const randomPort = () => 49152 + Math.floor(Math.random() * 16383);
+// Prefer an explicit port, else the port this session last bound (so a restart
+// reuses it and an already-open browser tab reconnects), else a random high port.
+function preferredPort() {
+  if (process.env.BRAINSTORM_PORT) return Number(process.env.BRAINSTORM_PORT);
+  if (PORT_FILE) {
+    try {
+      const p = Number(fs.readFileSync(PORT_FILE, 'utf-8').trim());
+      if (Number.isInteger(p) && p > 1023 && p < 65536) return p;
+    } catch (e) { /* no prior port recorded */ }
+  }
+  return randomPort();
+}
+let PORT = preferredPort();
+const HOST = process.env.BRAINSTORM_HOST || '127.0.0.1';
+const URL_HOST = process.env.BRAINSTORM_URL_HOST || (HOST === '127.0.0.1' ? 'localhost' : HOST);
+const SESSION_DIR = process.env.BRAINSTORM_DIR || '/tmp/brainstorm';
+const CONTENT_DIR = path.join(SESSION_DIR, 'content');
+const STATE_DIR = path.join(SESSION_DIR, 'state');
+const SUPERPOWERS_VERSION = readSuperpowersVersion();
+const SUPERPOWERS_BRAND_IMAGE_URL = 'https://primeradiant.com/brand/superpowers-visual-brainstorming-logo.png';
+const TELEMETRY_DISABLE_ENV_VARS = [
+  'SUPERPOWERS_DISABLE_TELEMETRY',
+  'DISABLE_TELEMETRY',
+  'CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC'
+];
+const SUPERPOWERS_TELEMETRY_DISABLED = TELEMETRY_DISABLE_ENV_VARS.some(name => isTruthyEnv(process.env[name]));
+let ownerPid = process.env.BRAINSTORM_OWNER_PID ? Number(process.env.BRAINSTORM_OWNER_PID) : null;
+
+// Per-session secret key. The companion is reachable by any local browser tab
+// and, when bound to a non-loopback host, by any host that can route to it.
+// The key authenticates the real client uniformly across loopback, tunnel, and
+// remote binds — and defeats DNS rebinding — where a Host/Origin allowlist
+// cannot. It rides the served URL as ?key= and is mirrored into a cookie on
+// first load so same-origin subresources and the WebSocket carry it for free.
+// Persisted alongside the port (BRAINSTORM_TOKEN_FILE) so a restart keeps the
+// same key and an already-open tab's cookie still validates.
+const TOKEN_FILE = process.env.BRAINSTORM_TOKEN_FILE || null;
+function generateToken() {
+  return crypto.randomBytes(32).toString('hex');
+}
+
+function chmodOwnerOnly(file) {
+  try { fs.chmodSync(file, 0o600); } catch (e) { /* best effort */ }
+}
+
+function initialToken() {
+  if (process.env.BRAINSTORM_TOKEN) {
+    return { value: process.env.BRAINSTORM_TOKEN, source: 'env' };
+  }
+  if (TOKEN_FILE) {
+    try {
+      const t = fs.readFileSync(TOKEN_FILE, 'utf-8').trim();
+      if (/^[0-9a-f]{32,}$/i.test(t)) {
+        chmodOwnerOnly(TOKEN_FILE);
+        return { value: t, source: 'file' };
+      }
+    } catch (e) { /* no prior token recorded */ }
+  }
+  return { value: generateToken(), source: 'generated' };
+}
+
+const tokenInfo = initialToken();
+let TOKEN = tokenInfo.value;
+let tokenSource = tokenInfo.source;
+let COOKIE_NAME = 'brainstorm-key-' + PORT; // refined to the actual bound port in onListen
+
+const MIME_TYPES = {
+  '.html': 'text/html', '.css': 'text/css', '.js': 'application/javascript',
+  '.json': 'application/json', '.png': 'image/png', '.jpg': 'image/jpeg',
+  '.jpeg': 'image/jpeg', '.gif': 'image/gif', '.svg': 'image/svg+xml'
+};
+
+// ========== Templates and Constants ==========
+
+function waitingPage() {
+  return renderBranding(`<!DOCTYPE html>
+<html>
+<head><meta charset="utf-8"><title>Brainstorm Companion</title>
+<style>
+body { font-family: system-ui, sans-serif; padding: 2rem; max-width: 800px; margin: 0 auto; }
+h1 { color: #333; } p { color: #666; }
+.brand { display: flex; align-items: center; min-width: 0; overflow: hidden; margin-bottom: 1.5rem; color: #666; font-size: 0.9rem; line-height: 1; }
+.brand a { color: inherit; text-decoration: none; display: flex; align-items: center; gap: 0.5rem; min-width: 0; max-width: 100%; line-height: 1; }
+.brand-copy { display: block; min-width: 0; overflow: hidden; text-overflow: ellipsis; white-space: nowrap; line-height: 1; transform: translateY(-1px); }
+.brand-logo { display: block; height: 1em; width: auto; max-width: 180px; filter: invert(1); }
+</style>
+</head>
+<body><!-- BRANDING --><h1>Brainstorm Companion</h1>
+<p>Waiting for the agent to push a screen...</p></body></html>`);
+}
+
+const FORBIDDEN_PAGE = `<!DOCTYPE html>
+<html>
+<head><meta charset="utf-8"><title>Session key required</title>
+<style>body { font-family: system-ui, sans-serif; padding: 2rem; max-width: 800px; margin: 0 auto; }
+h1 { color: #333; } p { color: #666; } code { background: #f0f0f0; padding: 0.1em 0.3em; border-radius: 4px; }</style>
+</head>
+<body><h1>Session key required</h1>
+<p>This page needs the full URL your coding agent gave you, including the
+<code>?key=&hellip;</code> part. Copy the complete URL and open it again.</p></body></html>`;
+
+function bootstrapPage(key) {
+  const jsonKey = JSON.stringify(String(key));
+  return `<!DOCTYPE html>
+<html>
+<head><meta charset="utf-8"><title>Opening Brainstorm Companion</title></head>
+<body>
+<script>
+try { sessionStorage.setItem('brainstorm-session-key', ${jsonKey}); } catch (e) {}
+location.replace('/');
+</script>
+</body>
+</html>`;
+}
+
+const frameTemplate = fs.readFileSync(path.join(__dirname, 'frame-template.html'), 'utf-8');
+const helperScript = fs.readFileSync(path.join(__dirname, 'helper.js'), 'utf-8');
+const helperInjection = '<script>\n' + helperScript + '\n</script>';
+
+// ========== Helper Functions ==========
+
+function readSuperpowersVersion() {
+  const root = path.join(__dirname, '../../..');
+  const manifests = [
+    path.join(root, 'package.json'),
+    path.join(root, '.codex-plugin/plugin.json')
+  ];
+
+  for (const manifest of manifests) {
+    try {
+      const data = JSON.parse(fs.readFileSync(manifest, 'utf-8'));
+      if (data.version) return String(data.version);
+    } catch (e) {
+      // Packaged Codex plugins omit package.json; try the next manifest.
+    }
+  }
+
+  return 'unknown';
+}
+
+function isTruthyEnv(value) {
+  if (!value) return false;
+  const normalized = String(value).trim().toLowerCase();
+  if (!normalized) return false;
+  return !['0', 'false', 'no', 'off'].includes(normalized);
+}
+
+function escapeHtmlText(value) {
+  return String(value)
+    .replace(/&/g, '&amp;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;');
+}
+
+function brandMarkup() {
+  const version = escapeHtmlText(SUPERPOWERS_VERSION);
+  const text = SUPERPOWERS_TELEMETRY_DISABLED
+    ? 'Prime Radiant Superpowers v' + version
+    : 'Superpowers v' + version;
+  const logo = SUPERPOWERS_TELEMETRY_DISABLED
+    ? ''
+    : '<img class="brand-logo" src="' + SUPERPOWERS_BRAND_IMAGE_URL + '?v=' + encodeURIComponent(SUPERPOWERS_VERSION) + '" alt="Prime Radiant" referrerpolicy="no-referrer" decoding="async">';
+
+  return '<div class="brand"><a href="https://github.com/obra/superpowers">' + logo + '<span class="brand-copy">' + text + '</span></a></div>';
+}
+
+function renderBranding(html) {
+  return html.split('<!-- BRANDING -->').join(brandMarkup());
+}
+
+function isFullDocument(html) {
+  const trimmed = html.trimStart().toLowerCase();
+  return trimmed.startsWith('<!doctype') || trimmed.startsWith('<html');
+}
+
+function wrapInFrame(content) {
+  return renderBranding(frameTemplate).replace('<!-- CONTENT -->', content);
+}
+
+function getNewestScreen() {
+  const files = fs.readdirSync(CONTENT_DIR)
+    .filter(f => !f.startsWith('.') && f.endsWith('.html'))
+    .map(f => {
+      const fp = path.join(CONTENT_DIR, f);
+      if (!isRegularFileInsideContentDir(fp)) return null;
+      return { path: fp, mtime: fs.statSync(fp).mtime.getTime() };
+    })
+    .filter(Boolean)
+    .sort((a, b) => b.mtime - a.mtime);
+  return files.length > 0 ? files[0].path : null;
+}
+
+function urlHostForHttp(host) {
+  const h = String(host);
+  if (h.startsWith('[') && h.endsWith(']')) return h;
+  return h.includes(':') ? '[' + h + ']' : h;
+}
+
+function companionUrl() {
+  return 'http://' + urlHostForHttp(URL_HOST) + ':' + PORT + '/?key=' + TOKEN;
+}
+
+function browserLauncherForPlatform(url, {
+  platform = process.platform,
+  osRelease = require('os').release(),
+  env = process.env
+} = {}) {
+  const isWSL = platform === 'linux' && /microsoft/i.test(osRelease);
+  if (platform === 'darwin') return { bin: 'open', args: [url] };
+  if (platform === 'win32' || isWSL) {
+    return { bin: 'rundll32.exe', args: ['url.dll,FileProtocolHandler', url] };
+  }
+  if (env.DISPLAY || env.WAYLAND_DISPLAY) return { bin: 'xdg-open', args: [url] };
+  return null;
+}
+
+function isRegularFileInsideContentDir(filePath) {
+  let stat, realContentDir, realFilePath;
+  try {
+    stat = fs.lstatSync(filePath);
+    if (stat.isSymbolicLink()) return false;
+    if (!stat.isFile()) return false;
+    if (stat.nlink !== 1) return false;
+    realContentDir = fs.realpathSync(CONTENT_DIR);
+    realFilePath = fs.realpathSync(filePath);
+  } catch (e) {
+    return false;
+  }
+  return realFilePath.startsWith(realContentDir + path.sep);
+}
+
+// ========== Authentication ==========
+
+function timingSafeEqualStr(a, b) {
+  const ab = Buffer.from(String(a));
+  const bb = Buffer.from(String(b));
+  if (ab.length !== bb.length) return false;
+  return crypto.timingSafeEqual(ab, bb);
+}
+
+function parseCookies(header) {
+  const out = {};
+  if (!header) return out;
+  for (const part of header.split(';')) {
+    const eq = part.indexOf('=');
+    if (eq < 0) continue;
+    out[part.slice(0, eq).trim()] = part.slice(eq + 1).trim();
+  }
+  return out;
+}
+
+// A request is authorized if it carries the session key as ?key= or as the
+// session cookie. Both are compared in constant time.
+function isAuthorized(req) {
+  const q = req.url.indexOf('?');
+  if (q >= 0) {
+    const params = new URLSearchParams(req.url.slice(q + 1));
+    if (params.has('key')) {
+      const key = params.get('key');
+      return Boolean(key && timingSafeEqualStr(key, TOKEN));
+    }
+  }
+  const cookie = parseCookies(req.headers['cookie'])[COOKIE_NAME];
+  if (cookie && timingSafeEqualStr(cookie, TOKEN)) return true;
+  return false;
+}
+
+function pathnameOf(url) {
+  const q = url.indexOf('?');
+  return q >= 0 ? url.slice(0, q) : url;
+}
+
+function queryKey(url) {
+  const q = url.indexOf('?');
+  if (q < 0) return null;
+  return new URLSearchParams(url.slice(q + 1)).get('key');
+}
+
+function securityHeaders(headers = {}) {
+  return {
+    'Referrer-Policy': 'no-referrer',
+    'Cache-Control': 'no-store',
+    'X-Frame-Options': 'DENY',
+    'Content-Security-Policy': "frame-ancestors 'none'",
+    'Cross-Origin-Resource-Policy': 'same-origin',
+    ...headers
+  };
+}
+
+function isAllowedWebSocketOrigin(req) {
+  const origin = req.headers.origin;
+  if (!origin) return true;
+  const host = req.headers.host;
+  if (!host) return false;
+  return origin === 'http://' + host;
+}
+
+// ========== HTTP Request Handler ==========
+
+function handleRequest(req, res) {
+  if (!isAuthorized(req)) {
+    res.writeHead(403, securityHeaders({ 'Content-Type': 'text/html; charset=utf-8' }));
+    res.end(FORBIDDEN_PAGE);
+    return;
+  }
+  touchActivity(); // only authorized requests count as activity
+
+  // Mirror the key into a cookie so same-origin subresources (/files/*) can
+  // authenticate after bootstrap. HttpOnly keeps it away from page scripts; the
+  // WebSocket Origin check below is what blocks cross-origin localhost injection.
+  res.setHeader('Set-Cookie',
+    COOKIE_NAME + '=' + TOKEN + '; HttpOnly; SameSite=Strict; Path=/');
+
+  const pathname = pathnameOf(req.url);
+  const keyFromQuery = queryKey(req.url);
+  if (req.method === 'GET' && pathname === '/' && keyFromQuery && timingSafeEqualStr(keyFromQuery, TOKEN)) {
+    res.writeHead(200, securityHeaders({ 'Content-Type': 'text/html; charset=utf-8' }));
+    res.end(bootstrapPage(keyFromQuery));
+  } else if (req.method === 'GET' && pathname === '/') {
+    const screenFile = getNewestScreen();
+    let html = screenFile
+      ? (raw => isFullDocument(raw) ? raw : wrapInFrame(raw))(fs.readFileSync(screenFile, 'utf-8'))
+      : waitingPage();
+
+    if (html.includes('</body>')) {
+      html = html.replace('</body>', helperInjection + '\n</body>');
+    } else {
+      html += helperInjection;
+    }
+
+    res.writeHead(200, securityHeaders({ 'Content-Type': 'text/html; charset=utf-8' }));
+    res.end(html);
+  } else if (req.method === 'GET' && pathname.startsWith('/files/')) {
+    const fileName = path.basename(pathname.slice(7));
+    const filePath = path.join(CONTENT_DIR, fileName);
+    // Reject empty/dotfile names and anything that isn't a regular file —
+    // `/files/` would otherwise resolve to CONTENT_DIR and crash readFileSync (EISDIR).
+    if (!fileName || fileName.startsWith('.') || !isRegularFileInsideContentDir(filePath)) {
+      res.writeHead(404, securityHeaders());
+      res.end('Not found');
+      return;
+    }
+    const ext = path.extname(filePath).toLowerCase();
+    const contentType = MIME_TYPES[ext] || 'application/octet-stream';
+    res.writeHead(200, securityHeaders({ 'Content-Type': contentType }));
+    res.end(fs.readFileSync(filePath));
+  } else {
+    res.writeHead(404, securityHeaders());
+    res.end('Not found');
+  }
+}
+
+// ========== WebSocket Connection Handling ==========
+
+const clients = new Set();
+
+function handleUpgrade(req, socket) {
+  if (!isAuthorized(req) || !isAllowedWebSocketOrigin(req)) { socket.destroy(); return; }
+
+  const key = req.headers['sec-websocket-key'];
+  if (!key) { socket.destroy(); return; }
+
+  const accept = computeAcceptKey(key);
+  socket.write(
+    'HTTP/1.1 101 Switching Protocols\r\n' +
+    'Upgrade: websocket\r\n' +
+    'Connection: Upgrade\r\n' +
+    'Sec-WebSocket-Accept: ' + accept + '\r\n\r\n'
+  );
+
+  let buffer = Buffer.alloc(0);
+  clients.add(socket);
+
+  socket.on('data', (chunk) => {
+    buffer = Buffer.concat([buffer, chunk]);
+    while (buffer.length > 0) {
+      let result;
+      try {
+        result = decodeFrame(buffer);
+      } catch (e) {
+        socket.end(encodeFrame(OPCODES.CLOSE, Buffer.alloc(0)));
+        clients.delete(socket);
+        return;
+      }
+      if (!result) break;
+      buffer = buffer.slice(result.bytesConsumed);
+
+      switch (result.opcode) {
+        case OPCODES.TEXT:
+          handleMessage(result.payload.toString());
+          break;
+        case OPCODES.CLOSE:
+          socket.end(encodeFrame(OPCODES.CLOSE, Buffer.alloc(0)));
+          clients.delete(socket);
+          return;
+        case OPCODES.PING:
+          socket.write(encodeFrame(OPCODES.PONG, result.payload));
+          break;
+        case OPCODES.PONG:
+          break;
+        default: {
+          const closeBuf = Buffer.alloc(2);
+          closeBuf.writeUInt16BE(1003);
+          socket.end(encodeFrame(OPCODES.CLOSE, closeBuf));
+          clients.delete(socket);
+          return;
+        }
+      }
+    }
+  });
+
+  socket.on('close', () => clients.delete(socket));
+  socket.on('error', () => clients.delete(socket));
+}
+
+function handleMessage(text) {
+  let event;
+  try {
+    event = JSON.parse(text);
+  } catch (e) {
+    console.error('Failed to parse WebSocket message:', e.message);
+    return;
+  }
+  touchActivity();
+  console.log(JSON.stringify({ source: 'user-event', ...event }));
+  if (event && event.choice) {
+    const eventsFile = path.join(STATE_DIR, 'events');
+    fs.appendFileSync(eventsFile, JSON.stringify(event) + '\n');
+  }
+}
+
+function broadcast(msg) {
+  const frame = encodeFrame(OPCODES.TEXT, Buffer.from(JSON.stringify(msg)));
+  for (const socket of clients) {
+    try { socket.write(frame); } catch (e) { clients.delete(socket); }
+  }
+}
+
+// Best-effort: open the user's browser the first time a screen is actually ready
+// to show. Skips when disabled, on a non-loopback (remote) bind, or when a
+// browser is already connected. Override the launcher with BRAINSTORM_OPEN_CMD.
+let browserOpened = false;
+function maybeOpenBrowser() {
+  if (browserOpened) return;
+  browserOpened = true;
+  if (!process.env.BRAINSTORM_OPEN) return; // opt-in: only after the user approves the companion
+  if (HOST !== '127.0.0.1' && HOST !== 'localhost') return;
+  if (clients.size > 0) return; // the user already opened it
+  const url = companionUrl(); // must carry the key or the gate 403s it
+  const cp = require('child_process');
+  // Operator-provided launcher: run as given (this env var is trusted operator input).
+  if (process.env.BRAINSTORM_OPEN_CMD) {
+    try { cp.exec(process.env.BRAINSTORM_OPEN_CMD + ' ' + JSON.stringify(url), () => {}); } catch (e) { /* best effort */ }
+    return;
+  }
+  // Platform launchers: pass the URL as an argv element via execFile (no shell),
+  // so a url-host containing shell metacharacters can't inject a command.
+  const launcher = browserLauncherForPlatform(url);
+  if (!launcher) return; // headless: nothing to open
+  try { cp.execFile(launcher.bin, launcher.args, () => {}); } catch (e) { /* best effort */ }
+}
+
+// ========== Activity Tracking ==========
+
+// Idle timeout: shut down after this long with no activity. Default 4 hours;
+// override with BRAINSTORM_IDLE_TIMEOUT_MS (start-server.sh: --idle-timeout-minutes).
+const IDLE_TIMEOUT_MS = (() => {
+  const ms = Number(process.env.BRAINSTORM_IDLE_TIMEOUT_MS);
+  return Number.isFinite(ms) && ms > 0 ? ms : 4 * 60 * 60 * 1000;
+})();
+// How often the watchdog checks for owner-death / idleness. Configurable mainly
+// so tests can run fast; production default is 60s.
+const LIFECYCLE_CHECK_MS = (() => {
+  const ms = Number(process.env.BRAINSTORM_LIFECYCLE_CHECK_MS);
+  return Number.isFinite(ms) && ms > 0 ? ms : 60 * 1000;
+})();
+let lastActivity = Date.now();
+
+function touchActivity() {
+  lastActivity = Date.now();
+}
+
+// ========== File Watching ==========
+
+const debounceTimers = new Map();
+
+// ========== Server Startup ==========
+
+function startServer() {
+  if (!fs.existsSync(CONTENT_DIR)) fs.mkdirSync(CONTENT_DIR, { recursive: true });
+  if (!fs.existsSync(STATE_DIR)) fs.mkdirSync(STATE_DIR, { recursive: true });
+
+  // Track known files to distinguish new screens from updates.
+  // macOS fs.watch reports 'rename' for both new files and overwrites,
+  // so we can't rely on eventType alone.
+  const knownFiles = new Set(
+    fs.readdirSync(CONTENT_DIR).filter(f => !f.startsWith('.') && f.endsWith('.html'))
+  );
+
+  const server = http.createServer(handleRequest);
+  server.on('upgrade', handleUpgrade);
+
+  const watcher = fs.watch(CONTENT_DIR, (eventType, filename) => {
+    if (!filename || filename.startsWith('.') || !filename.endsWith('.html')) return;
+
+    if (debounceTimers.has(filename)) clearTimeout(debounceTimers.get(filename));
+    debounceTimers.set(filename, setTimeout(() => {
+      debounceTimers.delete(filename);
+      const filePath = path.join(CONTENT_DIR, filename);
+
+      if (!fs.existsSync(filePath)) return; // file was deleted
+      touchActivity();
+
+      if (!knownFiles.has(filename)) {
+        knownFiles.add(filename);
+        const eventsFile = path.join(STATE_DIR, 'events');
+        if (fs.existsSync(eventsFile)) fs.unlinkSync(eventsFile);
+        console.log(JSON.stringify({ type: 'screen-added', file: filePath }));
+        maybeOpenBrowser();
+      } else {
+        console.log(JSON.stringify({ type: 'screen-updated', file: filePath }));
+      }
+
+      broadcast({ type: 'reload' });
+    }, 100));
+  });
+  watcher.on('error', (err) => console.error('fs.watch error:', err.message));
+
+  function shutdown(reason) {
+    console.log(JSON.stringify({ type: 'server-stopped', reason }));
+    const infoFile = path.join(STATE_DIR, 'server-info');
+    if (fs.existsSync(infoFile)) fs.unlinkSync(infoFile);
+    fs.writeFileSync(
+      path.join(STATE_DIR, 'server-stopped'),
+      JSON.stringify({ reason, timestamp: Date.now() }) + '\n'
+    );
+    watcher.close();
+    clearInterval(lifecycleCheck);
+    // Close any upgraded WebSocket sockets so server.close() can complete and
+    // the process actually exits instead of lingering on an open connection.
+    for (const socket of clients) {
+      try { socket.destroy(); } catch (e) { /* already gone */ }
+    }
+    server.close(() => process.exit(0));
+  }
+
+  function ownerAlive() {
+    if (!ownerPid) return true;
+    try { process.kill(ownerPid, 0); return true; } catch (e) { return e.code === 'EPERM'; }
+  }
+
+  // Periodically exit if the owner process died or we've been idle too long.
+  const lifecycleCheck = setInterval(() => {
+    if (!ownerAlive()) shutdown('owner process exited');
+    else if (Date.now() - lastActivity > IDLE_TIMEOUT_MS) shutdown('idle timeout');
+  }, LIFECYCLE_CHECK_MS);
+  lifecycleCheck.unref();
+
+  // Validate owner PID at startup. If it's already dead, the PID resolution
+  // was wrong (common on WSL, Tailscale SSH, and cross-user scenarios).
+  // Disable monitoring and rely on the idle timeout instead.
+  if (ownerPid) {
+    try { process.kill(ownerPid, 0); }
+    catch (e) {
+      if (e.code !== 'EPERM') {
+        console.log(JSON.stringify({ type: 'owner-pid-invalid', pid: ownerPid, reason: 'dead at startup' }));
+        ownerPid = null;
+      }
+    }
+  }
+
+  // If the preferred port is already taken (e.g. a previous server is still
+  // alive), fall back to a random port once instead of failing.
+  let triedFallback = false;
+
+  function onListen() {
+    // Cookie name keys on the ACTUAL bound port (may differ from the preferred
+    // one after an EADDRINUSE fallback) so it can't collide with another server's
+    // cookie in the shared localhost jar.
+    COOKIE_NAME = 'brainstorm-key-' + PORT;
+    // Record the bound port AND token so the next restart of this session reuses
+    // them — but ONLY when we got our preferred port. On a fallback we bound a
+    // *different* port because someone else holds the preferred one; persisting
+    // would overwrite the shared files and strand that other session's open tab.
+    if (PORT_FILE && !triedFallback) {
+      try { fs.writeFileSync(PORT_FILE, String(PORT)); } catch (e) { /* best effort */ }
+      if (TOKEN_FILE) {
+        try {
+          fs.writeFileSync(TOKEN_FILE, TOKEN, { mode: 0o600 });
+          chmodOwnerOnly(TOKEN_FILE);
+        } catch (e) { /* best effort */ }
+      }
+    }
+    const info = JSON.stringify({
+      type: 'server-started', port: Number(PORT), host: HOST,
+      url_host: URL_HOST, url: companionUrl(),
+      screen_dir: CONTENT_DIR, state_dir: STATE_DIR, idle_timeout_ms: IDLE_TIMEOUT_MS
+    });
+    console.log(info);
+    // server-info embeds the key — keep it owner-only.
+    fs.writeFileSync(path.join(STATE_DIR, 'server-info'), info + '\n', { mode: 0o600 });
+  }
+
+  server.on('error', (err) => {
+    if (err.code === 'EADDRINUSE' && !triedFallback) {
+      if (tokenSource === 'env') {
+        console.error('Server failed to bind: preferred port is in use and BRAINSTORM_TOKEN is set; refusing fallback with explicit token');
+        process.exit(1);
+      }
+      triedFallback = true;
+      PORT = randomPort();
+      if (tokenSource === 'file') {
+        TOKEN = generateToken();
+        tokenSource = 'generated-fallback';
+      }
+      server.listen(PORT, HOST, onListen);
+    } else {
+      console.error('Server failed to bind:', err.message);
+      process.exit(1);
+    }
+  });
+  server.listen(PORT, HOST, onListen);
+}
+
+if (require.main === module) {
+  startServer();
+}
+
+module.exports = {
+  computeAcceptKey,
+  encodeFrame,
+  decodeFrame,
+  browserLauncherForPlatform,
+  OPCODES,
+  MAX_FRAME_PAYLOAD_BYTES
+};

skills/brainstorming/scripts/start-server.sh

@@ -0,0 +1,209 @@
+#!/usr/bin/env bash
+# Start the brainstorm server and output connection info
+# Usage: start-server.sh [--project-dir <path>] [--host <bind-host>] [--url-host <display-host>] [--foreground] [--background]
+#
+# Starts server on a random high port, outputs JSON with URL.
+# Each session gets its own directory to avoid conflicts.
+#
+# Options:
+#   --project-dir <path>  Store session files under <path>/.superpowers/brainstorm/
+#                         instead of /tmp. Files persist after server stops.
+#   --host <bind-host>    Host/interface to bind (default: 127.0.0.1).
+#                         Use 0.0.0.0 in remote/containerized environments.
+#   --url-host <host>     Hostname shown in returned URL JSON.
+#   --idle-timeout-minutes <n>  Shut down after n minutes idle (default 240 = 4h).
+#   --open                Auto-open the browser on the first screen (use only
+#                         after the user approves the visual companion).
+#   --foreground          Run server in the current terminal (no backgrounding).
+#   --background          Force background mode (overrides Codex auto-foreground).
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+
+# Parse arguments
+PROJECT_DIR=""
+FOREGROUND="false"
+FORCE_BACKGROUND="false"
+BIND_HOST="127.0.0.1"
+URL_HOST=""
+IDLE_TIMEOUT_MINUTES=""
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --project-dir)
+      PROJECT_DIR="$2"
+      shift 2
+      ;;
+    --host)
+      BIND_HOST="$2"
+      shift 2
+      ;;
+    --url-host)
+      URL_HOST="$2"
+      shift 2
+      ;;
+    --idle-timeout-minutes)
+      IDLE_TIMEOUT_MINUTES="$2"
+      shift 2
+      ;;
+    --open)
+      export BRAINSTORM_OPEN=1
+      shift
+      ;;
+    --foreground|--no-daemon)
+      FOREGROUND="true"
+      shift
+      ;;
+    --background|--daemon)
+      FORCE_BACKGROUND="true"
+      shift
+      ;;
+    *)
+      echo "{\"error\": \"Unknown argument: $1\"}"
+      exit 1
+      ;;
+  esac
+done
+
+if [[ -z "$URL_HOST" ]]; then
+  if [[ "$BIND_HOST" == "127.0.0.1" || "$BIND_HOST" == "localhost" ]]; then
+    URL_HOST="localhost"
+  else
+    URL_HOST="$BIND_HOST"
+  fi
+fi
+
+if [[ -n "$IDLE_TIMEOUT_MINUTES" ]]; then
+  if ! [[ "$IDLE_TIMEOUT_MINUTES" =~ ^[0-9]+$ ]] || [[ "$IDLE_TIMEOUT_MINUTES" -lt 1 ]]; then
+    echo "{\"error\": \"--idle-timeout-minutes must be a positive integer\"}"
+    exit 1
+  fi
+  export BRAINSTORM_IDLE_TIMEOUT_MS=$(( IDLE_TIMEOUT_MINUTES * 60 * 1000 ))
+fi
+
+is_windows_like_shell() {
+  case "${OSTYPE:-}" in
+    msys*|cygwin*|mingw*) return 0 ;;
+  esac
+  if [[ -n "${MSYSTEM:-}" ]]; then
+    return 0
+  fi
+  local uname_s
+  uname_s="$(uname -s 2>/dev/null || true)"
+  case "$uname_s" in
+    MSYS*|MINGW*|CYGWIN*) return 0 ;;
+  esac
+  return 1
+}
+
+# Some environments reap detached/background processes. Auto-foreground when detected.
+if [[ -n "${CODEX_CI:-}" && "$FOREGROUND" != "true" && "$FORCE_BACKGROUND" != "true" ]]; then
+  FOREGROUND="true"
+fi
+
+# Windows/Git Bash reaps nohup background processes. Auto-foreground when detected.
+if [[ "$FOREGROUND" != "true" && "$FORCE_BACKGROUND" != "true" ]]; then
+  if is_windows_like_shell; then
+    FOREGROUND="true"
+  fi
+fi
+
+# Session files (server.log, server-info, .last-token) embed the session key —
+# keep everything this script and the server create owner-only.
+umask 077
+
+# Generate unique session directory
+SESSION_ID="$$-$(date +%s)"
+
+if [[ -n "$PROJECT_DIR" ]]; then
+  SESSION_DIR="${PROJECT_DIR}/.superpowers/brainstorm/${SESSION_ID}"
+  # Persist the bound port and key per project so a restart reuses them and an
+  # already-open browser tab reconnects to the same URL with a valid cookie.
+  export BRAINSTORM_PORT_FILE="${PROJECT_DIR}/.superpowers/brainstorm/.last-port"
+  export BRAINSTORM_TOKEN_FILE="${PROJECT_DIR}/.superpowers/brainstorm/.last-token"
+else
+  SESSION_DIR="/tmp/brainstorm-${SESSION_ID}"
+fi
+
+STATE_DIR="${SESSION_DIR}/state"
+PID_FILE="${STATE_DIR}/server.pid"
+LOG_FILE="${STATE_DIR}/server.log"
+SERVER_ID_FILE="${STATE_DIR}/server-instance-id"
+
+# Create fresh session directory with content and state peers
+mkdir -p "${SESSION_DIR}/content" "$STATE_DIR"
+
+SERVER_ID=""
+if [[ -r /dev/urandom ]]; then
+  SERVER_ID="$(od -An -N24 -tx1 /dev/urandom 2>/dev/null | tr -d ' \n' || true)"
+fi
+if ! [[ "$SERVER_ID" =~ ^[A-Za-z0-9_-]{32,64}$ ]]; then
+  SERVER_ID="$(printf '%08x%08x%08x%08x' "$$" "$(date +%s)" "${RANDOM:-0}" "${RANDOM:-0}")"
+fi
+printf '%s\n' "$SERVER_ID" > "$SERVER_ID_FILE"
+chmod 600 "$SERVER_ID_FILE" 2>/dev/null || true
+
+# Kill any existing server
+if [[ -f "$PID_FILE" ]]; then
+  old_pid=$(cat "$PID_FILE")
+  kill "$old_pid" 2>/dev/null
+  rm -f "$PID_FILE"
+fi
+
+cd "$SCRIPT_DIR" || exit 1
+
+# Resolve the harness PID (grandparent of this script).
+# $PPID is the ephemeral shell the harness spawned to run us — it dies
+# when this script exits. The harness itself is $PPID's parent.
+OWNER_PID="$(ps -o ppid= -p "$PPID" 2>/dev/null | tr -d ' ')"
+if [[ -z "$OWNER_PID" || "$OWNER_PID" == "1" ]]; then
+  OWNER_PID="$PPID"
+fi
+
+# Windows/MSYS2: Node.js cannot see POSIX PIDs from the MSYS2 namespace.
+# Passing a PID node cannot verify causes server to log owner-pid-invalid
+# and self-terminate at the 60-second lifecycle check. Clear it so the
+# watchdog is disabled and the idle timeout becomes the only shutdown trigger.
+if is_windows_like_shell; then
+  OWNER_PID=""
+fi
+
+# Foreground mode for environments that reap detached/background processes.
+if [[ "$FOREGROUND" == "true" ]]; then
+  env BRAINSTORM_DIR="$SESSION_DIR" BRAINSTORM_HOST="$BIND_HOST" BRAINSTORM_URL_HOST="$URL_HOST" BRAINSTORM_OWNER_PID="$OWNER_PID" node server.cjs "--brainstorm-server-id=$SERVER_ID" &
+  SERVER_PID=$!
+  echo "$SERVER_PID" > "$PID_FILE"
+  wait "$SERVER_PID"
+  exit $?
+fi
+
+# Start server, capturing output to log file
+# Use nohup to survive shell exit; disown to remove from job table
+nohup env BRAINSTORM_DIR="$SESSION_DIR" BRAINSTORM_HOST="$BIND_HOST" BRAINSTORM_URL_HOST="$URL_HOST" BRAINSTORM_OWNER_PID="$OWNER_PID" node server.cjs "--brainstorm-server-id=$SERVER_ID" > "$LOG_FILE" 2>&1 &
+SERVER_PID=$!
+disown "$SERVER_PID" 2>/dev/null
+echo "$SERVER_PID" > "$PID_FILE"
+
+# Wait for server-started message (check log file)
+for _ in {1..50}; do
+  if grep -q "server-started" "$LOG_FILE" 2>/dev/null; then
+    # Verify server is still alive after a short window (catches process reapers)
+    alive="true"
+    for _ in {1..20}; do
+      if ! kill -0 "$SERVER_PID" 2>/dev/null; then
+        alive="false"
+        break
+      fi
+      sleep 0.1
+    done
+    if [[ "$alive" != "true" ]]; then
+      echo "{\"error\": \"Server started but was killed. Retry in a persistent terminal with: $SCRIPT_DIR/start-server.sh${PROJECT_DIR:+ --project-dir $PROJECT_DIR} --host $BIND_HOST --url-host $URL_HOST --foreground\"}"
+      exit 1
+    fi
+    grep "server-started" "$LOG_FILE" | head -1
+    exit 0
+  fi
+  sleep 0.1
+done
+
+# Timeout - server didn't start
+echo '{"error": "Server failed to start within 5 seconds"}'
+exit 1

skills/brainstorming/scripts/stop-server.sh

@@ -0,0 +1,120 @@
+#!/usr/bin/env bash
+# Stop the brainstorm server and clean up
+# Usage: stop-server.sh <session_dir>
+#
+# Kills the server process. Only deletes session directory if it's
+# under /tmp (ephemeral). Persistent directories (.superpowers/) are
+# kept so mockups can be reviewed later.
+
+SESSION_DIR="$1"
+
+if [[ -z "$SESSION_DIR" ]]; then
+  echo '{"error": "Usage: stop-server.sh <session_dir>"}'
+  exit 1
+fi
+
+STATE_DIR="${SESSION_DIR}/state"
+PID_FILE="${STATE_DIR}/server.pid"
+SERVER_ID_FILE="${STATE_DIR}/server-instance-id"
+
+mark_stopped() {
+  local reason="$1"
+  rm -f "${STATE_DIR}/server-info"
+  printf '{"reason":"%s","timestamp":%s}\n' "$reason" "$(date +%s)" > "${STATE_DIR}/server-stopped"
+}
+
+read_expected_server_id() {
+  [[ -f "$SERVER_ID_FILE" ]] || return 1
+  local id
+  id="$(tr -d '\r\n' < "$SERVER_ID_FILE" 2>/dev/null || true)"
+  [[ "$id" =~ ^[A-Za-z0-9_-]{32,64}$ ]] || return 1
+  printf '%s\n' "$id"
+}
+
+command_line_for_pid() {
+  local pid="$1"
+  if [[ -r "/proc/$pid/cmdline" ]]; then
+    tr '\0' '\n' < "/proc/$pid/cmdline" 2>/dev/null || true
+    return 0
+  fi
+  ps -ww -p "$pid" -o command= 2>/dev/null || ps -f -p "$pid" 2>/dev/null | sed '1d' || true
+}
+
+command_has_server_id() {
+  local pid="$1"
+  local expected="$2"
+  local expected_arg="--brainstorm-server-id=$expected"
+  if [[ -r "/proc/$pid/cmdline" ]]; then
+    local arg
+    while IFS= read -r -d '' arg || [[ -n "$arg" ]]; do
+      [[ "$arg" == "$expected_arg" ]] && return 0
+    done < "/proc/$pid/cmdline"
+    return 1
+  fi
+  local command_line
+  command_line="$(command_line_for_pid "$pid")"
+  [[ -n "$command_line" ]] || return 1
+  case " $command_line " in
+    *" $expected_arg "*) return 0 ;;
+    *) return 1 ;;
+  esac
+}
+
+# Confirm a PID has this session's per-start instance id, not just a familiar
+# process name. Ambiguous or legacy metadata fails closed as stale_pid.
+is_brainstorm_server() {
+  kill -0 "$1" 2>/dev/null || return 1
+  local expected_id
+  expected_id="$(read_expected_server_id)" || return 1
+  command_has_server_id "$1" "$expected_id" || return 1
+  return 0
+}
+
+if [[ -f "$PID_FILE" ]]; then
+  pid=$(cat "$PID_FILE")
+
+  # Refuse to signal a PID we can't prove is our server. A stale pid file may
+  # point at an unrelated process after a reboot/PID wraparound.
+  if ! is_brainstorm_server "$pid"; then
+    rm -f "$PID_FILE" "$SERVER_ID_FILE"
+    mark_stopped "stale_pid"
+    echo '{"status": "stale_pid"}'
+    exit 0
+  fi
+
+  # Try to stop gracefully, fallback to force if still alive
+  kill "$pid" 2>/dev/null || true
+
+  # Wait for graceful shutdown (up to ~2s)
+  for _ in {1..20}; do
+    if ! kill -0 "$pid" 2>/dev/null; then
+      break
+    fi
+    sleep 0.1
+  done
+
+  # If still running, escalate to SIGKILL
+  if kill -0 "$pid" 2>/dev/null; then
+    kill -9 "$pid" 2>/dev/null || true
+
+    # Give SIGKILL a moment to take effect
+    sleep 0.1
+  fi
+
+  if kill -0 "$pid" 2>/dev/null; then
+    echo '{"status": "failed", "error": "process still running"}'
+    exit 1
+  fi
+
+  rm -f "$PID_FILE" "$SERVER_ID_FILE" "${STATE_DIR}/server.log"
+  mark_stopped "stop-server.sh"
+
+  # Only delete ephemeral /tmp directories
+  if [[ "$SESSION_DIR" == /tmp/* ]]; then
+    rm -rf "$SESSION_DIR"
+  fi
+
+  echo '{"status": "stopped"}'
+else
+  echo '{"status": "not_running"}'
+fi

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

@@ -0,0 +1,49 @@
+# Spec Document Reviewer Prompt Template
+
+Use this template when dispatching a spec document reviewer subagent.
+
+**Purpose:** Verify the spec is complete, consistent, and ready for implementation planning.
+
+**Dispatch after:** Spec document is written to docs/superpowers/specs/
+
+```
+Subagent (general-purpose):
+  description: "Review spec document"
+  prompt: |
+    You are a spec document reviewer. Verify this spec is complete and ready for planning.
+
+    **Spec to review:** [SPEC_FILE_PATH]
+
+    ## What to Check
+
+    | Category | What to Look For |
+    |----------|------------------|
+    | Completeness | TODOs, placeholders, "TBD", incomplete sections |
+    | Consistency | Internal contradictions, conflicting requirements |
+    | Clarity | Requirements ambiguous enough to cause someone to build the wrong thing |
+    | Scope | Focused enough for a single plan — not covering multiple independent subsystems |
+    | YAGNI | Unrequested features, over-engineering |
+
+    ## Calibration
+
+    **Only flag issues that would cause real problems during implementation planning.**
+    A missing section, a contradiction, or a requirement so ambiguous it could be
+    interpreted two different ways — those are issues. Minor wording improvements,
+    stylistic preferences, and "sections less detailed than others" are not.
+
+    Approve unless there are serious gaps that would lead to a flawed plan.
+
+    ## Output Format
+
+    ## Spec Review
+
+    **Status:** Approved | Issues Found
+
+    **Issues (if any):**
+    - [Section X]: [specific issue] - [why it matters for planning]
+
+    **Recommendations (advisory, do not block approval):**
+    - [suggestions for improvement]
+```
+
+**Reviewer returns:** Status, Issues (if any), Recommendations

skills/brainstorming/visual-companion.md

@@ -0,0 +1,298 @@
+# Visual Companion Guide
+
+Browser-based visual brainstorming companion for showing mockups, diagrams, and options.
+
+## When to Use
+
+Decide per-question, not per-session. The test: **would the user understand this better by seeing it than reading it?**
+
+**Use the browser** when the content itself is visual:
+
+- **UI mockups** — wireframes, layouts, navigation structures, component designs
+- **Architecture diagrams** — system components, data flow, relationship maps
+- **Side-by-side visual comparisons** — comparing two layouts, two color schemes, two design directions
+- **Design polish** — when the question is about look and feel, spacing, visual hierarchy
+- **Spatial relationships** — state machines, flowcharts, entity relationships rendered as diagrams
+
+**Use the terminal** when the content is text or tabular:
+
+- **Requirements and scope questions** — "what does X mean?", "which features are in scope?"
+- **Conceptual A/B/C choices** — picking between approaches described in words
+- **Tradeoff lists** — pros/cons, comparison tables
+- **Technical decisions** — API design, data modeling, architectural approach selection
+- **Clarifying questions** — anything where the answer is words, not a visual preference
+
+A question *about* a UI topic is not automatically a visual question. "What kind of wizard do you want?" is conceptual — use the terminal. "Which of these wizard layouts feels right?" is visual — use the browser.
+
+## How It Works
+
+The server watches a directory for HTML files and serves the newest one to the browser. You write HTML content to `screen_dir`, the user sees it in their browser and can click to select options. Selections are recorded to `state_dir/events` that you read on your next turn.
+
+**Content fragments vs full documents:** If your HTML file starts with `<!DOCTYPE` or `<html`, the server serves it as-is (just injects the helper script). Otherwise, the server automatically wraps your content in the frame template — adding the header, CSS theme, connection status, and all interactive infrastructure. **Write content fragments by default.** Only write full documents when you need complete control over the page.
+
+## Starting a Session
+
+```bash
+# Start AFTER the user approves the companion. --open auto-opens their browser on
+# the first screen; --project-dir persists mockups and enables same-port restart.
+scripts/start-server.sh --project-dir /path/to/project --open
+
+# Returns: {"type":"server-started","port":52341,
+#           "url":"http://localhost:52341/?key=ab12…",
+#           "screen_dir":"/path/to/project/.superpowers/brainstorm/12345-1706000000/content",
+#           "state_dir":"/path/to/project/.superpowers/brainstorm/12345-1706000000/state"}
+```
+
+Save `screen_dir` and `state_dir` from the response. With `--open`, the browser opens itself when you push the first screen — you don't need to ask the user to open it, but still share the URL as a fallback (headless/remote setups won't auto-open).
+
+**The URL contains a session key (`?key=…`).** The server rejects any request
+without it, so always give the user the **complete** URL from the `url` field —
+never strip the query string, and never hand out a bare `http://host:port`. The
+key gates HTTP and WebSocket access so a stray browser tab or another machine on
+the network can't read the screens or inject events. After the first load the
+browser remembers the key via a cookie, so reloads and `/files/*` assets work
+without repeating it.
+
+**Finding connection info:** The server writes its startup JSON to `$STATE_DIR/server-info`. If you launched the server in the background and didn't capture stdout, read that file to get the URL and port. When using `--project-dir`, check `<project>/.superpowers/brainstorm/` for the session directory.
+
+**Note:** Pass the project root as `--project-dir` so mockups persist in `.superpowers/brainstorm/` and survive server restarts. Without it, files go to `/tmp` and get cleaned up. Remind the user to add `.superpowers/` to `.gitignore` if it's not already there.
+
+**Launching the server by platform:**
+
+**Claude Code:**
+```bash
+# Default mode works — the script backgrounds the server itself.
+scripts/start-server.sh --project-dir /path/to/project --open
+```
+
+On Windows, the script auto-detects and switches to foreground mode (which blocks the tool call). Use `run_in_background: true` on the Bash tool call so the server survives across conversation turns, then read `$STATE_DIR/server-info` on the next turn to get the URL and port.
+
+**Codex:**
+```bash
+# Codex reaps background processes. The script auto-detects CODEX_CI and
+# switches to foreground mode. Run it normally — no extra flags needed.
+scripts/start-server.sh --project-dir /path/to/project --open
+```
+
+**Gemini CLI:**
+```bash
+# Use --foreground and set is_background: true on your shell tool call
+# so the process survives across turns
+scripts/start-server.sh --project-dir /path/to/project --open --foreground
+```
+
+**Copilot CLI:**
+```bash
+# Use --foreground and start the server via the bash tool with mode: "async"
+# so the process survives across turns. Capture the returned shellId for
+# read_bash / stop_bash if you need to interact with it later.
+scripts/start-server.sh --project-dir /path/to/project --open --foreground
+```
+
+**Other environments:** The server must keep running in the background across conversation turns. If your environment reaps detached processes, use `--foreground` and launch the command with your platform's background execution mechanism.
+
+If the URL is unreachable from your browser (common in remote/containerized setups), bind a non-loopback host:
+
+```bash
+scripts/start-server.sh \
+  --project-dir /path/to/project \
+  --host 0.0.0.0 \
+  --url-host localhost
+```
+
+Use `--url-host` to control what hostname is printed in the returned URL JSON.
+
+## The Loop
+
+1. **Check server is alive**, then **write HTML** to a new file in `screen_dir`:
+   - **Required: confirm the server is alive before referring to the URL or pushing a screen.** Check that `$STATE_DIR/server-info` exists and `$STATE_DIR/server-stopped` does not. If it has shut down, restart it with `start-server.sh` using the **same `--project-dir`** — it reuses the same port, so the user's open tab reconnects on its own (it shows a "paused" overlay while the server is down) and you don't need to send a new URL. The server auto-exits after 4 hours idle (configurable with `--idle-timeout-minutes`).
+   - Use semantic filenames: `platform.html`, `visual-style.html`, `layout.html`
+   - **Never reuse filenames** — each screen gets a fresh file
+   - Use your file-creation tool — **never use cat/heredoc** (dumps noise into terminal)
+   - Server automatically serves the newest file
+
+2. **Tell user what to expect and end your turn:**
+   - Remind them of the URL (every step, not just first)
+   - Give a brief text summary of what's on screen (e.g., "Showing 3 layout options for the homepage")
+   - Ask them to respond in the terminal: "Take a look and let me know what you think. Click to select an option if you'd like."
+
+3. **On your next turn** — after the user responds in the terminal:
+   - Read `$STATE_DIR/events` if it exists — this contains the user's browser interactions (clicks, selections) as JSON lines
+   - Merge with the user's terminal text to get the full picture
+   - The terminal message is the primary feedback; `state_dir/events` provides structured interaction data
+
+4. **Iterate or advance** — if feedback changes current screen, write a new file (e.g., `layout-v2.html`). Only move to the next question when the current step is validated.
+
+5. **Unload when returning to terminal** — when the next step doesn't need the browser (e.g., a clarifying question, a tradeoff discussion), push a waiting screen to clear the stale content:
+
+   ```html
+   <!-- filename: waiting.html (or waiting-2.html, etc.) -->
+   <div style="display:flex;align-items:center;justify-content:center;min-height:60vh">
+     <p class="subtitle">Continuing in terminal...</p>
+   </div>
+   ```
+
+   This prevents the user from staring at a resolved choice while the conversation has moved on. When the next visual question comes up, push a new content file as usual.
+
+6. Repeat until done.
+
+## Writing Content Fragments
+
+Write just the content that goes inside the page. The server wraps it in the frame template automatically (header, theme CSS, connection status, and all interactive infrastructure).
+
+**Minimal example:**
+
+```html
+<h2>Which layout works better?</h2>
+<p class="subtitle">Consider readability and visual hierarchy</p>
+
+<div class="options">
+  <div class="option" data-choice="a" onclick="toggleSelect(this)">
+    <div class="letter">A</div>
+    <div class="content">
+      <h3>Single Column</h3>
+      <p>Clean, focused reading experience</p>
+    </div>
+  </div>
+  <div class="option" data-choice="b" onclick="toggleSelect(this)">
+    <div class="letter">B</div>
+    <div class="content">
+      <h3>Two Column</h3>
+      <p>Sidebar navigation with main content</p>
+    </div>
+  </div>
+</div>
+```
+
+That's it. No `<html>`, no CSS, no `<script>` tags needed. The server provides all of that.
+
+## CSS Classes Available
+
+The frame template provides these CSS classes for your content:
+
+### Options (A/B/C choices)
+
+```html
+<div class="options">
+  <div class="option" data-choice="a" onclick="toggleSelect(this)">
+    <div class="letter">A</div>
+    <div class="content">
+      <h3>Title</h3>
+      <p>Description</p>
+    </div>
+  </div>
+</div>
+```
+
+**Multi-select:** Add `data-multiselect` to the container to let users select multiple options. Each click toggles the item's selected styling.
+
+```html
+<div class="options" data-multiselect>
+  <!-- same option markup — users can select/deselect multiple -->
+</div>
+```
+
+### Cards (visual designs)
+
+```html
+<div class="cards">
+  <div class="card" data-choice="design1" onclick="toggleSelect(this)">
+    <div class="card-image"><!-- mockup content --></div>
+    <div class="card-body">
+      <h3>Name</h3>
+      <p>Description</p>
+    </div>
+  </div>
+</div>
+```
+
+### Mockup container
+
+```html
+<div class="mockup">
+  <div class="mockup-header">Preview: Dashboard Layout</div>
+  <div class="mockup-body"><!-- your mockup HTML --></div>
+</div>
+```
+
+### Split view (side-by-side)
+
+```html
+<div class="split">
+  <div class="mockup"><!-- left --></div>
+  <div class="mockup"><!-- right --></div>
+</div>
+```
+
+### Pros/Cons
+
+```html
+<div class="pros-cons">
+  <div class="pros"><h4>Pros</h4><ul><li>Benefit</li></ul></div>
+  <div class="cons"><h4>Cons</h4><ul><li>Drawback</li></ul></div>
+</div>
+```
+
+### Mock elements (wireframe building blocks)
+
+```html
+<div class="mock-nav">Logo | Home | About | Contact</div>
+<div style="display: flex;">
+  <div class="mock-sidebar">Navigation</div>
+  <div class="mock-content">Main content area</div>
+</div>
+<button class="mock-button">Action Button</button>
+<input class="mock-input" placeholder="Input field">
+<div class="placeholder">Placeholder area</div>
+```
+
+### Typography and sections
+
+- `h2` — page title
+- `h3` — section heading
+- `.subtitle` — secondary text below title
+- `.section` — content block with bottom margin
+- `.label` — small uppercase label text
+
+## Browser Events Format
+
+When the user clicks options in the browser, their interactions are recorded to `$STATE_DIR/events` (one JSON object per line). The file is cleared automatically when you push a new screen.
+
+```jsonl
+{"type":"click","choice":"a","text":"Option A - Simple Layout","timestamp":1706000101}
+{"type":"click","choice":"c","text":"Option C - Complex Grid","timestamp":1706000108}
+{"type":"click","choice":"b","text":"Option B - Hybrid","timestamp":1706000115}
+```
+
+The full event stream shows the user's exploration path — they may click multiple options before settling. The last `choice` event is typically the final selection, but the pattern of clicks can reveal hesitation or preferences worth asking about.
+
+If `$STATE_DIR/events` doesn't exist, the user didn't interact with the browser — use only their terminal text.
+
+## Design Tips
+
+- **Scale fidelity to the question** — wireframes for layout, polish for polish questions
+- **Explain the question on each page** — "Which layout feels more professional?" not just "Pick one"
+- **Iterate before advancing** — if feedback changes current screen, write a new version
+- **2-4 options max** per screen
+- **Use real content when it matters** — for a photography portfolio, use actual images (Unsplash). Placeholder content obscures design issues.
+- **Keep mockups simple** — focus on layout and structure, not pixel-perfect design
+
+## File Naming
+
+- Use semantic names: `platform.html`, `visual-style.html`, `layout.html`
+- Never reuse filenames — each screen must be a new file
+- For iterations: append version suffix like `layout-v2.html`, `layout-v3.html`
+- Server serves newest file by modification time
+
+## Cleaning Up
+
+```bash
+scripts/stop-server.sh $SESSION_DIR
+```
+
+If the session used `--project-dir`, mockup files persist in `.superpowers/brainstorm/` for later reference. Only `/tmp` sessions get deleted on stop.
+
+## Reference
+
+- Frame template (CSS reference): `scripts/frame-template.html`
+- Helper script (client-side): `scripts/helper.js`

skills/dispatching-parallel-agents/SKILL.md

@@ -7,6 +7,8 @@ description: Use when facing 2+ independent tasks that can be worked on without
 
 ## Overview
 
+You delegate tasks to specialized agents with isolated context. By precisely crafting their instructions and context, you ensure they stay focused and succeed at their task. They should never inherit your session's context or history — you construct exactly what they need. This also preserves your own context for coordination work.
+
 When you have multiple unrelated failures (different test files, different subsystems, different bugs), investigating them sequentially wastes time. Each investigation is independent and can happen in parallel.
 
 **Core principle:** Dispatch one agent per independent problem domain. Let them work concurrently.
@@ -63,14 +65,17 @@ Each agent gets:
 
 ### 3. Dispatch in Parallel
 
-```typescript
-// In Claude Code / AI environment
-Task("Fix agent-tool-abort.test.ts failures")
-Task("Fix batch-completion-behavior.test.ts failures")
-Task("Fix tool-approval-race-conditions.test.ts failures")
-// All three run concurrently
+Issue all three subagent dispatches in the same response — they run in parallel:
+
+```text
+Subagent (general-purpose): "Fix agent-tool-abort.test.ts failures"
+Subagent (general-purpose): "Fix batch-completion-behavior.test.ts failures"
+Subagent (general-purpose): "Fix tool-approval-race-conditions.test.ts failures"
+# All three run concurrently.
 ```
 
+Multiple dispatch calls in one response = parallel execution. One per response = sequential.
+
 ### 4. Review and Integrate
 
 When agents return:

skills/executing-plans/SKILL.md

@@ -7,22 +7,21 @@ description: Use when you have a written implementation plan to execute in a sep
 
 ## Overview
 
-Load plan, review critically, execute tasks in batches, report for review between batches.
-
-**Core principle:** Batch execution with checkpoints for architect review.
+Load plan, review critically, execute all tasks, report when complete.
 
 **Announce at start:** "I'm using the executing-plans skill to implement this plan."
 
+**Note:** Tell your human partner that Superpowers works much better with access to subagents. The quality of its work will be significantly higher if run on a platform with subagent support (Claude Code, Codex CLI, Codex App, Copilot CLI, and Gemini CLI all qualify; see the per-platform tool refs in `../using-superpowers/references/`). If subagents are available, use superpowers:subagent-driven-development instead of this skill.
+
 ## The Process
 
 ### Step 1: Load and Review Plan
 1. Read plan file
 2. Review critically - identify any questions or concerns about the plan
 3. If concerns: Raise them with your human partner before starting
-4. If no concerns: Create TodoWrite and proceed
+4. If no concerns: Create todos for the plan items and proceed
 
-### Step 2: Execute Batch
-**Default: First 3 tasks**
+### Step 2: Execute Tasks
 
 For each task:
 1. Mark as in_progress
@@ -30,19 +29,7 @@ For each task:
 3. Run verifications as specified
 4. Mark as completed
 
-### Step 3: Report
-When batch complete:
-- Show what was implemented
-- Show verification output
-- Say: "Ready for feedback."
-
-### Step 4: Continue
-Based on feedback:
-- Apply changes if needed
-- Execute next batch
-- Repeat until complete
-
-### Step 5: Complete Development
+### Step 3: Complete Development
 
 After all tasks complete and verified:
 - Announce: "I'm using the finishing-a-development-branch skill to complete this work."
@@ -52,7 +39,7 @@ After all tasks complete and verified:
 ## When to Stop and Ask for Help
 
 **STOP executing immediately when:**
-- Hit a blocker mid-batch (missing dependency, test fails, instruction unclear)
+- Hit a blocker (missing dependency, test fails, instruction unclear)
 - Plan has critical gaps preventing starting
 - You don't understand an instruction
 - Verification fails repeatedly
@@ -72,5 +59,12 @@ After all tasks complete and verified:
 - Follow plan steps exactly
 - Don't skip verifications
 - Reference skills when plan says to
-- Between batches: just report and wait
 - Stop when blocked, don't guess
+- Never start implementation on main/master branch without explicit user consent
+
+## Integration
+
+**Required workflow skills:**
+- **superpowers:using-git-worktrees** - Ensures isolated workspace (creates one or verifies existing)
+- **superpowers:writing-plans** - Creates the plan this skill executes
+- **superpowers:finishing-a-development-branch** - Complete development after all tasks

skills/finishing-a-development-branch/SKILL.md

@@ -9,7 +9,7 @@ description: Use when implementation is complete, all tests pass, and you need t
 
 Guide completion of development work by presenting clear options and handling chosen workflow.
 
-**Core principle:** Verify tests → Present options → Execute choice → Clean up.
+**Core principle:** Verify tests → Detect environment → Present options → Execute choice → Clean up.
 
 **Announce at start:** "I'm using the finishing-a-development-branch skill to complete this work."
 
@@ -37,7 +37,24 @@ Stop. Don't proceed to Step 2.
 
 **If tests pass:** Continue to Step 2.
 
-### Step 2: Determine Base Branch
+### Step 2: Detect Environment
+
+**Determine workspace state before presenting options:**
+
+```bash
+GIT_DIR=$(cd "$(git rev-parse --git-dir)" 2>/dev/null && pwd -P)
+GIT_COMMON=$(cd "$(git rev-parse --git-common-dir)" 2>/dev/null && pwd -P)
+```
+
+This determines which menu to show and how cleanup works:
+
+| State | Menu | Cleanup |
+|-------|------|---------|
+| `GIT_DIR == GIT_COMMON` (normal repo) | Standard 4 options | No worktree to clean up |
+| `GIT_DIR != GIT_COMMON`, named branch | Standard 4 options | Provenance-based (see Step 6) |
+| `GIT_DIR != GIT_COMMON`, detached HEAD | Reduced 3 options (no merge) | No cleanup (externally managed) |
+
+### Step 3: Determine Base Branch
 
 ```bash
 # Try common base branches
@@ -46,9 +63,9 @@ git merge-base HEAD main 2>/dev/null || git merge-base HEAD master 2>/dev/null
 
 Or ask: "This branch split from main - is that correct?"
 
-### Step 3: Present Options
+### Step 4: Present Options
 
-Present exactly these 4 options:
+**Normal repo and named-branch worktree — present exactly these 4 options:**
 
 ```
 Implementation complete. What would you like to do?
@@ -61,49 +78,54 @@ Implementation complete. What would you like to do?
 Which option?
 ```
 
+**Detached HEAD — present exactly these 3 options:**
+
+```
+Implementation complete. You're on a detached HEAD (externally managed workspace).
+
+1. Push as new branch and create a Pull Request
+2. Keep as-is (I'll handle it later)
+3. Discard this work
+
+Which option?
+```
+
 **Don't add explanation** - keep options concise.
 
-### Step 4: Execute Choice
+### Step 5: Execute Choice
 
 #### Option 1: Merge Locally
 
 ```bash
-# Switch to base branch
+# Get main repo root for CWD safety
+MAIN_ROOT=$(git -C "$(git rev-parse --git-common-dir)/.." rev-parse --show-toplevel)
+cd "$MAIN_ROOT"
+
+# Merge first — verify success before removing anything
 git checkout <base-branch>
-
-# Pull latest
 git pull
-
-# Merge feature branch
 git merge <feature-branch>
 
 # Verify tests on merged result
 <test command>
 
-# If tests pass
-git branch -d <feature-branch>
+# Only after merge succeeds: cleanup worktree (Step 6), then delete branch
 ```
 
-Then: Cleanup worktree (Step 5)
+Then: Cleanup worktree (Step 6), then delete branch:
+
+```bash
+git branch -d <feature-branch>
+```
 
 #### Option 2: Push and Create PR
 
 ```bash
 # Push branch
 git push -u origin <feature-branch>
-
-# Create PR
-gh pr create --title "<title>" --body "$(cat <<'EOF'
-## Summary
-<2-3 bullets of what changed>
-
-## Test Plan
-- [ ] <verification steps>
-EOF
-)"
 ```
 
-Then: Cleanup worktree (Step 5)
+**Do NOT clean up worktree** — user needs it alive to iterate on PR feedback.
 
 #### Option 3: Keep As-Is
 
@@ -127,36 +149,46 @@ Wait for exact confirmation.
 
 If confirmed:
 ```bash
-git checkout <base-branch>
+MAIN_ROOT=$(git -C "$(git rev-parse --git-common-dir)/.." rev-parse --show-toplevel)
+cd "$MAIN_ROOT"
+```
+
+Then: Cleanup worktree (Step 6), then force-delete branch:
+```bash
 git branch -D <feature-branch>
 ```
 
-Then: Cleanup worktree (Step 5)
+### Step 6: Cleanup Workspace
 
-### Step 5: Cleanup Worktree
+**Only runs for Options 1 and 4.** Options 2 and 3 always preserve the worktree.
 
-**For Options 1, 2, 4:**
-
-Check if in worktree:
 ```bash
-git worktree list | grep $(git branch --show-current)
+GIT_DIR=$(cd "$(git rev-parse --git-dir)" 2>/dev/null && pwd -P)
+GIT_COMMON=$(cd "$(git rev-parse --git-common-dir)" 2>/dev/null && pwd -P)
+WORKTREE_PATH=$(git rev-parse --show-toplevel)
 ```
 
-If yes:
+**If `GIT_DIR == GIT_COMMON`:** Normal repo, no worktree to clean up. Done.
+
+**If worktree path is under `.worktrees/` or `worktrees/`:** Superpowers created this worktree — we own cleanup.
+
 ```bash
-git worktree remove <worktree-path>
+MAIN_ROOT=$(git -C "$(git rev-parse --git-common-dir)/.." rev-parse --show-toplevel)
+cd "$MAIN_ROOT"
+git worktree remove "$WORKTREE_PATH"
+git worktree prune  # Self-healing: clean up any stale registrations
 ```
 
-**For Option 3:** Keep worktree.
+**Otherwise:** The host environment (harness) owns this workspace. Do NOT remove it. If your platform provides a workspace-exit tool, use it. Otherwise, leave the workspace in place.
 
 ## Quick Reference
 
 | Option | Merge | Push | Keep Worktree | Cleanup Branch |
 |--------|-------|------|---------------|----------------|
-| 1. Merge locally | ✓ | - | - | ✓ |
-| 2. Create PR | - | ✓ | ✓ | - |
-| 3. Keep as-is | - | - | ✓ | - |
-| 4. Discard | - | - | - | ✓ (force) |
+| 1. Merge locally | yes | - | - | yes |
+| 2. Create PR | - | yes | yes | - |
+| 3. Keep as-is | - | - | yes | - |
+| 4. Discard | - | - | - | yes (force) |
 
 ## Common Mistakes
 
@@ -165,13 +197,25 @@ git worktree remove <worktree-path>
 - **Fix:** Always verify tests before offering options
 
 **Open-ended questions**
-- **Problem:** "What should I do next?" → ambiguous
-- **Fix:** Present exactly 4 structured options
+- **Problem:** "What should I do next?" is ambiguous
+- **Fix:** Present exactly 4 structured options (or 3 for detached HEAD)
 
-**Automatic worktree cleanup**
-- **Problem:** Remove worktree when might need it (Option 2, 3)
+**Cleaning up worktree for Option 2**
+- **Problem:** Remove worktree user needs for PR iteration
 - **Fix:** Only cleanup for Options 1 and 4
 
+**Deleting branch before removing worktree**
+- **Problem:** `git branch -d` fails because worktree still references the branch
+- **Fix:** Merge first, remove worktree, then delete branch
+
+**Running git worktree remove from inside the worktree**
+- **Problem:** Command fails silently when CWD is inside the worktree being removed
+- **Fix:** Always `cd` to main repo root before `git worktree remove`
+
+**Cleaning up harness-owned worktrees**
+- **Problem:** Removing a worktree the harness created causes phantom state
+- **Fix:** Only clean up worktrees under `.worktrees/` or `worktrees/`
+
 **No confirmation for discard**
 - **Problem:** Accidentally delete work
 - **Fix:** Require typed "discard" confirmation
@@ -183,18 +227,15 @@ git worktree remove <worktree-path>
 - Merge without verifying tests on result
 - Delete work without confirmation
 - Force-push without explicit request
+- Remove a worktree before confirming merge success
+- Clean up worktrees you didn't create (provenance check)
+- Run `git worktree remove` from inside the worktree
 
 **Always:**
 - Verify tests before offering options
-- Present exactly 4 options
+- Detect environment before presenting menu
+- Present exactly 4 options (or 3 for detached HEAD)
 - Get typed confirmation for Option 4
 - Clean up worktree for Options 1 & 4 only
-
-## Integration
-
-**Called by:**
-- **subagent-driven-development** (Step 7) - After all tasks complete
-- **executing-plans** (Step 5) - After all batches complete
-
-**Pairs with:**
-- **using-git-worktrees** - Cleans up worktree created by that skill
+- `cd` to main repo root before worktree removal
+- Run `git worktree prune` after removal

skills/receiving-code-review/SKILL.md

@@ -27,7 +27,7 @@ WHEN receiving code review feedback:
 ## Forbidden Responses
 
 **NEVER:**
-- "You're absolutely right!" (explicit CLAUDE.md violation)
+- "You're absolutely right!" (explicit instruction-file violation)
 - "Great point!" / "Excellent feedback!" (performative)
 - "Let me implement that now" (before verification)
 
@@ -126,7 +126,7 @@ Push back when:
 - Reference working tests/code
 - Involve your human partner if architectural
 
-**Signal if uncomfortable pushing back out loud:** "Strange things are afoot at the Circle K"
+**If you're uncomfortable pushing back out loud:** Name that tension, then tell your partner about the issue you've seen. They'll appreciate your honesty.
 
 ## Acknowledging Correct Feedback
 
@@ -200,6 +200,10 @@ You understand 1,2,3,6. Unclear on 4,5.
 ✅ "Understand 1,2,3,6. Need clarification on 4 and 5 before implementing."
 ```
 
+## GitHub Thread Replies
+
+When replying to inline review comments on GitHub, reply in the comment thread (`gh api repos/{owner}/{repo}/pulls/{pr}/comments/{id}/replies`), not as a top-level PR comment.
+
 ## The Bottom Line
 
 **External feedback = suggestions to evaluate, not orders to follow.**

skills/requesting-code-review/SKILL.md

@@ -5,7 +5,7 @@ description: Use when completing tasks, implementing major features, or before m
 
 # Requesting Code Review
 
-Dispatch superpowers:code-reviewer subagent to catch issues before they cascade.
+Dispatch a code reviewer subagent to catch issues before they cascade. The reviewer gets precisely crafted context for evaluation — never your session's history. This keeps the reviewer focused on the work product, not your thought process, and preserves your own context for continued work.
 
 **Core principle:** Review early, review often.
 
@@ -29,16 +29,15 @@ BASE_SHA=$(git rev-parse HEAD~1)  # or origin/main
 HEAD_SHA=$(git rev-parse HEAD)
 ```
 
-**2. Dispatch code-reviewer subagent:**
+**2. Dispatch code reviewer subagent:**
 
-Use Task tool with superpowers:code-reviewer type, fill template at `code-reviewer.md`
+Dispatch a `general-purpose` subagent, filling the template at [code-reviewer.md](code-reviewer.md)
 
 **Placeholders:**
-- `{WHAT_WAS_IMPLEMENTED}` - What you just built
+- `{DESCRIPTION}` - Brief summary of what you built
 - `{PLAN_OR_REQUIREMENTS}` - What it should do
 - `{BASE_SHA}` - Starting commit
 - `{HEAD_SHA}` - Ending commit
-- `{DESCRIPTION}` - Brief summary
 
 **3. Act on feedback:**
 - Fix Critical issues immediately
@@ -56,12 +55,11 @@ You: Let me request code review before proceeding.
 BASE_SHA=$(git log --oneline | grep "Task 1" | head -1 | awk '{print $1}')
 HEAD_SHA=$(git rev-parse HEAD)
 
-[Dispatch superpowers:code-reviewer subagent]
-  WHAT_WAS_IMPLEMENTED: Verification and repair functions for conversation index
-  PLAN_OR_REQUIREMENTS: Task 2 from docs/plans/deployment-plan.md
+[Dispatch code reviewer subagent]
+  DESCRIPTION: Added verifyIndex() and repairIndex() with 4 issue types
+  PLAN_OR_REQUIREMENTS: Task 2 from docs/superpowers/plans/deployment-plan.md
   BASE_SHA: a7981ec
   HEAD_SHA: 3df7661
-  DESCRIPTION: Added verifyIndex() and repairIndex() with 4 issue types
 
 [Subagent returns]:
   Strengths: Clean architecture, real tests
@@ -82,7 +80,7 @@ You: [Fix progress indicators]
 - Fix before moving to next task
 
 **Executing Plans:**
-- Review after each batch (3 tasks)
+- Review after each task or at natural checkpoints
 - Get feedback, apply, continue
 
 **Ad-Hoc Development:**
@@ -102,4 +100,4 @@ You: [Fix progress indicators]
 - Show code/tests that prove it works
 - Request clarification
 
-See template at: requesting-code-review/code-reviewer.md
+See template at: [code-reviewer.md](code-reviewer.md)

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

@@ -1,111 +1,137 @@
-# Code Review Agent
+# Code Reviewer Prompt Template
 
-You are reviewing code changes for production readiness.
+Use this template when dispatching a code reviewer subagent.
 
-**Your task:**
-1. Review {WHAT_WAS_IMPLEMENTED}
-2. Compare against {PLAN_OR_REQUIREMENTS}
-3. Check code quality, architecture, testing
-4. Categorize issues by severity
-5. Assess production readiness
+**Purpose:** Review completed work against requirements and code quality standards before it cascades into more work.
 
-## What Was Implemented
+```
+Subagent (general-purpose):
+  description: "Review code changes"
+  prompt: |
+    You are a Senior Code Reviewer with expertise in software architecture,
+    design patterns, and best practices. Your job is to review completed work
+    against its plan or requirements and identify issues before they cascade.
 
-{DESCRIPTION}
+    ## What Was Implemented
 
-## Requirements/Plan
+    [DESCRIPTION]
 
-{PLAN_REFERENCE}
+    ## Requirements / Plan
 
-## Git Range to Review
+    [PLAN_OR_REQUIREMENTS]
 
-**Base:** {BASE_SHA}
-**Head:** {HEAD_SHA}
+    ## Git Range to Review
 
-```bash
-git diff --stat {BASE_SHA}..{HEAD_SHA}
-git diff {BASE_SHA}..{HEAD_SHA}
+    **Base:** [BASE_SHA]
+    **Head:** [HEAD_SHA]
+
+    ```bash
+    git diff --stat [BASE_SHA]..[HEAD_SHA]
+    git diff [BASE_SHA]..[HEAD_SHA]
+    ```
+
+    ## Read-Only Review
+
+    Your review is read-only on this checkout. Do not mutate the working tree, the index, HEAD, or branch state in any way. Use tools like `git show`, `git diff`, and `git log` to inspect history. If you need a working copy of a different revision, check it out into a separate temporary directory (e.g. `git worktree add /tmp/review-[SHA] [SHA]`) — never move HEAD on this checkout.
+
+    ## What to Check
+
+    **Plan alignment:**
+    - Does the implementation match the plan / requirements?
+    - Are deviations justified improvements, or problematic departures?
+    - Is all planned functionality present?
+
+    **Code quality:**
+    - Clean separation of concerns?
+    - Proper error handling?
+    - Type safety where applicable?
+    - DRY without premature abstraction?
+    - Edge cases handled?
+
+    **Architecture:**
+    - Sound design decisions?
+    - Reasonable scalability and performance?
+    - Security concerns?
+    - Integrates cleanly with surrounding code?
+
+    **Testing:**
+    - Tests verify real behavior, not mocks?
+    - Edge cases covered?
+    - Integration tests where they matter?
+    - All tests passing?
+
+    **Production readiness:**
+    - Migration strategy if schema changed?
+    - Backward compatibility considered?
+    - Documentation complete?
+    - No obvious bugs?
+
+    ## Calibration
+
+    Categorize issues by actual severity. Not everything is Critical.
+    Acknowledge what was done well before listing issues — accurate praise
+    helps the implementer trust the rest of the feedback.
+
+    If you find significant deviations from the plan, flag them specifically
+    so the implementer can confirm whether the deviation was intentional.
+    If you find issues with the plan itself rather than the implementation,
+    say so.
+
+    ## Output Format
+
+    ### Strengths
+    [What's well done? Be specific.]
+
+    ### Issues
+
+    #### Critical (Must Fix)
+    [Bugs, security issues, data loss risks, broken functionality]
+
+    #### Important (Should Fix)
+    [Architecture problems, missing features, poor error handling, test gaps]
+
+    #### Minor (Nice to Have)
+    [Code style, optimization opportunities, documentation polish]
+
+    For each issue:
+    - File:line reference
+    - What's wrong
+    - Why it matters
+    - How to fix (if not obvious)
+
+    ### Recommendations
+    [Improvements for code quality, architecture, or process]
+
+    ### Assessment
+
+    **Ready to merge?** [Yes | No | With fixes]
+
+    **Reasoning:** [1-2 sentence technical assessment]
+
+    ## Critical Rules
+
+    **DO:**
+    - Categorize by actual severity
+    - Be specific (file:line, not vague)
+    - Explain WHY each issue matters
+    - Acknowledge strengths
+    - Give a clear verdict
+
+    **DON'T:**
+    - Say "looks good" without checking
+    - Mark nitpicks as Critical
+    - Give feedback on code you didn't actually read
+    - Be vague ("improve error handling")
+    - Avoid giving a clear verdict
 ```
 
-## Review Checklist
+**Placeholders:**
+- `[DESCRIPTION]` — brief summary of what was built
+- `[PLAN_OR_REQUIREMENTS]` — what it should do (plan file path, task text, or requirements)
+- `[BASE_SHA]` — starting commit
+- `[HEAD_SHA]` — ending commit
 
-**Code Quality:**
-- Clean separation of concerns?
-- Proper error handling?
-- Type safety (if applicable)?
-- DRY principle followed?
-- Edge cases handled?
-
-**Architecture:**
-- Sound design decisions?
-- Scalability considerations?
-- Performance implications?
-- Security concerns?
-
-**Testing:**
-- Tests actually test logic (not mocks)?
-- Edge cases covered?
-- Integration tests where needed?
-- All tests passing?
-
-**Requirements:**
-- All plan requirements met?
-- Implementation matches spec?
-- No scope creep?
-- Breaking changes documented?
-
-**Production Readiness:**
-- Migration strategy (if schema changes)?
-- Backward compatibility considered?
-- Documentation complete?
-- No obvious bugs?
-
-## Output Format
-
-### Strengths
-[What's well done? Be specific.]
-
-### Issues
-
-#### Critical (Must Fix)
-[Bugs, security issues, data loss risks, broken functionality]
-
-#### Important (Should Fix)
-[Architecture problems, missing features, poor error handling, test gaps]
-
-#### Minor (Nice to Have)
-[Code style, optimization opportunities, documentation improvements]
-
-**For each issue:**
-- File:line reference
-- What's wrong
-- Why it matters
-- How to fix (if not obvious)
-
-### Recommendations
-[Improvements for code quality, architecture, or process]
-
-### Assessment
-
-**Ready to merge?** [Yes/No/With fixes]
-
-**Reasoning:** [Technical assessment in 1-2 sentences]
-
-## Critical Rules
-
-**DO:**
-- Categorize by actual severity (not everything is Critical)
-- Be specific (file:line, not vague)
-- Explain WHY issues matter
-- Acknowledge strengths
-- Give clear verdict
-
-**DON'T:**
-- Say "looks good" without checking
-- Mark nitpicks as Critical
-- Give feedback on code you didn't review
-- Be vague ("improve error handling")
-- Avoid giving a clear verdict
+**Reviewer returns:** Strengths, Issues (Critical / Important / Minor), Recommendations, Assessment
 
 ## Example Output
 

skills/subagent-driven-development/SKILL.md

@@ -5,9 +5,16 @@ description: Use when executing implementation plans with independent tasks in t
 
 # Subagent-Driven Development
 
-Execute plan by dispatching fresh subagent per task, with two-stage review after each: spec compliance review first, then code quality review.
+Execute plan by dispatching a fresh implementer subagent per task, a task review (spec compliance + code quality) after each, and a broad whole-branch review at the end.
 
-**Core principle:** Fresh subagent per task + two-stage review (spec then quality) = high quality, fast iteration
+**Why subagents:** You delegate tasks to specialized agents with isolated context. By precisely crafting their instructions and context, you ensure they stay focused and succeed at their task. They should never inherit your session's context or history — you construct exactly what they need. This also preserves your own context for coordination work.
+
+**Core principle:** Fresh subagent per task + task review (spec + quality) + broad final review = high quality, fast iteration
+
+**Narration:** between tool calls, narrate at most one short line — the
+ledger and the tool results carry the record.
+
+**Continuous execution:** Do not pause to check in with your human partner between tasks. Execute all tasks from the plan without stopping. The only reasons to stop are: BLOCKED status you cannot resolve, ambiguity that genuinely prevents progress, or all tasks complete. "Should I continue?" prompts and progress summaries waste their time — they asked you to execute the plan, so execute it.
 
 ## When to Use
 
@@ -32,7 +39,7 @@ digraph when_to_use {
 **vs. Executing Plans (parallel session):**
 - Same session (no context switch)
 - Fresh subagent per task (no context pollution)
-- Two-stage review after each task: spec compliance first, then code quality
+- Review after each task (spec compliance + code quality), broad review at the end
 - Faster iteration (no human-in-loop between tasks)
 
 ## The Process
@@ -47,60 +54,232 @@ digraph process {
         "Implementer subagent asks questions?" [shape=diamond];
         "Answer questions, provide context" [shape=box];
         "Implementer subagent implements, tests, commits, self-reviews" [shape=box];
-        "Dispatch spec reviewer subagent (./spec-reviewer-prompt.md)" [shape=box];
-        "Spec reviewer subagent confirms code matches spec?" [shape=diamond];
-        "Implementer subagent fixes spec gaps" [shape=box];
-        "Dispatch code quality reviewer subagent (./code-quality-reviewer-prompt.md)" [shape=box];
-        "Code quality reviewer subagent approves?" [shape=diamond];
-        "Implementer subagent fixes quality issues" [shape=box];
-        "Mark task complete in TodoWrite" [shape=box];
+        "Write diff file, dispatch task reviewer subagent (./task-reviewer-prompt.md)" [shape=box];
+        "Task reviewer reports spec ✅ and quality approved?" [shape=diamond];
+        "Dispatch fix subagent for Critical/Important findings" [shape=box];
+        "Mark task complete in todo list and progress ledger" [shape=box];
     }
 
-    "Read plan, extract all tasks with full text, note context, create TodoWrite" [shape=box];
+    "Read plan, note context and global constraints, create todos" [shape=box];
     "More tasks remain?" [shape=diamond];
-    "Dispatch final code reviewer subagent for entire implementation" [shape=box];
+    "Dispatch final code reviewer subagent (../requesting-code-review/code-reviewer.md)" [shape=box];
     "Use superpowers:finishing-a-development-branch" [shape=box style=filled fillcolor=lightgreen];
 
-    "Read plan, extract all tasks with full text, note context, create TodoWrite" -> "Dispatch implementer subagent (./implementer-prompt.md)";
+    "Read plan, note context and global constraints, create todos" -> "Dispatch implementer subagent (./implementer-prompt.md)";
     "Dispatch implementer subagent (./implementer-prompt.md)" -> "Implementer subagent asks questions?";
     "Implementer subagent asks questions?" -> "Answer questions, provide context" [label="yes"];
     "Answer questions, provide context" -> "Dispatch implementer subagent (./implementer-prompt.md)";
     "Implementer subagent asks questions?" -> "Implementer subagent implements, tests, commits, self-reviews" [label="no"];
-    "Implementer subagent implements, tests, commits, self-reviews" -> "Dispatch spec reviewer subagent (./spec-reviewer-prompt.md)";
-    "Dispatch spec reviewer subagent (./spec-reviewer-prompt.md)" -> "Spec reviewer subagent confirms code matches spec?";
-    "Spec reviewer subagent confirms code matches spec?" -> "Implementer subagent fixes spec gaps" [label="no"];
-    "Implementer subagent fixes spec gaps" -> "Dispatch spec reviewer subagent (./spec-reviewer-prompt.md)" [label="re-review"];
-    "Spec reviewer subagent confirms code matches spec?" -> "Dispatch code quality reviewer subagent (./code-quality-reviewer-prompt.md)" [label="yes"];
-    "Dispatch code quality reviewer subagent (./code-quality-reviewer-prompt.md)" -> "Code quality reviewer subagent approves?";
-    "Code quality reviewer subagent approves?" -> "Implementer subagent fixes quality issues" [label="no"];
-    "Implementer subagent fixes quality issues" -> "Dispatch code quality reviewer subagent (./code-quality-reviewer-prompt.md)" [label="re-review"];
-    "Code quality reviewer subagent approves?" -> "Mark task complete in TodoWrite" [label="yes"];
-    "Mark task complete in TodoWrite" -> "More tasks remain?";
+    "Implementer subagent implements, tests, commits, self-reviews" -> "Write diff file, dispatch task reviewer subagent (./task-reviewer-prompt.md)";
+    "Write diff file, dispatch task reviewer subagent (./task-reviewer-prompt.md)" -> "Task reviewer reports spec ✅ and quality approved?";
+    "Task reviewer reports spec ✅ and quality approved?" -> "Dispatch fix subagent for Critical/Important findings" [label="no"];
+    "Dispatch fix subagent for Critical/Important findings" -> "Write diff file, dispatch task reviewer subagent (./task-reviewer-prompt.md)" [label="re-review"];
+    "Task reviewer reports spec ✅ and quality approved?" -> "Mark task complete in todo list and progress ledger" [label="yes"];
+    "Mark task complete in todo list and progress ledger" -> "More tasks remain?";
     "More tasks remain?" -> "Dispatch implementer subagent (./implementer-prompt.md)" [label="yes"];
-    "More tasks remain?" -> "Dispatch final code reviewer subagent for entire implementation" [label="no"];
-    "Dispatch final code reviewer subagent for entire implementation" -> "Use superpowers:finishing-a-development-branch";
+    "More tasks remain?" -> "Dispatch final code reviewer subagent (../requesting-code-review/code-reviewer.md)" [label="no"];
+    "Dispatch final code reviewer subagent (../requesting-code-review/code-reviewer.md)" -> "Use superpowers:finishing-a-development-branch";
 }
 ```
 
+## Pre-Flight Plan Review
+
+Before dispatching Task 1, scan the plan once for conflicts:
+
+- tasks that contradict each other or the plan's Global Constraints
+- anything the plan explicitly mandates that the review rubric treats as a
+  defect (a test that asserts nothing, verbatim duplication of a logic block)
+
+Present everything you find to your human partner as one batched question —
+each finding beside the plan text that mandates it, asking which governs —
+before execution begins, not one interrupt per discovery mid-plan. If the
+scan is clean, proceed without comment. The review loop remains the net for
+conflicts that only emerge from implementation.
+
+## Model Selection
+
+Use the least powerful model that can handle each role to conserve cost and increase speed.
+
+**Mechanical implementation tasks** (isolated functions, clear specs, 1-2 files): use a fast, cheap model. Most implementation tasks are mechanical when the plan is well-specified.
+
+**Integration and judgment tasks** (multi-file coordination, pattern matching, debugging): use a standard model.
+
+**Architecture and design tasks**: use the most capable available model.
+The final whole-branch review is one of these — dispatch it on the most
+capable available model, not the session default.
+
+**Review tasks**: choose the model with the same judgment, scaled to the
+diff's size, complexity, and risk. A small mechanical diff does not need the
+most capable model; a subtle concurrency change does.
+
+**Always specify the model explicitly when dispatching a subagent.** An
+omitted model inherits your session's model — often the most capable and
+most expensive — which silently defeats this section.
+
+**Turn count beats token price.** Wall-clock and context cost scale with how
+many turns a subagent takes, and the cheapest models routinely take 2-3× the
+turns on multi-step work — costing more overall. Use a mid-tier model as the
+floor for reviewers and for implementers working from prose descriptions.
+When the task's plan text contains the complete code to write, the
+implementation is transcription plus testing: use the cheapest tier for
+that implementer. Single-file mechanical fixes also take the cheapest tier.
+
+**Task complexity signals (implementation tasks):**
+- Touches 1-2 files with a complete spec → cheap model
+- Touches multiple files with integration concerns → standard model
+- Requires design judgment or broad codebase understanding → most capable model
+
+## Handling Implementer Status
+
+Implementer subagents report one of four statuses. Handle each appropriately:
+
+**DONE:** Generate the review package (`scripts/review-package BASE HEAD`, from this skill's directory — it prints the unique file path it wrote; BASE is the commit you recorded before dispatching the implementer — never `HEAD~1`, which silently drops all but the last commit of a multi-commit task), then dispatch the task reviewer with the printed path.
+
+**DONE_WITH_CONCERNS:** The implementer completed the work but flagged doubts. Read the concerns before proceeding. If the concerns are about correctness or scope, address them before review. If they're observations (e.g., "this file is getting large"), note them and proceed to review.
+
+**NEEDS_CONTEXT:** The implementer needs information that wasn't provided. Provide the missing context and re-dispatch.
+
+**BLOCKED:** The implementer cannot complete the task. Assess the blocker:
+1. If it's a context problem, provide more context and re-dispatch with the same model
+2. If the task requires more reasoning, re-dispatch with a more capable model
+3. If the task is too large, break it into smaller pieces
+4. If the plan itself is wrong, escalate to the human
+
+**Never** ignore an escalation or force the same model to retry without changes. If the implementer said it's stuck, something needs to change.
+
+## Handling Reviewer ⚠️ Items
+
+The task reviewer may report "⚠️ Cannot verify from diff" items — requirements
+that live in unchanged code or span tasks. These do not block the rest of the
+review, but you must resolve each one yourself before marking the task
+complete: you hold the plan and cross-task context the reviewer
+lacks. If you confirm an item is a real gap, treat it as a failed spec
+review — send it back to the implementer and re-review.
+
+## Constructing Reviewer Prompts
+
+Per-task reviews are task-scoped gates. The broad review happens once, at the
+final whole-branch review. When you fill a reviewer template:
+
+- Do not add open-ended directives like "check all uses" or "run race tests
+  if useful" without a concrete, task-specific reason
+- Do not ask a reviewer to re-run tests the implementer already ran on the
+  same code — the implementer's report carries the test evidence
+- Do not pre-judge findings for the reviewer — never instruct a reviewer to
+  ignore or not flag a specific issue. If you believe a finding would be a
+  false positive, let the reviewer raise it and adjudicate it in the review
+  loop. If the prompt you are writing contains "do not flag," "don't treat X
+  as a defect," "at most Minor," or "the plan chose" — stop: you are
+  pre-judging, usually to spare yourself a review loop.
+- The global-constraints block you hand the reviewer is its attention
+  lens. Copy the binding requirements verbatim from the plan's Global
+  Constraints section or the spec: exact values, exact formats, and the
+  stated relationships between components ("same layout as X", "matches
+  Y"). The reviewer's template already carries the process rules (YAGNI,
+  test hygiene, review method) — the constraints block is for what THIS
+  project's spec demands.
+- Hand the reviewer its diff as a file: run this skill's
+  `scripts/review-package BASE HEAD` and pass the reviewer the file path
+  it prints (or, without bash: `git log --oneline`, `git diff --stat`,
+  and `git diff -U10` for the range, redirected to one uniquely named
+  file). The output never enters your own context, and the reviewer sees
+  the commit list, stat summary, and full diff with context in one Read
+  call. Use the BASE you recorded before dispatching the implementer —
+  never `HEAD~1`, which silently truncates multi-commit tasks.
+- A dispatch prompt describes one task, not the session's history. Do not
+  paste accumulated prior-task summaries ("state after Tasks 1-3") into
+  later dispatches — a real session's dispatch hit 42k chars of which 99%
+  was pasted history. A fresh subagent needs its task, the interfaces it
+  touches, and the global constraints. Nothing else.
+- Dispatch fix subagents for Critical and Important findings. Record Minor
+  findings in the progress ledger as you go, and point the final
+  whole-branch review at that list so it can triage which must be fixed
+  before merge. A roll-up nobody reads is a silent discard.
+- A finding labeled plan-mandated — or any finding that conflicts with
+  what the plan's text requires — is the human's decision, like any plan
+  contradiction: present the finding and the plan text, ask which governs.
+  Do not dismiss the finding because the plan mandates it, and do not
+  dispatch a fix that contradicts the plan without asking.
+- The final whole-branch review gets a package too: run
+  `scripts/review-package MERGE_BASE HEAD` (MERGE_BASE = the commit the
+  branch started from, e.g. `git merge-base main HEAD`) and include the
+  printed path in the final review dispatch, so the final reviewer reads
+  one file instead of re-deriving the branch diff with git commands.
+- Every fix dispatch carries the implementer contract: the fix subagent
+  re-runs the tests covering its change and reports the results. Name the
+  covering test files in the dispatch — a one-line fix does not need the
+  whole suite. Before re-dispatching the reviewer, confirm the fix report
+  contains the covering tests, the command run, and the output; dispatch
+  the re-review once all three are present.
+- If the final whole-branch review returns findings, dispatch ONE fix
+  subagent with the complete findings list — not one fixer per finding.
+  Per-finding fixers each rebuild context and re-run suites; a real
+  session's final-review fix wave cost more than all its tasks combined.
+
+## File Handoffs
+
+Everything you paste into a dispatch prompt — and everything a subagent
+prints back — stays resident in your context for the rest of the session
+and is re-read on every later turn. Hand artifacts over as files:
+
+- **Task brief:** before dispatching an implementer, run this skill's
+  `scripts/task-brief PLAN_FILE N` — it extracts the task's full text to a
+  uniquely named file and prints the path. Compose the dispatch so the
+  brief stays the single source of requirements. Your dispatch should
+  contain: (1) one line on where this task fits in the project; (2) the
+  brief path, introduced as "read this first — it is your requirements,
+  with the exact values to use verbatim"; (3) interfaces and decisions
+  from earlier tasks that the brief cannot know; (4) your resolution of
+  any ambiguity you noticed in the brief; (5) the report-file path and
+  report contract. Exact values (numbers, magic strings, signatures, test
+  cases) appear only in the brief.
+- **Report file:** name the implementer's report file after the brief
+  (brief `…/task-N-brief.md` → report `…/task-N-report.md`) and put it in
+  the dispatch prompt. The implementer writes the full report there and
+  returns only status, commits, a one-line test summary, and concerns.
+- **Reviewer inputs:** the task reviewer gets three paths — the same brief
+  file, the report file, and the review package — plus the global
+  constraints that bind the task.
+- Fix dispatches append their fix report (with test results) to the same
+  report file and return a short summary; re-reviews read the updated file.
+
+## Durable Progress
+
+Conversation memory does not survive compaction. In real sessions,
+controllers that lost their place have re-dispatched entire completed task
+sequences — the single most expensive failure observed. Track progress in
+a ledger file, not only in todos.
+
+- At skill start, check for a ledger:
+  `cat "$(git rev-parse --show-toplevel)/.superpowers/sdd/progress.md"`. Tasks listed there
+  as complete are DONE — do not re-dispatch them; resume at the first task
+  not marked complete.
+- When a task's review comes back clean, append one line to the ledger in
+  the same message as your other bookkeeping:
+  `Task N: complete (commits <base7>..<head7>, review clean)`.
+- The ledger is your recovery map: the commits it names exist in git even
+  when your context no longer remembers creating them. After compaction,
+  trust the ledger and `git log` over your own recollection.
+- `git clean -fdx` will destroy the ledger (it's git-ignored scratch); if
+  that happens, recover from `git log`.
+
 ## Prompt Templates
 
-- `./implementer-prompt.md` - Dispatch implementer subagent
-- `./spec-reviewer-prompt.md` - Dispatch spec compliance reviewer subagent
-- `./code-quality-reviewer-prompt.md` - Dispatch code quality reviewer subagent
+- [implementer-prompt.md](implementer-prompt.md) - Dispatch implementer subagent
+- [task-reviewer-prompt.md](task-reviewer-prompt.md) - Dispatch task reviewer subagent (spec compliance + code quality)
+- Final whole-branch review: use superpowers:requesting-code-review's [code-reviewer.md](../requesting-code-review/code-reviewer.md)
 
 ## Example Workflow
 
 ```
 You: I'm using Subagent-Driven Development to execute this plan.
 
-[Read plan file once: docs/plans/feature-plan.md]
-[Extract all 5 tasks with full text and context]
-[Create TodoWrite with all tasks]
+[Read plan file once: docs/superpowers/plans/feature-plan.md]
+[Create todos for all tasks]
 
 Task 1: Hook installation script
 
-[Get Task 1 text and context (already extracted)]
-[Dispatch implementation subagent with full task text + context]
+[Run task-brief for Task 1; dispatch implementer with brief + report paths + context]
 
 Implementer: "Before I begin - should the hook be installed at user or system level?"
 
@@ -113,18 +292,15 @@ Implementer: "Got it. Implementing now..."
   - Self-review: Found I missed --force flag, added it
   - Committed
 
-[Dispatch spec compliance reviewer]
-Spec reviewer: ✅ Spec compliant - all requirements met, nothing extra
-
-[Get git SHAs, dispatch code quality reviewer]
-Code reviewer: Strengths: Good test coverage, clean. Issues: None. Approved.
+[Run review-package, dispatch task reviewer with the printed path]
+Task reviewer: Spec ✅ - all requirements met, nothing extra.
+  Strengths: Good test coverage, clean. Issues: None. Task quality: Approved.
 
 [Mark Task 1 complete]
 
 Task 2: Recovery modes
 
-[Get Task 2 text and context (already extracted)]
-[Dispatch implementation subagent with full task text + context]
+[Run task-brief for Task 2; dispatch implementer with brief + report paths + context]
 
 Implementer: [No questions, proceeds]
 Implementer:
@@ -133,25 +309,17 @@ Implementer:
   - Self-review: All good
   - Committed
 
-[Dispatch spec compliance reviewer]
-Spec reviewer: ❌ Issues:
+[Run review-package, dispatch task reviewer with the printed path]
+Task reviewer: Spec ❌:
   - Missing: Progress reporting (spec says "report every 100 items")
   - Extra: Added --json flag (not requested)
+  Issues (Important): Magic number (100)
 
-[Implementer fixes issues]
-Implementer: Removed --json flag, added progress reporting
+[Dispatch fix subagent with all findings]
+Fixer: Removed --json flag, added progress reporting, extracted PROGRESS_INTERVAL constant
 
-[Spec reviewer reviews again]
-Spec reviewer: ✅ Spec compliant now
-
-[Dispatch code quality reviewer]
-Code reviewer: Strengths: Solid. Issues (Important): Magic number (100)
-
-[Implementer fixes]
-Implementer: Extracted PROGRESS_INTERVAL constant
-
-[Code reviewer reviews again]
-Code reviewer: ✅ Approved
+[Task reviewer reviews again]
+Task reviewer: Spec ✅. Task quality: Approved.
 
 [Mark Task 2 complete]
 
@@ -178,20 +346,20 @@ Done!
 - Review checkpoints automatic
 
 **Efficiency gains:**
-- No file reading overhead (controller provides full text)
-- Controller curates exactly what context is needed
+- Controller curates exactly what context is needed; bulk artifacts move
+  as files, not pasted text
 - Subagent gets complete information upfront
 - Questions surfaced before work begins (not after)
 
 **Quality gates:**
 - Self-review catches issues before handoff
-- Two-stage review: spec compliance, then code quality
+- Task review carries two verdicts: spec compliance and code quality
 - Review loops ensure fixes actually work
 - Spec compliance prevents over/under-building
 - Code quality ensures implementation is well-built
 
 **Cost:**
-- More subagent invocations (implementer + 2 reviewers per task)
+- More subagent invocations (implementer + reviewer per task)
 - Controller does more prep work (extracting all tasks upfront)
 - Review loops add iterations
 - But catches issues early (cheaper than debugging later)
@@ -199,17 +367,26 @@ Done!
 ## Red Flags
 
 **Never:**
-- Skip reviews (spec compliance OR code quality)
+- Start implementation on main/master branch without explicit user consent
+- Skip task review, or accept a report missing either verdict (spec compliance AND task quality are both required)
 - Proceed with unfixed issues
 - Dispatch multiple implementation subagents in parallel (conflicts)
-- Make subagent read plan file (provide full text instead)
+- Make a subagent read the whole plan file (hand it its task brief —
+  `scripts/task-brief` — instead)
 - Skip scene-setting context (subagent needs to understand where task fits)
 - Ignore subagent questions (answer before letting them proceed)
-- Accept "close enough" on spec compliance (spec reviewer found issues = not done)
+- Accept "close enough" on spec compliance (reviewer found spec 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)
-- Move to next task while either review has open issues
+- Tell a reviewer what not to flag, or pre-rate a finding's severity in the
+  dispatch prompt ("treat it as Minor at most") — the plan's example code is
+  a starting point, not evidence that its weaknesses were chosen
+- Dispatch a task reviewer without a diff file — generate it first
+  (`scripts/review-package BASE HEAD`) and name the printed path in the
+  prompt
+- Move to next task while the review has open Critical/Important issues
+- Re-dispatch a task the progress ledger already marks complete — check
+  the ledger (and `git log`) after any compaction or resume
 
 **If subagent asks questions:**
 - Answer clearly and completely
@@ -229,8 +406,9 @@ Done!
 ## Integration
 
 **Required workflow skills:**
+- **superpowers:using-git-worktrees** - Ensures isolated workspace (creates one or verifies existing)
 - **superpowers:writing-plans** - Creates the plan this skill executes
-- **superpowers:requesting-code-review** - Code review template for reviewer subagents
+- **superpowers:requesting-code-review** - Code review template for the final whole-branch review
 - **superpowers:finishing-a-development-branch** - Complete development after all tasks
 
 **Subagents should use:**

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

@@ -1,20 +0,0 @@
-# Code Quality Reviewer Prompt Template
-
-Use this template when dispatching a code quality reviewer subagent.
-
-**Purpose:** Verify implementation is well-built (clean, tested, maintainable)
-
-**Only dispatch after spec compliance review passes.**
-
-```
-Task tool (superpowers:code-reviewer):
-  Use template at requesting-code-review/code-reviewer.md
-
-  WHAT_WAS_IMPLEMENTED: [from implementer's report]
-  PLAN_OR_REQUIREMENTS: Task N from [plan-file]
-  BASE_SHA: [commit before task]
-  HEAD_SHA: [current commit]
-  DESCRIPTION: [task summary]
-```
-
-**Code reviewer returns:** Strengths, Issues (Critical/Important/Minor), Assessment

skills/subagent-driven-development/implementer-prompt.md

@@ -3,14 +3,17 @@
 Use this template when dispatching an implementer subagent.
 
 ```
-Task tool (general-purpose):
+Subagent (general-purpose):
   description: "Implement Task N: [task name]"
+  model: [MODEL — REQUIRED: choose per SKILL.md Model Selection; an omitted
+         model silently inherits the session's most expensive one]
   prompt: |
     You are implementing Task N: [task name]
 
     ## Task Description
 
-    [FULL TEXT of task from plan - paste it here, don't make subagent read file]
+    Read your task brief first: [BRIEF_FILE]
+    It contains the full task text from the plan.
 
     ## Context
 
@@ -41,6 +44,39 @@ Task tool (general-purpose):
     **While you work:** If you encounter something unexpected or unclear, **ask questions**.
     It's always OK to pause and clarify. Don't guess or make assumptions.
 
+    While iterating, run the focused test for what you're changing; run the
+    full suite once before committing, not after every edit.
+
+    ## Code Organization
+
+    You reason best about code you can hold in context at once, and your edits are more
+    reliable when files are focused. Keep this in mind:
+    - Follow the file structure defined in the plan
+    - Each file should have one clear responsibility with a well-defined interface
+    - If a file you're creating is growing beyond the plan's intent, stop and report
+      it as DONE_WITH_CONCERNS — don't split files on your own without plan guidance
+    - If an existing file you're modifying is already large or tangled, work carefully
+      and note it as a concern in your report
+    - In existing codebases, follow established patterns. Improve code you're touching
+      the way a good developer would, but don't restructure things outside your task.
+
+    ## When You're in Over Your Head
+
+    It is always OK to stop and say "this is too hard for me." Bad work is worse than
+    no work. You will not be penalized for escalating.
+
+    **STOP and escalate when:**
+    - The task requires architectural decisions with multiple valid approaches
+    - You need to understand code beyond what was provided and can't find clarity
+    - You feel uncertain about whether your approach is correct
+    - The task involves restructuring existing code in ways the plan didn't anticipate
+    - You've been reading file after file trying to understand the system without progress
+
+    **How to escalate:** Report back with status BLOCKED or NEEDS_CONTEXT. Describe
+    specifically what you're stuck on, what you've tried, and what kind of help you need.
+    The controller can provide more context, re-dispatch with a more capable model,
+    or break the task into smaller pieces.
+
     ## Before Reporting Back: Self-Review
 
     Review your work with fresh eyes. Ask yourself:
@@ -64,15 +100,40 @@ Task tool (general-purpose):
     - Do tests actually verify behavior (not just mock behavior)?
     - Did I follow TDD if required?
     - Are tests comprehensive?
+    - Is the test output pristine (no stray warnings or noise)?
 
     If you find issues during self-review, fix them now before reporting.
 
+    ## After Review Findings
+
+    If a reviewer finds issues and you fix them, re-run the tests that cover
+    the amended code and append the results to your report file. Reviewers
+    will not re-run tests for you — your report is the test evidence.
+
     ## Report Format
 
-    When done, report:
-    - What you implemented
+    Write your full report to [REPORT_FILE]:
+    - What you implemented (or what you attempted, if blocked)
     - What you tested and test results
+    - **TDD Evidence** (if TDD was required for this task):
+      - RED: command run, relevant failing output before implementation, and why the failure was expected
+      - GREEN: command run and relevant passing output after implementation
     - Files changed
     - Self-review findings (if any)
     - Any issues or concerns
+
+    Then report back with ONLY (under 15 lines — the detail lives in the
+    report file):
+    - **Status:** DONE | DONE_WITH_CONCERNS | BLOCKED | NEEDS_CONTEXT
+    - Commits created (short SHA + subject)
+    - One-line test summary (e.g. "14/14 passing, output pristine")
+    - Your concerns, if any
+    - The report file path
+
+    If BLOCKED or NEEDS_CONTEXT, put the specifics in the final message
+    itself — the controller acts on it directly.
+
+    Use DONE_WITH_CONCERNS if you completed the work but have doubts about correctness.
+    Use BLOCKED if you cannot complete the task. Use NEEDS_CONTEXT if you need
+    information that wasn't provided. Never silently produce work you're unsure about.
 ```

skills/subagent-driven-development/scripts/review-package

@@ -0,0 +1,44 @@
+#!/usr/bin/env bash
+# Generate a review package: commit list, stat summary, and the net
+# diff with extended context, written to a file the reviewer reads in one
+# call. Using the recorded per-task BASE (not HEAD~1) keeps multi-commit
+# tasks intact.
+#
+# Usage: review-package BASE HEAD [OUTFILE]
+# Default OUTFILE: <repo-root>/.superpowers/sdd/review-<base7>..<head7>.diff
+# (named per range, so a re-review after fixes gets a distinct fresh file).
+set -euo pipefail
+
+if [ $# -lt 2 ] || [ $# -gt 3 ]; then
+  echo "usage: review-package BASE HEAD [OUTFILE]" >&2
+  exit 2
+fi
+
+base=$1
+head=$2
+
+git rev-parse --verify --quiet "$base" >/dev/null || { echo "bad BASE: $base" >&2; exit 2; }
+git rev-parse --verify --quiet "$head" >/dev/null || { echo "bad HEAD: $head" >&2; exit 2; }
+
+if [ $# -eq 3 ]; then
+  out=$3
+else
+  dir=$("$(cd "$(dirname "$0")" && pwd)/sdd-workspace")
+  out="$dir/review-$(git rev-parse --short "$base")..$(git rev-parse --short "$head").diff"
+fi
+
+{
+  echo "# Review package: ${base}..${head}"
+  echo
+  echo "## Commits"
+  git log --oneline "${base}..${head}"
+  echo
+  echo "## Files changed"
+  git diff --stat "${base}..${head}"
+  echo
+  echo "## Diff"
+  git diff -U10 "${base}..${head}"
+} > "$out"
+
+commits=$(git rev-list --count "${base}..${head}")
+echo "wrote ${out}: ${commits} commit(s), $(wc -c < "$out" | tr -d ' ') bytes"

skills/subagent-driven-development/scripts/sdd-workspace

@@ -0,0 +1,22 @@
+#!/usr/bin/env bash
+# Resolve and ensure the working-tree directory SDD uses for its short-lived
+# artifacts: task briefs, implementer reports, review packages, and the
+# progress ledger. Print the directory's absolute path.
+#
+# The workspace lives in the working tree (not under .git/) because Claude Code
+# treats .git/ as a protected path and denies agent writes there — which blocks
+# an implementer subagent from writing its report file. A self-ignoring
+# .gitignore keeps the workspace out of `git status` and out of accidental
+# commits without modifying any tracked file.
+#
+# Single source of truth for the workspace location, so task-brief and
+# review-package cannot drift to different directories.
+#
+# Usage: sdd-workspace
+set -euo pipefail
+
+root=$(git rev-parse --show-toplevel)
+dir="$root/.superpowers/sdd"
+mkdir -p "$dir"
+printf '*\n' > "$dir/.gitignore"
+cd "$dir" && pwd

skills/subagent-driven-development/scripts/task-brief

@@ -0,0 +1,40 @@
+#!/usr/bin/env bash
+# Extract one task's full text from an implementation plan into a file the
+# implementer reads in one call, so the task text never has to be pasted
+# through the controller's context.
+#
+# Usage: task-brief PLAN_FILE TASK_NUMBER [OUTFILE]
+# Default OUTFILE: <repo-root>/.superpowers/sdd/task-<N>-brief.md
+# (per worktree; concurrent runs in the same working tree share it).
+set -euo pipefail
+
+if [ $# -lt 2 ] || [ $# -gt 3 ]; then
+  echo "usage: task-brief PLAN_FILE TASK_NUMBER [OUTFILE]" >&2
+  exit 2
+fi
+
+plan=$1
+n=$2
+[ -f "$plan" ] || { echo "no such plan file: $plan" >&2; exit 2; }
+
+if [ $# -eq 3 ]; then
+  out=$3
+else
+  dir=$("$(cd "$(dirname "$0")" && pwd)/sdd-workspace")
+  out="$dir/task-${n}-brief.md"
+fi
+
+awk -v n="$n" '
+  /^```/ { infence = !infence }
+  !infence && /^#+[ \t]+Task[ \t]+[0-9]+/ {
+    intask = ($0 ~ ("^#+[ \t]+Task[ \t]+" n "([^0-9]|$)"))
+  }
+  intask { print }
+' "$plan" > "$out"
+
+if [ ! -s "$out" ]; then
+  echo "task ${n} not found in ${plan} (no heading matching 'Task ${n}')" >&2
+  exit 3
+fi
+
+echo "wrote ${out}: $(wc -l < "$out" | tr -d ' ') lines"

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

@@ -1,61 +0,0 @@
-# Spec Compliance Reviewer Prompt Template
-
-Use this template when dispatching a spec compliance reviewer subagent.
-
-**Purpose:** Verify implementer built what was requested (nothing more, nothing less)
-
-```
-Task tool (general-purpose):
-  description: "Review spec compliance for Task N"
-  prompt: |
-    You are reviewing whether an implementation matches its specification.
-
-    ## What Was Requested
-
-    [FULL TEXT of task requirements]
-
-    ## What Implementer Claims They Built
-
-    [From implementer's report]
-
-    ## CRITICAL: Do Not Trust the Report
-
-    The implementer finished suspiciously quickly. Their report may be incomplete,
-    inaccurate, or optimistic. You MUST verify everything independently.
-
-    **DO NOT:**
-    - Take their word for what they implemented
-    - Trust their claims about completeness
-    - Accept their interpretation of requirements
-
-    **DO:**
-    - Read the actual code they wrote
-    - Compare actual implementation to requirements line by line
-    - Check for missing pieces they claimed to implement
-    - Look for extra features they didn't mention
-
-    ## Your Job
-
-    Read the implementation code and verify:
-
-    **Missing requirements:**
-    - Did they implement everything that was requested?
-    - Are there requirements they skipped or missed?
-    - Did they claim something works but didn't actually implement it?
-
-    **Extra/unneeded work:**
-    - Did they build things that weren't requested?
-    - Did they over-engineer or add unnecessary features?
-    - Did they add "nice to haves" that weren't in spec?
-
-    **Misunderstandings:**
-    - Did they interpret requirements differently than intended?
-    - Did they solve the wrong problem?
-    - Did they implement the right feature but wrong way?
-
-    **Verify by reading code, not by trusting report.**
-
-    Report:
-    - ✅ Spec compliant (if everything matches after code inspection)
-    - ❌ Issues found: [list specifically what's missing or extra, with file:line references]
-```