Add Codex superpowers integration

- Single unified script: superpowers-codex with bootstrap/use-skill/find-skills commands - Cross-platform Node.js implementation (works on Windows, macOS, Linux) - Namespaced skills: superpowers:skill-name for core, skill-name for personal - Personal skills override superpowers skills when names match - Clean skill display: shows name/description without raw frontmatter - Helpful context: shows supporting files directory for each skill - Tool mapping for Codex: TodoWrite→update_plan, Skill→superpowers-codex, etc. - Subagent orchestration instructions for codex --yolo exec - Updated terminology: "Superpowers skills" instead of "Core skills" - Bootstrap integration with AGENTS.md for automatic startup
2026-06-09 17:02:07 +00:00 · 2025-10-28 00:23:47 +00:00
136 changed files with 1429 additions and 14755 deletions
--- a/.claude-plugin/marketplace.json
+++ b/.claude-plugin/marketplace.json
@@ -9,7 +9,7 @@
    {
      "name": "superpowers",
      "description": "Core skills library for Claude Code: TDD, debugging, collaboration patterns, and proven techniques",
-      "version": "5.0.6",
+      "version": "3.2.2",
      "source": "./",
      "author": {
        "name": "Jesse Vincent",
--- a/.claude-plugin/plugin.json
+++ b/.claude-plugin/plugin.json
@@ -1,7 +1,7 @@
 {
  "name": "superpowers",
  "description": "Core skills library for Claude Code: TDD, debugging, collaboration patterns, and proven techniques",
-  "version": "5.0.6",
+  "version": "3.2.3",
  "author": {
    "name": "Jesse Vincent",
    "email": "jesse@fsck.com"
@@ -9,12 +9,5 @@
  "homepage": "https://github.com/obra/superpowers",
  "repository": "https://github.com/obra/superpowers",
  "license": "MIT",
-  "keywords": [
+  "keywords": ["skills", "tdd", "debugging", "collaboration", "best-practices", "workflows"]
    "skills",
    "tdd",
    "debugging",
    "collaboration",
    "best-practices",
    "workflows"
  ]
 }
--- a/.codex/INSTALL.md
+++ b/.codex/INSTALL.md
@@ -1,67 +0,0 @@
 # Installing Superpowers for Codex
 Enable superpowers skills in Codex via native skill discovery. Just clone and symlink.
 ## Prerequisites
 - Git
 ## Installation
 1. **Clone the superpowers repository:**
   ```bash
   git clone https://github.com/obra/superpowers.git ~/.codex/superpowers
   ```
 2. **Create the skills symlink:**
   ```bash
   mkdir -p ~/.agents/skills
   ln -s ~/.codex/superpowers/skills ~/.agents/skills/superpowers
   ```
   **Windows (PowerShell):**
   ```powershell
   New-Item -ItemType Directory -Force -Path "$env:USERPROFILE\.agents\skills"
   cmd /c mklink /J "$env:USERPROFILE\.agents\skills\superpowers" "$env:USERPROFILE\.codex\superpowers\skills"
   ```
 3. **Restart Codex** (quit and relaunch the CLI) to discover the skills.
 ## Migrating from old bootstrap
 If you installed superpowers before native skill discovery, you need to:
 1. **Update the repo:**
   ```bash
   cd ~/.codex/superpowers && git pull
   ```
 2. **Create the skills symlink** (step 2 above) — this is the new discovery mechanism.
 3. **Remove the old bootstrap block** from `~/.codex/AGENTS.md` — any block referencing `superpowers-codex bootstrap` is no longer needed.
 4. **Restart Codex.**
 ## Verify
 ```bash
 ls -la ~/.agents/skills/superpowers
 ```
 You should see a symlink (or junction on Windows) pointing to your superpowers skills directory.
 ## Updating
 ```bash
 cd ~/.codex/superpowers && git pull
 ```
 Skills update instantly through the symlink.
 ## Uninstalling
 ```bash
 rm ~/.agents/skills/superpowers
 ```
 Optionally delete the clone: `rm -rf ~/.codex/superpowers`.
--- a/.cursor-plugin/plugin.json
+++ b/.cursor-plugin/plugin.json
@@ -1,25 +0,0 @@
 {
  "name": "superpowers",
  "displayName": "Superpowers",
  "description": "Core skills library: TDD, debugging, collaboration patterns, and proven techniques",
  "version": "5.0.6",
  "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/",
  "agents": "./agents/",
  "commands": "./commands/",
  "hooks": "./hooks/hooks-cursor.json"
 }
--- a/.gitattributes
+++ b/.gitattributes
@@ -1,18 +0,0 @@
 # 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
--- a/.github/FUNDING.yml
+++ b/.github/FUNDING.yml
@@ -1,3 +0,0 @@
 # These are supported funding model platforms
 github: [obra]
--- a/.github/ISSUE_TEMPLATE/bug_report.md
+++ b/.github/ISSUE_TEMPLATE/bug_report.md
@@ -1,52 +0,0 @@
 ---
 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
 | Field | Value |
 |-------|-------|
 | Superpowers version | |
 | Harness (Claude Code, Cursor, etc.) | |
 | Harness version | |
 | Model | |
 | 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. -->
--- a/.github/ISSUE_TEMPLATE/config.yml
+++ b/.github/ISSUE_TEMPLATE/config.yml
@@ -1,5 +0,0 @@
 blank_issues_enabled: false
 contact_links:
  - name: Questions & Help
    url: https://discord.gg/Jd8Vphy9jq
    about: For usage questions, troubleshooting help, and general discussion, please visit our Discord instead of opening an issue.
--- a/.github/ISSUE_TEMPLATE/feature_request.md
+++ b/.github/ISSUE_TEMPLATE/feature_request.md
@@ -1,34 +0,0 @@
 ---
 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. -->
 ## Context
 <!-- Optional: version info, harness, model, workflow where you hit this. -->
--- a/.github/ISSUE_TEMPLATE/platform_support.md
+++ b/.github/ISSUE_TEMPLATE/platform_support.md
@@ -1,23 +0,0 @@
 ---
 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? -->
--- a/.github/PULL_REQUEST_TEMPLATE.md
+++ b/.github/PULL_REQUEST_TEMPLATE.md
@@ -1,87 +0,0 @@
 <!--
 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.
 -->
 ## 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 |
 |-------------------------------------|-----------------|-------|------------------|
 |                                     |                 |       |                  |
 ## 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
 -->
--- a/.gitignore
+++ b/.gitignore
@@ -1,7 +1,2 @@
 .worktrees/
 .private-journal/
 .claude/
 .DS_Store
 node_modules/
 inspo
 triage/
--- a/.opencode/INSTALL.md
+++ b/.opencode/INSTALL.md
@@ -1,83 +0,0 @@
 # Installing Superpowers for OpenCode
 ## Prerequisites
 - [OpenCode.ai](https://opencode.ai) installed
 ## Installation
 Add superpowers to the `plugin` array in your `opencode.json` (global or project-level):
 ```json
 {
  "plugin": ["superpowers@git+https://github.com/obra/superpowers.git"]
 }
 ```
 Restart OpenCode. That's it — the plugin auto-installs and registers all skills.
 Verify by asking: "Tell me about your superpowers"
 ## Migrating from the old symlink-based install
 If you previously installed superpowers using `git clone` and symlinks, remove the old setup:
 ```bash
 # 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
 ```
 Then follow the installation steps above.
 ## Usage
 Use OpenCode's native `skill` tool:
 ```
 use skill tool to list skills
 use skill tool to load superpowers/brainstorming
 ```
 ## Updating
 Superpowers updates automatically when you restart OpenCode.
 To pin a specific version:
 ```json
 {
  "plugin": ["superpowers@git+https://github.com/obra/superpowers.git#v5.0.3"]
 }
 ```
 ## Troubleshooting
 ### Plugin not loading
 1. Check logs: `opencode run --print-logs "hello" 2>&1 | grep -i superpowers`
 2. Verify the plugin line in your `opencode.json`
 3. Make sure you're running a recent version of OpenCode
 ### Skills not found
 1. Use `skill` tool to list what's discovered
 2. Check that the plugin is loading (see above)
 ### Tool mapping
 When skills reference Claude Code tools:
 - `TodoWrite` → `todowrite`
 - `Task` with subagents → `@mention` syntax
 - `Skill` tool → OpenCode's native `skill` tool
 - File operations → your native tools
 ## Getting Help
 - Report issues: https://github.com/obra/superpowers/issues
 - Full documentation: https://github.com/obra/superpowers/blob/main/docs/README.opencode.md
--- a/.opencode/plugins/superpowers.js
+++ b/.opencode/plugins/superpowers.js
@@ -1,107 +0,0 @@
 /**
 * Superpowers plugin for OpenCode.ai
 *
 * Injects superpowers bootstrap context via system prompt 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);
 };
 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
  const getBootstrapContent = () => {
    // Try to load using-superpowers skill
    const skillPath = path.join(superpowersSkillsDir, 'using-superpowers', 'SKILL.md');
    if (!fs.existsSync(skillPath)) return null;
    const fullContent = fs.readFileSync(skillPath, 'utf8');
    const { content } = extractAndStripFrontmatter(fullContent);
    const toolMapping = `**Tool Mapping for OpenCode:**
 When skills reference tools you don't have, substitute OpenCode equivalents:
 - \`TodoWrite\` → \`todowrite\`
 - \`Task\` tool with subagents → Use OpenCode's subagent system (@mention)
 - \`Skill\` tool → OpenCode's native \`skill\` tool
 - \`Read\`, \`Write\`, \`Edit\`, \`Bash\` → Your native tools
 **Skills location:**
 Superpowers skills are in \`${configDir}/skills/superpowers/\`
 Use OpenCode's native \`skill\` tool to list and load skills.`;
    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 skill tool to load "using-superpowers" again - that would be redundant.**
 ${content}
 ${toolMapping}
 </EXTREMELY_IMPORTANT>`;
  };
  return {
    // Inject skills path into live config so OpenCode discovers superpowers skills
    // without requiring manual symlinks or config file edits.
    // This works because Config.get() returns a cached singleton — modifications
    // here are visible when skills are lazily discovered later.
    config: async (config) => {
      config.skills = config.skills || {};
      config.skills.paths = config.skills.paths || [];
      if (!config.skills.paths.includes(superpowersSkillsDir)) {
        config.skills.paths.push(superpowersSkillsDir);
      }
    },
    // Use system prompt transform to inject bootstrap (fixes #226 agent reset bug)
    'experimental.chat.system.transform': async (_input, output) => {
      const bootstrap = getBootstrapContent();
      if (bootstrap) {
        (output.system ||= []).push(bootstrap);
      }
    }
  };
 };
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -1,13 +0,0 @@
 # Changelog
 ## [5.0.5] - 2026-03-17
 ### Fixed
 - **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](https://github.com/obra/superpowers/pull/784) by @sarbojitrana, fixes [#774](https://github.com/obra/superpowers/issues/774), [#780](https://github.com/obra/superpowers/issues/780), [#783](https://github.com/obra/superpowers/issues/783))
 - **Brainstorm owner-PID on Windows**: Skip `BRAINSTORM_OWNER_PID` lifecycle monitoring on Windows/MSYS2 where the PID namespace is invisible to Node.js. Prevents the server from self-terminating after 60 seconds. The 30-minute idle timeout remains as the safety net. ([#770](https://github.com/obra/superpowers/issues/770), docs from [PR #768](https://github.com/obra/superpowers/pull/768) by @lucasyhzhu-debug)
 - **stop-server.sh reliability**: Verify the server process actually died before reporting success. Waits up to 2 seconds for graceful shutdown, escalates to `SIGKILL`, and reports failure if the process survives. ([#723](https://github.com/obra/superpowers/issues/723))
 ### Changed
 - **Execution handoff**: Restore user choice between subagent-driven-development and executing-plans after plan writing. Subagent-driven is recommended but no longer mandatory. (Reverts `5e51c3e`)
--- a/CODE_OF_CONDUCT.md
+++ b/CODE_OF_CONDUCT.md
@@ -1,128 +0,0 @@
 # 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.
--- a/GEMINI.md
+++ b/GEMINI.md
@@ -1,2 +0,0 @@
@./skills/using-superpowers/SKILL.md
@./skills/using-superpowers/references/gemini-tools.md
--- a/README.md
+++ b/README.md
@@ -1,133 +1,88 @@
 # 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.
+Give Claude Code superpowers with a comprehensive skills library of proven techniques, patterns, and workflows.
-## How it works
+## What You Get
-It starts from the moment you fire up your coding agent. As soon as it sees that you're building something, it *doesn't* just jump into trying to write code. Instead, it steps back and asks you what you're really trying to do. 
+- **Testing Skills** - TDD, async testing, anti-patterns
 - **Debugging Skills** - Systematic debugging, root cause tracing, verification
 - **Collaboration Skills** - Brainstorming, planning, code review, parallel agents
 - **Development Skills** - Git worktrees, finishing branches, subagent workflows
 - **Meta Skills** - Creating, testing, and sharing skills
-Once it's teased a spec out of the conversation, it shows it to you in chunks short enough to actually read and digest. 
+Plus:
 - **Slash Commands** - `/superpowers:brainstorm`, `/superpowers:write-plan`, `/superpowers:execute-plan`
 - **Automatic Integration** - Skills activate automatically when relevant
 - **Consistent Workflows** - Systematic approaches to common engineering tasks
-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. 
+## Learn More
 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.
 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.
 ## 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
 Read the introduction: [Superpowers for Claude Code](https://blog.fsck.com/2025/10/09/superpowers/)
 ## Installation
-**Note:** Installation differs by platform. Claude Code or Cursor have built-in plugin marketplaces. Codex and OpenCode require manual setup.
+### Via Plugin Marketplace (Recommended)
 ### Claude Code Official Marketplace
 Superpowers is available via the [official Claude plugin marketplace](https://claude.com/plugins/superpowers)
 Install the plugin from Claude marketplace:
 ```bash
 /plugin install superpowers@claude-plugins-official
 ```
 ### Claude Code (via Plugin Marketplace)
 In Claude Code, register the marketplace first:
 ```bash
 # In Claude Code
 /plugin marketplace add obra/superpowers-marketplace
 ```
 Then install the plugin from this marketplace:
 ```bash
 /plugin install superpowers@superpowers-marketplace
 ```
 ### Cursor (via Plugin Marketplace)
 In Cursor Agent chat, install from marketplace:
 ```text
 /add-plugin superpowers
 ```
 or search for "superpowers" in the plugin marketplace.
 ### Codex
 Tell Codex:
 ```
 Fetch and follow instructions from https://raw.githubusercontent.com/obra/superpowers/refs/heads/main/.codex/INSTALL.md
 ```
 **Detailed docs:** [docs/README.codex.md](docs/README.codex.md)
 ### OpenCode
 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)
 ### Gemini CLI
 ```bash
 gemini extensions install https://github.com/obra/superpowers
 ```
 To update:
 ```bash
 gemini extensions update superpowers
 ```
 ### Verify Installation
-Start a new session in your chosen platform and ask for something that should trigger a skill (for example, "help me plan this feature" or "let's debug this issue"). The agent should automatically invoke the relevant superpowers skill.
+```bash
 # Check that commands appear
 /help
-## The Basic Workflow
+# Should see:
 # /superpowers:brainstorm - Interactive design refinement
 # /superpowers:write-plan - Create implementation plan
 # /superpowers:execute-plan - Execute plan in batches
 ```
-1. **brainstorming** - Activates before writing code. Refines rough ideas through questions, explores alternatives, presents design in sections for validation. Saves design document.
+## Quick Start
-2. **using-git-worktrees** - Activates after design approval. Creates isolated workspace on new branch, runs project setup, verifies clean test baseline.
+### Using Slash Commands
-3. **writing-plans** - Activates with approved design. Breaks work into bite-sized tasks (2-5 minutes each). Every task has exact file paths, complete code, verification steps.
+**Brainstorm a design:**
 ```
 /superpowers:brainstorm
 ```
-4. **subagent-driven-development** or **executing-plans** - Activates with plan. Dispatches fresh subagent per task with two-stage review (spec compliance, then code quality), or executes in batches with human checkpoints.
+**Create an implementation plan:**
 ```
 /superpowers:write-plan
 ```
-5. **test-driven-development** - Activates during implementation. Enforces RED-GREEN-REFACTOR: write failing test, watch it fail, write minimal code, watch it pass, commit. Deletes code written before tests.
+**Execute the plan:**
 ```
 /superpowers:execute-plan
 ```
-6. **requesting-code-review** - Activates between tasks. Reviews against plan, reports issues by severity. Critical issues block progress.
+### Automatic Skill Activation
-7. **finishing-a-development-branch** - Activates when tasks complete. Verifies tests, presents options (merge/PR/keep/discard), cleans up worktree.
+Skills activate automatically when relevant. For example:
-
+- `test-driven-development` activates when implementing features
-**The agent checks for relevant skills before any task.** Mandatory workflows, not suggestions.
+- `systematic-debugging` activates when debugging issues
 - `verification-before-completion` activates before claiming work is done
 ## What's Inside
 ### Skills Library
-**Testing**
+**Testing** (`skills/testing/`)
- **test-driven-development** - RED-GREEN-REFACTOR cycle (includes testing anti-patterns reference)
+- **test-driven-development** - RED-GREEN-REFACTOR cycle
 - **condition-based-waiting** - Async test patterns
 - **testing-anti-patterns** - Common pitfalls to avoid
-**Debugging**
+**Debugging** (`skills/debugging/`)
- **systematic-debugging** - 4-phase root cause process (includes root-cause-tracing, defense-in-depth, condition-based-waiting techniques)
+- **systematic-debugging** - 4-phase root cause process
 - **root-cause-tracing** - Find the real problem
 - **verification-before-completion** - Ensure it's actually fixed
 - **defense-in-depth** - Multiple validation layers
-**Collaboration** 
+**Collaboration** (`skills/collaboration/`)
 - **brainstorming** - Socratic design refinement
 - **writing-plans** - Detailed implementation plans
 - **executing-plans** - Batch execution with checkpoints
@@ -136,20 +91,36 @@ Start a new session in your chosen platform and ask for something that should tr
 - **receiving-code-review** - Responding to feedback
 - **using-git-worktrees** - Parallel development branches
 - **finishing-a-development-branch** - Merge/PR decision workflow
- **subagent-driven-development** - Fast iteration with two-stage review (spec compliance, then code quality)
+- **subagent-driven-development** - Fast iteration with quality gates
-**Meta**
+**Meta** (`skills/meta/`)
- **writing-skills** - Create new skills following best practices (includes testing methodology)
+- **writing-skills** - Create new skills following best practices
 - **sharing-skills** - Contribute skills back via branch and PR
 - **testing-skills-with-subagents** - Validate skill quality
 - **using-superpowers** - Introduction to the skills system
 ### Commands
 All commands are thin wrappers that activate the corresponding skill:
 - **brainstorm.md** - Activates the `brainstorming` skill
 - **write-plan.md** - Activates the `writing-plans` skill
 - **execute-plan.md** - Activates the `executing-plans` skill
 ## How It Works
 1. **SessionStart Hook** - Loads the `using-superpowers` skill at session start
 2. **Skills System** - Uses Claude Code's first-party skills system
 3. **Automatic Discovery** - Claude finds and uses relevant skills for your task
 4. **Mandatory Workflows** - When a skill exists for your task, using it becomes required
 ## Philosophy
 - **Test-Driven Development** - Write tests first, always
 - **Systematic over ad-hoc** - Process over guessing
 - **Complexity reduction** - Simplicity as primary goal
 - **Evidence over claims** - Verify before declaring success
-
+- **Domain over implementation** - Work at problem level, not solution level
 Read more: [Superpowers for Claude Code](https://blog.fsck.com/2025/10/09/superpowers/)
 ## Contributing
@@ -157,10 +128,11 @@ Skills live directly in this repository. To contribute:
 1. Fork the repository
 2. Create a branch for your skill
-3. Follow the `writing-skills` skill for creating and testing new skills
+3. Follow the `writing-skills` skill for creating new skills
-4. Submit a PR
+4. Use the `testing-skills-with-subagents` skill to validate quality
 5. Submit a PR
-See `skills/writing-skills/SKILL.md` for the complete guide.
+See `skills/meta/writing-skills/SKILL.md` for the complete guide.
 ## Updating
@@ -174,14 +146,7 @@ Skills update automatically when you update the plugin:
 MIT License - see LICENSE file for details
 ## Community
 Superpowers is built by [Jesse Vincent](https://blog.fsck.com) and the rest of the folks at [Prime Radiant](https://primeradiant.com).
 For community support, questions, and sharing what you're building with Superpowers, join us on [Discord](https://discord.gg/Jd8Vphy9jq).
 ## Support
 - **Discord**: [Join us on Discord](https://discord.gg/Jd8Vphy9jq)
 - **Issues**: https://github.com/obra/superpowers/issues
 - **Marketplace**: https://github.com/obra/superpowers-marketplace
--- a/RELEASE-NOTES.md
+++ b/RELEASE-NOTES.md
@@ -1,688 +1,5 @@
 # Superpowers Release Notes
 ## 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
 **Clarified how to access skills in Claude Code**
 Fixed a confusing pattern where Claude would invoke a skill via the Skill tool, then try to Read the skill file separately. The `using-superpowers` skill now explicitly states that the Skill tool loads skill content directly—no need to read files.
 - Added "How to Access Skills" section to `using-superpowers`
 - 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
 **Two-stage code review in subagent-driven-development**
 Subagent workflows now use two separate review stages after each task:
 1. **Spec compliance review** - Skeptical reviewer verifies implementation matches spec exactly. Catches missing requirements AND over-building. Won't trust implementer's report—reads actual code.
 2. **Code quality review** - Only runs after spec compliance passes. Reviews for clean code, test coverage, maintainability.
 This catches the common failure mode where code is well-written but doesn't match what was requested. Reviews are loops, not one-shot: if reviewer finds issues, implementer fixes them, then reviewer checks again.
 Other subagent workflow improvements:
 - Controller provides full task text to workers (not file references)
 - Workers can ask clarifying questions before AND during work
 - Self-review checklist before reporting completion
 - Plan read once at start, extracted to TodoWrite
 New prompt templates in `skills/subagent-driven-development/`:
 - `implementer-prompt.md` - Includes self-review checklist, encourages questions
 - `spec-reviewer-prompt.md` - Skeptical verification against requirements
 - `code-quality-reviewer-prompt.md` - Standard code review
 **Debugging techniques consolidated with tools**
 `systematic-debugging` now bundles supporting techniques and tools:
 - `root-cause-tracing.md` - Trace bugs backward through call stack
 - `defense-in-depth.md` - Add validation at multiple layers
 - `condition-based-waiting.md` - Replace arbitrary timeouts with condition polling
 - `find-polluter.sh` - Bisection script to find which test creates pollution
 - `condition-based-waiting-example.ts` - Complete implementation from real debugging session
 **Testing anti-patterns reference**
 `test-driven-development` now includes `testing-anti-patterns.md` covering:
 - Testing mock behavior instead of real behavior
 - Adding test-only methods to production classes
 - Mocking without understanding dependencies
 - Incomplete mocks that hide structural assumptions
 **Skill test infrastructure**
 Three new test frameworks for validating skill behavior:
 `tests/skill-triggering/` - Validates skills trigger from naive prompts without explicit naming. Tests 6 skills to ensure descriptions alone are sufficient.
 `tests/claude-code/` - Integration tests using `claude -p` for headless testing. Verifies skill usage via session transcript (JSONL) analysis. Includes `analyze-token-usage.py` for cost tracking.
 `tests/subagent-driven-dev/` - End-to-end workflow validation with two complete test projects:
 - `go-fractals/` - CLI tool with Sierpinski/Mandelbrot (10 tasks)
 - `svelte-todo/` - CRUD app with localStorage and Playwright (12 tasks)
 ### Major Changes
 **DOT flowcharts as executable specifications**
 Rewrote key skills using DOT/GraphViz flowcharts as the authoritative process definition. Prose becomes supporting content.
 **The Description Trap** (documented in `writing-skills`): Discovered that skill descriptions override flowchart content when descriptions contain workflow summaries. Claude follows the short description instead of reading the detailed flowchart. Fix: descriptions must be trigger-only ("Use when X") with no process details.
 **Skill priority in using-superpowers**
 When multiple skills apply, process skills (brainstorming, debugging) now explicitly come before implementation skills. "Build X" triggers brainstorming first, then domain skills.
 **brainstorming trigger strengthened**
 Description changed to imperative: "You MUST use this before any creative work—creating features, building components, adding functionality, or modifying behavior."
 ### Breaking Changes
 **Skill consolidation** - Six standalone skills merged:
 - `root-cause-tracing`, `defense-in-depth`, `condition-based-waiting` → bundled in `systematic-debugging/`
 - `testing-skills-with-subagents` → bundled in `writing-skills/`
 - `testing-anti-patterns` → bundled in `test-driven-development/`
 - `sharing-skills` removed (obsolete)
 ### Other Improvements
 - **render-graphs.js** - Tool to extract DOT diagrams from skills and render to SVG
 - **Rationalizations table** in using-superpowers - Scannable format including new entries: "I need more context first", "Let me explore first", "This feels productive"
 - **docs/testing.md** - Guide to testing skills with Claude Code integration tests
 ---
 ## v3.6.2 (2025-12-03)
 ### Fixed
 - **Linux Compatibility**: Fixed polyglot hook wrapper (`run-hook.cmd`) to use POSIX-compliant syntax
  - Replaced bash-specific `${BASH_SOURCE[0]:-$0}` with standard `$0` on line 16
  - Resolves "Bad substitution" error on Ubuntu/Debian systems where `/bin/sh` is dash
  - Fixes #141
 ---
 ## v3.5.1 (2025-11-24)
 ### Changed
 - **OpenCode Bootstrap Refactor**: Switched from `chat.message` hook to `session.created` event for bootstrap injection
  - Bootstrap now injects at session creation via `session.prompt()` with `noReply: true`
  - Explicitly tells the model that using-superpowers is already loaded to prevent redundant skill loading
  - Consolidated bootstrap content generation into shared `getBootstrapContent()` helper
  - Cleaner single-implementation approach (removed fallback pattern)
 ---
 ## v3.5.0 (2025-11-23)
 ### Added
 - **OpenCode Support**: Native JavaScript plugin for OpenCode.ai
  - Custom tools: `use_skill` and `find_skills`
  - Message insertion pattern for skill persistence across context compaction
  - Automatic context injection via chat.message hook
  - Auto re-injection on session.compacted events
  - Three-tier skill priority: project > personal > superpowers
  - Project-local skills support (`.opencode/skills/`)
  - Shared core module (`lib/skills-core.js`) for code reuse with Codex
  - Automated test suite with proper isolation (`tests/opencode/`)
  - Platform-specific documentation (`docs/README.opencode.md`, `docs/README.codex.md`)
 ### Changed
 - **Refactored Codex Implementation**: Now uses shared `lib/skills-core.js` ES module
  - Eliminates code duplication between Codex and OpenCode
  - Single source of truth for skill discovery and parsing
  - Codex successfully loads ES modules via Node.js interop
 - **Improved Documentation**: Rewrote README to explain problem/solution clearly
  - Removed duplicate sections and conflicting information
  - Added complete workflow description (brainstorm → plan → execute → finish)
  - Simplified platform installation instructions
  - Emphasized skill-checking protocol over automatic activation claims
 ---
 ## v3.4.1 (2025-10-31)
 ### Improvements
 - Optimized superpowers bootstrap to eliminate redundant skill execution. The `using-superpowers` skill content is now provided directly in session context, with clear guidance to use the Skill tool only for other skills. This reduces overhead and prevents the confusing loop where agents would execute `using-superpowers` manually despite already having the content from session start.
 ## v3.4.0 (2025-10-30)
 ### Improvements
 - Simplified `brainstorming` skill to return to original conversational vision. Removed heavyweight 6-phase process with formal checklists in favor of natural dialogue: ask questions one at a time, then present design in 200-300 word sections with validation. Keeps documentation and implementation handoff features.
 ## v3.3.1 (2025-10-28)
 ### Improvements
 - Updated `brainstorming` skill to require autonomous recon before questioning, encourage recommendation-driven decisions, and prevent agents from delegating prioritization back to humans.
 - Applied writing clarity improvements to `brainstorming` skill following Strunk's "Elements of Style" principles (omitted needless words, converted negative to positive form, improved parallel construction).
 ### Bug Fixes
 - Clarified `writing-skills` guidance so it points to the correct agent-specific personal skill directories (`~/.claude/skills` for Claude Code, `~/.codex/skills` for Codex).
 ## v3.3.0 (2025-10-28)
 ### New Features
 **Experimental Codex Support**
 - Added unified `superpowers-codex` script with bootstrap/use-skill/find-skills commands
 - Cross-platform Node.js implementation (works on Windows, macOS, Linux)
 - Namespaced skills: `superpowers:skill-name` for superpowers skills, `skill-name` for personal
 - Personal skills override superpowers skills when names match
 - Clean skill display: shows name/description without raw frontmatter
 - Helpful context: shows supporting files directory for each skill
 - Tool mapping for Codex: TodoWrite→update_plan, subagents→manual fallback, etc.
 - Bootstrap integration with minimal AGENTS.md for automatic startup
 - Complete installation guide and bootstrap instructions specific to Codex
 **Key differences from Claude Code integration:**
 - Single unified script instead of separate tools
 - Tool substitution system for Codex-specific equivalents
 - Simplified subagent handling (manual work instead of delegation)
 - Updated terminology: "Superpowers skills" instead of "Core skills"
 ### Files Added
 - `.codex/INSTALL.md` - Installation guide for Codex users
 - `.codex/superpowers-bootstrap.md` - Bootstrap instructions with Codex adaptations
 - `.codex/superpowers-codex` - Unified Node.js executable with all functionality
 **Note:** Codex support is experimental. The integration provides core superpowers functionality but may require refinement based on user feedback.
 ## v3.2.3 (2025-10-23)
 ### Improvements
--- a/agents/code-reviewer.md
+++ b/agents/code-reviewer.md
@@ -1,8 +1,7 @@
 ---
 name: code-reviewer
-description: |
+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>
-  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>
+model: sonnet
 model: inherit
 ---
 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.
--- a/codex/INSTALL.md
+++ b/codex/INSTALL.md
@@ -0,0 +1,135 @@
 # Installing Superpowers for Codex
 This guide will help you install and set up the Superpowers skill system for Codex.
 ## Quick Installation
 1. **Clone Superpowers to ~/.codex/superpowers/**:
   ```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. **Add script paths to your environment** (optional but recommended):
   ```bash
   echo 'export PATH="$HOME/.codex/superpowers/scripts:$PATH"' >> ~/.bashrc
   source ~/.bashrc
   ```
 ## Directory Structure
 After installation, you'll have:
 ```
 ~/.codex/
 ├── superpowers/           # Core superpowers repository
 │   ├── skills/           # Core skills (brainstorming, TDD, etc.)
 │   ├── scripts/          # find-skills and skill-run tools
 │   └── .codex/           # Codex-specific configuration
 └── skills/               # Your personal skills (override core)
    └── category/
        └── skill-name/
            └── SKILL.md
 ```
 ## Tool Usage
 ### Finding Skills
 ```bash
 find-skills                    # List all available skills
 find-skills brainstorm        # Filter skills by pattern
 ```
 ### Running Skills
 ```bash
 skill-run brainstorming              # Load a skill
 skill-run skills/brainstorming       # Same thing
 ```
 ## Skill Override System
 Personal skills in `~/.codex/skills/` take precedence over core skills:
 - **Core skill**: `~/.codex/superpowers/skills/brainstorming/SKILL.md`
 - **Personal override**: `~/.codex/skills/brainstorming/SKILL.md` ← This wins
 ## Bootstrap Setup
 The bootstrap system ensures Codex automatically:
 1. Reads the superpowers-bootstrap.md on startup
 2. Runs find-skills to show available skills
 3. Knows how to use the skill tools
 See `~/.codex/AGENTS.md` for the bootstrap configuration.
 ## Troubleshooting
 ### Scripts not found
 ```bash
 # Add to PATH or use full paths:
 ~/.codex/superpowers/scripts/find-skills
 ~/.codex/superpowers/scripts/skill-run
 ```
 ### No skills showing
 ```bash
 # Check directory structure:
 ls ~/.codex/superpowers/skills/
 ls ~/.codex/skills/
 ```
 ### Permission errors
 ```bash
 # Make scripts executable:
 chmod +x ~/.codex/superpowers/scripts/*
 ```
 ## Creating Personal Skills
 1. Create directory structure:
   ```bash
   mkdir -p ~/.codex/skills/my-category/my-skill
   ```
 2. Create SKILL.md with frontmatter:
   ```markdown
   ---
   name: My Skill Name
   description: What this skill does
   when_to_use: When to apply this skill
   ---
   # My Skill
   Skill content here...
   ```
 3. Test it:
   ```bash
   find-skills my-skill
   skill-run my-skill
   ```
 ## Integration with Codex
 Once installed, Codex will automatically have access to:
 - **find-skills**: Discover available skills
 - **skill-run**: Load and apply skills
 - **Mandatory workflows**: Brainstorming before coding, systematic debugging, etc.
 - **TodoWrite integration**: Checklist tracking from skills
 The bootstrap ensures these tools are available from the first Codex session.
 ## Compatibility Notes
 - Scripts are compatible with bash 3.2+ (works on macOS and Linux)
 - No external dependencies required
 - Works with existing Codex configuration
--- a/codex/superpowers-bootstrap.md
+++ b/codex/superpowers-bootstrap.md
@@ -0,0 +1,131 @@
 # Superpowers Bootstrap for Codex
 <EXTREMELY_IMPORTANT>
 You have superpowers.
 **Tool path for running skills:**
 - superpowers-codex: ~/.codex/superpowers/scripts/superpowers-codex
 **Important:** ALL AVAILABLE SKILLS ARE DISCLOSED ABOVE. You have complete visibility into every skill at session start.
 **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 → `codex --yolo exec "prompt"` (see subagent section below)
 - `Skill` tool → `superpowers-codex use-skill` command (already available)
 - `Read`, `Write`, `Edit`, `Bash` → Use your native tools with similar functions
 </EXTREMELY_IMPORTANT>
 ## Getting Started with Skills
 Two skill libraries work together:
 - **Superpowers skills** at `~/.codex/superpowers/skills/` (from superpowers repository)
 - **Personal skills** at `~/.codex/skills/` (yours to create and share)
 Personal skills shadow superpowers skills when names match.
 ## Critical Rules
 1. **Use skill-run before announcing skill usage.** The bootstrap does NOT read skills for you. Announcing without calling skill-run = lying.
 2. **Follow mandatory workflows.** Brainstorming before coding. Check for skills before ANY task.
 3. **Create TodoWrite todos for checklists.** Mental tracking = steps get skipped. Every time.
 ## Mandatory Workflow: Before ANY Task
 **1. Review skills list** (completely disclosed above - no searching needed).
 **2. If relevant skill exists, YOU MUST use it:**
 - Use superpowers-codex: `~/.codex/superpowers/scripts/superpowers-codex use-skill superpowers:skill-name`
 - Read ENTIRE output, not just summary
 - Announce: "I've read the [Skill Name] skill and I'm using it to [purpose]"
 - Follow it exactly
 **Don't rationalize:**
 - "I remember this skill" - Skills evolve. Read the current version.
 - "Bootstrap showed it to me" - That was just the list. Read the actual skill.
 - "This doesn't count as a task" - It counts. Find and read skills.
 **Why:** Skills document proven techniques that save time and prevent mistakes. Not using available skills means repeating solved problems and making known errors.
 ## Skills with Checklists
 If a skill has a checklist, YOU MUST create TodoWrite todos for EACH item.
 **Don't:**
 - Work through checklist mentally
 - Skip creating todos "to save time"
 - Batch multiple items into one todo
 - Mark complete without doing them
 **Why:** Checklists without TodoWrite tracking = steps get skipped. Every time.
 ## How to Use skill-run
 Every skill has the same structure:
 1. **Frontmatter** - `when_to_use` tells you if this skill matches your situation
 2. **Overview** - Core principle in 1-2 sentences
 3. **Quick Reference** - Scan for your specific pattern
 4. **Implementation** - Full details and examples
 5. **Supporting files** - Load only when implementing
 **Many skills contain rigid rules (TDD, debugging, verification).** Follow them exactly. Don't adapt away the discipline.
 **Some skills are flexible patterns (architecture, naming).** Adapt core principles to your context.
 ## Instructions ≠ Permission to Skip Workflows
 Your human partner's specific instructions describe WHAT to do, not HOW.
 "Add X", "Fix Y" = the goal, NOT permission to skip brainstorming, TDD, or RED-GREEN-REFACTOR.
 ## Summary
 **Starting any task:**
 1. Run find-skills to check for relevant skills
 2. If relevant skill exists → Use skill-run with full path
 3. Announce you're using it
 4. Follow what it says
 **Skill has checklist?** TodoWrite for every item.
 **Finding a relevant skill = mandatory to read and use it. Not optional.**
 ## Subagent Orchestration for Codex
 When skills reference dispatching subagents or parallel agents, use Codex's subagent capabilities:
 **Launch subagents with:**
 ```bash
 codex --yolo exec "your detailed prompt here"
 ```
 **Key guidelines:**
 1. **Always quote/escape prompts** - avoid unescaped backticks or `$()` that shell might interpolate
 2. **Set timeout for long tasks** - use `timeout_ms: 1800000` (30 minutes) in your bash calls
 3. **Parallel execution** - use background jobs (`& ... & wait`) but check individual logs for completion
 4. **Lightweight prompts** - subagents inherit CLI defaults, so keep prompts focused and clear
 **Example:**
 ```bash
 # Single subagent
 codex --yolo exec "Debug the authentication bug in user.py and propose a fix"
 # Parallel subagents
 codex --yolo exec "Test the API endpoints" &
 codex --yolo exec "Review the database schema" &
 wait
 # Using superpowers skills in subagents
 codex --yolo exec "Use superpowers:systematic-debugging to find the root cause of the login failure"
 ```
 **When to use subagents:**
 - Skills mention "dispatching parallel agents"
 - Tasks that can be broken into independent work
 - Code review, testing, or investigation that benefits from fresh perspective
 ---
--- a/commands/brainstorm.md
+++ b/commands/brainstorm.md
@@ -1,5 +1,5 @@
 ---
-description: "Deprecated - use the superpowers:brainstorming skill instead"
+description: Interactive design refinement using Socratic method
 ---
-Tell your human partner that this command is deprecated and will be removed in the next major release. They should ask you to use the "superpowers brainstorming" skill instead.
+Use and follow the brainstorming skill exactly as written
--- a/commands/execute-plan.md
+++ b/commands/execute-plan.md
@@ -1,5 +1,5 @@
 ---
-description: "Deprecated - use the superpowers:executing-plans skill instead"
+description: Execute plan in batches with review checkpoints
 ---
-Tell your human partner that this command is deprecated and will be removed in the next major release. They should ask you to use the "superpowers executing-plans" skill instead.
+Use the executing-plans skill exactly as written
--- a/commands/write-plan.md
+++ b/commands/write-plan.md
@@ -1,5 +1,5 @@
 ---
-description: "Deprecated - use the superpowers:writing-plans skill instead"
+description: Create detailed implementation plan with bite-sized tasks
 ---
-Tell your human partner that this command is deprecated and will be removed in the next major release. They should ask you to use the "superpowers writing-plans" skill instead.
+Use the writing-plans skill exactly as written
--- a/docs/README.codex.md
+++ b/docs/README.codex.md
@@ -1,126 +0,0 @@
 # Superpowers for Codex
 Guide for using Superpowers with OpenAI Codex via native skill discovery.
 ## 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 CLI
 - Git
 ### Steps
 1. Clone the repo:
   ```bash
   git clone https://github.com/obra/superpowers.git ~/.codex/superpowers
   ```
 2. Create the skills symlink:
   ```bash
   mkdir -p ~/.agents/skills
   ln -s ~/.codex/superpowers/skills ~/.agents/skills/superpowers
   ```
 3. Restart Codex.
 4. **For subagent skills** (optional): Skills like `dispatching-parallel-agents` and `subagent-driven-development` require Codex's multi-agent feature. Add to your Codex config:
   ```toml
   [features]
   multi_agent = true
   ```
 ### Windows
 Use a junction instead of a symlink (works without Developer Mode):
 ```powershell
 New-Item -ItemType Directory -Force -Path "$env:USERPROFILE\.agents\skills"
 cmd /c mklink /J "$env:USERPROFILE\.agents\skills\superpowers" "$env:USERPROFILE\.codex\superpowers\skills"
 ```
 ## How It Works
 Codex has native skill discovery — it scans `~/.agents/skills/` at startup, parses SKILL.md frontmatter, and loads skills on demand. Superpowers skills are made visible through a single symlink:
 ```
 ~/.agents/skills/superpowers/ → ~/.codex/superpowers/skills/
 ```
 The `using-superpowers` skill is discovered automatically and enforces skill usage discipline — no additional configuration needed.
 ## Usage
 Skills are discovered automatically. Codex activates them when:
 - You mention a skill by name (e.g., "use brainstorming")
 - The task matches a skill's description
 - The `using-superpowers` skill directs Codex to use one
 ### Personal Skills
 Create your own skills in `~/.agents/skills/`:
 ```bash
 mkdir -p ~/.agents/skills/my-skill
 ```
 Create `~/.agents/skills/my-skill/SKILL.md`:
 ```markdown
 ---
 name: my-skill
 description: Use when [condition] - [what it does]
 ---
 # My Skill
 [Your skill content here]
 ```
 The `description` field is how Codex decides when to activate a skill automatically — write it as a clear trigger condition.
 ## Updating
 ```bash
 cd ~/.codex/superpowers && git pull
 ```
 Skills update instantly through the symlink.
 ## Uninstalling
 ```bash
 rm ~/.agents/skills/superpowers
 ```
 **Windows (PowerShell):**
 ```powershell
 Remove-Item "$env:USERPROFILE\.agents\skills\superpowers"
 ```
 Optionally delete the clone: `rm -rf ~/.codex/superpowers` (Windows: `Remove-Item -Recurse -Force "$env:USERPROFILE\.codex\superpowers"`).
 ## Troubleshooting
 ### Skills not showing up
 1. Verify the symlink: `ls -la ~/.agents/skills/superpowers`
 2. Check skills exist: `ls ~/.codex/superpowers/skills`
 3. Restart Codex — skills are discovered at startup
 ### Windows junction issues
 Junctions normally work without special permissions. If creation fails, try running PowerShell as administrator.
 ## Getting Help
 - Report issues: https://github.com/obra/superpowers/issues
 - Main documentation: https://github.com/obra/superpowers
--- a/docs/README.opencode.md
+++ b/docs/README.opencode.md
@@ -1,130 +0,0 @@
 # Superpowers for OpenCode
 Complete guide for using Superpowers with [OpenCode.ai](https://opencode.ai).
 ## Installation
 Add superpowers to the `plugin` array in your `opencode.json` (global or project-level):
 ```json
 {
  "plugin": ["superpowers@git+https://github.com/obra/superpowers.git"]
 }
 ```
 Restart OpenCode. The plugin auto-installs via Bun and registers all skills automatically.
 Verify by asking: "Tell me about your superpowers"
 ### Migrating from the old symlink-based install
 If you previously installed superpowers using `git clone` and symlinks, remove the old setup:
 ```bash
 # 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
 ```
 Then follow the installation steps above.
 ## Usage
 ### Finding Skills
 Use OpenCode's native `skill` tool to list all available skills:
 ```
 use skill tool to list skills
 ```
 ### Loading a Skill
 ```
 use skill tool to load superpowers/brainstorming
 ```
 ### Personal Skills
 Create your own skills in `~/.config/opencode/skills/`:
 ```bash
 mkdir -p ~/.config/opencode/skills/my-skill
 ```
 Create `~/.config/opencode/skills/my-skill/SKILL.md`:
 ```markdown
 ---
 name: my-skill
 description: Use when [condition] - [what it does]
 ---
 # My Skill
 [Your skill content here]
 ```
 ### Project Skills
 Create project-specific skills in `.opencode/skills/` within your project.
 **Skill Priority:** Project skills > Personal skills > Superpowers skills
 ## Updating
 Superpowers updates automatically when you restart OpenCode. The plugin is re-installed from the git repository on each launch.
 To pin a specific version, use a branch or tag:
 ```json
 {
  "plugin": ["superpowers@git+https://github.com/obra/superpowers.git#v5.0.3"]
 }
 ```
 ## How It Works
 The plugin does two things:
 1. **Injects bootstrap context** via the `experimental.chat.system.transform` hook, adding superpowers awareness to every conversation.
 2. **Registers the skills directory** via the `config` hook, so OpenCode discovers all superpowers skills without symlinks or manual config.
 ### Tool Mapping
 Skills written for Claude Code are automatically adapted for OpenCode:
 - `TodoWrite` → `todowrite`
 - `Task` with subagents → OpenCode's `@mention` system
 - `Skill` tool → OpenCode's native `skill` tool
 - File operations → Native OpenCode tools
 ## Troubleshooting
 ### Plugin not loading
 1. Check OpenCode logs: `opencode run --print-logs "hello" 2>&1 | grep -i superpowers`
 2. Verify the plugin line in your `opencode.json` is correct
 3. Make sure you're running a recent version of OpenCode
 ### Skills not found
 1. Use OpenCode's `skill` tool to list available skills
 2. Check that the plugin is loading (see above)
 3. Each skill needs a `SKILL.md` file with valid YAML frontmatter
 ### Bootstrap not appearing
 1. Check OpenCode version supports `experimental.chat.system.transform` hook
 2. Restart OpenCode after config changes
 ## Getting Help
 - Report issues: https://github.com/obra/superpowers/issues
 - Main documentation: https://github.com/obra/superpowers
 - OpenCode docs: https://opencode.ai/docs/
--- a/docs/plans/2025-11-22-opencode-support-design.md
+++ b/docs/plans/2025-11-22-opencode-support-design.md
@@ -1,294 +0,0 @@
 # OpenCode Support Design
 **Date:** 2025-11-22
 **Author:** Bot & Jesse
 **Status:** Design Complete, Awaiting Implementation
 ## Overview
 Add full superpowers support for OpenCode.ai using a native OpenCode plugin architecture that shares core functionality with the existing Codex implementation.
 ## Background
 OpenCode.ai is a coding agent similar to Claude Code and Codex. Previous attempts to port superpowers to OpenCode (PR #93, PR #116) used file-copying approaches. This design takes a different approach: building a native OpenCode plugin using their JavaScript/TypeScript plugin system while sharing code with the Codex implementation.
 ### Key Differences Between Platforms
 - **Claude Code**: Native Anthropic plugin system + file-based skills
 - **Codex**: No plugin system → bootstrap markdown + CLI script
 - **OpenCode**: JavaScript/TypeScript plugins with event hooks and custom tools API
 ### OpenCode's Agent System
 - **Primary agents**: Build (default, full access) and Plan (restricted, read-only)
 - **Subagents**: General (research, searching, multi-step tasks)
 - **Invocation**: Automatic dispatch by primary agents OR manual `@mention` syntax
 - **Configuration**: Custom agents in `opencode.json` or `~/.config/opencode/agent/`
 ## Architecture
 ### High-Level Structure
 1. **Shared Core Module** (`lib/skills-core.js`)
   - Common skill discovery and parsing logic
   - Used by both Codex and OpenCode implementations
 2. **Platform-Specific Wrappers**
   - Codex: CLI script (`.codex/superpowers-codex`)
   - OpenCode: Plugin module (`.opencode/plugin/superpowers.js`)
 3. **Skill Directories**
   - Core: `~/.config/opencode/superpowers/skills/` (or installed location)
   - Personal: `~/.config/opencode/skills/` (shadows core skills)
 ### Code Reuse Strategy
 Extract common functionality from `.codex/superpowers-codex` into shared module:
 ```javascript
 // lib/skills-core.js
 module.exports = {
  extractFrontmatter(filePath),      // Parse name + description from YAML
  findSkillsInDir(dir, maxDepth),    // Recursive SKILL.md discovery
  findAllSkills(dirs),                // Scan multiple directories
  resolveSkillPath(skillName, dirs), // Handle shadowing (personal > core)
  checkForUpdates(repoDir)           // Git fetch/status check
 };
 ```
 ### Skill Frontmatter Format
 Current format (no `when_to_use` field):
 ```yaml
 ---
 name: skill-name
 description: Use when [condition] - [what it does]; [additional context]
 ---
 ```
 ## OpenCode Plugin Implementation
 ### Custom Tools
 **Tool 1: `use_skill`**
 Loads a specific skill's content into the conversation (equivalent to Claude's Skill tool).
 ```javascript
 {
  name: 'use_skill',
  description: 'Load and read a specific skill to guide your work',
  schema: z.object({
    skill_name: z.string().describe('Name of skill (e.g., "superpowers:brainstorming")')
  }),
  execute: async ({ skill_name }) => {
    const { skillPath, content, frontmatter } = resolveAndReadSkill(skill_name);
    const skillDir = path.dirname(skillPath);
    return `# ${frontmatter.name}
 # ${frontmatter.description}
 # Supporting tools and docs are in ${skillDir}
 # ============================================
 ${content}`;
  }
 }
 ```
 **Tool 2: `find_skills`**
 Lists all available skills with metadata.
 ```javascript
 {
  name: 'find_skills',
  description: 'List all available skills',
  schema: z.object({}),
  execute: async () => {
    const skills = discoverAllSkills();
    return skills.map(s =>
      `${s.namespace}:${s.name}
  ${s.description}
  Directory: ${s.directory}
 `).join('\n');
  }
 }
 ```
 ### Session Startup Hook
 When a new session starts (`session.started` event):
 1. **Inject using-superpowers content**
   - Full content of the using-superpowers skill
   - Establishes mandatory workflows
 2. **Run find_skills automatically**
   - Display full list of available skills upfront
   - Include skill directories for each
 3. **Inject tool mapping instructions**
   ```markdown
   **Tool Mapping for OpenCode:**
   When skills reference tools you don't have, substitute:
   - `TodoWrite` → `update_plan`
   - `Task` with subagents → Use OpenCode subagent system (@mention)
   - `Skill` tool → `use_skill` custom tool
   - Read, Write, Edit, Bash → Your native equivalents
   **Skill directories contain:**
   - Supporting scripts (run with bash)
   - Additional documentation (read with read tool)
   - Utilities specific to that skill
   ```
 4. **Check for updates** (non-blocking)
   - Quick git fetch with timeout
   - Notify if updates available
 ### Plugin Structure
 ```javascript
 // .opencode/plugin/superpowers.js
 const skillsCore = require('../../lib/skills-core');
 const path = require('path');
 const fs = require('fs');
 const { z } = require('zod');
 export const SuperpowersPlugin = async ({ client, directory, $ }) => {
  const superpowersDir = path.join(process.env.HOME, '.config/opencode/superpowers');
  const personalDir = path.join(process.env.HOME, '.config/opencode/skills');
  return {
    'session.started': async () => {
      const usingSuperpowers = await readSkill('using-superpowers');
      const skillsList = await findAllSkills();
      const toolMapping = getToolMappingInstructions();
      return {
        context: `${usingSuperpowers}\n\n${skillsList}\n\n${toolMapping}`
      };
    },
    tools: [
      {
        name: 'use_skill',
        description: 'Load and read a specific skill',
        schema: z.object({
          skill_name: z.string()
        }),
        execute: async ({ skill_name }) => {
          // Implementation using skillsCore
        }
      },
      {
        name: 'find_skills',
        description: 'List all available skills',
        schema: z.object({}),
        execute: async () => {
          // Implementation using skillsCore
        }
      }
    ]
  };
 };
 ```
 ## File Structure
 ```
 superpowers/
 ├── lib/
 │   └── skills-core.js           # NEW: Shared skill logic
 ├── .codex/
 │   ├── superpowers-codex        # UPDATED: Use skills-core
 │   ├── superpowers-bootstrap.md
 │   └── INSTALL.md
 ├── .opencode/
 │   ├── plugin/
 │   │   └── superpowers.js       # NEW: OpenCode plugin
 │   └── INSTALL.md               # NEW: Installation guide
 └── skills/                       # Unchanged
 ```
 ## Implementation Plan
 ### Phase 1: Refactor Shared Core
 1. Create `lib/skills-core.js`
   - Extract frontmatter parsing from `.codex/superpowers-codex`
   - Extract skill discovery logic
   - Extract path resolution (with shadowing)
   - Update to use only `name` and `description` (no `when_to_use`)
 2. Update `.codex/superpowers-codex` to use shared core
   - Import from `../lib/skills-core.js`
   - Remove duplicated code
   - Keep CLI wrapper logic
 3. Test Codex implementation still works
   - Verify bootstrap command
   - Verify use-skill command
   - Verify find-skills command
 ### Phase 2: Build OpenCode Plugin
 1. Create `.opencode/plugin/superpowers.js`
   - Import shared core from `../../lib/skills-core.js`
   - Implement plugin function
   - Define custom tools (use_skill, find_skills)
   - Implement session.started hook
 2. Create `.opencode/INSTALL.md`
   - Installation instructions
   - Directory setup
   - Configuration guidance
 3. Test OpenCode implementation
   - Verify session startup bootstrap
   - Verify use_skill tool works
   - Verify find_skills tool works
   - Verify skill directories are accessible
 ### Phase 3: Documentation & Polish
 1. Update README with OpenCode support
 2. Add OpenCode installation to main docs
 3. Update RELEASE-NOTES
 4. Test both Codex and OpenCode work correctly
 ## Next Steps
 1. **Create isolated workspace** (using git worktrees)
   - Branch: `feature/opencode-support`
 2. **Follow TDD where applicable**
   - Test shared core functions
   - Test skill discovery and parsing
   - Integration tests for both platforms
 3. **Incremental implementation**
   - Phase 1: Refactor shared core + update Codex
   - Verify Codex still works before moving on
   - Phase 2: Build OpenCode plugin
   - Phase 3: Documentation and polish
 4. **Testing strategy**
   - Manual testing with real OpenCode installation
   - Verify skill loading, directories, scripts work
   - Test both Codex and OpenCode side-by-side
   - Verify tool mappings work correctly
 5. **PR and merge**
   - Create PR with complete implementation
   - Test in clean environment
   - Merge to main
 ## Benefits
 - **Code reuse**: Single source of truth for skill discovery/parsing
 - **Maintainability**: Bug fixes apply to both platforms
 - **Extensibility**: Easy to add future platforms (Cursor, Windsurf, etc.)
 - **Native integration**: Uses OpenCode's plugin system properly
 - **Consistency**: Same skill experience across all platforms
--- a/docs/plans/2025-11-22-opencode-support-implementation.md
+++ b/docs/plans/2025-11-22-opencode-support-implementation.md
--- a/docs/plans/2025-11-28-skills-improvements-from-user-feedback.md
+++ b/docs/plans/2025-11-28-skills-improvements-from-user-feedback.md
@@ -1,711 +0,0 @@
 # Skills Improvements from User Feedback
 **Date:** 2025-11-28
 **Status:** Draft
 **Source:** Two Claude instances using superpowers in real development scenarios
 ---
 ## Executive Summary
 Two Claude instances provided detailed feedback from actual development sessions. Their feedback reveals **systematic gaps** in current skills that allowed preventable bugs to ship despite following the skills.
 **Critical insight:** These are problem reports, not just solution proposals. The problems are real; the solutions need careful evaluation.
 **Key themes:**
 1. **Verification gaps** - We verify operations succeed but not that they achieve intended outcomes
 2. **Process hygiene** - Background processes accumulate and interfere across subagents
 3. **Context optimization** - Subagents get too much irrelevant information
 4. **Self-reflection missing** - No prompt to critique own work before handoff
 5. **Mock safety** - Mocks can drift from interfaces without detection
 6. **Skill activation** - Skills exist but aren't being read/used
 ---
 ## Problems Identified
 ### Problem 1: Configuration Change Verification Gap
 **What happened:**
 - Subagent tested "OpenAI integration"
 - Set `OPENAI_API_KEY` env var
 - Got status 200 responses
 - Reported "OpenAI integration working"
 - **BUT** response contained `"model": "claude-sonnet-4-20250514"` - was actually using Anthropic
 **Root cause:**
 `verification-before-completion` checks operations succeed but not that outcomes reflect intended configuration changes.
 **Impact:** High - False confidence in integration tests, bugs ship to production
 **Example failure pattern:**
 - Switch LLM provider → verify status 200 but don't check model name
 - Enable feature flag → verify no errors but don't check feature is active
 - Change environment → verify deployment succeeds but don't check environment vars
 ---
 ### Problem 2: Background Process Accumulation
 **What happened:**
 - Multiple subagents dispatched during session
 - Each started background server processes
 - Processes accumulated (4+ servers running)
 - Stale processes still bound to ports
 - Later E2E test hit stale server with wrong config
 - Confusing/incorrect test results
 **Root cause:**
 Subagents are stateless - don't know about previous subagents' processes. No cleanup protocol.
 **Impact:** Medium-High - Tests hit wrong server, false passes/failures, debugging confusion
 ---
 ### Problem 3: Context Bloat in Subagent Prompts
 **What happened:**
 - Standard approach: give subagent full plan file to read
 - Experiment: give only task + pattern + file + verify command
 - Result: Faster, more focused, single-attempt completion more common
 **Root cause:**
 Subagents waste tokens and attention on irrelevant plan sections.
 **Impact:** Medium - Slower execution, more failed attempts
 **What worked:**
 ```
 You are adding a single E2E test to packnplay's test suite.
 **Your task:** Add `TestE2E_FeaturePrivilegedMode` to `pkg/runner/e2e_test.go`
 **What to test:** A local devcontainer feature that requests `"privileged": true`
 in its metadata should result in the container running with `--privileged` flag.
 **Follow the exact pattern of TestE2E_FeatureOptionValidation** (at the end of the file)
 **After writing, run:** `go test -v ./pkg/runner -run TestE2E_FeaturePrivilegedMode -timeout 5m`
 ```
 ---
 ### Problem 4: No Self-Reflection Before Handoff
 **What happened:**
 - Added self-reflection prompt: "Look at your work with fresh eyes - what could be better?"
 - Implementer for Task 5 identified failing test was due to implementation bug, not test bug
 - Traced to line 99: `strings.Join(metadata.Entrypoint, " ")` creating invalid Docker syntax
 - Without self-reflection, would have just reported "test fails" without root cause
 **Root cause:**
 Implementers don't naturally step back and critique their own work before reporting completion.
 **Impact:** Medium - Bugs handed off to reviewer that implementer could have caught
 ---
 ### Problem 5: Mock-Interface Drift
 **What happened:**
 ```typescript
 // Interface defines close()
 interface PlatformAdapter {
  close(): Promise<void>;
 }
 // Code (BUGGY) calls cleanup()
 await adapter.cleanup();
 // Mock (MATCHES BUG) defines cleanup()
 vi.mock('web-adapter', () => ({
  WebAdapter: vi.fn().mockImplementation(() => ({
    cleanup: vi.fn().mockResolvedValue(undefined),  // Wrong!
  })),
 }));
 ```
 - Tests passed
 - Runtime crashed: "adapter.cleanup is not a function"
 **Root cause:**
 Mock derived from what buggy code calls, not from interface definition. TypeScript can't catch inline mocks with wrong method names.
 **Impact:** High - Tests give false confidence, runtime crashes
 **Why testing-anti-patterns didn't prevent this:**
 The skill covers testing mock behavior and mocking without understanding, but not the specific pattern of "derive mock from interface, not implementation."
 ---
 ### Problem 6: Code Reviewer File Access
 **What happened:**
 - Code reviewer subagent dispatched
 - Couldn't find test file: "The file doesn't appear to exist in the repository"
 - File actually exists
 - Reviewer didn't know to explicitly read it first
 **Root cause:**
 Reviewer prompts don't include explicit file reading instructions.
 **Impact:** Low-Medium - Reviews fail or incomplete
 ---
 ### Problem 7: Fix Workflow Latency
 **What happened:**
 - Implementer identifies bug during self-reflection
 - Implementer knows the fix
 - Current workflow: report → I dispatch fixer → fixer fixes → I verify
 - Extra round-trip adds latency without adding value
 **Root cause:**
 Rigid separation between implementer and fixer roles when implementer has already diagnosed.
 **Impact:** Low - Latency, but no correctness issue
 ---
 ### Problem 8: Skills Not Being Read
 **What happened:**
 - `testing-anti-patterns` skill exists
 - Neither human nor subagents read it before writing tests
 - Would have prevented some issues (though not all - see Problem 5)
 **Root cause:**
 No enforcement that subagents read relevant skills. No prompt includes skill reading.
 **Impact:** Medium - Skill investment wasted if not used
 ---
 ## Proposed Improvements
 ### 1. verification-before-completion: Add Configuration Change Verification
 **Add new section:**
 ```markdown
 ## Verifying Configuration Changes
 When testing changes to configuration, providers, feature flags, or environment:
 **Don't just verify the operation succeeded. Verify the output reflects the intended change.**
 ### Common Failure Pattern
 Operation succeeds because *some* valid config exists, but it's not the config you intended to test.
 ### Examples
 | Change | Insufficient | Required |
 |--------|-------------|----------|
 | Switch LLM provider | Status 200 | Response contains expected model name |
 | Enable feature flag | No errors | Feature behavior actually active |
 | Change environment | Deploy succeeds | Logs/vars reference new environment |
 | Set credentials | Auth succeeds | Authenticated user/context is correct |
 ### Gate Function
 ```
 BEFORE claiming configuration change works:
 1. IDENTIFY: What should be DIFFERENT after this change?
 2. LOCATE: Where is that difference observable?
   - Response field (model name, user ID)
   - Log line (environment, provider)
   - Behavior (feature active/inactive)
 3. RUN: Command that shows the observable difference
 4. VERIFY: Output contains expected difference
 5. ONLY THEN: Claim configuration change works
 Red flags:
  - "Request succeeded" without checking content
  - Checking status code but not response body
  - Verifying no errors but not positive confirmation
 ```
 **Why this works:**
 Forces verification of INTENT, not just operation success.
 ---
 ### 2. subagent-driven-development: Add Process Hygiene for E2E Tests
 **Add new section:**
 ```markdown
 ## Process Hygiene for E2E Tests
 When dispatching subagents that start services (servers, databases, message queues):
 ### Problem
 Subagents are stateless - they don't know about processes started by previous subagents. Background processes persist and can interfere with later tests.
 ### Solution
 **Before dispatching E2E test subagent, include cleanup in prompt:**
 ```
 BEFORE starting any services:
 1. Kill existing processes: pkill -f "<service-pattern>" 2>/dev/null || true
 2. Wait for cleanup: sleep 1
 3. Verify port free: lsof -i :<port> && echo "ERROR: Port still in use" || echo "Port free"
 AFTER tests complete:
 1. Kill the process you started
 2. Verify cleanup: pgrep -f "<service-pattern>" || echo "Cleanup successful"
 ```
 ### Example
 ```
 Task: Run E2E test of API server
 Prompt includes:
 "Before starting the server:
 - Kill any existing servers: pkill -f 'node.*server.js' 2>/dev/null || true
 - Verify port 3001 is free: lsof -i :3001 && exit 1 || echo 'Port available'
 After tests:
 - Kill the server you started
 - Verify: pgrep -f 'node.*server.js' || echo 'Cleanup verified'"
 ```
 ### Why This Matters
 - Stale processes serve requests with wrong config
 - Port conflicts cause silent failures
 - Process accumulation slows system
 - Confusing test results (hitting wrong server)
 ```
 **Trade-off analysis:**
 - Adds boilerplate to prompts
 - But prevents very confusing debugging
 - Worth it for E2E test subagents
 ---
 ### 3. subagent-driven-development: Add Lean Context Option
 **Modify Step 2: Execute Task with Subagent**
 **Before:**
 ```
 Read that task carefully from [plan-file].
 ```
 **After:**
 ```
 ## Context Approaches
 **Full Plan (default):**
 Use when tasks are complex or have dependencies:
 ```
 Read Task N from [plan-file] carefully.
 ```
 **Lean Context (for independent tasks):**
 Use when task is standalone and pattern-based:
 ```
 You are implementing: [1-2 sentence task description]
 File to modify: [exact path]
 Pattern to follow: [reference to existing function/test]
 What to implement: [specific requirement]
 Verification: [exact command to run]
 [Do NOT include full plan file]
 ```
 **Use lean context when:**
 - Task follows existing pattern (add similar test, implement similar feature)
 - Task is self-contained (doesn't need context from other tasks)
 - Pattern reference is sufficient (e.g., "follow TestE2E_FeatureOptionValidation")
 **Use full plan when:**
 - Task has dependencies on other tasks
 - Requires understanding of overall architecture
 - Complex logic that needs context
 ```
 **Example:**
 ```
 Lean context prompt:
 "You are adding a test for privileged mode in devcontainer features.
 File: pkg/runner/e2e_test.go
 Pattern: Follow TestE2E_FeatureOptionValidation (at end of file)
 Test: Feature with `"privileged": true` in metadata results in `--privileged` flag
 Verify: go test -v ./pkg/runner -run TestE2E_FeaturePrivilegedMode -timeout 5m
 Report: Implementation, test results, any issues."
 ```
 **Why this works:**
 Reduces token usage, increases focus, faster completion when appropriate.
 ---
 ### 4. subagent-driven-development: Add Self-Reflection Step
 **Modify Step 2: Execute Task with Subagent**
 **Add to prompt template:**
 ```
 When done, BEFORE reporting back:
 Take a step back and review your work with fresh eyes.
 Ask yourself:
 - Does this actually solve the task as specified?
 - Are there edge cases I didn't consider?
 - Did I follow the pattern correctly?
 - If tests are failing, what's the ROOT CAUSE (implementation bug vs test bug)?
 - What could be better about this implementation?
 If you identify issues during this reflection, fix them now.
 Then report:
 - What you implemented
 - Self-reflection findings (if any)
 - Test results
 - Files changed
 ```
 **Why this works:**
 Catches bugs implementer can find themselves before handoff. Documented case: identified entrypoint bug through self-reflection.
 **Trade-off:**
 Adds ~30 seconds per task, but catches issues before review.
 ---
 ### 5. requesting-code-review: Add Explicit File Reading
 **Modify the code-reviewer template:**
 **Add at the beginning:**
 ```markdown
 ## Files to Review
 BEFORE analyzing, read these files:
 1. [List specific files that changed in the diff]
 2. [Files referenced by changes but not modified]
 Use Read tool to load each file.
 If you cannot find a file:
 - Check exact path from diff
 - Try alternate locations
 - Report: "Cannot locate [path] - please verify file exists"
 DO NOT proceed with review until you've read the actual code.
 ```
 **Why this works:**
 Explicit instruction prevents "file not found" issues.
 ---
 ### 6. testing-anti-patterns: Add Mock-Interface Drift Anti-Pattern
 **Add new Anti-Pattern 6:**
 ```markdown
 ## Anti-Pattern 6: Mocks Derived from Implementation
 **The violation:**
 ```typescript
 // Code (BUGGY) calls cleanup()
 await adapter.cleanup();
 // Mock (MATCHES BUG) has cleanup()
 const mock = {
  cleanup: vi.fn().mockResolvedValue(undefined)
 };
 // Interface (CORRECT) defines close()
 interface PlatformAdapter {
  close(): Promise<void>;
 }
 ```
 **Why this is wrong:**
 - Mock encodes the bug into the test
 - TypeScript can't catch inline mocks with wrong method names
 - Test passes because both code and mock are wrong
 - Runtime crashes when real object is used
 **The fix:**
 ```typescript
 // ✅ GOOD: Derive mock from interface
 // Step 1: Open interface definition (PlatformAdapter)
 // Step 2: List methods defined there (close, initialize, etc.)
 // Step 3: Mock EXACTLY those methods
 const mock = {
  initialize: vi.fn().mockResolvedValue(undefined),
  close: vi.fn().mockResolvedValue(undefined),  // From interface!
 };
 // Now test FAILS because code calls cleanup() which doesn't exist
 // That failure reveals the bug BEFORE runtime
 ```
 ### Gate Function
 ```
 BEFORE writing any mock:
  1. STOP - Do NOT look at the code under test yet
  2. FIND: The interface/type definition for the dependency
  3. READ: The interface file
  4. LIST: Methods defined in the interface
  5. MOCK: ONLY those methods with EXACTLY those names
  6. DO NOT: Look at what your code calls
  IF your test fails because code calls something not in mock:
    ✅ GOOD - The test found a bug in your code
    Fix the code to call the correct interface method
    NOT the mock
  Red flags:
    - "I'll mock what the code calls"
    - Copying method names from implementation
    - Mock written without reading interface
    - "The test is failing so I'll add this method to the mock"
 ```
 **Detection:**
 When you see runtime error "X is not a function" and tests pass:
 1. Check if X is mocked
 2. Compare mock methods to interface methods
 3. Look for method name mismatches
 ```
 **Why this works:**
 Directly addresses the failure pattern from feedback.
 ---
 ### 7. subagent-driven-development: Require Skills Reading for Test Subagents
 **Add to prompt template when task involves testing:**
 ```markdown
 BEFORE writing any tests:
 1. Read testing-anti-patterns skill:
   Use Skill tool: superpowers:testing-anti-patterns
 2. Apply gate functions from that skill when:
   - Writing mocks
   - Adding methods to production classes
   - Mocking dependencies
 This is NOT optional. Tests that violate anti-patterns will be rejected in review.
 ```
 **Why this works:**
 Ensures skills are actually used, not just exist.
 **Trade-off:**
 Adds time to each task, but prevents entire classes of bugs.
 ---
 ### 8. subagent-driven-development: Allow Implementer to Fix Self-Identified Issues
 **Modify Step 2:**
 **Current:**
 ```
 Subagent reports back with summary of work.
 ```
 **Proposed:**
 ```
 Subagent performs self-reflection, then:
 IF self-reflection identifies fixable issues:
  1. Fix the issues
  2. Re-run verification
  3. Report: "Initial implementation + self-reflection fix"
 ELSE:
  Report: "Implementation complete"
 Include in report:
 - Self-reflection findings
 - Whether fixes were applied
 - Final verification results
 ```
 **Why this works:**
 Reduces latency when implementer already knows the fix. Documented case: would have saved one round-trip for entrypoint bug.
 **Trade-off:**
 Slightly more complex prompt, but faster end-to-end.
 ---
 ## Implementation Plan
 ### Phase 1: High-Impact, Low-Risk (Do First)
 1. **verification-before-completion: Configuration change verification**
   - Clear addition, doesn't change existing content
   - Addresses high-impact problem (false confidence in tests)
   - File: `skills/verification-before-completion/SKILL.md`
 2. **testing-anti-patterns: Mock-interface drift**
   - Adds new anti-pattern, doesn't modify existing
   - Addresses high-impact problem (runtime crashes)
   - File: `skills/testing-anti-patterns/SKILL.md`
 3. **requesting-code-review: Explicit file reading**
   - Simple addition to template
   - Fixes concrete problem (reviewers can't find files)
   - File: `skills/requesting-code-review/SKILL.md`
 ### Phase 2: Moderate Changes (Test Carefully)
 4. **subagent-driven-development: Process hygiene**
   - Adds new section, doesn't change workflow
   - Addresses medium-high impact (test reliability)
   - File: `skills/subagent-driven-development/SKILL.md`
 5. **subagent-driven-development: Self-reflection**
   - Changes prompt template (higher risk)
   - But documented to catch bugs
   - File: `skills/subagent-driven-development/SKILL.md`
 6. **subagent-driven-development: Skills reading requirement**
   - Adds prompt overhead
   - But ensures skills are actually used
   - File: `skills/subagent-driven-development/SKILL.md`
 ### Phase 3: Optimization (Validate First)
 7. **subagent-driven-development: Lean context option**
   - Adds complexity (two approaches)
   - Needs validation that it doesn't cause confusion
   - File: `skills/subagent-driven-development/SKILL.md`
 8. **subagent-driven-development: Allow implementer to fix**
   - Changes workflow (higher risk)
   - Optimization, not bug fix
   - File: `skills/subagent-driven-development/SKILL.md`
 ---
 ## Open Questions
 1. **Lean context approach:**
   - Should we make it the default for pattern-based tasks?
   - How do we decide which approach to use?
   - Risk of being too lean and missing important context?
 2. **Self-reflection:**
   - Will this slow down simple tasks significantly?
   - Should it only apply to complex tasks?
   - How do we prevent "reflection fatigue" where it becomes rote?
 3. **Process hygiene:**
   - Should this be in subagent-driven-development or a separate skill?
   - Does it apply to other workflows beyond E2E tests?
   - How do we handle cases where process SHOULD persist (dev servers)?
 4. **Skills reading enforcement:**
   - Should we require ALL subagents to read relevant skills?
   - How do we keep prompts from becoming too long?
   - Risk of over-documenting and losing focus?
 ---
 ## Success Metrics
 How do we know these improvements work?
 1. **Configuration verification:**
   - Zero instances of "test passed but wrong config was used"
   - Jesse doesn't say "that's not actually testing what you think"
 2. **Process hygiene:**
   - Zero instances of "test hit wrong server"
   - No port conflict errors during E2E test runs
 3. **Mock-interface drift:**
   - Zero instances of "tests pass but runtime crashes on missing method"
   - No method name mismatches between mocks and interfaces
 4. **Self-reflection:**
   - Measurable: Do implementer reports include self-reflection findings?
   - Qualitative: Do fewer bugs make it to code review?
 5. **Skills reading:**
   - Subagent reports reference skill gate functions
   - Fewer anti-pattern violations in code review
 ---
 ## Risks and Mitigations
 ### Risk: Prompt Bloat
 **Problem:** Adding all these requirements makes prompts overwhelming
 **Mitigation:**
 - Phase implementation (don't add everything at once)
 - Make some additions conditional (E2E hygiene only for E2E tests)
 - Consider templates for different task types
 ### Risk: Analysis Paralysis
 **Problem:** Too much reflection/verification slows execution
 **Mitigation:**
 - Keep gate functions quick (seconds, not minutes)
 - Make lean context opt-in initially
 - Monitor task completion times
 ### Risk: False Sense of Security
 **Problem:** Following checklist doesn't guarantee correctness
 **Mitigation:**
 - Emphasize gate functions are minimums, not maximums
 - Keep "use judgment" language in skills
 - Document that skills catch common failures, not all failures
 ### Risk: Skill Divergence
 **Problem:** Different skills give conflicting advice
 **Mitigation:**
 - Review changes across all skills for consistency
 - Document how skills interact (Integration sections)
 - Test with real scenarios before deployment
 ---
 ## Recommendation
 **Proceed with Phase 1 immediately:**
 - verification-before-completion: Configuration change verification
 - testing-anti-patterns: Mock-interface drift
 - requesting-code-review: Explicit file reading
 **Test Phase 2 with Jesse before finalizing:**
 - Get feedback on self-reflection impact
 - Validate process hygiene approach
 - Confirm skills reading requirement is worth overhead
 **Hold Phase 3 pending validation:**
 - Lean context needs real-world testing
 - Implementer-fix workflow change needs careful evaluation
 These changes address real problems documented by users while minimizing risk of making skills worse.
--- a/docs/plans/2026-01-17-visual-brainstorming.md
+++ b/docs/plans/2026-01-17-visual-brainstorming.md
@@ -1,571 +0,0 @@
 # 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
--- a/docs/superpowers/plans/2026-01-22-document-review-system.md
+++ b/docs/superpowers/plans/2026-01-22-document-review-system.md
@@ -1,301 +0,0 @@
 # 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"
 ```
--- a/docs/superpowers/plans/2026-02-19-visual-brainstorming-refactor.md
+++ b/docs/superpowers/plans/2026-02-19-visual-brainstorming-refactor.md
@@ -1,523 +0,0 @@
 # 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
 ```
--- a/docs/superpowers/plans/2026-03-11-zero-dep-brainstorm-server.md
+++ b/docs/superpowers/plans/2026-03-11-zero-dep-brainstorm-server.md
@@ -1,479 +0,0 @@
 # 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
 ```
--- a/docs/superpowers/plans/2026-03-23-codex-app-compatibility.md
+++ b/docs/superpowers/plans/2026-03-23-codex-app-compatibility.md
@@ -1,564 +0,0 @@
 # 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
 ./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.
--- a/docs/superpowers/specs/2026-01-22-document-review-system-design.md
+++ b/docs/superpowers/specs/2026-01-22-document-review-system-design.md
@@ -1,136 +0,0 @@
 # 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
--- a/docs/superpowers/specs/2026-02-19-visual-brainstorming-refactor-design.md
+++ b/docs/superpowers/specs/2026-02-19-visual-brainstorming-refactor-design.md
@@ -1,162 +0,0 @@
 # 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.
--- a/docs/superpowers/specs/2026-03-11-zero-dep-brainstorm-server-design.md
+++ b/docs/superpowers/specs/2026-03-11-zero-dep-brainstorm-server-design.md
@@ -1,118 +0,0 @@
 # 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).
--- a/docs/superpowers/specs/2026-03-23-codex-app-compatibility-design.md
+++ b/docs/superpowers/specs/2026-03-23-codex-app-compatibility-design.md
@@ -1,244 +0,0 @@
 # 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
--- a/docs/testing.md
+++ b/docs/testing.md
@@ -1,303 +0,0 @@
 # Testing Superpowers Skills
 This document describes how to test Superpowers skills, particularly the integration tests for complex skills like `subagent-driven-development`.
 ## Overview
 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.
 ## Test Structure
 ```
 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)
 ```
 ## Running Tests
 ### Integration Tests
 Integration tests execute real Claude Code sessions with actual skills:
 ```bash
 # Run the subagent-driven-development integration test
 cd tests/claude-code
 ./test-subagent-driven-development-integration.sh
 ```
 **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.
--- a/docs/windows/polyglot-hooks.md
+++ b/docs/windows/polyglot-hooks.md
@@ -1,212 +0,0 @@
 # 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.
 ## The Problem
 Claude Code runs hook commands through the system's default shell:
 - **Windows**: CMD.exe
 - **macOS/Linux**: bash or sh
 This creates several challenges:
 1. **Script execution**: Windows CMD can't execute `.sh` files directly - it tries to open them in a text editor
 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
 ## The Solution: Polyglot `.cmd` Wrapper
 A polyglot script is valid syntax in multiple languages simultaneously. Our wrapper is valid in both CMD and bash:
 ```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
 ```
 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
 ```json
 {
  "hooks": {
    "SessionStart": [
      {
        "matcher": "startup|resume|clear|compact",
        "hooks": [
          {
            "type": "command",
            "command": "\"${CLAUDE_PLUGIN_ROOT}/hooks/session-start.cmd\""
          }
        ]
      }
    ]
  }
 }
 ```
 Note: The path must be quoted because `${CLAUDE_PLUGIN_ROOT}` may contain spaces on Windows (e.g., `C:\Program Files\...`).
 ## Requirements
 ### 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
 ### Unix (macOS/Linux)
 - Standard bash or sh shell
 - The `.cmd` file must have execute permission (`chmod +x`)
 ## Writing Cross-Platform Hook Scripts
 Your actual hook logic goes in the `.sh` file. To ensure it works on Windows (via Git Bash):
 ### 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`)
 ### Example: JSON Escaping Without sed/awk
 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"
    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"
 }
 ```
 ## 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 "$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.
 ### 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.
 ### Script opens in text editor instead of running
 The hooks.json is pointing directly to the `.sh` file. Point to the `.cmd` wrapper instead.
 ### 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"
 ```
 ## 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
--- a/gemini-extension.json
+++ b/gemini-extension.json
@@ -1,6 +0,0 @@
 {
  "name": "superpowers",
  "description": "Core skills library: TDD, debugging, collaboration patterns, and proven techniques",
  "version": "5.0.6",
  "contextFileName": "GEMINI.md"
 }
--- a/hooks/hooks-cursor.json
+++ b/hooks/hooks-cursor.json
@@ -1,10 +0,0 @@
 {
  "version": 1,
  "hooks": {
    "sessionStart": [
      {
        "command": "./hooks/session-start"
      }
    ]
  }
 }
--- a/hooks/hooks.json
+++ b/hooks/hooks.json
@@ -2,12 +2,11 @@
  "hooks": {
    "SessionStart": [
      {
-        "matcher": "startup|clear|compact",
+        "matcher": "startup|resume|clear|compact",
        "hooks": [
          {
            "type": "command",
-            "command": "\"${CLAUDE_PLUGIN_ROOT}/hooks/run-hook.cmd\" session-start",
+            "command": "${CLAUDE_PLUGIN_ROOT}/hooks/session-start.sh"
            "async": false
          }
        ]
      }
--- a/hooks/run-hook.cmd
+++ b/hooks/run-hook.cmd
@@ -1,46 +0,0 @@
 : << 'CMDBLOCK'
@echo off
 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...]
 if "%~1"=="" (
    echo run-hook.cmd: missing script name >&2
    exit /b 1
 )
 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: run the named script directly
 SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
 SCRIPT_NAME="$1"
 shift
 exec bash "${SCRIPT_DIR}/${SCRIPT_NAME}" "$@"
--- a/hooks/session-start
+++ b/hooks/session-start
@@ -1,57 +0,0 @@
 #!/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)"
 # 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 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")
 warning_escaped=$(escape_for_json "$warning_message")
 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\n${warning_escaped}\n</EXTREMELY_IMPORTANT>"
 # Output context injection as JSON.
 # Cursor hooks expect additional_context.
 # Claude Code hooks expect hookSpecificOutput.additionalContext.
 # Claude Code reads BOTH fields without deduplication, so we must only
 # emit the field consumed by the current platform to avoid double injection.
 #
 # Uses printf instead of heredoc (cat <<EOF) to work around a bash 5.3+
 # bug where heredoc variable expansion hangs when content exceeds ~512 bytes.
 # See: https://github.com/obra/superpowers/issues/571
 if [ -n "${CURSOR_PLUGIN_ROOT:-}" ]; then
  # Cursor sets CURSOR_PLUGIN_ROOT (may also set CLAUDE_PLUGIN_ROOT) — emit additional_context
  printf '{\n  "additional_context": "%s"\n}\n' "$session_context"
 elif [ -n "${CLAUDE_PLUGIN_ROOT:-}" ]; then
  # Claude Code sets CLAUDE_PLUGIN_ROOT — emit only hookSpecificOutput
  printf '{\n  "hookSpecificOutput": {\n    "hookEventName": "SessionStart",\n    "additionalContext": "%s"\n  }\n}\n' "$session_context"
 else
  # Other platforms — emit additional_context as fallback
  printf '{\n  "additional_context": "%s"\n}\n' "$session_context"
 fi
 exit 0
--- a/hooks/session-start.sh
+++ b/hooks/session-start.sh
@@ -0,0 +1,34 @@
 #!/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_superpowers_escaped=$(echo "$using_superpowers_content" | sed 's/\\/\\\\/g' | sed 's/"/\\"/g' | awk '{printf "%s\\n", $0}')
 warning_escaped=$(echo "$warning_message" | sed 's/\\/\\\\/g' | sed 's/"/\\"/g' | awk '{printf "%s\\n", $0}')
 # Output context injection as JSON
 cat <<EOF
 {
  "hookSpecificOutput": {
    "hookEventName": "SessionStart",
    "additionalContext": "<EXTREMELY_IMPORTANT>\nYou have superpowers.\n\n**The content below is from skills/using-superpowers/SKILL.md - your introduction to using skills:**\n\n${using_superpowers_escaped}\n\n${warning_escaped}\n</EXTREMELY_IMPORTANT>"
  }
 }
 EOF
 exit 0
--- a/lib/initialize-skills.sh
+++ b/lib/initialize-skills.sh
@@ -0,0 +1,88 @@
 #!/usr/bin/env bash
 set -euo pipefail
 SKILLS_DIR="${HOME}/.config/superpowers/skills"
 SKILLS_REPO="https://github.com/obra/superpowers-skills.git"
 # Check if skills directory exists and is a valid git repo
 if [ -d "$SKILLS_DIR/.git" ]; then
    cd "$SKILLS_DIR"
    # Get the remote name for the current tracking branch
    TRACKING_REMOTE=$(git rev-parse --abbrev-ref --symbolic-full-name @{u} 2>/dev/null | cut -d'/' -f1 || echo "")
    # Fetch from tracking remote if set, otherwise try upstream then origin
    if [ -n "$TRACKING_REMOTE" ]; then
        git fetch "$TRACKING_REMOTE" 2>/dev/null || true
    else
        git fetch upstream 2>/dev/null || git fetch origin 2>/dev/null || true
    fi
    # Check if we can fast-forward
    LOCAL=$(git rev-parse @ 2>/dev/null || echo "")
    REMOTE=$(git rev-parse @{u} 2>/dev/null || echo "")
    BASE=$(git merge-base @ @{u} 2>/dev/null || echo "")
    # Try to fast-forward merge first
    if [ -n "$LOCAL" ] && [ -n "$REMOTE" ] && [ "$LOCAL" != "$REMOTE" ]; then
        # Check if we can fast-forward (local is ancestor of remote)
        if [ "$LOCAL" = "$BASE" ]; then
            # Fast-forward merge is possible - local is behind
            echo "Updating skills to latest version..."
            if git merge --ff-only @{u} 2>&1; then
                echo "✓ Skills updated successfully"
                echo "SKILLS_UPDATED=true"
            else
                echo "Failed to update skills"
            fi
        elif [ "$REMOTE" != "$BASE" ]; then
            # Remote has changes (local is behind or diverged)
            echo "SKILLS_BEHIND=true"
        fi
        # If REMOTE = BASE, local is ahead - no action needed
    fi
    exit 0
 fi
 # Skills directory doesn't exist or isn't a git repo - initialize it
 echo "Initializing skills repository..."
 # Handle migration from old installation
 if [ -d "${HOME}/.config/superpowers/.git" ]; then
    echo "Found existing installation. Backing up..."
    mv "${HOME}/.config/superpowers/.git" "${HOME}/.config/superpowers/.git.bak"
    if [ -d "${HOME}/.config/superpowers/skills" ]; then
        mv "${HOME}/.config/superpowers/skills" "${HOME}/.config/superpowers/skills.bak"
        echo "Your old skills are in ~/.config/superpowers/skills.bak"
    fi
 fi
 # Clone the skills repository
 mkdir -p "${HOME}/.config/superpowers"
 git clone "$SKILLS_REPO" "$SKILLS_DIR"
 cd "$SKILLS_DIR"
 # Offer to fork if gh is installed
 if command -v gh &> /dev/null; then
    echo ""
    echo "GitHub CLI detected. Would you like to fork superpowers-skills?"
    echo "Forking allows you to share skill improvements with the community."
    echo ""
    read -p "Fork superpowers-skills? (y/N): " -n 1 -r
    echo
    if [[ $REPLY =~ ^[Yy]$ ]]; then
        gh repo fork obra/superpowers-skills --remote=true
        echo "Forked! You can now contribute skills back to the community."
    else
        git remote add upstream "$SKILLS_REPO"
    fi
 else
    # No gh, just set up upstream remote
    git remote add upstream "$SKILLS_REPO"
 fi
 echo "Skills repository initialized at $SKILLS_DIR"
--- a/package.json
+++ b/package.json
@@ -1,6 +0,0 @@
 {
  "name": "superpowers",
  "version": "5.0.6",
  "type": "module",
  "main": ".opencode/plugins/superpowers.js"
 }
--- a/scripts/superpowers-codex
+++ b/scripts/superpowers-codex
@@ -0,0 +1,351 @@
 #!/usr/bin/env node
 const fs = require('fs');
 const path = require('path');
 const os = require('os');
 // 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');
 // Utility functions
 function extractFrontmatter(filePath) {
    try {
        const content = fs.readFileSync(filePath, 'utf8');
        const lines = content.split('\n');
        let inFrontmatter = false;
        let name = '';
        let description = '';
        let whenToUse = '';
        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;
                        case 'when_to_use': whenToUse = value.trim(); break;
                    }
                }
            }
        }
        return { name, description, whenToUse };
    } catch (error) {
        return { name: '', description: '', whenToUse: '' };
    }
 }
 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, whenToUse } = extractFrontmatter(skillFile);
    if (description) console.log(`  ${description}`);
    if (whenToUse) console.log(`  When to use: ${whenToUse}`);
    console.log('');
 }
 function findSkillsInDir(dir, sourceType, maxDepth = 1) {
    const skills = [];
    if (!fs.existsSync(dir)) return skills;
    function searchDir(currentDir, currentDepth) {
        if (currentDepth > maxDepth) return;
        try {
            const entries = fs.readdirSync(currentDir, { withFileTypes: true });
            for (const entry of entries) {
                if (entry.isDirectory()) {
                    const skillDir = path.join(currentDir, entry.name);
                    const skillFile = path.join(skillDir, 'SKILL.md');
                    if (fs.existsSync(skillFile)) {
                        skills.push(skillDir);
                    }
                    // For personal skills, search deeper (category/skill structure)
                    if (sourceType === 'personal' && currentDepth < maxDepth) {
                        searchDir(skillDir, currentDepth + 1);
                    }
                }
            }
        } catch (error) {
            // Ignore permission errors or other issues
        }
    }
    searchDir(dir, 0);
    return skills;
 }
 // Commands
 function runFindSkills() {
    console.log('Available skills:');
    console.log('==================');
    console.log('');
    const foundSkills = new Set();
    // Find personal skills first (these take precedence)
    const personalSkills = findSkillsInDir(personalSkillsDir, 'personal', 2);
    for (const skillPath of personalSkills) {
        const relPath = path.relative(personalSkillsDir, skillPath);
        foundSkills.add(relPath);
        printSkill(skillPath, 'personal');
    }
    // Find superpowers skills (only if not already found in personal)
    const superpowersSkills = findSkillsInDir(superpowersSkillsDir, 'superpowers', 1);
    for (const skillPath of superpowersSkills) {
        const relPath = path.relative(superpowersSkillsDir, skillPath);
        if (!foundSkills.has(relPath)) {
            printSkill(skillPath, '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('');
    // 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
    let content, frontmatter;
    try {
        const fullContent = fs.readFileSync(skillFile, 'utf8');
        const { name, description, whenToUse } = extractFrontmatter(skillFile);
        // Extract just the content after frontmatter
        const lines = fullContent.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);
            }
        }
        content = contentLines.join('\n').trim();
        frontmatter = { name, description, whenToUse };
    } 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}`);
    }
    if (frontmatter.whenToUse) {
        console.log(`# When to use: ${frontmatter.whenToUse}`);
    }
    console.log(`# Supporting tools and docs are 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;
 }
--- a/skills/brainstorming/SKILL.md
+++ b/skills/brainstorming/SKILL.md
@@ -1,164 +1,165 @@
 ---
 name: brainstorming
-description: "You MUST use this before any creative work - creating features, building components, adding functionality, or modifying behavior. Explores user intent, requirements and design before implementation."
+description: Use when creating or developing anything, before writing code or implementation plans - refines rough ideas into fully-formed designs through structured Socratic questioning, alternative exploration, and incremental validation
 ---
 # Brainstorming Ideas Into Designs
-Help turn ideas into fully formed designs and specs through natural collaborative dialogue.
+## Overview
-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.
+Transform rough ideas into fully-formed designs through structured questioning and alternative exploration.
-<HARD-GATE>
+**Core principle:** Ask questions to understand, explore alternatives, present design incrementally for validation.
 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"
+**Announce at start:** "I'm using the brainstorming skill to refine your idea into 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.
+## Quick Reference
-## Checklist
+| Phase | Key Activities | Tool Usage | Output |
-
+|-------|---------------|------------|--------|
-You MUST create a task for each of these items and complete them in order:
+| **1. Understanding** | Ask questions (one at a time) | AskUserQuestion for choices | Purpose, constraints, criteria |
-
+| **2. Exploration** | Propose 2-3 approaches | AskUserQuestion for approach selection | Architecture options with trade-offs |
-1. **Explore project context** — check files, docs, recent commits
+| **3. Design Presentation** | Present in 200-300 word sections | Open-ended questions | Complete design with validation |
-2. **Offer visual companion** (if topic will involve visual questions) — this is its own message, not combined with a clarifying question. See the Visual Companion section below.
+| **4. Design Documentation** | Write design document | writing-clearly-and-concisely skill | Design doc in docs/plans/ |
-3. **Ask clarifying questions** — one at a time, understand purpose/constraints/success criteria
+| **5. Worktree Setup** | Set up isolated workspace | using-git-worktrees skill | Ready development environment |
-4. **Propose 2-3 approaches** — with trade-offs and your recommendation
+| **6. Planning Handoff** | Create implementation plan | writing-plans skill | Detailed task breakdown |
 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];
    "Visual questions ahead?" [shape=diamond];
    "Offer Visual Companion\n(own message, no other content)" [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" -> "Visual questions ahead?";
    "Visual questions ahead?" -> "Offer Visual Companion\n(own message, no other content)" [label="yes"];
    "Visual questions ahead?" -> "Ask clarifying questions" [label="no"];
    "Offer Visual Companion\n(own message, no other content)" -> "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:**
+Copy this checklist to track progress:
- Check out the current project state first (files, docs, recent commits)
+```
- 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.
+Brainstorming Progress:
- 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.
+- [ ] Phase 1: Understanding (purpose, constraints, criteria gathered)
- For appropriately-scoped projects, ask questions one at a time to refine the idea
+- [ ] Phase 2: Exploration (2-3 approaches proposed and evaluated)
- Prefer multiple choice questions when possible, but open-ended is fine too
+- [ ] Phase 3: Design Presentation (design validated in sections)
- Only one question per message - if a topic needs more exploration, break it into multiple questions
+- [ ] Phase 4: Design Documentation (design written to docs/plans/)
- Focus on understanding: purpose, constraints, success criteria
+- [ ] Phase 5: Worktree Setup (if implementing)
 - [ ] Phase 6: Planning Handoff (if implementing)
 ```
-**Exploring approaches:**
+### Phase 1: Understanding
 - Check current project state in working directory
 - Ask ONE question at a time to refine the idea
 - **Use AskUserQuestion tool** when you have multiple choice options
 - Gather: Purpose, constraints, success criteria
- Propose 2-3 different approaches with trade-offs
+**Example using AskUserQuestion:**
- Present options conversationally with your recommendation and reasoning
+```
- Lead with your recommended option and explain why
+Question: "Where should the authentication data be stored?"
 Options:
  - "Session storage" (clears on tab close, more secure)
  - "Local storage" (persists across sessions, more convenient)
  - "Cookies" (works with SSR, compatible with older approach)
 ```
-**Presenting the design:**
+### Phase 2: Exploration
 - Propose 2-3 different approaches
 - For each: Core architecture, trade-offs, complexity assessment
 - **Use AskUserQuestion tool** to present approaches as structured choices
 - Ask your human partner which approach resonates
- Once you believe you understand what you're building, present the design
+**Example using AskUserQuestion:**
- 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
+Question: "Which architectural approach should we use?"
- Cover: architecture, components, data flow, error handling, testing
+Options:
- Be ready to go back and clarify if something doesn't make sense
+  - "Event-driven with message queue" (scalable, complex setup, eventual consistency)
  - "Direct API calls with retry logic" (simple, synchronous, easier to debug)
  - "Hybrid with background jobs" (balanced, moderate complexity, best of both)
 ```
-**Design for isolation and clarity:**
+### Phase 3: Design Presentation
 - Present in 200-300 word sections
 - Cover: Architecture, components, data flow, error handling, testing
 - Ask after each section: "Does this look right so far?" (open-ended)
 - Use open-ended questions here to allow freeform feedback
- Break the system into smaller units that each have one clear purpose, communicate through well-defined interfaces, and can be understood and tested independently
+### Phase 4: Design Documentation
- For each unit, you should be able to answer: what does it do, how do you use it, and what does it depend on?
+After design is validated, write it to a permanent document:
- 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.
+- **File location:** `docs/plans/YYYY-MM-DD-<topic>-design.md` (use actual date and descriptive topic)
- 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.
+- **RECOMMENDED SUB-SKILL:** Use elements-of-style:writing-clearly-and-concisely (if available) for documentation quality
 - **Content:** Capture the design as discussed and validated in Phase 3, organized into the sections that emerged from the conversation
 - Commit the design document to git before proceeding
-**Working in existing codebases:**
+### Phase 5: Worktree Setup (for implementation)
 When design is approved and implementation will follow:
 - Announce: "I'm using the using-git-worktrees skill to set up an isolated workspace."
 - **REQUIRED SUB-SKILL:** Use superpowers:using-git-worktrees
 - Follow that skill's process for directory selection, safety verification, and setup
 - Return here when worktree ready
- Explore the current structure before proposing changes. Follow existing patterns.
+### Phase 6: Planning Handoff
- 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.
+Ask: "Ready to create the implementation plan?"
 - Don't propose unrelated refactoring. Stay focused on what serves the current goal.
-## After the Design
+When your human partner confirms (any affirmative response):
 - Announce: "I'm using the writing-plans skill to create the implementation plan."
 - **REQUIRED SUB-SKILL:** Use superpowers:writing-plans
 - Create detailed plan in the worktree
-**Documentation:**
+## Question Patterns
- Write the validated design (spec) to `docs/superpowers/specs/YYYY-MM-DD-<topic>-design.md`
+### When to Use AskUserQuestion Tool
  - (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
-**Spec Self-Review:**
+**Use AskUserQuestion for:**
-After writing the spec document, look at it with fresh eyes:
+- Phase 1: Clarifying questions with 2-4 clear options
 - Phase 2: Architectural approach selection (2-3 alternatives)
 - Any decision with distinct, mutually exclusive choices
 - When options have clear trade-offs to explain
-1. **Placeholder scan:** Any "TBD", "TODO", incomplete sections, or vague requirements? Fix them.
+**Benefits:**
-2. **Internal consistency:** Do any sections contradict each other? Does the architecture match the feature descriptions?
+- Structured presentation of options with descriptions
-3. **Scope check:** Is this focused enough for a single implementation plan, or does it need decomposition?
+- Clear trade-off visibility for partner
-4. **Ambiguity check:** Could any requirement be interpreted two different ways? If so, pick one and make it explicit.
+- Forces explicit choice (prevents vague "maybe both" responses)
-Fix any issues inline. No need to re-review — just fix and move on.
+### When to Use Open-Ended Questions
-**User Review Gate:**
+**Use open-ended questions for:**
-After the spec review loop passes, ask the user to review the written spec before proceeding:
+- Phase 3: Design validation ("Does this look right so far?")
 - When you need detailed feedback or explanation
 - When partner should describe their own requirements
 - When structured options would limit creative input
-> "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."
+**Example decision flow:**
 - "What authentication method?" → Use AskUserQuestion (2-4 options)
 - "Does this design handle your use case?" → Open-ended (validation)
-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.
+## When to Revisit Earlier Phases
-**Implementation:**
+```dot
 digraph revisit_phases {
    rankdir=LR;
    "New constraint revealed?" [shape=diamond];
    "Partner questions approach?" [shape=diamond];
    "Requirements unclear?" [shape=diamond];
    "Return to Phase 1" [shape=box, style=filled, fillcolor="#ffcccc"];
    "Return to Phase 2" [shape=box, style=filled, fillcolor="#ffffcc"];
    "Continue forward" [shape=box, style=filled, fillcolor="#ccffcc"];
- Invoke the writing-plans skill to create a detailed implementation plan
+    "New constraint revealed?" -> "Return to Phase 1" [label="yes"];
- Do NOT invoke any other skill. writing-plans is the next step.
+    "New constraint revealed?" -> "Partner questions approach?" [label="no"];
    "Partner questions approach?" -> "Return to Phase 2" [label="yes"];
    "Partner questions approach?" -> "Requirements unclear?" [label="no"];
    "Requirements unclear?" -> "Return to Phase 1" [label="yes"];
    "Requirements unclear?" -> "Continue forward" [label="no"];
 }
 ```
 **You can and should go backward when:**
 - Partner reveals new constraint during Phase 2 or 3 → Return to Phase 1
 - Validation shows fundamental gap in requirements → Return to Phase 1
 - Partner questions approach during Phase 3 → Return to Phase 2
 - Something doesn't make sense → Go back and clarify
 **Don't force forward linearly** when going backward would give better results.
 ## Key Principles
- **One question at a time** - Don't overwhelm with multiple questions
+| Principle | Application |
- **Multiple choice preferred** - Easier to answer than open-ended when possible
+|-----------|-------------|
- **YAGNI ruthlessly** - Remove unnecessary features from all designs
+| **One question at a time** | Phase 1: Single question per message, use AskUserQuestion for choices |
- **Explore alternatives** - Always propose 2-3 approaches before settling
+| **Structured choices** | Use AskUserQuestion tool for 2-4 options with trade-offs |
- **Incremental validation** - Present design, get approval before moving on
+| **YAGNI ruthlessly** | Remove unnecessary features from all designs |
- **Be flexible** - Go back and clarify when something doesn't make sense
+| **Explore alternatives** | Always propose 2-3 approaches before settling |
-
+| **Incremental validation** | Present design in sections, validate each |
-## Visual Companion
+| **Flexible progression** | Go backward when needed - flexibility > rigidity |
-
+| **Announce usage** | State skill usage at start of session |
 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:** When you anticipate that upcoming questions will involve visual content (mockups, layouts, diagrams), offer it once for consent:
 > "Some of what we're working on might be easier to explain if I can show it to you in a web browser. I can put together mockups, diagrams, comparisons, and other visuals as we go. This feature is still new and can be token-intensive. Want to try it? (Requires opening a local URL)"
 **This offer MUST be its own message.** Do not combine it with clarifying questions, context summaries, or any other content. The message should contain ONLY the offer above and nothing else. Wait for the user's response before continuing. If they decline, proceed with text-only brainstorming.
 **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`
--- a/skills/brainstorming/scripts/frame-template.html
+++ b/skills/brainstorming/scripts/frame-template.html
@@ -1,214 +0,0 @@
 <!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
     * - Fixed header and selection indicator bar
     * - Scrollable main content area
     * - CSS helpers for common UI patterns
     *
     * Content is injected via placeholder comment in #claude-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 ===== */
    .header {
      background: var(--bg-secondary);
      padding: 0.5rem 1.5rem;
      display: flex;
      justify-content: space-between;
      align-items: center;
      border-bottom: 1px solid var(--border);
      flex-shrink: 0;
    }
    .header h1 { font-size: 0.85rem; font-weight: 500; color: var(--text-secondary); }
    .header .status { font-size: 0.7rem; color: var(--success); display: flex; align-items: center; gap: 0.4rem; }
    .header .status::before { content: ''; width: 6px; height: 6px; background: var(--success); border-radius: 50%; }
    .main { flex: 1; overflow-y: auto; }
    #claude-content { padding: 2rem; min-height: 100%; }
    .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;
    }
    /* ===== 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">
    <h1><a href="https://github.com/obra/superpowers" style="color: inherit; text-decoration: none;">Superpowers Brainstorming</a></h1>
    <div class="status">Connected</div>
  </div>
  <div class="main">
    <div id="claude-content">
      <!-- CONTENT -->
    </div>
  </div>
  <div class="indicator-bar">
    <span id="indicator-text">Click an option above, then return to the terminal</span>
  </div>
 </body>
 </html>
--- a/skills/brainstorming/scripts/helper.js
+++ b/skills/brainstorming/scripts/helper.js
@@ -1,88 +0,0 @@
 (function() {
  const WS_URL = 'ws://' + window.location.host;
  let ws = null;
  let eventQueue = [];
  function connect() {
    ws = new WebSocket(WS_URL);
    ws.onopen = () => {
      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 = () => {
      setTimeout(connect, 1000);
    };
  }
  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
    });
    // Update indicator bar (defer so toggleSelect runs first)
    setTimeout(() => {
      const indicator = document.getElementById('indicator-text');
      if (!indicator) return;
      const container = target.closest('.options') || target.closest('.cards');
      const selected = container ? container.querySelectorAll('.selected') : [];
      if (selected.length === 0) {
        indicator.textContent = 'Click an option above, then return to the terminal';
      } else if (selected.length === 1) {
        const label = selected[0].querySelector('h3, .content h3, .card-body h3')?.textContent?.trim() || selected[0].dataset.choice;
        indicator.innerHTML = '<span class="selected-text">' + label + ' selected</span> — return to terminal to continue';
      } else {
        indicator.innerHTML = '<span class="selected-text">' + selected.length + ' selected</span> — return to terminal to continue';
      }
    }, 0);
  });
  // 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();
 })();
--- a/skills/brainstorming/scripts/server.cjs
+++ b/skills/brainstorming/scripts/server.cjs
@@ -1,354 +0,0 @@
 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';
 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;
    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 };
 }
 // ========== Configuration ==========
 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 SESSION_DIR = process.env.BRAINSTORM_DIR || '/tmp/brainstorm';
 const CONTENT_DIR = path.join(SESSION_DIR, 'content');
 const STATE_DIR = path.join(SESSION_DIR, 'state');
 let ownerPid = process.env.BRAINSTORM_OWNER_PID ? Number(process.env.BRAINSTORM_OWNER_PID) : null;
 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 ==========
 const WAITING_PAGE = `<!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; }</style>
 </head>
 <body><h1>Brainstorm Companion</h1>
 <p>Waiting for the agent to push a screen...</p></body></html>`;
 const frameTemplate = fs.readFileSync(path.join(__dirname, 'frame-template.html'), 'utf-8');
 const helperScript = fs.readFileSync(path.join(__dirname, 'helper.js'), 'utf-8');
 const helperInjection = '<script>\n' + helperScript + '\n</script>';
 // ========== Helper Functions ==========
 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(CONTENT_DIR)
    .filter(f => f.endsWith('.html'))
    .map(f => {
      const fp = path.join(CONTENT_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;
 }
 // ========== HTTP Request Handler ==========
 function handleRequest(req, res) {
  touchActivity();
  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; charset=utf-8' });
    res.end(html);
  } else if (req.method === 'GET' && req.url.startsWith('/files/')) {
    const fileName = req.url.slice(7);
    const filePath = path.join(CONTENT_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');
  }
 }
 // ========== WebSocket Connection Handling ==========
 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: {
          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.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); }
  }
 }
 // ========== Activity Tracking ==========
 const IDLE_TIMEOUT_MS = 30 * 60 * 1000; // 30 minutes
 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.endsWith('.html'))
  );
  const server = http.createServer(handleRequest);
  server.on('upgrade', handleUpgrade);
  const watcher = fs.watch(CONTENT_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(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 }));
      } 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);
    server.close(() => process.exit(0));
  }
  function ownerAlive() {
    if (!ownerPid) return true;
    try { process.kill(ownerPid, 0); return true; } catch (e) { return e.code === 'EPERM'; }
  }
  // Check every 60s: exit if owner process died or idle for 30 minutes
  const lifecycleCheck = setInterval(() => {
    if (!ownerAlive()) shutdown('owner process exited');
    else if (Date.now() - lastActivity > IDLE_TIMEOUT_MS) shutdown('idle timeout');
  }, 60 * 1000);
  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;
      }
    }
  }
  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: CONTENT_DIR, state_dir: STATE_DIR
    });
    console.log(info);
    fs.writeFileSync(path.join(STATE_DIR, 'server-info'), info + '\n');
  });
 }
 if (require.main === module) {
  startServer();
 }
 module.exports = { computeAcceptKey, encodeFrame, decodeFrame, OPCODES };
--- a/skills/brainstorming/scripts/start-server.sh
+++ b/skills/brainstorming/scripts/start-server.sh
@@ -1,148 +0,0 @@
 #!/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.
 #   --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=""
 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
      ;;
    --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
 # 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
  case "${OSTYPE:-}" in
    msys*|cygwin*|mingw*) FOREGROUND="true" ;;
  esac
  if [[ -n "${MSYSTEM:-}" ]]; then
    FOREGROUND="true"
  fi
 fi
 # Generate unique session directory
 SESSION_ID="$$-$(date +%s)"
 if [[ -n "$PROJECT_DIR" ]]; then
  SESSION_DIR="${PROJECT_DIR}/.superpowers/brainstorm/${SESSION_ID}"
 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"
 # Create fresh session directory with content and state peers
 mkdir -p "${SESSION_DIR}/content" "$STATE_DIR"
 # 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"
 # 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
 # Foreground mode for environments that reap detached/background processes.
 if [[ "$FOREGROUND" == "true" ]]; then
  echo "$$" > "$PID_FILE"
  env BRAINSTORM_DIR="$SESSION_DIR" BRAINSTORM_HOST="$BIND_HOST" BRAINSTORM_URL_HOST="$URL_HOST" BRAINSTORM_OWNER_PID="$OWNER_PID" node server.cjs
  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 > "$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 i 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
--- a/skills/brainstorming/scripts/stop-server.sh
+++ b/skills/brainstorming/scripts/stop-server.sh
@@ -1,56 +0,0 @@
 #!/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"
 if [[ -f "$PID_FILE" ]]; then
  pid=$(cat "$PID_FILE")
  # Try to stop gracefully, fallback to force if still alive
  kill "$pid" 2>/dev/null || true
  # Wait for graceful shutdown (up to ~2s)
  for i in {1..20}; do
    if ! kill -0 "$pid" 2>/dev/null; then
      break
    fi
    sleep 0.1
  done
  # If still running, escalate to SIGKILL
  if kill -0 "$pid" 2>/dev/null; then
    kill -9 "$pid" 2>/dev/null || true
    # Give SIGKILL a moment to take effect
    sleep 0.1
  fi
  if kill -0 "$pid" 2>/dev/null; then
    echo '{"status": "failed", "error": "process still running"}'
    exit 1
  fi
  rm -f "$PID_FILE" "${STATE_DIR}/server.log"
  # Only delete ephemeral /tmp directories
  if [[ "$SESSION_DIR" == /tmp/* ]]; then
    rm -rf "$SESSION_DIR"
  fi
  echo '{"status": "stopped"}'
 else
  echo '{"status": "not_running"}'
 fi
--- a/skills/brainstorming/spec-document-reviewer-prompt.md
+++ b/skills/brainstorming/spec-document-reviewer-prompt.md
@@ -1,49 +0,0 @@
 # 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 |
    | 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
--- a/skills/brainstorming/visual-companion.md
+++ b/skills/brainstorming/visual-companion.md
@@ -1,287 +0,0 @@
 # 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, selection indicator, 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 server with persistence (mockups saved to project)
 scripts/start-server.sh --project-dir /path/to/project
 # Returns: {"type":"server-started","port":52341,"url":"http://localhost:52341",
 #           "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. Tell user to open the URL.
 **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 (macOS / Linux):**
 ```bash
 # Default mode works — the script backgrounds the server itself
 scripts/start-server.sh --project-dir /path/to/project
 ```
 **Claude Code (Windows):**
 ```bash
 # Windows auto-detects and uses foreground mode, which blocks the tool call.
 # Use run_in_background: true on the Bash tool call so the server survives
 # across conversation turns.
 scripts/start-server.sh --project-dir /path/to/project
 ```
 When calling this via the Bash tool, set `run_in_background: true`. 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
 ```
 **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 --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`:
   - Before each write, check that `$STATE_DIR/server-info` exists. If it doesn't (or `$STATE_DIR/server-stopped` exists), the server has shut down — restart it with `start-server.sh` before continuing. The server auto-exits after 30 minutes of inactivity.
   - 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 `$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, selection indicator, 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. The indicator bar shows the count.
 ```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`
--- a/skills/commands/brainstorm.md
+++ b/skills/commands/brainstorm.md
@@ -0,0 +1 @@
 Use your brainstorming skill.
--- a/skills/commands/execute-plan.md
+++ b/skills/commands/execute-plan.md
@@ -0,0 +1 @@
 Use your Executing-Plans skill.
--- a/skills/commands/write-plan.md
+++ b/skills/commands/write-plan.md
@@ -0,0 +1 @@
 Use your Writing-Plans skill.
--- a/skills/systematic-debugging/condition-based-waiting.md
+++ b/skills/systematic-debugging/condition-based-waiting.md
@@ -1,3 +1,8 @@
 ---
 name: condition-based-waiting
 description: Use when tests have race conditions, timing dependencies, or inconsistent pass/fail behavior - replaces arbitrary timeouts with condition polling to wait for actual state changes, eliminating flaky tests from timing guesses
 ---
 # Condition-Based Waiting
 ## Overview
@@ -79,7 +84,7 @@ async function waitFor<T>(
 }
 ```
-See `condition-based-waiting-example.ts` in this directory for complete implementation with domain-specific helpers (`waitForEvent`, `waitForEventCount`, `waitForEventMatch`) from actual debugging session.
+See @example.ts for complete implementation with domain-specific helpers (`waitForEvent`, `waitForEventCount`, `waitForEventMatch`) from actual debugging session.
 ## Common Mistakes
--- a/skills/systematic-debugging/condition-based-waiting-example.ts
+++ b/skills/systematic-debugging/condition-based-waiting-example.ts
--- a/skills/systematic-debugging/defense-in-depth.md
+++ b/skills/systematic-debugging/defense-in-depth.md
@@ -1,3 +1,8 @@
 ---
 name: defense-in-depth
 description: Use when invalid data causes failures deep in execution, requiring validation at multiple system layers - validates at every layer data passes through to make bugs structurally impossible
 ---
 # Defense-in-Depth Validation
 ## Overview
--- a/skills/dispatching-parallel-agents/SKILL.md
+++ b/skills/dispatching-parallel-agents/SKILL.md
@@ -1,14 +1,12 @@
 ---
 name: dispatching-parallel-agents
-description: Use when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies
+description: Use when facing 3+ independent failures that can be investigated without shared state or dependencies - dispatches multiple Claude agents to investigate and fix independent problems concurrently
 ---
 # Dispatching Parallel Agents
 ## 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.
--- a/skills/executing-plans/SKILL.md
+++ b/skills/executing-plans/SKILL.md
@@ -1,18 +1,18 @@
 ---
 name: executing-plans
-description: Use when you have a written implementation plan to execute in a separate session with review checkpoints
+description: Use when partner provides a complete implementation plan to execute in controlled batches with review checkpoints - loads plan, reviews critically, executes tasks in batches, reports for review between batches
 ---
 # Executing Plans
 ## Overview
-Load plan, review critically, execute all tasks, report when complete.
+Load plan, review critically, execute tasks in batches, report for review between batches.
 **Core principle:** Batch execution with checkpoints for architect review.
 **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 (such as Claude Code or Codex). If subagents are available, use superpowers:subagent-driven-development instead of this skill.
 ## The Process
 ### Step 1: Load and Review Plan
@@ -21,7 +21,8 @@ Load plan, review critically, execute all tasks, report when complete.
 3. If concerns: Raise them with your human partner before starting
 4. If no concerns: Create TodoWrite and proceed
-### Step 2: Execute Tasks
+### Step 2: Execute Batch
 **Default: First 3 tasks**
 For each task:
 1. Mark as in_progress
@@ -29,7 +30,19 @@ For each task:
 3. Run verifications as specified
 4. Mark as completed
-### Step 3: Complete Development
+### 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
 After all tasks complete and verified:
 - Announce: "I'm using the finishing-a-development-branch skill to complete this work."
@@ -39,7 +52,7 @@ After all tasks complete and verified:
 ## When to Stop and Ask for Help
 **STOP executing immediately when:**
- Hit a blocker (missing dependency, test fails, instruction unclear)
+- Hit a blocker mid-batch (missing dependency, test fails, instruction unclear)
 - Plan has critical gaps preventing starting
 - You don't understand an instruction
 - Verification fails repeatedly
@@ -59,12 +72,5 @@ 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** - REQUIRED: Set up isolated workspace before starting
 - **superpowers:writing-plans** - Creates the plan this skill executes
 - **superpowers:finishing-a-development-branch** - Complete development after all tasks
--- a/skills/receiving-code-review/SKILL.md
+++ b/skills/receiving-code-review/SKILL.md
@@ -200,10 +200,6 @@ 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.**
--- a/skills/requesting-code-review/SKILL.md
+++ b/skills/requesting-code-review/SKILL.md
@@ -1,11 +1,11 @@
 ---
 name: requesting-code-review
-description: Use when completing tasks, implementing major features, or before merging to verify work meets requirements
+description: Use when completing tasks, implementing major features, or before merging to verify work meets requirements - dispatches superpowers:code-reviewer subagent to review implementation against plan or requirements before proceeding
 ---
 # Requesting Code Review
-Dispatch superpowers: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.
+Dispatch superpowers:code-reviewer subagent to catch issues before they cascade.
 **Core principle:** Review early, review often.
@@ -58,7 +58,7 @@ 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/superpowers/plans/deployment-plan.md
+  PLAN_OR_REQUIREMENTS: Task 2 from docs/plans/deployment-plan.md
  BASE_SHA: a7981ec
  HEAD_SHA: 3df7661
  DESCRIPTION: Added verifyIndex() and repairIndex() with 4 issue types
--- a/skills/systematic-debugging/root-cause-tracing.md
+++ b/skills/systematic-debugging/root-cause-tracing.md
@@ -1,3 +1,8 @@
 ---
 name: root-cause-tracing
 description: Use when errors occur deep in execution and you need to trace back to find the original trigger - systematically traces bugs backward through call stack, adding instrumentation when needed, to identify source of invalid data or incorrect behavior
 ---
 # Root Cause Tracing
 ## Overview
@@ -98,7 +103,7 @@ npm test 2>&1 | grep 'DEBUG git init'
 If something appears during tests but you don't know which test:
-Use the bisection script `find-polluter.sh` in this directory:
+Use the bisection script: @find-polluter.sh
 ```bash
 ./find-polluter.sh '.git' 'src/**/*.test.ts'
--- a/skills/systematic-debugging/find-polluter.sh
+++ b/skills/systematic-debugging/find-polluter.sh
@@ -1,4 +1,4 @@
-#!/usr/bin/env bash
+#!/bin/bash
 # Bisection script to find which test creates unwanted files/state
 # Usage: ./find-polluter.sh <file_or_dir_to_check> <test_pattern>
 # Example: ./find-polluter.sh '.git' 'src/**/*.test.ts'
--- a/skills/sharing-skills/SKILL.md
+++ b/skills/sharing-skills/SKILL.md
@@ -0,0 +1,194 @@
 ---
 name: sharing-skills
 description: Use when you've developed a broadly useful skill and want to contribute it upstream via pull request - guides process of branching, committing, pushing, and creating PR to contribute skills back to upstream repository
 ---
 # Sharing Skills
 ## Overview
 Contribute skills from your local branch back to the upstream repository.
 **Workflow:** Branch → Edit/Create skill → Commit → Push → PR
 ## When to Share
 **Share when:**
 - Skill applies broadly (not project-specific)
 - Pattern/technique others would benefit from
 - Well-tested and documented
 - Follows writing-skills guidelines
 **Keep personal when:**
 - Project-specific or organization-specific
 - Experimental or unstable
 - Contains sensitive information
 - Too narrow/niche for general use
 ## Prerequisites
 - `gh` CLI installed and authenticated
 - Working directory is `~/.config/superpowers/skills/` (your local clone)
 - **REQUIRED:** Skill has been tested using writing-skills TDD process
 ## Sharing Workflow
 ### 1. Ensure You're on Main and Synced
 ```bash
 cd ~/.config/superpowers/skills/
 git checkout main
 git pull upstream main
 git push origin main  # Push to your fork
 ```
 ### 2. Create Feature Branch
 ```bash
 # Branch name: add-skillname-skill
 skill_name="your-skill-name"
 git checkout -b "add-${skill_name}-skill"
 ```
 ### 3. Create or Edit Skill
 ```bash
 # Work on your skill in skills/
 # Create new skill or edit existing one
 # Skill should be in skills/category/skill-name/SKILL.md
 ```
 ### 4. Commit Changes
 ```bash
 # Add and commit
 git add skills/your-skill-name/
 git commit -m "Add ${skill_name} skill
 $(cat <<'EOF'
 Brief description of what this skill does and why it's useful.
 Tested with: [describe testing approach]
 EOF
 )"
 ```
 ### 5. Push to Your Fork
 ```bash
 git push -u origin "add-${skill_name}-skill"
 ```
 ### 6. Create Pull Request
 ```bash
 # Create PR to upstream using gh CLI
 gh pr create \
  --repo upstream-org/upstream-repo \
  --title "Add ${skill_name} skill" \
  --body "$(cat <<'EOF'
 ## Summary
 Brief description of the skill and what problem it solves.
 ## Testing
 Describe how you tested this skill (pressure scenarios, baseline tests, etc.).
 ## Context
 Any additional context about why this skill is needed and how it should be used.
 EOF
 )"
 ```
 ## Complete Example
 Here's a complete example of sharing a skill called "async-patterns":
 ```bash
 # 1. Sync with upstream
 cd ~/.config/superpowers/skills/
 git checkout main
 git pull upstream main
 git push origin main
 # 2. Create branch
 git checkout -b "add-async-patterns-skill"
 # 3. Create/edit the skill
 # (Work on skills/async-patterns/SKILL.md)
 # 4. Commit
 git add skills/async-patterns/
 git commit -m "Add async-patterns skill
 Patterns for handling asynchronous operations in tests and application code.
 Tested with: Multiple pressure scenarios testing agent compliance."
 # 5. Push
 git push -u origin "add-async-patterns-skill"
 # 6. Create PR
 gh pr create \
  --repo upstream-org/upstream-repo \
  --title "Add async-patterns skill" \
  --body "## Summary
 Patterns for handling asynchronous operations correctly in tests and application code.
 ## Testing
 Tested with multiple application scenarios. Agents successfully apply patterns to new code.
 ## Context
 Addresses common async pitfalls like race conditions, improper error handling, and timing issues."
 ```
 ## After PR is Merged
 Once your PR is merged:
 1. Sync your local main branch:
 ```bash
 cd ~/.config/superpowers/skills/
 git checkout main
 git pull upstream main
 git push origin main
 ```
 2. Delete the feature branch:
 ```bash
 git branch -d "add-${skill_name}-skill"
 git push origin --delete "add-${skill_name}-skill"
 ```
 ## Troubleshooting
 **"gh: command not found"**
 - Install GitHub CLI: https://cli.github.com/
 - Authenticate: `gh auth login`
 **"Permission denied (publickey)"**
 - Check SSH keys: `gh auth status`
 - Set up SSH: https://docs.github.com/en/authentication
 **"Skill already exists"**
 - You're creating a modified version
 - Consider different skill name or coordinate with the skill's maintainer
 **PR merge conflicts**
 - Rebase on latest upstream: `git fetch upstream && git rebase upstream/main`
 - Resolve conflicts
 - Force push: `git push -f origin your-branch`
 ## Multi-Skill Contributions
 **Do NOT batch multiple skills in one PR.**
 Each skill should:
 - Have its own feature branch
 - Have its own PR
 - Be independently reviewable
 **Why?** Individual skills can be reviewed, iterated, and merged independently.
 ## Related Skills
 - **writing-skills** - REQUIRED: How to create well-tested skills before sharing
--- a/skills/subagent-driven-development/SKILL.md
+++ b/skills/subagent-driven-development/SKILL.md
@@ -1,194 +1,140 @@
 ---
 name: subagent-driven-development
-description: Use when executing implementation plans with independent tasks in the current session
+description: Use when executing implementation plans with independent tasks in the current session - dispatches fresh subagent for each task with code review between tasks, enabling fast iteration with quality gates
 ---
 # 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 fresh subagent per task, with code review after each.
-**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 + review between tasks = high quality, fast iteration
-**Core principle:** Fresh subagent per task + two-stage review (spec then quality) = high quality, fast iteration
+## Overview
 ## When to Use
 ```dot
 digraph when_to_use {
    "Have implementation plan?" [shape=diamond];
    "Tasks mostly independent?" [shape=diamond];
    "Stay in this session?" [shape=diamond];
    "subagent-driven-development" [shape=box];
    "executing-plans" [shape=box];
    "Manual execution or brainstorm first" [shape=box];
    "Have implementation plan?" -> "Tasks mostly independent?" [label="yes"];
    "Have implementation plan?" -> "Manual execution or brainstorm first" [label="no"];
    "Tasks mostly independent?" -> "Stay in this session?" [label="yes"];
    "Tasks mostly independent?" -> "Manual execution or brainstorm first" [label="no - tightly coupled"];
    "Stay in this session?" -> "subagent-driven-development" [label="yes"];
    "Stay in this session?" -> "executing-plans" [label="no - parallel session"];
 }
 ```
 **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
+- Code review after each task (catch issues early)
 - Faster iteration (no human-in-loop between tasks)
 **When to use:**
 - Staying in this session
 - Tasks are mostly independent
 - Want continuous progress with quality gates
 **When NOT to use:**
 - Need to review plan first (use executing-plans)
 - Tasks are tightly coupled (manual execution better)
 - Plan needs revision (brainstorm first)
 ## The Process
-```dot
+### 1. Load Plan
 digraph process {
    rankdir=TB;
-    subgraph cluster_per_task {
+Read plan file, create TodoWrite with all tasks.
        label="Per Task";
        "Dispatch implementer subagent (./implementer-prompt.md)" [shape=box];
        "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];
    }
-    "Read plan, extract all tasks with full text, note context, create TodoWrite" [shape=box];
+### 2. Execute Task with Subagent
    "More tasks remain?" [shape=diamond];
    "Dispatch final code reviewer subagent for entire implementation" [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)";
+For each task:
-    "Dispatch implementer subagent (./implementer-prompt.md)" -> "Implementer subagent asks questions?";
+
-    "Implementer subagent asks questions?" -> "Answer questions, provide context" [label="yes"];
+**Dispatch fresh subagent:**
-    "Answer questions, provide context" -> "Dispatch implementer subagent (./implementer-prompt.md)";
+```
-    "Implementer subagent asks questions?" -> "Implementer subagent implements, tests, commits, self-reviews" [label="no"];
+Task tool (general-purpose):
-    "Implementer subagent implements, tests, commits, self-reviews" -> "Dispatch spec reviewer subagent (./spec-reviewer-prompt.md)";
+  description: "Implement Task N: [task name]"
-    "Dispatch spec reviewer subagent (./spec-reviewer-prompt.md)" -> "Spec reviewer subagent confirms code matches spec?";
+  prompt: |
-    "Spec reviewer subagent confirms code matches spec?" -> "Implementer subagent fixes spec gaps" [label="no"];
+    You are implementing Task N from [plan-file].
-    "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"];
+    Read that task carefully. Your job is to:
-    "Dispatch code quality reviewer subagent (./code-quality-reviewer-prompt.md)" -> "Code quality reviewer subagent approves?";
+    1. Implement exactly what the task specifies
-    "Code quality reviewer subagent approves?" -> "Implementer subagent fixes quality issues" [label="no"];
+    2. Write tests (following TDD if task says to)
-    "Implementer subagent fixes quality issues" -> "Dispatch code quality reviewer subagent (./code-quality-reviewer-prompt.md)" [label="re-review"];
+    3. Verify implementation works
-    "Code quality reviewer subagent approves?" -> "Mark task complete in TodoWrite" [label="yes"];
+    4. Commit your work
-    "Mark task complete in TodoWrite" -> "More tasks remain?";
+    5. Report back
-    "More tasks remain?" -> "Dispatch implementer subagent (./implementer-prompt.md)" [label="yes"];
+
-    "More tasks remain?" -> "Dispatch final code reviewer subagent for entire implementation" [label="no"];
+    Work from: [directory]
-    "Dispatch final code reviewer subagent for entire implementation" -> "Use superpowers:finishing-a-development-branch";
+
-}
+    Report: What you implemented, what you tested, test results, files changed, any issues
 ```
-## Model Selection
+**Subagent reports back** with summary of work.
-Use the least powerful model that can handle each role to conserve cost and increase speed.
+### 3. Review Subagent's Work
-**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.
+**Dispatch code-reviewer subagent:**
 ```
 Task tool (superpowers:code-reviewer):
  Use template at requesting-code-review/code-reviewer.md
-**Integration and judgment tasks** (multi-file coordination, pattern matching, debugging): use a standard model.
+  WHAT_WAS_IMPLEMENTED: [from subagent's report]
  PLAN_OR_REQUIREMENTS: Task N from [plan-file]
  BASE_SHA: [commit before task]
  HEAD_SHA: [current commit]
  DESCRIPTION: [task summary]
 ```
-**Architecture, design, and review tasks**: use the most capable available model.
+**Code reviewer returns:** Strengths, Issues (Critical/Important/Minor), Assessment
-**Task complexity signals:**
+### 4. Apply Review Feedback
 - 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
+**If issues found:**
 - Fix Critical issues immediately
 - Fix Important issues before next task
 - Note Minor issues
-Implementer subagents report one of four statuses. Handle each appropriately:
+**Dispatch follow-up subagent if needed:**
 ```
 "Fix issues from code review: [list issues]"
 ```
-**DONE:** Proceed to spec compliance review.
+### 5. Mark Complete, Next Task
-**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.
+- Mark task as completed in TodoWrite
 - Move to next task
 - Repeat steps 2-5
-**NEEDS_CONTEXT:** The implementer needs information that wasn't provided. Provide the missing context and re-dispatch.
+### 6. Final Review
-**BLOCKED:** The implementer cannot complete the task. Assess the blocker:
+After all tasks complete, dispatch final code-reviewer:
-1. If it's a context problem, provide more context and re-dispatch with the same model
+- Reviews entire implementation
-2. If the task requires more reasoning, re-dispatch with a more capable model
+- Checks all plan requirements met
-3. If the task is too large, break it into smaller pieces
+- Validates overall architecture
 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.
+### 7. Complete Development
-## Prompt Templates
+After final review passes:
-
+- Announce: "I'm using the finishing-a-development-branch skill to complete this work."
- `./implementer-prompt.md` - Dispatch implementer subagent
+- **REQUIRED SUB-SKILL:** Use superpowers:finishing-a-development-branch
- `./spec-reviewer-prompt.md` - Dispatch spec compliance reviewer subagent
+- Follow that skill to verify tests, present options, execute choice
 - `./code-quality-reviewer-prompt.md` - Dispatch code quality reviewer subagent
 ## Example Workflow
 ```
 You: I'm using Subagent-Driven Development to execute this plan.
-[Read plan file once: docs/superpowers/plans/feature-plan.md]
+[Load plan, create TodoWrite]
 [Extract all 5 tasks with full text and context]
 [Create TodoWrite with all tasks]
 Task 1: Hook installation script
-[Get Task 1 text and context (already extracted)]
+[Dispatch implementation subagent]
-[Dispatch implementation subagent with full task text + context]
+Subagent: Implemented install-hook with tests, 5/5 passing
-Implementer: "Before I begin - should the hook be installed at user or system level?"
+[Get git SHAs, dispatch code-reviewer]
-
+Reviewer: Strengths: Good test coverage. Issues: None. Ready.
 You: "User level (~/.config/superpowers/hooks/)"
 Implementer: "Got it. Implementing now..."
 [Later] Implementer:
  - Implemented install-hook command
  - Added tests, 5/5 passing
  - 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.
 [Mark Task 1 complete]
 Task 2: Recovery modes
-[Get Task 2 text and context (already extracted)]
+[Dispatch implementation subagent]
-[Dispatch implementation subagent with full task text + context]
+Subagent: Added verify/repair, 8/8 tests passing
-Implementer: [No questions, proceeds]
+[Dispatch code-reviewer]
-Implementer:
+Reviewer: Strengths: Solid. Issues (Important): Missing progress reporting
  - Added verify/repair modes
  - 8/8 tests passing
  - Self-review: All good
  - Committed
-[Dispatch spec compliance reviewer]
+[Dispatch fix subagent]
-Spec reviewer: ❌ Issues:
+Fix subagent: Added progress every 100 conversations
  - Missing: Progress reporting (spec says "report every 100 items")
  - Extra: Added --json flag (not requested)
-[Implementer fixes issues]
+[Verify fix, mark Task 2 complete]
 Implementer: Removed --json flag, added progress reporting
 [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
 [Mark Task 2 complete]
 ...
@@ -205,58 +151,23 @@ Done!
 - Subagents follow TDD naturally
 - Fresh context per task (no confusion)
 - Parallel-safe (subagents don't interfere)
 - Subagent can ask questions (before AND during work)
 **vs. Executing Plans:**
 - Same session (no handoff)
 - Continuous progress (no waiting)
 - Review checkpoints automatic
 **Efficiency gains:**
 - No file reading overhead (controller provides full text)
 - Controller curates exactly what context is needed
 - 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
 - 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
 - Controller does more prep work (extracting all tasks upfront)
 - Review loops add iterations
 - But catches issues early (cheaper than debugging later)
 ## Red Flags
 **Never:**
- Start implementation on main/master branch without explicit user consent
+- Skip code review between tasks
- Skip reviews (spec compliance OR code quality)
+- Proceed with unfixed Critical issues
 - Proceed with unfixed issues
 - Dispatch multiple implementation subagents in parallel (conflicts)
- Make subagent read plan file (provide full text instead)
+- Implement without reading plan task
 - 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)
 - 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
 **If subagent asks questions:**
 - Answer clearly and completely
 - Provide additional context if needed
 - Don't rush them into implementation
 **If reviewer finds issues:**
 - Implementer (same subagent) fixes them
 - Reviewer reviews again
 - Repeat until approved
 - Don't skip the re-review
 **If subagent fails task:**
 - Dispatch fix subagent with specific instructions
@@ -265,13 +176,14 @@ Done!
 ## Integration
 **Required workflow skills:**
- **superpowers:using-git-worktrees** - REQUIRED: Set up isolated workspace before starting
+- **writing-plans** - REQUIRED: Creates the plan that this skill executes
- **superpowers:writing-plans** - Creates the plan this skill executes
+- **requesting-code-review** - REQUIRED: Review after each task (see Step 3)
- **superpowers:requesting-code-review** - Code review template for reviewer subagents
+- **finishing-a-development-branch** - REQUIRED: Complete development after all tasks (see Step 7)
 - **superpowers:finishing-a-development-branch** - Complete development after all tasks
-**Subagents should use:**
+**Subagents must use:**
- **superpowers:test-driven-development** - Subagents follow TDD for each task
+- **test-driven-development** - Subagents follow TDD for each task
 **Alternative workflow:**
- **superpowers:executing-plans** - Use for parallel session instead of same-session execution
+- **executing-plans** - Use for parallel session instead of same-session execution
 See code-reviewer template: requesting-code-review/code-reviewer.md
--- a/skills/subagent-driven-development/code-quality-reviewer-prompt.md
+++ b/skills/subagent-driven-development/code-quality-reviewer-prompt.md
@@ -1,26 +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]
 ```
 **In addition to standard code quality concerns, the reviewer should check:**
 - 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 implementation create new files that are already large, or significantly grow existing files? (Don't flag pre-existing file sizes — focus on what this change contributed.)
 **Code reviewer returns:** Strengths, Issues (Critical/Important/Minor), Assessment
--- a/skills/subagent-driven-development/implementer-prompt.md
+++ b/skills/subagent-driven-development/implementer-prompt.md
@@ -1,113 +0,0 @@
 # Implementer Subagent Prompt Template
 Use this template when dispatching an implementer subagent.
 ```
 Task tool (general-purpose):
  description: "Implement Task N: [task name]"
  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]
    ## Context
    [Scene-setting: where this fits, dependencies, architectural context]
    ## Before You Begin
    If you have questions about:
    - The requirements or acceptance criteria
    - The approach or implementation strategy
    - Dependencies or assumptions
    - Anything unclear in the task description
    **Ask them now.** Raise any concerns before starting work.
    ## Your Job
    Once you're clear on requirements:
    1. Implement exactly what the task specifies
    2. Write tests (following TDD if task says to)
    3. Verify implementation works
    4. Commit your work
    5. Self-review (see below)
    6. Report back
    Work from: [directory]
    **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.
    ## 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:
    **Completeness:**
    - Did I fully implement everything in the spec?
    - Did I miss any requirements?
    - Are there edge cases I didn't handle?
    **Quality:**
    - Is this my best work?
    - Are names clear and accurate (match what things do, not how they work)?
    - Is the code clean and maintainable?
    **Discipline:**
    - Did I avoid overbuilding (YAGNI)?
    - Did I only build what was requested?
    - Did I follow existing patterns in the codebase?
    **Testing:**
    - Do tests actually verify behavior (not just mock behavior)?
    - Did I follow TDD if required?
    - Are tests comprehensive?
    If you find issues during self-review, fix them now before reporting.
    ## Report Format
    When done, report:
    - **Status:** DONE | DONE_WITH_CONCERNS | BLOCKED | NEEDS_CONTEXT
    - What you implemented (or what you attempted, if blocked)
    - What you tested and test results
    - Files changed
    - Self-review findings (if any)
    - Any issues or concerns
    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.
 ```
--- a/skills/subagent-driven-development/spec-reviewer-prompt.md
+++ b/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]
 ```
--- a/skills/systematic-debugging/SKILL.md
+++ b/skills/systematic-debugging/SKILL.md
@@ -1,6 +1,6 @@
 ---
 name: systematic-debugging
-description: Use when encountering any bug, test failure, or unexpected behavior, before proposing fixes
+description: Use when encountering any bug, test failure, or unexpected behavior, before proposing fixes - four-phase framework (root cause investigation, pattern analysis, hypothesis testing, implementation) that ensures understanding before attempting solutions
 ---
 # Systematic Debugging
@@ -111,7 +111,7 @@ You MUST complete each phase before proceeding to the next.
   **WHEN error is deep in call stack:**
-   See `root-cause-tracing.md` in this directory for the complete backward tracing technique.
+   **REQUIRED SUB-SKILL:** Use superpowers:root-cause-tracing for backward tracing technique
   **Quick version:**
   - Where does bad value originate?
@@ -176,7 +176,7 @@ You MUST complete each phase before proceeding to the next.
   - Automated test if possible
   - One-off test script if no framework
   - MUST have before fixing
-   - Use the `superpowers:test-driven-development` skill for writing proper failing tests
+   - **REQUIRED SUB-SKILL:** Use superpowers:test-driven-development for writing proper failing tests
 2. **Implement Single Fix**
   - Address the root cause identified
@@ -275,17 +275,16 @@ If systematic investigation reveals issue is truly environmental, timing-depende
 **But:** 95% of "no root cause" cases are incomplete investigation.
-## Supporting Techniques
+## Integration with Other Skills
-These techniques are part of systematic debugging and available in this directory:
+**This skill requires using:**
 - **root-cause-tracing** - REQUIRED when error is deep in call stack (see Phase 1, Step 5)
 - **test-driven-development** - REQUIRED for creating failing test case (see Phase 4, Step 1)
- **`root-cause-tracing.md`** - Trace bugs backward through call stack to find original trigger
+**Complementary skills:**
- **`defense-in-depth.md`** - Add validation at multiple layers after finding root cause
+- **defense-in-depth** - Add validation at multiple layers after finding root cause
- **`condition-based-waiting.md`** - Replace arbitrary timeouts with condition polling
+- **condition-based-waiting** - Replace arbitrary timeouts identified in Phase 2
-
+- **verification-before-completion** - Verify fix worked before claiming success
 **Related skills:**
 - **superpowers:test-driven-development** - For creating failing test case (Phase 4, Step 1)
 - **superpowers:verification-before-completion** - Verify fix worked before claiming success
 ## Real-World Impact
--- a/skills/test-driven-development/SKILL.md
+++ b/skills/test-driven-development/SKILL.md
@@ -1,6 +1,6 @@
 ---
 name: test-driven-development
-description: Use when implementing any feature or bugfix, before writing implementation code
+description: Use when implementing any feature or bugfix, before writing implementation code - write the test first, watch it fail, write minimal code to pass; ensures tests actually verify behavior by requiring failure first
 ---
 # Test-Driven Development (TDD)
@@ -354,13 +354,6 @@ Bug found? Write failing test reproducing it. Follow TDD cycle. Test proves fix
 Never fix bugs without a test.
 ## Testing Anti-Patterns
 When adding mocks or test utilities, read @testing-anti-patterns.md to avoid common pitfalls:
 - Testing mock behavior instead of real behavior
 - Adding test-only methods to production classes
 - Mocking without understanding dependencies
 ## Final Rule
 ```
--- a/skills/test-driven-development/testing-anti-patterns.md
+++ b/skills/test-driven-development/testing-anti-patterns.md
@@ -1,6 +1,9 @@
-# Testing Anti-Patterns
+---
 name: testing-anti-patterns
 description: Use when writing or changing tests, adding mocks, or tempted to add test-only methods to production code - prevents testing mock behavior, production pollution with test-only methods, and mocking without understanding dependencies
 ---
-**Load this reference when:** writing or changing tests, adding mocks, or tempted to add test-only methods to production code.
+# Testing Anti-Patterns
 ## Overview
--- a/skills/writing-skills/testing-skills-with-subagents.md
+++ b/skills/writing-skills/testing-skills-with-subagents.md
@@ -1,6 +1,9 @@
-# Testing Skills With Subagents
+---
 name: testing-skills-with-subagents
 description: Use when creating or editing skills, before deployment, to verify they work under pressure and resist rationalization - applies RED-GREEN-REFACTOR cycle to process documentation by running baseline without skill, writing to address failures, iterating to close loopholes
 ---
-**Load this reference when:** creating or editing skills, before deployment, to verify they work under pressure and resist rationalization.
+# Testing Skills With Subagents
 ## Overview
@@ -324,7 +327,7 @@ Before deploying skill, verify you followed RED-GREEN-REFACTOR:
 - [ ] Added explicit counters for each loophole
 - [ ] Updated rationalization table
 - [ ] Updated red flags list
- [ ] Updated description with violation symptoms
+- [ ] Updated description ith violation symptoms
 - [ ] Re-tested - agent still complies
 - [ ] Meta-tested to verify clarity
 - [ ] Agent follows rule under maximum pressure
--- a/skills/testing-skills-with-subagents/examples/CLAUDE_MD_TESTING.md
+++ b/skills/testing-skills-with-subagents/examples/CLAUDE_MD_TESTING.md
--- a/skills/using-git-worktrees/SKILL.md
+++ b/skills/using-git-worktrees/SKILL.md
@@ -52,14 +52,14 @@ Which would you prefer?
 ### For Project-Local Directories (.worktrees or worktrees)
-**MUST verify directory is ignored before creating worktree:**
+**MUST verify .gitignore before creating worktree:**
 ```bash
-# Check if directory is ignored (respects local, global, and system gitignore)
+# Check if directory pattern in .gitignore
-git check-ignore -q .worktrees 2>/dev/null || git check-ignore -q worktrees 2>/dev/null
+grep -q "^\.worktrees/$" .gitignore || grep -q "^worktrees/$" .gitignore
 ```
-**If NOT ignored:**
+**If NOT in .gitignore:**
 Per Jesse's rule "Fix broken things immediately":
 1. Add appropriate line to .gitignore
@@ -145,33 +145,29 @@ Ready to implement <feature-name>
 | Situation | Action |
 |-----------|--------|
-| `.worktrees/` exists | Use it (verify ignored) |
+| `.worktrees/` exists | Use it (verify .gitignore) |
-| `worktrees/` exists | Use it (verify ignored) |
+| `worktrees/` exists | Use it (verify .gitignore) |
 | Both exist | Use `.worktrees/` |
 | Neither exists | Check CLAUDE.md → Ask user |
-| Directory not ignored | Add to .gitignore + commit |
+| Directory not in .gitignore | Add it immediately + commit |
 | Tests fail during baseline | Report failures + ask |
 | No package.json/Cargo.toml | Skip dependency install |
 ## Common Mistakes
-### Skipping ignore verification
+**Skipping .gitignore verification**
 - **Problem:** Worktree contents get tracked, pollute git status
- **Fix:** Always use `git check-ignore` before creating project-local worktree
+- **Fix:** Always grep .gitignore before creating project-local worktree
 ### Assuming directory location
 **Assuming directory location**
 - **Problem:** Creates inconsistency, violates project conventions
 - **Fix:** Follow priority: existing > CLAUDE.md > ask
-### Proceeding with failing tests
+**Proceeding with failing tests**
 - **Problem:** Can't distinguish new bugs from pre-existing issues
 - **Fix:** Report failures, get explicit permission to proceed
-### Hardcoding setup commands
+**Hardcoding setup commands**
 - **Problem:** Breaks on projects using different tools
 - **Fix:** Auto-detect from project files (package.json, etc.)
@@ -181,7 +177,7 @@ Ready to implement <feature-name>
 You: I'm using the using-git-worktrees skill to set up an isolated workspace.
 [Check .worktrees/ - exists]
-[Verify ignored - git check-ignore confirms .worktrees/ is ignored]
+[Verify .gitignore - contains .worktrees/]
 [Create worktree: git worktree add .worktrees/auth -b feature/auth]
 [Run npm install]
 [Run npm test - 47 passing]
@@ -194,7 +190,7 @@ Ready to implement auth feature
 ## Red Flags
 **Never:**
- Create worktree without verifying it's ignored (project-local)
+- Create worktree without .gitignore verification (project-local)
 - Skip baseline test verification
 - Proceed with failing tests without asking
 - Assume directory location when ambiguous
@@ -202,7 +198,7 @@ Ready to implement auth feature
 **Always:**
 - Follow directory priority: existing > CLAUDE.md > ask
- Verify directory is ignored for project-local
+- Verify .gitignore for project-local
 - Auto-detect and run project setup
 - Verify clean test baseline
@@ -210,9 +206,8 @@ Ready to implement auth feature
 **Called by:**
 - **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
 - Any skill needing isolated workspace
 **Pairs with:**
 - **finishing-a-development-branch** - REQUIRED for cleanup after work complete
 - **executing-plans** or **subagent-driven-development** - Work happens in this worktree
--- a/skills/using-superpowers/SKILL.md
+++ b/skills/using-superpowers/SKILL.md
@@ -1,115 +1,101 @@
 ---
 name: using-superpowers
-description: Use when starting any conversation - establishes how to find and use skills, requiring Skill tool invocation before ANY response including clarifying questions
+description: Use when starting any conversation - establishes mandatory workflows for finding and using skills, including using Skill tool before announcing usage, following brainstorming before coding, and creating TodoWrite todos for checklists
 ---
 <SUBAGENT-STOP>
 If you were dispatched as a subagent to execute a specific task, skip this skill.
 </SUBAGENT-STOP>
 <EXTREMELY-IMPORTANT>
-If you think there is even a 1% chance a skill might apply to what you are doing, you ABSOLUTELY MUST invoke the skill.
+If you think there is even a 1% chance a skill might apply to what you are doing, you ABSOLUTELY MUST read the skill.
 IF A SKILL APPLIES TO YOUR TASK, YOU DO NOT HAVE A CHOICE. YOU MUST USE IT.
 This is not negotiable. This is not optional. You cannot rationalize your way out of this.
 </EXTREMELY-IMPORTANT>
-## Instruction Priority
+# Getting Started with Skills
-Superpowers skills override default system prompt behavior, but **user instructions always take precedence**:
+## MANDATORY FIRST RESPONSE PROTOCOL
-1. **User's explicit instructions** (CLAUDE.md, GEMINI.md, AGENTS.md, direct requests) — highest priority
+Before responding to ANY user message, you MUST complete this checklist:
 2. **Superpowers skills** — override default system behavior where they conflict
 3. **Default system prompt** — lowest priority
-If CLAUDE.md, GEMINI.md, or AGENTS.md says "don't use TDD" and a skill says "always use TDD," follow the user's instructions. The user is in control.
+1. ☐ List available skills in your mind
 2. ☐ Ask yourself: "Does ANY skill match this request?"
 3. ☐ If yes → Use the Skill tool to read and run the skill file
 4. ☐ Announce which skill you're using
 5. ☐ Follow the skill exactly
-## How to Access Skills
+**Responding WITHOUT completing this checklist = automatic failure.**
-**In Claude Code:** Use the `Skill` tool. When you invoke a skill, its content is loaded and presented to you—follow it directly. Never use the Read tool on skill files.
+## Critical Rules
-**In Gemini CLI:** Skills activate via the `activate_skill` tool. Gemini loads skill metadata at session start and activates the full content on demand.
+1. **Follow mandatory workflows.** Brainstorming before coding. Check for relevant skills before ANY task.
-**In other environments:** Check your platform's documentation for how skills are loaded.
+2. Execute skills with the Skill tool
-## Platform Adaptation
+## Common Rationalizations That Mean You're About To Fail
-Skills use Claude Code tool names. Non-CC platforms: see `references/codex-tools.md` (Codex) for tool equivalents. Gemini CLI users get the tool mapping loaded automatically via GEMINI.md.
+If you catch yourself thinking ANY of these thoughts, STOP. You are rationalizing. Check for and use the skill.
-# Using Skills
+- "This is just a simple question" → WRONG. Questions are tasks. Check for skills.
 - "I can check git/files quickly" → WRONG. Files don't have conversation context. Check for skills.
 - "Let me gather information first" → WRONG. Skills tell you HOW to gather information. Check for skills.
 - "This doesn't need a formal skill" → WRONG. If a skill exists for it, use it.
 - "I remember this skill" → WRONG. Skills evolve. Run the current version.
 - "This doesn't count as a task" → WRONG. If you're taking action, it's a task. Check for skills.
 - "The skill is overkill for this" → WRONG. Skills exist because simple things become complex. Use it.
 - "I'll just do this one thing first" → WRONG. Check for skills BEFORE doing anything.
-## The Rule
+**Why:** Skills document proven techniques that save time and prevent mistakes. Not using available skills means repeating solved problems and making known errors.
-**Invoke relevant or requested skills BEFORE any response or action.** Even a 1% chance a skill might apply means that you should invoke the skill to check. If an invoked skill turns out to be wrong for the situation, you don't need to use it.
+If a skill for your task exists, you must use it or you will fail at your task.
-```dot
+## Skills with Checklists
 digraph skill_flow {
    "User message received" [shape=doublecircle];
    "About to EnterPlanMode?" [shape=doublecircle];
    "Already brainstormed?" [shape=diamond];
    "Invoke brainstorming skill" [shape=box];
    "Might any skill apply?" [shape=diamond];
    "Invoke Skill tool" [shape=box];
    "Announce: 'Using [skill] to [purpose]'" [shape=box];
    "Has checklist?" [shape=diamond];
    "Create TodoWrite todo per item" [shape=box];
    "Follow skill exactly" [shape=box];
    "Respond (including clarifications)" [shape=doublecircle];
-    "About to EnterPlanMode?" -> "Already brainstormed?";
+If a skill has a checklist, YOU MUST create TodoWrite todos for EACH item.
    "Already brainstormed?" -> "Invoke brainstorming skill" [label="no"];
    "Already brainstormed?" -> "Might any skill apply?" [label="yes"];
    "Invoke brainstorming skill" -> "Might any skill apply?";
-    "User message received" -> "Might any skill apply?";
+**Don't:**
-    "Might any skill apply?" -> "Invoke Skill tool" [label="yes, even 1%"];
+- Work through checklist mentally
-    "Might any skill apply?" -> "Respond (including clarifications)" [label="definitely not"];
+- Skip creating todos "to save time"
-    "Invoke Skill tool" -> "Announce: 'Using [skill] to [purpose]'";
+- Batch multiple items into one todo
-    "Announce: 'Using [skill] to [purpose]'" -> "Has checklist?";
+- Mark complete without doing them
    "Has checklist?" -> "Create TodoWrite todo per item" [label="yes"];
    "Has checklist?" -> "Follow skill exactly" [label="no"];
    "Create TodoWrite todo per item" -> "Follow skill exactly";
 }
 ```
-## Red Flags
+**Why:** Checklists without TodoWrite tracking = steps get skipped. Every time. The overhead of TodoWrite is tiny compared to the cost of missing steps.
-These thoughts mean STOP—you're rationalizing:
+## Announcing Skill Usage
-| Thought | Reality |
+Before using a skill, announce that you are using it.
-|---------|---------|
+"I'm using [Skill Name] to [what you're doing]."
 | "This is just a simple question" | Questions are tasks. Check for skills. |
 | "I need more context first" | Skill check comes BEFORE clarifying questions. |
 | "Let me explore the codebase first" | Skills tell you HOW to explore. Check first. |
 | "I can check git/files quickly" | Files lack conversation context. Check for skills. |
 | "Let me gather information first" | Skills tell you HOW to gather information. |
 | "This doesn't need a formal skill" | If a skill exists, use it. |
 | "I remember this skill" | Skills evolve. Read current version. |
 | "This doesn't count as a task" | Action = task. Check for skills. |
 | "The skill is overkill" | Simple things become complex. Use it. |
 | "I'll just do this one thing first" | Check BEFORE doing anything. |
 | "This feels productive" | Undisciplined action wastes time. Skills prevent this. |
 | "I know what that means" | Knowing the concept ≠ using the skill. Invoke it. |
-## Skill Priority
+**Examples:**
 - "I'm using the brainstorming skill to refine your idea into a design."
 - "I'm using the test-driven-development skill to implement this feature."
-When multiple skills could apply, use this order:
+**Why:** Transparency helps your human partner understand your process and catch errors early. It also confirms you actually read the skill.
-1. **Process skills first** (brainstorming, debugging) - these determine HOW to approach the task
+# About these skills
 2. **Implementation skills second** (frontend-design, mcp-builder) - these guide execution
-"Let's build X" → brainstorming first, then implementation skills.
+**Many skills contain rigid rules (TDD, debugging, verification).** Follow them exactly. Don't adapt away the discipline.
 "Fix this bug" → debugging first, then domain-specific skills.
-## Skill Types
+**Some skills are flexible patterns (architecture, naming).** Adapt core principles to your context.
-**Rigid** (TDD, debugging): Follow exactly. Don't adapt away discipline.
+The skill itself tells you which type it is.
-**Flexible** (patterns): Adapt principles to context.
+## Instructions ≠ Permission to Skip Workflows
-The skill itself tells you which.
+Your human partner's specific instructions describe WHAT to do, not HOW.
-## User Instructions
+"Add X", "Fix Y" = the goal, NOT permission to skip brainstorming, TDD, or RED-GREEN-REFACTOR.
-Instructions say WHAT, not HOW. "Add X" or "Fix Y" doesn't mean skip workflows.
+**Red flags:** "Instruction was specific" • "Seems simple" • "Workflow is overkill"
 **Why:** Specific instructions mean clear requirements, which is when workflows matter MOST. Skipping process on "simple" tasks is how simple tasks become complex problems.
 ## Summary
 **Starting any task:**
 1. If relevant skill exists → Use the skill
 3. Announce you're using it
 4. Follow what it says
 **Skill has checklist?** TodoWrite for every item.
 **Finding a relevant skill = mandatory to read and use it. Not optional.**
--- a/skills/using-superpowers/references/codex-tools.md
+++ b/skills/using-superpowers/references/codex-tools.md
@@ -1,100 +0,0 @@
 # Codex Tool Mapping
 Skills use Claude Code tool names. When you encounter these in a skill, use your platform equivalent:
 | Skill references | Codex equivalent |
 |-----------------|------------------|
 | `Task` tool (dispatch subagent) | `spawn_agent` (see [Named agent dispatch](#named-agent-dispatch)) |
 | Multiple `Task` calls (parallel) | Multiple `spawn_agent` calls |
 | Task returns result | `wait` |
 | Task completes automatically | `close_agent` to free slot |
 | `TodoWrite` (task tracking) | `update_plan` |
 | `Skill` tool (invoke a skill) | Skills load natively — just follow the instructions |
 | `Read`, `Write`, `Edit` (files) | Use your native file tools |
 | `Bash` (run commands) | Use your native shell tools |
 ## Subagent dispatch requires multi-agent support
 Add to your Codex config (`~/.codex/config.toml`):
 ```toml
 [features]
 multi_agent = true
 ```
 This enables `spawn_agent`, `wait`, and `close_agent` for skills like `dispatching-parallel-agents` and `subagent-driven-development`.
 ## Named agent dispatch
 Claude Code skills reference named agent types like `superpowers:code-reviewer`.
 Codex does not have a named agent registry — `spawn_agent` creates generic agents
 from built-in roles (`default`, `explorer`, `worker`).
 When a skill says to dispatch a named agent type:
 1. Find the agent's prompt file (e.g., `agents/code-reviewer.md` or the skill's
   local prompt template like `code-quality-reviewer-prompt.md`)
 2. Read the prompt content
 3. Fill any template placeholders (`{BASE_SHA}`, `{WHAT_WAS_IMPLEMENTED}`, etc.)
 4. Spawn a `worker` agent with the filled content as the `message`
 | Skill instruction | Codex equivalent |
 |-------------------|------------------|
 | `Task tool (superpowers:code-reviewer)` | `spawn_agent(agent_type="worker", message=...)` with `code-reviewer.md` content |
 | `Task tool (general-purpose)` with inline prompt | `spawn_agent(message=...)` with the same prompt |
 ### Message framing
 The `message` parameter is user-level input, not a system prompt. Structure it
 for maximum instruction adherence:
 ```
 Your task is to perform the following. Follow the instructions below exactly.
 <agent-instructions>
 [filled prompt content from the agent's .md file]
 </agent-instructions>
 Execute this now. Output ONLY the structured response following the format
 specified in the instructions above.
 ```
 - Use task-delegation framing ("Your task is...") rather than persona framing ("You are...")
 - Wrap instructions in XML tags — the model treats tagged blocks as authoritative
 - End with an explicit execution directive to prevent summarization of the instructions
 ### When this workaround can be removed
 This approach compensates for Codex's plugin system not yet supporting an `agents`
 field in `plugin.json`. When `RawPluginManifest` gains an `agents` field, the
 plugin can symlink to `agents/` (mirroring the existing `skills/` symlink) and
 skills can dispatch named agent types directly.
 ## 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 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.
--- a/skills/using-superpowers/references/gemini-tools.md
+++ b/skills/using-superpowers/references/gemini-tools.md
@@ -1,33 +0,0 @@
 # Gemini CLI Tool Mapping
 Skills use Claude Code tool names. When you encounter these in a skill, use your platform equivalent:
 | Skill references | Gemini CLI equivalent |
 |-----------------|----------------------|
 | `Read` (file reading) | `read_file` |
 | `Write` (file creation) | `write_file` |
 | `Edit` (file editing) | `replace` |
 | `Bash` (run commands) | `run_shell_command` |
 | `Grep` (search file content) | `grep_search` |
 | `Glob` (search files by name) | `glob` |
 | `TodoWrite` (task tracking) | `write_todos` |
 | `Skill` tool (invoke a skill) | `activate_skill` |
 | `WebSearch` | `google_web_search` |
 | `WebFetch` | `web_fetch` |
 | `Task` tool (dispatch subagent) | No equivalent — Gemini CLI does not support subagents |
 ## No subagent support
 Gemini CLI has no equivalent to Claude Code's `Task` tool. Skills that rely on subagent dispatch (`subagent-driven-development`, `dispatching-parallel-agents`) will fall back to single-session execution via `executing-plans`.
 ## Additional Gemini CLI tools
 These tools are available in Gemini CLI but have no Claude Code equivalent:
 | Tool | Purpose |
 |------|---------|
 | `list_directory` | List files and subdirectories |
 | `save_memory` | Persist facts to GEMINI.md across sessions |
 | `ask_user` | Request structured input from the user |
 | `tracker_create_task` | Rich task management (create, update, list, visualize) |
 | `enter_plan_mode` / `exit_plan_mode` | Switch to read-only research mode before making changes |
--- a/skills/writing-plans/SKILL.md
+++ b/skills/writing-plans/SKILL.md
@@ -1,6 +1,6 @@
 ---
 name: writing-plans
-description: Use when you have a spec or requirements for a multi-step task, before touching code
+description: Use when design is complete and you need detailed implementation tasks for engineers with zero codebase context - creates comprehensive implementation plans with exact file paths, complete code examples, and verification steps assuming engineer has minimal domain knowledge
 ---
 # Writing Plans
@@ -15,23 +15,7 @@ Assume they are a skilled developer, but know almost nothing about our toolset o
 **Context:** This should be run in a dedicated worktree (created by brainstorming skill).
-**Save plans to:** `docs/superpowers/plans/YYYY-MM-DD-<feature-name>.md`
+**Save plans to:** `docs/plans/YYYY-MM-DD-<feature-name>.md`
 - (User preferences for plan location override this default)
 ## Scope Check
 If the spec covers multiple independent subsystems, it should have been broken into sub-project specs during brainstorming. If it wasn't, suggest breaking this into separate plans — one per subsystem. Each plan should produce working, testable software on its own.
 ## File Structure
 Before defining tasks, map out which files will be created or modified and what each one is responsible for. This is where decomposition decisions get locked in.
 - Design units with clear boundaries and well-defined interfaces. Each file should have one clear responsibility.
 - You reason best about code you can hold in context at once, and your edits are more reliable when files are focused. Prefer smaller, focused files over large ones that do too much.
 - Files that change together should live together. Split by responsibility, not by technical layer.
 - In existing codebases, follow established patterns. If the codebase uses large files, don't unilaterally restructure - but if a file you're modifying has grown unwieldy, including a split in the plan is reasonable.
 This structure informs the task decomposition. Each task should produce self-contained changes that make sense independently.
 ## Bite-Sized Task Granularity
@@ -49,7 +33,7 @@ This structure informs the task decomposition. Each task should produce self-con
 ```markdown
 # [Feature Name] 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.
+> **For Claude:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.
 **Goal:** [One sentence describing what this builds]
@@ -62,7 +46,7 @@ This structure informs the task decomposition. Each task should produce self-con
 ## Task Structure
-````markdown
+```markdown
 ### Task N: [Component Name]
 **Files:**
@@ -70,7 +54,7 @@ This structure informs the task decomposition. Each task should produce self-con
 - Modify: `exact/path/to/existing.py:123-145`
 - Test: `tests/exact/path/to/test.py`
- [ ] **Step 1: Write the failing test**
+**Step 1: Write the failing test**
 ```python
 def test_specific_behavior():
@@ -78,75 +62,55 @@ def test_specific_behavior():
    assert result == expected
 ```
- [ ] **Step 2: Run test to verify it fails**
+**Step 2: Run test to verify it fails**
 Run: `pytest tests/path/test.py::test_name -v`
 Expected: FAIL with "function not defined"
- [ ] **Step 3: Write minimal implementation**
+**Step 3: Write minimal implementation**
 ```python
 def function(input):
    return expected
 ```
- [ ] **Step 4: Run test to verify it passes**
+**Step 4: Run test to verify it passes**
 Run: `pytest tests/path/test.py::test_name -v`
 Expected: PASS
- [ ] **Step 5: Commit**
+**Step 5: Commit**
 ```bash
 git add tests/path/test.py src/path/file.py
 git commit -m "feat: add specific feature"
 ```
-````
+```
 ## No Placeholders
 Every step must contain the actual content an engineer needs. These are **plan failures** — never write them:
 - "TBD", "TODO", "implement later", "fill in details"
 - "Add appropriate error handling" / "add validation" / "handle edge cases"
 - "Write tests for the above" (without actual test code)
 - "Similar to Task N" (repeat the code — the engineer may be reading tasks out of order)
 - Steps that describe what to do without showing how (code blocks required for code steps)
 - References to types, functions, or methods not defined in any task
 ## Remember
 - Exact file paths always
- Complete code in every step — if a step changes code, show the code
+- Complete code in plan (not "add validation")
 - Exact commands with expected output
 - Reference relevant skills with @ syntax
 - DRY, YAGNI, TDD, frequent commits
 ## Self-Review
 After writing the complete plan, look at the spec with fresh eyes and check the plan against it. This is a checklist you run yourself — not a subagent dispatch.
 **1. Spec coverage:** Skim each section/requirement in the spec. Can you point to a task that implements it? List any gaps.
 **2. Placeholder scan:** Search your plan for red flags — any of the patterns from the "No Placeholders" section above. Fix them.
 **3. Type consistency:** Do the types, method signatures, and property names you used in later tasks match what you defined in earlier tasks? A function called `clearLayers()` in Task 3 but `clearFullLayers()` in Task 7 is a bug.
 If you find issues, fix them inline. No need to re-review — just fix and move on. If you find a spec requirement with no task, add the task.
 ## Execution Handoff
 After saving the plan, offer execution choice:
-**"Plan complete and saved to `docs/superpowers/plans/<filename>.md`. Two execution options:**
+**"Plan complete and saved to `docs/plans/<filename>.md`. Two execution options:**
-**1. Subagent-Driven (recommended)** - I dispatch a fresh subagent per task, review between tasks, fast iteration
+**1. Subagent-Driven (this session)** - I dispatch fresh subagent per task, review between tasks, fast iteration
-**2. Inline Execution** - Execute tasks in this session using executing-plans, batch execution with checkpoints
+**2. Parallel Session (separate)** - Open new session with executing-plans, batch execution with checkpoints
 **Which approach?"**
 **If Subagent-Driven chosen:**
 - **REQUIRED SUB-SKILL:** Use superpowers:subagent-driven-development
- Fresh subagent per task + two-stage review
+- Stay in this session
 - Fresh subagent per task + code review
-**If Inline Execution chosen:**
+**If Parallel Session chosen:**
- **REQUIRED SUB-SKILL:** Use superpowers:executing-plans
+- Guide them to open new session in worktree
- Batch execution with checkpoints for review
+- **REQUIRED SUB-SKILL:** New session uses superpowers:executing-plans
--- a/skills/writing-plans/plan-document-reviewer-prompt.md
+++ b/skills/writing-plans/plan-document-reviewer-prompt.md
@@ -1,49 +0,0 @@
 # Plan Document Reviewer Prompt Template
 Use this template when dispatching a plan document reviewer subagent.
 **Purpose:** Verify the plan is complete, matches the spec, and has proper task decomposition.
 **Dispatch after:** The complete plan is written.
 ```
 Task tool (general-purpose):
  description: "Review plan document"
  prompt: |
    You are a plan document reviewer. Verify this plan is complete and ready for implementation.
    **Plan to review:** [PLAN_FILE_PATH]
    **Spec for reference:** [SPEC_FILE_PATH]
    ## What to Check
    | Category | What to Look For |
    |----------|------------------|
    | Completeness | TODOs, placeholders, incomplete tasks, missing steps |
    | Spec Alignment | Plan covers spec requirements, no major scope creep |
    | Task Decomposition | Tasks have clear boundaries, steps are actionable |
    | Buildability | Could an engineer follow this plan without getting stuck? |
    ## Calibration
    **Only flag issues that would cause real problems during implementation.**
    An implementer building the wrong thing or getting stuck is an issue.
    Minor wording, stylistic preferences, and "nice to have" suggestions are not.
    Approve unless there are serious gaps — missing requirements from the spec,
    contradictory steps, placeholder content, or tasks so vague they can't be acted on.
    ## Output Format
    ## Plan Review
    **Status:** Approved | Issues Found
    **Issues (if any):**
    - [Task X, Step Y]: [specific issue] - [why it matters for implementation]
    **Recommendations (advisory, do not block approval):**
    - [suggestions for improvement]
 ```
 **Reviewer returns:** Status, Issues (if any), Recommendations
--- a/skills/writing-skills/SKILL.md
+++ b/skills/writing-skills/SKILL.md
@@ -1,6 +1,6 @@
 ---
 name: writing-skills
-description: Use when creating new skills, editing existing skills, or verifying skills work before deployment
+description: Use when creating new skills, editing existing skills, or verifying skills work before deployment - applies TDD to process documentation by testing with subagents before writing, iterating until bulletproof against rationalization
 ---
 # Writing Skills
@@ -9,7 +9,7 @@ description: Use when creating new skills, editing existing skills, or verifying
 **Writing skills IS Test-Driven Development applied to process documentation.**
-**Personal skills live in agent-specific directories (`~/.claude/skills` for Claude Code, `~/.agents/skills/` for Codex)** 
+**Personal skills are written to `~/.claude/skills`** 
 You write test cases (pressure scenarios with subagents), watch them fail (baseline behavior), write the skill (documentation), watch tests pass (agents comply), and refactor (close loopholes).
@@ -56,7 +56,6 @@ The entire skill creation process follows RED-GREEN-REFACTOR.
 - One-off solutions
 - Standard practices well-documented elsewhere
 - Project-specific conventions (put in CLAUDE.md)
 - Mechanical constraints (if it's enforceable with regex/validation, automate it—save documentation for judgment calls)
 ## Skill Types
@@ -93,19 +92,18 @@ skills/
 ## SKILL.md Structure
 **Frontmatter (YAML):**
- Two required fields: `name` and `description` (see [agentskills.io/specification](https://agentskills.io/specification) for all supported fields)
+- Only two fields supported: `name` and `description`
 - Max 1024 characters total
 - `name`: Use letters, numbers, and hyphens only (no parentheses, special chars)
- `description`: Third-person, describes ONLY when to use (NOT what it does)
+- `description`: Third-person, includes BOTH what it does AND when to use it
  - Start with "Use when..." to focus on triggering conditions
  - Include specific symptoms, situations, and contexts
  - **NEVER summarize the skill's process or workflow** (see CSO section for why)
  - Keep under 500 characters if possible
 ```markdown
 ---
 name: Skill-Name-With-Hyphens
-description: Use when [specific triggering conditions and symptoms]
+description: Use when [specific triggering conditions and symptoms] - [what the skill does and how it helps, written in third person]
 ---
 # Skill Name
@@ -145,31 +143,7 @@ Concrete results
 **Purpose:** Claude reads description to decide which skills to load for a given task. Make it answer: "Should I read this skill right now?"
-**Format:** Start with "Use when..." to focus on triggering conditions
+**Format:** Start with "Use when..." to focus on triggering conditions, then explain what it does
 **CRITICAL: Description = When to Use, NOT What the Skill Does**
 The description should ONLY describe triggering conditions. Do NOT summarize the skill's process or workflow in the description.
 **Why this matters:** Testing revealed that when a description summarizes the skill's workflow, Claude may follow the description instead of reading the full skill content. A description saying "code review between tasks" caused Claude to do ONE review, even though the skill's flowchart clearly showed TWO reviews (spec compliance then code quality).
 When the description was changed to just "Use when executing implementation plans with independent tasks" (no workflow summary), Claude correctly read the flowchart and followed the two-stage review process.
 **The trap:** Descriptions that summarize workflow create a shortcut Claude will take. The skill body becomes documentation Claude skips.
 ```yaml
 # ❌ BAD: Summarizes workflow - Claude may follow this instead of reading skill
 description: Use when executing plans - dispatches subagent per task with code review between tasks
 # ❌ BAD: Too much process detail
 description: Use for TDD - write test first, watch it fail, write minimal code, refactor
 # ✅ GOOD: Just triggering conditions, no workflow summary
 description: Use when executing implementation plans with independent tasks in the current session
 # ✅ GOOD: Triggering conditions only
 description: Use when implementing any feature or bugfix, before writing implementation code
 ```
 **Content:**
 - Use concrete triggers, symptoms, and situations that signal this skill applies
@@ -177,7 +151,6 @@ description: Use when implementing any feature or bugfix, before writing impleme
 - Keep triggers technology-agnostic unless the skill itself is technology-specific
 - If skill is technology-specific, make that explicit in the trigger
 - Write in third person (injected into system prompt)
 - **NEVER summarize the skill's process or workflow**
 ```yaml
 # ❌ BAD: Too abstract, vague, doesn't include when to use
@@ -189,11 +162,11 @@ description: I can help you with async tests when they're flaky
 # ❌ BAD: Mentions technology but skill isn't specific to it
 description: Use when tests use setTimeout/sleep and are flaky
-# ✅ GOOD: Starts with "Use when", describes problem, no workflow
+# ✅ GOOD: Starts with "Use when", describes problem, then what it does
-description: Use when tests have race conditions, timing dependencies, or pass/fail inconsistently
+description: Use when tests have race conditions, timing dependencies, or pass/fail inconsistently - replaces arbitrary timeouts with condition polling for reliable async tests
 # ✅ GOOD: Technology-specific skill with explicit trigger
-description: Use when using React Router and handling authentication redirects
+description: Use when using React Router and handling authentication redirects - provides patterns for protected routes and auth state management
 ```
 ### 2. Keyword Coverage
@@ -208,7 +181,7 @@ Use words Claude would search for:
 **Use active voice, verb-first:**
 - ✅ `creating-skills` not `skill-creation`
- ✅ `condition-based-waiting` not `async-test-helpers`
+- ✅ `testing-skills-with-subagents` not `subagent-skill-testing`
 ### 4. Token Efficiency (Critical)
@@ -315,12 +288,6 @@ digraph when_flowchart {
 See @graphviz-conventions.dot for graphviz style rules.
 **Visualizing for your human partner:** Use `render-graphs.js` in this directory to render a skill's flowcharts to SVG:
 ```bash
 ./render-graphs.js ../some-skill           # Each diagram separately
 ./render-graphs.js ../some-skill --combine # All diagrams in one SVG
 ```
 ## Code Examples
 **One excellent example beats many mediocre ones**
@@ -553,7 +520,7 @@ Run same scenarios WITH skill. Agent should now comply.
 Agent found new rationalization? Add explicit counter. Re-test until bulletproof.
-**Testing methodology:** See @testing-skills-with-subagents.md for the complete testing methodology:
+**REQUIRED SUB-SKILL:** Use superpowers:testing-skills-with-subagents for the complete testing methodology:
 - How to write pressure scenarios
 - Pressure types (time, sunk cost, authority, exhaustion)
 - Plugging holes systematically
@@ -604,7 +571,7 @@ Deploying untested skills = deploying untested code. It's a violation of quality
 **GREEN Phase - Write Minimal Skill:**
 - [ ] Name uses only letters, numbers, hyphens (no parentheses/special chars)
- [ ] YAML frontmatter with required `name` and `description` fields (max 1024 chars; see [spec](https://agentskills.io/specification))
+- [ ] YAML frontmatter with only name and description (max 1024 chars)
 - [ ] Description starts with "Use when..." and includes specific triggers/symptoms
 - [ ] Description written in third person
 - [ ] Keywords throughout for search (errors, symptoms, tools)
--- a/skills/writing-skills/anthropic-best-practices.md
+++ b/skills/writing-skills/anthropic-best-practices.md
@@ -10,7 +10,7 @@ For conceptual background on how Skills work, see the [Skills overview](/en/docs
 ### Concise is key
-The [context window](https://platform.claude.com/docs/en/build-with-claude/context-windows) is a public good. Your Skill shares the context window with everything else Claude needs to know, including:
+The [context window](/en/docs/build-with-claude/context-windows) is a public good. Your Skill shares the context window with everything else Claude needs to know, including:
 * The system prompt
 * Conversation history
@@ -144,7 +144,7 @@ What works perfectly for Opus might need more detail for Haiku. If you plan to u
 ## Skill structure
 <Note>
-  **YAML Frontmatter**: The SKILL.md frontmatter requires two fields:
+  **YAML Frontmatter**: The SKILL.md frontmatter supports two fields:
  * `name` - Human-readable name of the Skill (64 characters maximum)
  * `description` - One-line description of what the Skill does and when to use it (1024 characters maximum)
@@ -1092,7 +1092,7 @@ reader = PdfReader("file.pdf")
 ### YAML frontmatter requirements
-The SKILL.md frontmatter requires `name` (64 characters max) and `description` (1024 characters max) fields. See the [Skills overview](/en/docs/agents-and-tools/agent-skills/overview#skill-structure) for complete structure details.
+The SKILL.md frontmatter includes only `name` (64 characters max) and `description` (1024 characters max) fields. See the [Skills overview](/en/docs/agents-and-tools/agent-skills/overview#skill-structure) for complete structure details.
 ### Token budgets
--- a/skills/writing-skills/render-graphs.js
+++ b/skills/writing-skills/render-graphs.js
@@ -1,168 +0,0 @@
 #!/usr/bin/env node
 /**
 * Render graphviz diagrams from a skill's SKILL.md to SVG files.
 *
 * Usage:
 *   ./render-graphs.js <skill-directory>           # Render each diagram separately
 *   ./render-graphs.js <skill-directory> --combine # Combine all into one diagram
 *
 * Extracts all ```dot blocks from SKILL.md and renders to SVG.
 * Useful for helping your human partner visualize the process flows.
 *
 * Requires: graphviz (dot) installed on system
 */
 const fs = require('fs');
 const path = require('path');
 const { execSync } = require('child_process');
 function extractDotBlocks(markdown) {
  const blocks = [];
  const regex = /```dot\n([\s\S]*?)```/g;
  let match;
  while ((match = regex.exec(markdown)) !== null) {
    const content = match[1].trim();
    // Extract digraph name
    const nameMatch = content.match(/digraph\s+(\w+)/);
    const name = nameMatch ? nameMatch[1] : `graph_${blocks.length + 1}`;
    blocks.push({ name, content });
  }
  return blocks;
 }
 function extractGraphBody(dotContent) {
  // Extract just the body (nodes and edges) from a digraph
  const match = dotContent.match(/digraph\s+\w+\s*\{([\s\S]*)\}/);
  if (!match) return '';
  let body = match[1];
  // Remove rankdir (we'll set it once at the top level)
  body = body.replace(/^\s*rankdir\s*=\s*\w+\s*;?\s*$/gm, '');
  return body.trim();
 }
 function combineGraphs(blocks, skillName) {
  const bodies = blocks.map((block, i) => {
    const body = extractGraphBody(block.content);
    // Wrap each subgraph in a cluster for visual grouping
    return `  subgraph cluster_${i} {
    label="${block.name}";
    ${body.split('\n').map(line => '  ' + line).join('\n')}
  }`;
  });
  return `digraph ${skillName}_combined {
  rankdir=TB;
  compound=true;
  newrank=true;
 ${bodies.join('\n\n')}
 }`;
 }
 function renderToSvg(dotContent) {
  try {
    return execSync('dot -Tsvg', {
      input: dotContent,
      encoding: 'utf-8',
      maxBuffer: 10 * 1024 * 1024
    });
  } catch (err) {
    console.error('Error running dot:', err.message);
    if (err.stderr) console.error(err.stderr.toString());
    return null;
  }
 }
 function main() {
  const args = process.argv.slice(2);
  const combine = args.includes('--combine');
  const skillDirArg = args.find(a => !a.startsWith('--'));
  if (!skillDirArg) {
    console.error('Usage: render-graphs.js <skill-directory> [--combine]');
    console.error('');
    console.error('Options:');
    console.error('  --combine    Combine all diagrams into one SVG');
    console.error('');
    console.error('Example:');
    console.error('  ./render-graphs.js ../subagent-driven-development');
    console.error('  ./render-graphs.js ../subagent-driven-development --combine');
    process.exit(1);
  }
  const skillDir = path.resolve(skillDirArg);
  const skillFile = path.join(skillDir, 'SKILL.md');
  const skillName = path.basename(skillDir).replace(/-/g, '_');
  if (!fs.existsSync(skillFile)) {
    console.error(`Error: ${skillFile} not found`);
    process.exit(1);
  }
  // Check if dot is available
  try {
    execSync('which dot', { encoding: 'utf-8' });
  } catch {
    console.error('Error: graphviz (dot) not found. Install with:');
    console.error('  brew install graphviz    # macOS');
    console.error('  apt install graphviz     # Linux');
    process.exit(1);
  }
  const markdown = fs.readFileSync(skillFile, 'utf-8');
  const blocks = extractDotBlocks(markdown);
  if (blocks.length === 0) {
    console.log('No ```dot blocks found in', skillFile);
    process.exit(0);
  }
  console.log(`Found ${blocks.length} diagram(s) in ${path.basename(skillDir)}/SKILL.md`);
  const outputDir = path.join(skillDir, 'diagrams');
  if (!fs.existsSync(outputDir)) {
    fs.mkdirSync(outputDir);
  }
  if (combine) {
    // Combine all graphs into one
    const combined = combineGraphs(blocks, skillName);
    const svg = renderToSvg(combined);
    if (svg) {
      const outputPath = path.join(outputDir, `${skillName}_combined.svg`);
      fs.writeFileSync(outputPath, svg);
      console.log(`  Rendered: ${skillName}_combined.svg`);
      // Also write the dot source for debugging
      const dotPath = path.join(outputDir, `${skillName}_combined.dot`);
      fs.writeFileSync(dotPath, combined);
      console.log(`  Source: ${skillName}_combined.dot`);
    } else {
      console.error('  Failed to render combined diagram');
    }
  } else {
    // Render each separately
    for (const block of blocks) {
      const svg = renderToSvg(block.content);
      if (svg) {
        const outputPath = path.join(outputDir, `${block.name}.svg`);
        fs.writeFileSync(outputPath, svg);
        console.log(`  Rendered: ${block.name}.svg`);
      } else {
        console.error(`  Failed: ${block.name}`);
      }
    }
  }
  console.log(`\nOutput: ${outputDir}/`);
 }
 main();
--- a/tests/brainstorm-server/package-lock.json
+++ b/tests/brainstorm-server/package-lock.json
@@ -1,36 +0,0 @@
 {
  "name": "brainstorm-server-tests",
  "version": "1.0.0",
  "lockfileVersion": 3,
  "requires": true,
  "packages": {
    "": {
      "name": "brainstorm-server-tests",
      "version": "1.0.0",
      "dependencies": {
        "ws": "^8.19.0"
      }
    },
    "node_modules/ws": {
      "version": "8.19.0",
      "resolved": "https://registry.npmjs.org/ws/-/ws-8.19.0.tgz",
      "integrity": "sha512-blAT2mjOEIi0ZzruJfIhb3nps74PRWTCz1IjglWEEpQl5XS/UNama6u2/rjFkDDouqr4L67ry+1aGIALViWjDg==",
      "license": "MIT",
      "engines": {
        "node": ">=10.0.0"
      },
      "peerDependencies": {
        "bufferutil": "^4.0.1",
        "utf-8-validate": ">=5.0.2"
      },
      "peerDependenciesMeta": {
        "bufferutil": {
          "optional": true
        },
        "utf-8-validate": {
          "optional": true
        }
      }
    }
  }
 }
--- a/tests/brainstorm-server/package.json
+++ b/tests/brainstorm-server/package.json
@@ -1,10 +0,0 @@
 {
  "name": "brainstorm-server-tests",
  "version": "1.0.0",
  "scripts": {
    "test": "node server.test.js"
  },
  "dependencies": {
    "ws": "^8.19.0"
  }
 }
--- a/tests/brainstorm-server/server.test.js
+++ b/tests/brainstorm-server/server.test.js
@@ -1,427 +0,0 @@
 /**
 * Integration tests for the brainstorm server.
 *
 * Tests the full server behavior: HTTP serving, WebSocket communication,
 * file watching, and the brainstorming workflow.
 *
 * Uses the `ws` npm package as a test client (test-only dependency,
 * not shipped to end users).
 */
 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, '../../skills/brainstorming/scripts/server.cjs');
 const TEST_PORT = 3334;
 const TEST_DIR = '/tmp/brainstorm-test';
 const CONTENT_DIR = path.join(TEST_DIR, 'content');
 const STATE_DIR = path.join(TEST_DIR, 'state');
 function cleanup() {
  if (fs.existsSync(TEST_DIR)) {
    fs.rmSync(TEST_DIR, { 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,
        headers: res.headers,
        body: data
      }));
    }).on('error', reject);
  });
 }
 function startServer() {
  return spawn('node', [SERVER_PATH], {
    env: { ...process.env, BRAINSTORM_PORT: TEST_PORT, BRAINSTORM_DIR: TEST_DIR }
  });
 }
 async function waitForServer(server) {
  let stdout = '';
  let stderr = '';
  return new Promise((resolve, reject) => {
    server.stdout.on('data', (data) => {
      stdout += data.toString();
      if (stdout.includes('server-started')) {
        resolve({ stdout, stderr, getStdout: () => stdout });
      }
    });
    server.stderr.on('data', (data) => { stderr += data.toString(); });
    server.on('error', reject);
    setTimeout(() => reject(new Error(`Server didn't start. stderr: ${stderr}`)), 5000);
  });
 }
 async function runTests() {
  cleanup();
  const server = startServer();
  let stdoutAccum = '';
  server.stdout.on('data', (data) => { stdoutAccum += data.toString(); });
  const { stdout: initialStdout } = await waitForServer(server);
  let passed = 0;
  let failed = 0;
  function test(name, fn) {
    return fn().then(() => {
      console.log(`  PASS: ${name}`);
      passed++;
    }).catch(e => {
      console.log(`  FAIL: ${name}`);
      console.log(`    ${e.message}`);
      failed++;
    });
  }
  try {
    // ========== Server Startup ==========
    console.log('\n--- Server Startup ---');
    await test('outputs server-started JSON on startup', () => {
      const msg = JSON.parse(initialStdout.trim());
      assert.strictEqual(msg.type, 'server-started');
      assert.strictEqual(msg.port, TEST_PORT);
      assert(msg.url, 'Should include URL');
      assert(msg.screen_dir, 'Should include screen_dir');
      return Promise.resolve();
    });
    await test('writes server-info to state/', () => {
      const infoPath = path.join(STATE_DIR, 'server-info');
      assert(fs.existsSync(infoPath), 'state/server-info should exist');
      const info = JSON.parse(fs.readFileSync(infoPath, 'utf-8').trim());
      assert.strictEqual(info.type, 'server-started');
      assert.strictEqual(info.port, TEST_PORT);
      assert.strictEqual(info.screen_dir, CONTENT_DIR, 'screen_dir should point to content/');
      assert.strictEqual(info.state_dir, STATE_DIR, 'state_dir should point to state/');
      return Promise.resolve();
    });
    // ========== HTTP Serving ==========
    console.log('\n--- HTTP Serving ---');
    await test('serves waiting page when no screens exist', async () => {
      const res = await fetch(`http://localhost:${TEST_PORT}/`);
      assert.strictEqual(res.status, 200);
      assert(res.body.includes('Waiting for the agent'), 'Should show waiting message');
    });
    await test('injects helper.js into waiting page', async () => {
      const res = await fetch(`http://localhost:${TEST_PORT}/`);
      assert(res.body.includes('WebSocket'), 'Should have helper.js injected');
      assert(res.body.includes('toggleSelect'), 'Should have toggleSelect from helper');
      assert(res.body.includes('brainstorm'), 'Should have brainstorm API from helper');
    });
    await test('returns Content-Type text/html', async () => {
      const res = await fetch(`http://localhost:${TEST_PORT}/`);
      assert(res.headers['content-type'].includes('text/html'), 'Should be text/html');
    });
    await test('serves full HTML documents as-is (not wrapped)', async () => {
      const fullDoc = '<!DOCTYPE html>\n<html><head><title>Custom</title></head><body><h1>Custom Page</h1></body></html>';
      fs.writeFileSync(path.join(CONTENT_DIR, 'full-doc.html'), fullDoc);
      await sleep(300);
      const res = await fetch(`http://localhost:${TEST_PORT}/`);
      assert(res.body.includes('<h1>Custom Page</h1>'), 'Should contain original content');
      assert(res.body.includes('WebSocket'), 'Should still inject helper.js');
      assert(!res.body.includes('indicator-bar'), 'Should NOT wrap in frame template');
    });
    await test('wraps content fragments in frame template', async () => {
      const fragment = '<h2>Pick a layout</h2>\n<div class="options"><div class="option" data-choice="a"><div class="letter">A</div></div></div>';
      fs.writeFileSync(path.join(CONTENT_DIR, 'fragment.html'), fragment);
      await sleep(300);
      const res = await fetch(`http://localhost:${TEST_PORT}/`);
      assert(res.body.includes('indicator-bar'), 'Fragment should get indicator bar');
      assert(!res.body.includes('<!-- CONTENT -->'), 'Placeholder should be replaced');
      assert(res.body.includes('Pick a layout'), 'Fragment content should be present');
      assert(res.body.includes('data-choice="a"'), 'Fragment interactive elements intact');
    });
    await test('serves newest file by mtime', async () => {
      fs.writeFileSync(path.join(CONTENT_DIR, 'older.html'), '<h2>Older</h2>');
      await sleep(100);
      fs.writeFileSync(path.join(CONTENT_DIR, 'newer.html'), '<h2>Newer</h2>');
      await sleep(300);
      const res = await fetch(`http://localhost:${TEST_PORT}/`);
      assert(res.body.includes('Newer'), 'Should serve newest file');
    });
    await test('ignores non-html files for serving', async () => {
      // Write a newer non-HTML file — should still serve newest .html
      fs.writeFileSync(path.join(CONTENT_DIR, 'data.json'), '{"not": "html"}');
      await sleep(300);
      const res = await fetch(`http://localhost:${TEST_PORT}/`);
      assert(res.body.includes('Newer'), 'Should still serve newest HTML');
      assert(!res.body.includes('"not"'), 'Should not serve JSON');
    });
    await test('returns 404 for non-root paths', async () => {
      const res = await fetch(`http://localhost:${TEST_PORT}/other`);
      assert.strictEqual(res.status, 404);
    });
    // ========== WebSocket Communication ==========
    console.log('\n--- WebSocket Communication ---');
    await test('accepts WebSocket upgrade on /', async () => {
      const ws = new WebSocket(`ws://localhost:${TEST_PORT}`);
      await new Promise((resolve, reject) => {
        ws.on('open', resolve);
        ws.on('error', reject);
      });
      ws.close();
    });
    await test('relays user events to stdout with source field', async () => {
      stdoutAccum = '';
      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(300);
      assert(stdoutAccum.includes('"source":"user-event"'), 'Should tag with source');
      assert(stdoutAccum.includes('Test Button'), 'Should include event data');
      ws.close();
    });
    await test('writes choice events to state/events', async () => {
      // Clean up events from prior tests
      const eventsFile = path.join(STATE_DIR, 'events');
      if (fs.existsSync(eventsFile)) fs.unlinkSync(eventsFile);
      const ws = new WebSocket(`ws://localhost:${TEST_PORT}`);
      await new Promise(resolve => ws.on('open', resolve));
      ws.send(JSON.stringify({ type: 'click', choice: 'b', text: 'Option B' }));
      await sleep(300);
      assert(fs.existsSync(eventsFile), '.events should exist');
      const lines = fs.readFileSync(eventsFile, 'utf-8').trim().split('\n');
      const event = JSON.parse(lines[lines.length - 1]);
      assert.strictEqual(event.choice, 'b');
      assert.strictEqual(event.text, 'Option B');
      ws.close();
    });
    await test('does NOT write non-choice events to state/events', async () => {
      const eventsFile = path.join(STATE_DIR, 'events');
      if (fs.existsSync(eventsFile)) fs.unlinkSync(eventsFile);
      const ws = new WebSocket(`ws://localhost:${TEST_PORT}`);
      await new Promise(resolve => ws.on('open', resolve));
      ws.send(JSON.stringify({ type: 'hover', text: 'Something' }));
      await sleep(300);
      // Non-choice events should not create .events file
      assert(!fs.existsSync(eventsFile), '.events should not exist for non-choice events');
      ws.close();
    });
    await test('handles multiple concurrent WebSocket clients', async () => {
      const ws1 = new WebSocket(`ws://localhost:${TEST_PORT}`);
      const ws2 = new WebSocket(`ws://localhost:${TEST_PORT}`);
      await Promise.all([
        new Promise(resolve => ws1.on('open', resolve)),
        new Promise(resolve => ws2.on('open', resolve))
      ]);
      let ws1Reload = false;
      let ws2Reload = false;
      ws1.on('message', (data) => {
        if (JSON.parse(data.toString()).type === 'reload') ws1Reload = true;
      });
      ws2.on('message', (data) => {
        if (JSON.parse(data.toString()).type === 'reload') ws2Reload = true;
      });
      fs.writeFileSync(path.join(CONTENT_DIR, 'multi-client.html'), '<h2>Multi</h2>');
      await sleep(500);
      assert(ws1Reload, 'Client 1 should receive reload');
      assert(ws2Reload, 'Client 2 should receive reload');
      ws1.close();
      ws2.close();
    });
    await test('cleans up closed clients from broadcast list', async () => {
      const ws1 = new WebSocket(`ws://localhost:${TEST_PORT}`);
      await new Promise(resolve => ws1.on('open', resolve));
      ws1.close();
      await sleep(100);
      // This should not throw even though ws1 is closed
      fs.writeFileSync(path.join(CONTENT_DIR, 'after-close.html'), '<h2>After</h2>');
      await sleep(300);
      // If we got here without error, the test passes
    });
    await test('handles malformed JSON from client gracefully', async () => {
      const ws = new WebSocket(`ws://localhost:${TEST_PORT}`);
      await new Promise(resolve => ws.on('open', resolve));
      // Send invalid JSON — server should not crash
      ws.send('not json at all {{{');
      await sleep(300);
      // Verify server is still responsive
      const res = await fetch(`http://localhost:${TEST_PORT}/`);
      assert.strictEqual(res.status, 200, 'Server should still be running');
      ws.close();
    });
    // ========== File Watching ==========
    console.log('\n--- File Watching ---');
    await test('sends reload on new .html file', async () => {
      const ws = new WebSocket(`ws://localhost:${TEST_PORT}`);
      await new Promise(resolve => ws.on('open', resolve));
      let gotReload = false;
      ws.on('message', (data) => {
        if (JSON.parse(data.toString()).type === 'reload') gotReload = true;
      });
      fs.writeFileSync(path.join(CONTENT_DIR, 'watch-new.html'), '<h2>New</h2>');
      await sleep(500);
      assert(gotReload, 'Should send reload on new file');
      ws.close();
    });
    await test('sends reload on .html file change', async () => {
      const filePath = path.join(CONTENT_DIR, 'watch-change.html');
      fs.writeFileSync(filePath, '<h2>Original</h2>');
      await sleep(500);
      const ws = new WebSocket(`ws://localhost:${TEST_PORT}`);
      await new Promise(resolve => ws.on('open', resolve));
      let gotReload = false;
      ws.on('message', (data) => {
        if (JSON.parse(data.toString()).type === 'reload') gotReload = true;
      });
      fs.writeFileSync(filePath, '<h2>Modified</h2>');
      await sleep(500);
      assert(gotReload, 'Should send reload on file change');
      ws.close();
    });
    await test('does NOT send reload for non-.html files', async () => {
      const ws = new WebSocket(`ws://localhost:${TEST_PORT}`);
      await new Promise(resolve => ws.on('open', resolve));
      let gotReload = false;
      ws.on('message', (data) => {
        if (JSON.parse(data.toString()).type === 'reload') gotReload = true;
      });
      fs.writeFileSync(path.join(CONTENT_DIR, 'data.txt'), 'not html');
      await sleep(500);
      assert(!gotReload, 'Should NOT reload for non-HTML files');
      ws.close();
    });
    await test('clears state/events on new screen', async () => {
      // Create an events file
      const eventsFile = path.join(STATE_DIR, 'events');
      fs.writeFileSync(eventsFile, '{"choice":"a"}\n');
      assert(fs.existsSync(eventsFile));
      fs.writeFileSync(path.join(CONTENT_DIR, 'clear-events.html'), '<h2>New screen</h2>');
      await sleep(500);
      assert(!fs.existsSync(eventsFile), 'state/events should be cleared on new screen');
    });
    await test('logs screen-added on new file', async () => {
      stdoutAccum = '';
      fs.writeFileSync(path.join(CONTENT_DIR, 'log-test.html'), '<h2>Log</h2>');
      await sleep(500);
      assert(stdoutAccum.includes('screen-added'), 'Should log screen-added');
    });
    await test('logs screen-updated on file change', async () => {
      const filePath = path.join(CONTENT_DIR, 'log-update.html');
      fs.writeFileSync(filePath, '<h2>V1</h2>');
      await sleep(500);
      stdoutAccum = '';
      fs.writeFileSync(filePath, '<h2>V2</h2>');
      await sleep(500);
      assert(stdoutAccum.includes('screen-updated'), 'Should log screen-updated');
    });
    // ========== Helper.js Content ==========
    console.log('\n--- Helper.js Verification ---');
    await test('helper.js defines required APIs', () => {
      const helperContent = fs.readFileSync(
        path.join(__dirname, '../../skills/brainstorming/scripts/helper.js'), 'utf-8'
      );
      assert(helperContent.includes('toggleSelect'), 'Should define toggleSelect');
      assert(helperContent.includes('sendEvent'), 'Should define sendEvent');
      assert(helperContent.includes('selectedChoice'), 'Should track selectedChoice');
      assert(helperContent.includes('brainstorm'), 'Should expose brainstorm API');
      return Promise.resolve();
    });
    // ========== Frame Template ==========
    console.log('\n--- Frame Template Verification ---');
    await test('frame template has required structure', () => {
      const template = fs.readFileSync(
        path.join(__dirname, '../../skills/brainstorming/scripts/frame-template.html'), 'utf-8'
      );
      assert(template.includes('indicator-bar'), 'Should have indicator bar');
      assert(template.includes('indicator-text'), 'Should have indicator text');
      assert(template.includes('<!-- CONTENT -->'), 'Should have content placeholder');
      assert(template.includes('claude-content'), 'Should have content container');
      return Promise.resolve();
    });
    // ========== Summary ==========
    console.log(`\n--- Results: ${passed} passed, ${failed} failed ---`);
    if (failed > 0) process.exit(1);
  } finally {
    server.kill();
    await sleep(100);
    cleanup();
  }
 }
 runTests().catch(err => {
  console.error('Test failed:', err);
  process.exit(1);
 });
--- a/tests/brainstorm-server/windows-lifecycle.test.sh
+++ b/tests/brainstorm-server/windows-lifecycle.test.sh
@@ -1,351 +0,0 @@
 #!/usr/bin/env bash
 # Windows lifecycle tests for the brainstorm server.
 #
 # Verifies that the brainstorm server survives the 60-second lifecycle
 # check on Windows, where OWNER_PID monitoring is disabled because the
 # MSYS2 PID namespace is invisible to Node.js.
 #
 # Requirements:
 #   - Node.js in PATH
 #   - Run from the repository root, or set SUPERPOWERS_ROOT
 #   - On Windows: Git Bash (OSTYPE=msys*)
 #
 # Usage:
 #   bash tests/brainstorm-server/windows-lifecycle.test.sh
 set -uo pipefail
 # ========== Configuration ==========
 SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
 REPO_ROOT="${SUPERPOWERS_ROOT:-$(cd "$SCRIPT_DIR/../.." && pwd)}"
 START_SCRIPT="$REPO_ROOT/skills/brainstorming/scripts/start-server.sh"
 STOP_SCRIPT="$REPO_ROOT/skills/brainstorming/scripts/stop-server.sh"
 SERVER_JS="$REPO_ROOT/skills/brainstorming/scripts/server.js"
 TEST_DIR="${TMPDIR:-/tmp}/brainstorm-win-test-$$"
 passed=0
 failed=0
 skipped=0
 # ========== Helpers ==========
 cleanup() {
  # Kill any server processes we started
  for pidvar in SERVER_PID CONTROL_PID STOP_TEST_PID; do
    pid="${!pidvar:-}"
    if [[ -n "$pid" ]]; then
      kill "$pid" 2>/dev/null || true
      wait "$pid" 2>/dev/null || true
    fi
  done
  if [[ -n "${TEST_DIR:-}" && -d "$TEST_DIR" ]]; then
    rm -rf "$TEST_DIR"
  fi
 }
 trap cleanup EXIT
 pass() {
  echo "  PASS: $1"
  passed=$((passed + 1))
 }
 fail() {
  echo "  FAIL: $1"
  echo "    $2"
  failed=$((failed + 1))
 }
 skip() {
  echo "  SKIP: $1 ($2)"
  skipped=$((skipped + 1))
 }
 wait_for_server_info() {
  local dir="$1"
  for _ in $(seq 1 50); do
    if [[ -f "$dir/.server-info" ]]; then
      return 0
    fi
    sleep 0.1
  done
  return 1
 }
 get_port_from_info() {
  # Read the port from .server-info. Use grep/sed instead of Node.js
  # to avoid MSYS2-to-Windows path translation issues.
  grep -o '"port":[0-9]*' "$1/.server-info" | head -1 | sed 's/"port"://'
 }
 http_check() {
  local port="$1"
  node -e "
    const http = require('http');
    http.get('http://localhost:$port/', (res) => {
      process.exit(res.statusCode === 200 ? 0 : 1);
    }).on('error', () => process.exit(1));
  " 2>/dev/null
 }
 # ========== Platform Detection ==========
 echo ""
 echo "=== Brainstorm Server Windows Lifecycle Tests ==="
 echo "Platform: ${OSTYPE:-unknown}"
 echo "MSYSTEM: ${MSYSTEM:-unset}"
 echo "Node: $(node --version 2>/dev/null || echo 'not found')"
 echo ""
 is_windows="false"
 case "${OSTYPE:-}" in
  msys*|cygwin*|mingw*) is_windows="true" ;;
 esac
 if [[ -n "${MSYSTEM:-}" ]]; then
  is_windows="true"
 fi
 if [[ "$is_windows" != "true" ]]; then
  echo "NOTE: Not running on Windows/MSYS2 (OSTYPE=${OSTYPE:-unset})."
  echo "Windows-specific tests will be skipped. Tests 4-6 still run."
  echo ""
 fi
 mkdir -p "$TEST_DIR"
 SERVER_PID=""
 CONTROL_PID=""
 STOP_TEST_PID=""
 # ========== Test 1: OWNER_PID is empty on Windows ==========
 echo "--- Owner PID Resolution ---"
 if [[ "$is_windows" == "true" ]]; then
  # Replicate the PID resolution logic from start-server.sh lines 104-112
  TEST_OWNER_PID="$(ps -o ppid= -p "$PPID" 2>/dev/null | tr -d ' ' || true)"
  if [[ -z "$TEST_OWNER_PID" || "$TEST_OWNER_PID" == "1" ]]; then
    TEST_OWNER_PID="$PPID"
  fi
  # The fix: clear on Windows
  case "${OSTYPE:-}" in
    msys*|cygwin*|mingw*) TEST_OWNER_PID="" ;;
  esac
  if [[ -z "$TEST_OWNER_PID" ]]; then
    pass "OWNER_PID is empty on Windows after fix"
  else
    fail "OWNER_PID is empty on Windows after fix" \
         "Expected empty, got '$TEST_OWNER_PID'"
  fi
 else
  skip "OWNER_PID is empty on Windows" "not on Windows"
 fi
 # ========== Test 2: start-server.sh passes empty BRAINSTORM_OWNER_PID ==========
 if [[ "$is_windows" == "true" ]]; then
  # Use a fake 'node' that captures the env var and exits
  FAKE_NODE_DIR="$TEST_DIR/fake-bin"
  mkdir -p "$FAKE_NODE_DIR"
  cat > "$FAKE_NODE_DIR/node" <<'FAKENODE'
 #!/usr/bin/env bash
 echo "CAPTURED_OWNER_PID=${BRAINSTORM_OWNER_PID:-__UNSET__}"
 exit 0
 FAKENODE
  chmod +x "$FAKE_NODE_DIR/node"
  captured=$(PATH="$FAKE_NODE_DIR:$PATH" bash "$START_SCRIPT" --project-dir "$TEST_DIR/session" --foreground 2>/dev/null || true)
  owner_pid_value=$(echo "$captured" | grep "CAPTURED_OWNER_PID=" | head -1 | sed 's/CAPTURED_OWNER_PID=//')
  if [[ "$owner_pid_value" == "" || "$owner_pid_value" == "__UNSET__" ]]; then
    pass "start-server.sh passes empty BRAINSTORM_OWNER_PID on Windows"
  else
    fail "start-server.sh passes empty BRAINSTORM_OWNER_PID on Windows" \
         "Expected empty or unset, got '$owner_pid_value'"
  fi
  rm -rf "$FAKE_NODE_DIR" "$TEST_DIR/session"
 else
  skip "start-server.sh passes empty BRAINSTORM_OWNER_PID" "not on Windows"
 fi
 # ========== Test 3: Auto-foreground detection on Windows ==========
 echo ""
 echo "--- Foreground Mode Detection ---"
 if [[ "$is_windows" == "true" ]]; then
  FAKE_NODE_DIR="$TEST_DIR/fake-bin"
  mkdir -p "$FAKE_NODE_DIR"
  cat > "$FAKE_NODE_DIR/node" <<'FAKENODE'
 #!/usr/bin/env bash
 echo "FOREGROUND_MODE=true"
 exit 0
 FAKENODE
  chmod +x "$FAKE_NODE_DIR/node"
  # Run WITHOUT --foreground flag — Windows should auto-detect
  captured=$(PATH="$FAKE_NODE_DIR:$PATH" bash "$START_SCRIPT" --project-dir "$TEST_DIR/session2" 2>/dev/null || true)
  if echo "$captured" | grep -q "FOREGROUND_MODE=true"; then
    pass "Windows auto-detects foreground mode"
  else
    fail "Windows auto-detects foreground mode" \
         "Expected foreground code path, output: $captured"
  fi
  rm -rf "$FAKE_NODE_DIR" "$TEST_DIR/session2"
 else
  skip "Windows auto-detects foreground mode" "not on Windows"
 fi
 # ========== Test 4: Server survives past 60-second lifecycle check ==========
 echo ""
 echo "--- Server Survival (lifecycle check) ---"
 mkdir -p "$TEST_DIR/survival"
 echo "  Starting server (will wait ~75s to verify survival past lifecycle check)..."
 BRAINSTORM_DIR="$TEST_DIR/survival" \
 BRAINSTORM_HOST="127.0.0.1" \
 BRAINSTORM_URL_HOST="localhost" \
 BRAINSTORM_OWNER_PID="" \
 BRAINSTORM_PORT=$((49152 + RANDOM % 16383)) \
  node "$SERVER_JS" > "$TEST_DIR/survival/.server.log" 2>&1 &
 SERVER_PID=$!
 if ! wait_for_server_info "$TEST_DIR/survival"; then
  fail "Server starts successfully" "Server did not write .server-info within 5 seconds"
  kill "$SERVER_PID" 2>/dev/null || true
  SERVER_PID=""
 else
  pass "Server starts successfully with empty OWNER_PID"
  SERVER_PORT=$(get_port_from_info "$TEST_DIR/survival")
  sleep 75
  if kill -0 "$SERVER_PID" 2>/dev/null; then
    pass "Server is still alive after 75 seconds"
  else
    fail "Server is still alive after 75 seconds" \
         "Server died. Log tail: $(tail -5 "$TEST_DIR/survival/.server.log" 2>/dev/null)"
  fi
  if http_check "$SERVER_PORT"; then
    pass "Server responds to HTTP after lifecycle check window"
  else
    fail "Server responds to HTTP after lifecycle check window" \
         "HTTP request to port $SERVER_PORT failed"
  fi
  if grep -q "owner process exited" "$TEST_DIR/survival/.server.log" 2>/dev/null; then
    fail "No 'owner process exited' in logs" \
         "Found spurious owner-exit shutdown in log"
  else
    pass "No 'owner process exited' in logs"
  fi
  kill "$SERVER_PID" 2>/dev/null || true
  wait "$SERVER_PID" 2>/dev/null || true
  SERVER_PID=""
 fi
 # ========== Test 5: Bad OWNER_PID causes shutdown (control) ==========
 echo ""
 echo "--- Control: Bad OWNER_PID causes shutdown ---"
 mkdir -p "$TEST_DIR/control"
 # Find a PID that does not exist
 BAD_PID=99999
 while kill -0 "$BAD_PID" 2>/dev/null; do
  BAD_PID=$((BAD_PID + 1))
 done
 BRAINSTORM_DIR="$TEST_DIR/control" \
 BRAINSTORM_HOST="127.0.0.1" \
 BRAINSTORM_URL_HOST="localhost" \
 BRAINSTORM_OWNER_PID="$BAD_PID" \
 BRAINSTORM_PORT=$((49152 + RANDOM % 16383)) \
  node "$SERVER_JS" > "$TEST_DIR/control/.server.log" 2>&1 &
 CONTROL_PID=$!
 if ! wait_for_server_info "$TEST_DIR/control"; then
  fail "Control server starts" "Server did not write .server-info within 5 seconds"
  kill "$CONTROL_PID" 2>/dev/null || true
  CONTROL_PID=""
 else
  pass "Control server starts with bad OWNER_PID=$BAD_PID"
  echo "  Waiting ~75s for lifecycle check to kill server..."
  sleep 75
  if kill -0 "$CONTROL_PID" 2>/dev/null; then
    fail "Control server self-terminates with bad OWNER_PID" \
         "Server is still alive (expected it to die)"
    kill "$CONTROL_PID" 2>/dev/null || true
  else
    pass "Control server self-terminates with bad OWNER_PID"
  fi
  if grep -q "owner process exited" "$TEST_DIR/control/.server.log" 2>/dev/null; then
    pass "Control server logs 'owner process exited'"
  else
    fail "Control server logs 'owner process exited'" \
         "Log tail: $(tail -5 "$TEST_DIR/control/.server.log" 2>/dev/null)"
  fi
 fi
 wait "$CONTROL_PID" 2>/dev/null || true
 CONTROL_PID=""
 # ========== Test 6: stop-server.sh cleanly stops the server ==========
 echo ""
 echo "--- Clean Shutdown ---"
 mkdir -p "$TEST_DIR/stop-test"
 BRAINSTORM_DIR="$TEST_DIR/stop-test" \
 BRAINSTORM_HOST="127.0.0.1" \
 BRAINSTORM_URL_HOST="localhost" \
 BRAINSTORM_OWNER_PID="" \
 BRAINSTORM_PORT=$((49152 + RANDOM % 16383)) \
  node "$SERVER_JS" > "$TEST_DIR/stop-test/.server.log" 2>&1 &
 STOP_TEST_PID=$!
 echo "$STOP_TEST_PID" > "$TEST_DIR/stop-test/.server.pid"
 if ! wait_for_server_info "$TEST_DIR/stop-test"; then
  fail "Stop-test server starts" "Server did not start"
  kill "$STOP_TEST_PID" 2>/dev/null || true
  STOP_TEST_PID=""
 else
  bash "$STOP_SCRIPT" "$TEST_DIR/stop-test" >/dev/null 2>&1 || true
  sleep 1
  if ! kill -0 "$STOP_TEST_PID" 2>/dev/null; then
    pass "stop-server.sh cleanly stops the server"
  else
    fail "stop-server.sh cleanly stops the server" \
         "Server PID $STOP_TEST_PID is still alive after stop"
    kill "$STOP_TEST_PID" 2>/dev/null || true
  fi
 fi
 wait "$STOP_TEST_PID" 2>/dev/null || true
 STOP_TEST_PID=""
 # ========== Summary ==========
 echo ""
 echo "=== Results: $passed passed, $failed failed, $skipped skipped ==="
 if [[ $failed -gt 0 ]]; then
  exit 1
 fi
 exit 0
--- a/tests/brainstorm-server/ws-protocol.test.js
+++ b/tests/brainstorm-server/ws-protocol.test.js
@@ -1,392 +0,0 @@
 /**
 * Unit tests for the zero-dependency WebSocket protocol implementation.
 *
 * Tests the WebSocket frame encoding/decoding, handshake computation,
 * and protocol-level behavior independent of the HTTP server.
 *
 * The module under test exports:
 *   - computeAcceptKey(clientKey) -> string
 *   - encodeFrame(opcode, payload) -> Buffer
 *   - decodeFrame(buffer) -> { opcode, payload, bytesConsumed } | null
 *   - OPCODES: { TEXT, CLOSE, PING, PONG }
 */
 const assert = require('assert');
 const crypto = require('crypto');
 const path = require('path');
 // The module under test — will be the new zero-dep server file
 const SERVER_PATH = path.join(__dirname, '../../skills/brainstorming/scripts/server.cjs');
 let ws;
 try {
  ws = require(SERVER_PATH);
 } catch (e) {
  // Module doesn't exist yet (TDD — tests written before implementation)
  console.error(`Cannot load ${SERVER_PATH}: ${e.message}`);
  console.error('This is expected if running tests before implementation.');
  process.exit(1);
 }
 function runTests() {
  let passed = 0;
  let failed = 0;
  function test(name, fn) {
    try {
      fn();
      console.log(`  PASS: ${name}`);
      passed++;
    } catch (e) {
      console.log(`  FAIL: ${name}`);
      console.log(`    ${e.message}`);
      failed++;
    }
  }
  // ========== Handshake ==========
  console.log('\n--- WebSocket Handshake ---');
  test('computeAcceptKey produces correct RFC 6455 accept value', () => {
    // RFC 6455 Section 4.2.2 example
    // The magic GUID is "258EAFA5-E914-47DA-95CA-C5AB0DC85B11"
    const clientKey = 'dGhlIHNhbXBsZSBub25jZQ==';
    const expected = 's3pPLMBiTxaQ9kYGzzhZRbK+xOo=';
    assert.strictEqual(ws.computeAcceptKey(clientKey), expected);
  });
  test('computeAcceptKey produces valid base64 for random keys', () => {
    for (let i = 0; i < 10; i++) {
      const randomKey = crypto.randomBytes(16).toString('base64');
      const result = ws.computeAcceptKey(randomKey);
      // Result should be valid base64
      assert.strictEqual(Buffer.from(result, 'base64').toString('base64'), result);
      // SHA-1 output is 20 bytes, base64 encoded = 28 chars
      assert.strictEqual(result.length, 28);
    }
  });
  // ========== Frame Encoding ==========
  console.log('\n--- Frame Encoding (server -> client) ---');
  test('encodes small text frame (< 126 bytes)', () => {
    const payload = 'Hello';
    const frame = ws.encodeFrame(ws.OPCODES.TEXT, Buffer.from(payload));
    // FIN bit + TEXT opcode = 0x81, length = 5
    assert.strictEqual(frame[0], 0x81);
    assert.strictEqual(frame[1], 5);
    assert.strictEqual(frame.slice(2).toString(), 'Hello');
    assert.strictEqual(frame.length, 7);
  });
  test('encodes empty text frame', () => {
    const frame = ws.encodeFrame(ws.OPCODES.TEXT, Buffer.alloc(0));
    assert.strictEqual(frame[0], 0x81);
    assert.strictEqual(frame[1], 0);
    assert.strictEqual(frame.length, 2);
  });
  test('encodes medium text frame (126-65535 bytes)', () => {
    const payload = Buffer.alloc(200, 0x41); // 200 'A's
    const frame = ws.encodeFrame(ws.OPCODES.TEXT, payload);
    assert.strictEqual(frame[0], 0x81);
    assert.strictEqual(frame[1], 126); // extended length marker
    assert.strictEqual(frame.readUInt16BE(2), 200);
    assert.strictEqual(frame.slice(4).toString(), payload.toString());
    assert.strictEqual(frame.length, 204);
  });
  test('encodes frame at exactly 126 bytes (boundary)', () => {
    const payload = Buffer.alloc(126, 0x42);
    const frame = ws.encodeFrame(ws.OPCODES.TEXT, payload);
    assert.strictEqual(frame[1], 126); // extended length marker
    assert.strictEqual(frame.readUInt16BE(2), 126);
    assert.strictEqual(frame.length, 130);
  });
  test('encodes frame at exactly 125 bytes (max small)', () => {
    const payload = Buffer.alloc(125, 0x43);
    const frame = ws.encodeFrame(ws.OPCODES.TEXT, payload);
    assert.strictEqual(frame[1], 125);
    assert.strictEqual(frame.length, 127);
  });
  test('encodes large frame (> 65535 bytes)', () => {
    const payload = Buffer.alloc(70000, 0x44);
    const frame = ws.encodeFrame(ws.OPCODES.TEXT, payload);
    assert.strictEqual(frame[0], 0x81);
    assert.strictEqual(frame[1], 127); // 64-bit length marker
    // 8-byte extended length at offset 2
    const len = Number(frame.readBigUInt64BE(2));
    assert.strictEqual(len, 70000);
    assert.strictEqual(frame.length, 10 + 70000);
  });
  test('encodes close frame', () => {
    const frame = ws.encodeFrame(ws.OPCODES.CLOSE, Buffer.alloc(0));
    assert.strictEqual(frame[0], 0x88); // FIN + CLOSE
    assert.strictEqual(frame[1], 0);
  });
  test('encodes pong frame with payload', () => {
    const payload = Buffer.from('ping-data');
    const frame = ws.encodeFrame(ws.OPCODES.PONG, payload);
    assert.strictEqual(frame[0], 0x8A); // FIN + PONG
    assert.strictEqual(frame[1], payload.length);
    assert.strictEqual(frame.slice(2).toString(), 'ping-data');
  });
  test('server frames are never masked (per RFC 6455)', () => {
    const frame = ws.encodeFrame(ws.OPCODES.TEXT, Buffer.from('test'));
    // Bit 7 of byte 1 is the mask bit — must be 0 for server frames
    assert.strictEqual(frame[1] & 0x80, 0);
  });
  // ========== Frame Decoding ==========
  console.log('\n--- Frame Decoding (client -> server) ---');
  // Helper: create a masked client frame
  function makeClientFrame(opcode, payload, fin = true) {
    const buf = Buffer.from(payload);
    const mask = crypto.randomBytes(4);
    const masked = Buffer.alloc(buf.length);
    for (let i = 0; i < buf.length; i++) {
      masked[i] = buf[i] ^ mask[i % 4];
    }
    let header;
    const finBit = fin ? 0x80 : 0x00;
    if (buf.length < 126) {
      header = Buffer.alloc(6);
      header[0] = finBit | opcode;
      header[1] = 0x80 | buf.length; // mask bit set
      mask.copy(header, 2);
    } else if (buf.length < 65536) {
      header = Buffer.alloc(8);
      header[0] = finBit | opcode;
      header[1] = 0x80 | 126;
      header.writeUInt16BE(buf.length, 2);
      mask.copy(header, 4);
    } else {
      header = Buffer.alloc(14);
      header[0] = finBit | opcode;
      header[1] = 0x80 | 127;
      header.writeBigUInt64BE(BigInt(buf.length), 2);
      mask.copy(header, 10);
    }
    return Buffer.concat([header, masked]);
  }
  test('decodes small masked text frame', () => {
    const frame = makeClientFrame(0x01, 'Hello');
    const result = ws.decodeFrame(frame);
    assert(result, 'Should return a result');
    assert.strictEqual(result.opcode, ws.OPCODES.TEXT);
    assert.strictEqual(result.payload.toString(), 'Hello');
    assert.strictEqual(result.bytesConsumed, frame.length);
  });
  test('decodes empty masked text frame', () => {
    const frame = makeClientFrame(0x01, '');
    const result = ws.decodeFrame(frame);
    assert(result, 'Should return a result');
    assert.strictEqual(result.opcode, ws.OPCODES.TEXT);
    assert.strictEqual(result.payload.length, 0);
  });
  test('decodes medium masked text frame (126-65535 bytes)', () => {
    const payload = 'A'.repeat(200);
    const frame = makeClientFrame(0x01, payload);
    const result = ws.decodeFrame(frame);
    assert(result, 'Should return a result');
    assert.strictEqual(result.payload.toString(), payload);
  });
  test('decodes large masked text frame (> 65535 bytes)', () => {
    const payload = 'B'.repeat(70000);
    const frame = makeClientFrame(0x01, payload);
    const result = ws.decodeFrame(frame);
    assert(result, 'Should return a result');
    assert.strictEqual(result.payload.length, 70000);
    assert.strictEqual(result.payload.toString(), payload);
  });
  test('decodes masked close frame', () => {
    const frame = makeClientFrame(0x08, '');
    const result = ws.decodeFrame(frame);
    assert(result, 'Should return a result');
    assert.strictEqual(result.opcode, ws.OPCODES.CLOSE);
  });
  test('decodes masked ping frame', () => {
    const frame = makeClientFrame(0x09, 'ping!');
    const result = ws.decodeFrame(frame);
    assert(result, 'Should return a result');
    assert.strictEqual(result.opcode, ws.OPCODES.PING);
    assert.strictEqual(result.payload.toString(), 'ping!');
  });
  test('returns null for incomplete frame (not enough header bytes)', () => {
    const result = ws.decodeFrame(Buffer.from([0x81]));
    assert.strictEqual(result, null, 'Should return null for 1-byte buffer');
  });
  test('returns null for incomplete frame (header ok, payload truncated)', () => {
    // Create a valid frame then truncate it
    const frame = makeClientFrame(0x01, 'Hello World');
    const truncated = frame.slice(0, frame.length - 3);
    const result = ws.decodeFrame(truncated);
    assert.strictEqual(result, null, 'Should return null for truncated frame');
  });
  test('returns null for incomplete extended-length header', () => {
    // Frame claiming 16-bit length but only 3 bytes total
    const buf = Buffer.alloc(3);
    buf[0] = 0x81;
    buf[1] = 0x80 | 126; // masked, 16-bit extended
    // Missing the 2 length bytes + mask
    const result = ws.decodeFrame(buf);
    assert.strictEqual(result, null);
  });
  test('rejects unmasked client frame', () => {
    // Server MUST reject unmasked client frames per RFC 6455 Section 5.1
    const buf = Buffer.alloc(7);
    buf[0] = 0x81; // FIN + TEXT
    buf[1] = 5;    // length 5, NO mask bit
    Buffer.from('Hello').copy(buf, 2);
    assert.throws(() => ws.decodeFrame(buf), /mask/i, 'Should reject unmasked client frame');
  });
  test('handles multiple frames in a single buffer', () => {
    const frame1 = makeClientFrame(0x01, 'first');
    const frame2 = makeClientFrame(0x01, 'second');
    const combined = Buffer.concat([frame1, frame2]);
    const result1 = ws.decodeFrame(combined);
    assert(result1, 'Should decode first frame');
    assert.strictEqual(result1.payload.toString(), 'first');
    assert.strictEqual(result1.bytesConsumed, frame1.length);
    const result2 = ws.decodeFrame(combined.slice(result1.bytesConsumed));
    assert(result2, 'Should decode second frame');
    assert.strictEqual(result2.payload.toString(), 'second');
  });
  test('correctly unmasks with all mask byte values', () => {
    // Use a known mask to verify unmasking arithmetic
    const payload = Buffer.from('ABCDEFGH');
    const mask = Buffer.from([0xFF, 0x00, 0xAA, 0x55]);
    const masked = Buffer.alloc(payload.length);
    for (let i = 0; i < payload.length; i++) {
      masked[i] = payload[i] ^ mask[i % 4];
    }
    // Build frame manually
    const header = Buffer.alloc(6);
    header[0] = 0x81; // FIN + TEXT
    header[1] = 0x80 | payload.length;
    mask.copy(header, 2);
    const frame = Buffer.concat([header, masked]);
    const result = ws.decodeFrame(frame);
    assert.strictEqual(result.payload.toString(), 'ABCDEFGH');
  });
  // ========== Frame Encoding Boundary at 65535/65536 ==========
  console.log('\n--- Frame Size Boundaries ---');
  test('encodes frame at exactly 65535 bytes (max 16-bit)', () => {
    const payload = Buffer.alloc(65535, 0x45);
    const frame = ws.encodeFrame(ws.OPCODES.TEXT, payload);
    assert.strictEqual(frame[1], 126);
    assert.strictEqual(frame.readUInt16BE(2), 65535);
    assert.strictEqual(frame.length, 4 + 65535);
  });
  test('encodes frame at exactly 65536 bytes (min 64-bit)', () => {
    const payload = Buffer.alloc(65536, 0x46);
    const frame = ws.encodeFrame(ws.OPCODES.TEXT, payload);
    assert.strictEqual(frame[1], 127);
    assert.strictEqual(Number(frame.readBigUInt64BE(2)), 65536);
    assert.strictEqual(frame.length, 10 + 65536);
  });
  test('decodes frame at 65535 bytes boundary', () => {
    const payload = 'X'.repeat(65535);
    const frame = makeClientFrame(0x01, payload);
    const result = ws.decodeFrame(frame);
    assert(result);
    assert.strictEqual(result.payload.length, 65535);
  });
  test('decodes frame at 65536 bytes boundary', () => {
    const payload = 'Y'.repeat(65536);
    const frame = makeClientFrame(0x01, payload);
    const result = ws.decodeFrame(frame);
    assert(result);
    assert.strictEqual(result.payload.length, 65536);
  });
  // ========== Close Frame with Status Code ==========
  console.log('\n--- Close Frame Details ---');
  test('decodes close frame with status code', () => {
    // Close frame payload: 2-byte status code + optional reason
    const statusBuf = Buffer.alloc(2);
    statusBuf.writeUInt16BE(1000); // Normal closure
    const frame = makeClientFrame(0x08, statusBuf);
    const result = ws.decodeFrame(frame);
    assert.strictEqual(result.opcode, ws.OPCODES.CLOSE);
    assert.strictEqual(result.payload.readUInt16BE(0), 1000);
  });
  test('decodes close frame with status code and reason', () => {
    const reason = 'Normal shutdown';
    const payload = Buffer.alloc(2 + reason.length);
    payload.writeUInt16BE(1000);
    payload.write(reason, 2);
    const frame = makeClientFrame(0x08, payload);
    const result = ws.decodeFrame(frame);
    assert.strictEqual(result.opcode, ws.OPCODES.CLOSE);
    assert.strictEqual(result.payload.slice(2).toString(), reason);
  });
  // ========== JSON Roundtrip ==========
  console.log('\n--- JSON Message Roundtrip ---');
  test('roundtrip encode/decode of JSON message', () => {
    const msg = { type: 'reload' };
    const payload = Buffer.from(JSON.stringify(msg));
    const serverFrame = ws.encodeFrame(ws.OPCODES.TEXT, payload);
    // Verify we can read what we encoded (unmasked server frame)
    // Server frames don't go through decodeFrame (that expects masked),
    // so just verify the payload bytes directly
    let offset;
    if (serverFrame[1] < 126) {
      offset = 2;
    } else if (serverFrame[1] === 126) {
      offset = 4;
    } else {
      offset = 10;
    }
    const decoded = JSON.parse(serverFrame.slice(offset).toString());
    assert.deepStrictEqual(decoded, msg);
  });
  test('roundtrip masked client JSON message', () => {
    const msg = { type: 'click', choice: 'a', text: 'Option A', timestamp: 1706000101 };
    const frame = makeClientFrame(0x01, JSON.stringify(msg));
    const result = ws.decodeFrame(frame);
    const decoded = JSON.parse(result.payload.toString());
    assert.deepStrictEqual(decoded, msg);
  });
  // ========== Summary ==========
  console.log(`\n--- Results: ${passed} passed, ${failed} failed ---`);
  if (failed > 0) process.exit(1);
 }
 runTests();
--- a/tests/claude-code/README.md
+++ b/tests/claude-code/README.md
@@ -1,158 +0,0 @@
 # Claude Code Skills Tests
 Automated tests for superpowers skills using Claude Code CLI.
 ## Overview
 This test suite verifies that skills are loaded correctly and Claude follows them as expected. Tests invoke Claude Code in headless mode (`claude -p`) and verify the behavior.
 ## Requirements
 - Claude Code CLI installed and in PATH (`claude --version` should work)
 - Local superpowers plugin installed (see main README for installation)
 ## Running Tests
 ### Run all fast tests (recommended):
 ```bash
 ./run-skill-tests.sh
 ```
 ### Run integration tests (slow, 10-30 minutes):
 ```bash
 ./run-skill-tests.sh --integration
 ```
 ### Run specific test:
 ```bash
 ./run-skill-tests.sh --test test-subagent-driven-development.sh
 ```
 ### Run with verbose output:
 ```bash
 ./run-skill-tests.sh --verbose
 ```
 ### Set custom timeout:
 ```bash
 ./run-skill-tests.sh --timeout 1800  # 30 minutes for integration tests
 ```
 ## Test Structure
 ### test-helpers.sh
 Common functions for skills testing:
 - `run_claude "prompt" [timeout]` - Run Claude with prompt
 - `assert_contains output pattern name` - Verify pattern exists
 - `assert_not_contains output pattern name` - Verify pattern absent
 - `assert_count output pattern count name` - Verify exact count
 - `assert_order output pattern_a pattern_b name` - Verify order
 - `create_test_project` - Create temp test directory
 - `create_test_plan project_dir` - Create sample plan file
 ### Test Files
 Each test file:
 1. Sources `test-helpers.sh`
 2. Runs Claude Code with specific prompts
 3. Verifies expected behavior using assertions
 4. Returns 0 on success, non-zero on failure
 ## Example Test
 ```bash
 #!/usr/bin/env bash
 set -euo pipefail
 SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
 source "$SCRIPT_DIR/test-helpers.sh"
 echo "=== Test: My Skill ==="
 # Ask Claude about the skill
 output=$(run_claude "What does the my-skill skill do?" 30)
 # Verify response
 assert_contains "$output" "expected behavior" "Skill describes behavior"
 echo "=== All tests passed ==="
 ```
 ## Current Tests
 ### Fast Tests (run by default)
 #### test-subagent-driven-development.sh
 Tests skill content and requirements (~2 minutes):
 - Skill loading and accessibility
 - Workflow ordering (spec compliance before code quality)
 - Self-review requirements documented
 - Plan reading efficiency documented
 - Spec compliance reviewer skepticism documented
 - Review loops documented
 - Task context provision documented
 ### Integration Tests (use --integration flag)
 #### test-subagent-driven-development-integration.sh
 Full workflow execution test (~10-30 minutes):
 - Creates real test project with Node.js setup
 - Creates implementation plan with 2 tasks
 - Executes plan using subagent-driven-development
 - Verifies actual behaviors:
  - Plan read once at start (not per task)
  - Full task text provided in subagent prompts
  - Subagents perform self-review before reporting
  - Spec compliance review happens before code quality
  - Spec reviewer reads code independently
  - Working implementation is produced
  - Tests pass
  - Proper git commits created
 **What it tests:**
 - The workflow actually works end-to-end
 - Our improvements are actually applied
 - Subagents follow the skill correctly
 - Final code is functional and tested
 ## Adding New Tests
 1. Create new test file: `test-<skill-name>.sh`
 2. Source test-helpers.sh
 3. Write tests using `run_claude` and assertions
 4. Add to test list in `run-skill-tests.sh`
 5. Make executable: `chmod +x test-<skill-name>.sh`
 ## Timeout Considerations
 - Default timeout: 5 minutes per test
 - Claude Code may take time to respond
 - Adjust with `--timeout` if needed
 - Tests should be focused to avoid long runs
 ## Debugging Failed Tests
 With `--verbose`, you'll see full Claude output:
 ```bash
 ./run-skill-tests.sh --verbose --test test-subagent-driven-development.sh
 ```
 Without verbose, only failures show output.
 ## CI/CD Integration
 To run in CI:
 ```bash
 # Run with explicit timeout for CI environments
 ./run-skill-tests.sh --timeout 900
 # Exit code 0 = success, non-zero = failure
 ```
 ## Notes
 - Tests verify skill *instructions*, not full execution
 - Full workflow tests would be very slow
 - Focus on verifying key skill requirements
 - Tests should be deterministic
 - Avoid testing implementation details
--- a/tests/claude-code/analyze-token-usage.py
+++ b/tests/claude-code/analyze-token-usage.py
@@ -1,168 +0,0 @@
 #!/usr/bin/env python3
 """
 Analyze token usage from Claude Code session transcripts.
 Breaks down usage by main session and individual subagents.
 """
 import json
 import sys
 from pathlib import Path
 from collections import defaultdict
 def analyze_main_session(filepath):
    """Analyze a session file and return token usage broken down by agent."""
    main_usage = {
        'input_tokens': 0,
        'output_tokens': 0,
        'cache_creation': 0,
        'cache_read': 0,
        'messages': 0
    }
    # Track usage per subagent
    subagent_usage = defaultdict(lambda: {
        'input_tokens': 0,
        'output_tokens': 0,
        'cache_creation': 0,
        'cache_read': 0,
        'messages': 0,
        'description': None
    })
    with open(filepath, 'r') as f:
        for line in f:
            try:
                data = json.loads(line)
                # Main session assistant messages
                if data.get('type') == 'assistant' and 'message' in data:
                    main_usage['messages'] += 1
                    msg_usage = data['message'].get('usage', {})
                    main_usage['input_tokens'] += msg_usage.get('input_tokens', 0)
                    main_usage['output_tokens'] += msg_usage.get('output_tokens', 0)
                    main_usage['cache_creation'] += msg_usage.get('cache_creation_input_tokens', 0)
                    main_usage['cache_read'] += msg_usage.get('cache_read_input_tokens', 0)
                # Subagent tool results
                if data.get('type') == 'user' and 'toolUseResult' in data:
                    result = data['toolUseResult']
                    if 'usage' in result and 'agentId' in result:
                        agent_id = result['agentId']
                        usage = result['usage']
                        # Get description from prompt if available
                        if subagent_usage[agent_id]['description'] is None:
                            prompt = result.get('prompt', '')
                            # Extract first line as description
                            first_line = prompt.split('\n')[0] if prompt else f"agent-{agent_id}"
                            if first_line.startswith('You are '):
                                first_line = first_line[8:]  # Remove "You are "
                            subagent_usage[agent_id]['description'] = first_line[:60]
                        subagent_usage[agent_id]['messages'] += 1
                        subagent_usage[agent_id]['input_tokens'] += usage.get('input_tokens', 0)
                        subagent_usage[agent_id]['output_tokens'] += usage.get('output_tokens', 0)
                        subagent_usage[agent_id]['cache_creation'] += usage.get('cache_creation_input_tokens', 0)
                        subagent_usage[agent_id]['cache_read'] += usage.get('cache_read_input_tokens', 0)
            except Exception:
                pass
    return main_usage, dict(subagent_usage)
 def format_tokens(n):
    """Format token count with thousands separators."""
    return f"{n:,}"
 def calculate_cost(usage, input_cost_per_m=3.0, output_cost_per_m=15.0):
    """Calculate estimated cost in dollars."""
    total_input = usage['input_tokens'] + usage['cache_creation'] + usage['cache_read']
    input_cost = total_input * input_cost_per_m / 1_000_000
    output_cost = usage['output_tokens'] * output_cost_per_m / 1_000_000
    return input_cost + output_cost
 def main():
    if len(sys.argv) < 2:
        print("Usage: analyze-token-usage.py <session-file.jsonl>")
        sys.exit(1)
    main_session_file = sys.argv[1]
    if not Path(main_session_file).exists():
        print(f"Error: Session file not found: {main_session_file}")
        sys.exit(1)
    # Analyze the session
    main_usage, subagent_usage = analyze_main_session(main_session_file)
    print("=" * 100)
    print("TOKEN USAGE ANALYSIS")
    print("=" * 100)
    print()
    # Print breakdown
    print("Usage Breakdown:")
    print("-" * 100)
    print(f"{'Agent':<15} {'Description':<35} {'Msgs':>5} {'Input':>10} {'Output':>10} {'Cache':>10} {'Cost':>8}")
    print("-" * 100)
    # Main session
    cost = calculate_cost(main_usage)
    print(f"{'main':<15} {'Main session (coordinator)':<35} "
          f"{main_usage['messages']:>5} "
          f"{format_tokens(main_usage['input_tokens']):>10} "
          f"{format_tokens(main_usage['output_tokens']):>10} "
          f"{format_tokens(main_usage['cache_read']):>10} "
          f"${cost:>7.2f}")
    # Subagents (sorted by agent ID)
    for agent_id in sorted(subagent_usage.keys()):
        usage = subagent_usage[agent_id]
        cost = calculate_cost(usage)
        desc = usage['description'] or f"agent-{agent_id}"
        print(f"{agent_id:<15} {desc:<35} "
              f"{usage['messages']:>5} "
              f"{format_tokens(usage['input_tokens']):>10} "
              f"{format_tokens(usage['output_tokens']):>10} "
              f"{format_tokens(usage['cache_read']):>10} "
              f"${cost:>7.2f}")
    print("-" * 100)
    # Calculate totals
    total_usage = {
        'input_tokens': main_usage['input_tokens'],
        'output_tokens': main_usage['output_tokens'],
        'cache_creation': main_usage['cache_creation'],
        'cache_read': main_usage['cache_read'],
        'messages': main_usage['messages']
    }
    for usage in subagent_usage.values():
        total_usage['input_tokens'] += usage['input_tokens']
        total_usage['output_tokens'] += usage['output_tokens']
        total_usage['cache_creation'] += usage['cache_creation']
        total_usage['cache_read'] += usage['cache_read']
        total_usage['messages'] += usage['messages']
    total_input = total_usage['input_tokens'] + total_usage['cache_creation'] + total_usage['cache_read']
    total_tokens = total_input + total_usage['output_tokens']
    total_cost = calculate_cost(total_usage)
    print()
    print("TOTALS:")
    print(f"  Total messages:         {format_tokens(total_usage['messages'])}")
    print(f"  Input tokens:           {format_tokens(total_usage['input_tokens'])}")
    print(f"  Output tokens:          {format_tokens(total_usage['output_tokens'])}")
    print(f"  Cache creation tokens:  {format_tokens(total_usage['cache_creation'])}")
    print(f"  Cache read tokens:      {format_tokens(total_usage['cache_read'])}")
    print()
    print(f"  Total input (incl cache): {format_tokens(total_input)}")
    print(f"  Total tokens:             {format_tokens(total_tokens)}")
    print()
    print(f"  Estimated cost: ${total_cost:.2f}")
    print("  (at $3/$15 per M tokens for input/output)")
    print()
    print("=" * 100)
 if __name__ == '__main__':
    main()
--- a/tests/claude-code/run-skill-tests.sh
+++ b/tests/claude-code/run-skill-tests.sh
@@ -1,187 +0,0 @@
 #!/usr/bin/env bash
 # Test runner for Claude Code skills
 # Tests skills by invoking Claude Code CLI and verifying behavior
 set -euo pipefail
 SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
 cd "$SCRIPT_DIR"
 echo "========================================"
 echo " Claude Code Skills Test Suite"
 echo "========================================"
 echo ""
 echo "Repository: $(cd ../.. && pwd)"
 echo "Test time: $(date)"
 echo "Claude version: $(claude --version 2>/dev/null || echo 'not found')"
 echo ""
 # Check if Claude Code is available
 if ! command -v claude &> /dev/null; then
    echo "ERROR: Claude Code CLI not found"
    echo "Install Claude Code first: https://code.claude.com"
    exit 1
 fi
 # Parse command line arguments
 VERBOSE=false
 SPECIFIC_TEST=""
 TIMEOUT=300  # Default 5 minute timeout per test
 RUN_INTEGRATION=false
 while [[ $# -gt 0 ]]; do
    case $1 in
        --verbose|-v)
            VERBOSE=true
            shift
            ;;
        --test|-t)
            SPECIFIC_TEST="$2"
            shift 2
            ;;
        --timeout)
            TIMEOUT="$2"
            shift 2
            ;;
        --integration|-i)
            RUN_INTEGRATION=true
            shift
            ;;
        --help|-h)
            echo "Usage: $0 [options]"
            echo ""
            echo "Options:"
            echo "  --verbose, -v        Show verbose output"
            echo "  --test, -t NAME      Run only the specified test"
            echo "  --timeout SECONDS    Set timeout per test (default: 300)"
            echo "  --integration, -i    Run integration tests (slow, 10-30 min)"
            echo "  --help, -h           Show this help"
            echo ""
            echo "Tests:"
            echo "  test-subagent-driven-development.sh  Test skill loading and requirements"
            echo ""
            echo "Integration Tests (use --integration):"
            echo "  test-subagent-driven-development-integration.sh  Full workflow execution"
            exit 0
            ;;
        *)
            echo "Unknown option: $1"
            echo "Use --help for usage information"
            exit 1
            ;;
    esac
 done
 # List of skill tests to run (fast unit tests)
 tests=(
    "test-subagent-driven-development.sh"
 )
 # Integration tests (slow, full execution)
 integration_tests=(
    "test-subagent-driven-development-integration.sh"
 )
 # Add integration tests if requested
 if [ "$RUN_INTEGRATION" = true ]; then
    tests+=("${integration_tests[@]}")
 fi
 # Filter to specific test if requested
 if [ -n "$SPECIFIC_TEST" ]; then
    tests=("$SPECIFIC_TEST")
 fi
 # Track results
 passed=0
 failed=0
 skipped=0
 # Run each test
 for test in "${tests[@]}"; do
    echo "----------------------------------------"
    echo "Running: $test"
    echo "----------------------------------------"
    test_path="$SCRIPT_DIR/$test"
    if [ ! -f "$test_path" ]; then
        echo "  [SKIP] Test file not found: $test"
        skipped=$((skipped + 1))
        continue
    fi
    if [ ! -x "$test_path" ]; then
        echo "  Making $test executable..."
        chmod +x "$test_path"
    fi
    start_time=$(date +%s)
    if [ "$VERBOSE" = true ]; then
        if timeout "$TIMEOUT" bash "$test_path"; then
            end_time=$(date +%s)
            duration=$((end_time - start_time))
            echo ""
            echo "  [PASS] $test (${duration}s)"
            passed=$((passed + 1))
        else
            exit_code=$?
            end_time=$(date +%s)
            duration=$((end_time - start_time))
            echo ""
            if [ $exit_code -eq 124 ]; then
                echo "  [FAIL] $test (timeout after ${TIMEOUT}s)"
            else
                echo "  [FAIL] $test (${duration}s)"
            fi
            failed=$((failed + 1))
        fi
    else
        # Capture output for non-verbose mode
        if output=$(timeout "$TIMEOUT" bash "$test_path" 2>&1); then
            end_time=$(date +%s)
            duration=$((end_time - start_time))
            echo "  [PASS] (${duration}s)"
            passed=$((passed + 1))
        else
            exit_code=$?
            end_time=$(date +%s)
            duration=$((end_time - start_time))
            if [ $exit_code -eq 124 ]; then
                echo "  [FAIL] (timeout after ${TIMEOUT}s)"
            else
                echo "  [FAIL] (${duration}s)"
            fi
            echo ""
            echo "  Output:"
            echo "$output" | sed 's/^/    /'
            failed=$((failed + 1))
        fi
    fi
    echo ""
 done
 # Print summary
 echo "========================================"
 echo " Test Results Summary"
 echo "========================================"
 echo ""
 echo "  Passed:  $passed"
 echo "  Failed:  $failed"
 echo "  Skipped: $skipped"
 echo ""
 if [ "$RUN_INTEGRATION" = false ] && [ ${#integration_tests[@]} -gt 0 ]; then
    echo "Note: Integration tests were not run (they take 10-30 minutes)."
    echo "Use --integration flag to run full workflow execution tests."
    echo ""
 fi
 if [ $failed -gt 0 ]; then
    echo "STATUS: FAILED"
    exit 1
 else
    echo "STATUS: PASSED"
    exit 0
 fi
--- a/tests/claude-code/test-document-review-system.sh
+++ b/tests/claude-code/test-document-review-system.sh
@@ -1,177 +0,0 @@
 #!/usr/bin/env bash
 # Integration Test: Document Review System
 # Actually runs spec/plan review and verifies reviewers catch issues
 set -euo pipefail
 SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
 source "$SCRIPT_DIR/test-helpers.sh"
 echo "========================================"
 echo " Integration Test: Document Review System"
 echo "========================================"
 echo ""
 echo "This test verifies the document review system by:"
 echo "  1. Creating a spec with intentional errors"
 echo "  2. Running the spec document reviewer"
 echo "  3. Verifying the reviewer catches the errors"
 echo ""
 # Create test project
 TEST_PROJECT=$(create_test_project)
 echo "Test project: $TEST_PROJECT"
 # Trap to cleanup
 trap "cleanup_test_project $TEST_PROJECT" EXIT
 cd "$TEST_PROJECT"
 # Create directory structure
 mkdir -p docs/superpowers/specs
 # Create a spec document WITH INTENTIONAL ERRORS for the reviewer to catch
 cat > docs/superpowers/specs/test-feature-design.md <<'EOF'
 # Test Feature Design
 ## Overview
 This is a test feature that does something useful.
 ## Requirements
 1. The feature should work correctly
 2. It should be fast
 3. TODO: Add more requirements here
 ## Architecture
 The feature will use a simple architecture with:
 - A frontend component
 - A backend service
 - Error handling will be specified later once we understand the failure modes better
 ## Data Flow
 Data flows from the frontend to the backend.
 ## Testing Strategy
 Tests will be written to cover the main functionality.
 EOF
 # Initialize git repo
 git init --quiet
 git config user.email "test@test.com"
 git config user.name "Test User"
 git add .
 git commit -m "Initial commit with test spec" --quiet
 echo ""
 echo "Created test spec with intentional errors:"
 echo "  - TODO placeholder in Requirements section"
 echo "  - 'specified later' deferral in Architecture section"
 echo ""
 echo "Running spec document reviewer..."
 echo ""
 # Run Claude to review the spec
 OUTPUT_FILE="$TEST_PROJECT/claude-output.txt"
 PROMPT="You are testing the spec document reviewer.
 Read the spec-document-reviewer-prompt.md template in skills/brainstorming/ to understand the review format.
 Then review the spec at $TEST_PROJECT/docs/superpowers/specs/test-feature-design.md using the criteria from that template.
 Look for:
 - TODOs, placeholders, 'TBD', incomplete sections
 - Sections saying 'to be defined later' or 'will spec when X is done'
 - Sections noticeably less detailed than others
 Output your review in the format specified in the template."
 echo "================================================================================"
 cd "$SCRIPT_DIR/../.." && timeout 120 claude -p "$PROMPT" --permission-mode bypassPermissions 2>&1 | tee "$OUTPUT_FILE" || {
    echo ""
    echo "================================================================================"
    echo "EXECUTION FAILED (exit code: $?)"
    exit 1
 }
 echo "================================================================================"
 echo ""
 echo "Analyzing reviewer output..."
 echo ""
 # Verification tests
 FAILED=0
 echo "=== Verification Tests ==="
 echo ""
 # Test 1: Reviewer found the TODO
 echo "Test 1: Reviewer found TODO..."
 if grep -qi "TODO" "$OUTPUT_FILE" && grep -qi "requirements\|Requirements" "$OUTPUT_FILE"; then
    echo "  [PASS] Reviewer identified TODO in Requirements section"
 else
    echo "  [FAIL] Reviewer did not identify TODO"
    FAILED=$((FAILED + 1))
 fi
 echo ""
 # Test 2: Reviewer found the "specified later" deferral
 echo "Test 2: Reviewer found 'specified later' deferral..."
 if grep -qi "specified later\|later\|defer\|incomplete\|error handling" "$OUTPUT_FILE"; then
    echo "  [PASS] Reviewer identified deferred content"
 else
    echo "  [FAIL] Reviewer did not identify deferred content"
    FAILED=$((FAILED + 1))
 fi
 echo ""
 # Test 3: Reviewer output includes Issues section
 echo "Test 3: Review output format..."
 if grep -qi "issues\|Issues" "$OUTPUT_FILE"; then
    echo "  [PASS] Review includes Issues section"
 else
    echo "  [FAIL] Review missing Issues section"
    FAILED=$((FAILED + 1))
 fi
 echo ""
 # Test 4: Reviewer did NOT approve (found issues)
 echo "Test 4: Reviewer verdict..."
 if grep -qi "Issues Found\|❌\|not approved\|issues found" "$OUTPUT_FILE"; then
    echo "  [PASS] Reviewer correctly found issues (not approved)"
 elif grep -qi "Approved\|✅" "$OUTPUT_FILE" && ! grep -qi "Issues Found\|❌" "$OUTPUT_FILE"; then
    echo "  [FAIL] Reviewer incorrectly approved spec with errors"
    FAILED=$((FAILED + 1))
 else
    echo "  [PASS] Reviewer identified problems (ambiguous format but found issues)"
 fi
 echo ""
 # Summary
 echo "========================================"
 echo " Test Summary"
 echo "========================================"
 echo ""
 if [ $FAILED -eq 0 ]; then
    echo "STATUS: PASSED"
    echo "All verification tests passed!"
    echo ""
    echo "The spec document reviewer correctly:"
    echo "  ✓ Found TODO placeholder"
    echo "  ✓ Found 'specified later' deferral"
    echo "  ✓ Produced properly formatted review"
    echo "  ✓ Did not approve spec with errors"
    exit 0
 else
    echo "STATUS: FAILED"
    echo "Failed $FAILED verification tests"
    echo ""
    echo "Output saved to: $OUTPUT_FILE"
    echo ""
    echo "Review the output to see what went wrong."
    exit 1
 fi
--- a/tests/claude-code/test-helpers.sh
+++ b/tests/claude-code/test-helpers.sh
@@ -1,202 +0,0 @@
 #!/usr/bin/env bash
 # Helper functions for Claude Code skill tests
 # Run Claude Code with a prompt and capture output
 # Usage: run_claude "prompt text" [timeout_seconds] [allowed_tools]
 run_claude() {
    local prompt="$1"
    local timeout="${2:-60}"
    local allowed_tools="${3:-}"
    local output_file=$(mktemp)
    # Build command
    local cmd="claude -p \"$prompt\""
    if [ -n "$allowed_tools" ]; then
        cmd="$cmd --allowed-tools=$allowed_tools"
    fi
    # Run Claude in headless mode with timeout
    if timeout "$timeout" bash -c "$cmd" > "$output_file" 2>&1; then
        cat "$output_file"
        rm -f "$output_file"
        return 0
    else
        local exit_code=$?
        cat "$output_file" >&2
        rm -f "$output_file"
        return $exit_code
    fi
 }
 # Check if output contains a pattern
 # Usage: assert_contains "output" "pattern" "test name"
 assert_contains() {
    local output="$1"
    local pattern="$2"
    local test_name="${3:-test}"
    if echo "$output" | grep -q "$pattern"; then
        echo "  [PASS] $test_name"
        return 0
    else
        echo "  [FAIL] $test_name"
        echo "  Expected to find: $pattern"
        echo "  In output:"
        echo "$output" | sed 's/^/    /'
        return 1
    fi
 }
 # Check if output does NOT contain a pattern
 # Usage: assert_not_contains "output" "pattern" "test name"
 assert_not_contains() {
    local output="$1"
    local pattern="$2"
    local test_name="${3:-test}"
    if echo "$output" | grep -q "$pattern"; then
        echo "  [FAIL] $test_name"
        echo "  Did not expect to find: $pattern"
        echo "  In output:"
        echo "$output" | sed 's/^/    /'
        return 1
    else
        echo "  [PASS] $test_name"
        return 0
    fi
 }
 # Check if output matches a count
 # Usage: assert_count "output" "pattern" expected_count "test name"
 assert_count() {
    local output="$1"
    local pattern="$2"
    local expected="$3"
    local test_name="${4:-test}"
    local actual=$(echo "$output" | grep -c "$pattern" || echo "0")
    if [ "$actual" -eq "$expected" ]; then
        echo "  [PASS] $test_name (found $actual instances)"
        return 0
    else
        echo "  [FAIL] $test_name"
        echo "  Expected $expected instances of: $pattern"
        echo "  Found $actual instances"
        echo "  In output:"
        echo "$output" | sed 's/^/    /'
        return 1
    fi
 }
 # Check if pattern A appears before pattern B
 # Usage: assert_order "output" "pattern_a" "pattern_b" "test name"
 assert_order() {
    local output="$1"
    local pattern_a="$2"
    local pattern_b="$3"
    local test_name="${4:-test}"
    # Get line numbers where patterns appear
    local line_a=$(echo "$output" | grep -n "$pattern_a" | head -1 | cut -d: -f1)
    local line_b=$(echo "$output" | grep -n "$pattern_b" | head -1 | cut -d: -f1)
    if [ -z "$line_a" ]; then
        echo "  [FAIL] $test_name: pattern A not found: $pattern_a"
        return 1
    fi
    if [ -z "$line_b" ]; then
        echo "  [FAIL] $test_name: pattern B not found: $pattern_b"
        return 1
    fi
    if [ "$line_a" -lt "$line_b" ]; then
        echo "  [PASS] $test_name (A at line $line_a, B at line $line_b)"
        return 0
    else
        echo "  [FAIL] $test_name"
        echo "  Expected '$pattern_a' before '$pattern_b'"
        echo "  But found A at line $line_a, B at line $line_b"
        return 1
    fi
 }
 # Create a temporary test project directory
 # Usage: test_project=$(create_test_project)
 create_test_project() {
    local test_dir=$(mktemp -d)
    echo "$test_dir"
 }
 # Cleanup test project
 # Usage: cleanup_test_project "$test_dir"
 cleanup_test_project() {
    local test_dir="$1"
    if [ -d "$test_dir" ]; then
        rm -rf "$test_dir"
    fi
 }
 # Create a simple plan file for testing
 # Usage: create_test_plan "$project_dir" "$plan_name"
 create_test_plan() {
    local project_dir="$1"
    local plan_name="${2:-test-plan}"
    local plan_file="$project_dir/docs/superpowers/plans/$plan_name.md"
    mkdir -p "$(dirname "$plan_file")"
    cat > "$plan_file" <<'EOF'
 # Test Implementation Plan
 ## Task 1: Create Hello Function
 Create a simple hello function that returns "Hello, World!".
 **File:** `src/hello.js`
 **Implementation:**
 ```javascript
 export function hello() {
  return "Hello, World!";
 }
 ```
 **Tests:** Write a test that verifies the function returns the expected string.
 **Verification:** `npm test`
 ## Task 2: Create Goodbye Function
 Create a goodbye function that takes a name and returns a goodbye message.
 **File:** `src/goodbye.js`
 **Implementation:**
 ```javascript
 export function goodbye(name) {
  return `Goodbye, ${name}!`;
 }
 ```
 **Tests:** Write tests for:
 - Default name
 - Custom name
 - Edge cases (empty string, null)
 **Verification:** `npm test`
 EOF
    echo "$plan_file"
 }
 # Export functions for use in tests
 export -f run_claude
 export -f assert_contains
 export -f assert_not_contains
 export -f assert_count
 export -f assert_order
 export -f create_test_project
 export -f cleanup_test_project
 export -f create_test_plan
--- a/tests/claude-code/test-subagent-driven-development-integration.sh
+++ b/tests/claude-code/test-subagent-driven-development-integration.sh
@@ -1,314 +0,0 @@
 #!/usr/bin/env bash
 # Integration Test: subagent-driven-development workflow
 # Actually executes a plan and verifies the new workflow behaviors
 set -euo pipefail
 SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
 source "$SCRIPT_DIR/test-helpers.sh"
 echo "========================================"
 echo " Integration Test: subagent-driven-development"
 echo "========================================"
 echo ""
 echo "This test executes a real plan using the skill and verifies:"
 echo "  1. Plan is read once (not per task)"
 echo "  2. Full task text provided to subagents"
 echo "  3. Subagents perform self-review"
 echo "  4. Spec compliance review before code quality"
 echo "  5. Review loops when issues found"
 echo "  6. Spec reviewer reads code independently"
 echo ""
 echo "WARNING: This test may take 10-30 minutes to complete."
 echo ""
 # Create test project
 TEST_PROJECT=$(create_test_project)
 echo "Test project: $TEST_PROJECT"
 # Trap to cleanup
 trap "cleanup_test_project $TEST_PROJECT" EXIT
 # Set up minimal Node.js project
 cd "$TEST_PROJECT"
 cat > package.json <<'EOF'
 {
  "name": "test-project",
  "version": "1.0.0",
  "type": "module",
  "scripts": {
    "test": "node --test"
  }
 }
 EOF
 mkdir -p src test docs/superpowers/plans
 # Create a simple implementation plan
 cat > docs/superpowers/plans/implementation-plan.md <<'EOF'
 # Test Implementation Plan
 This is a minimal plan to test the subagent-driven-development workflow.
 ## Task 1: Create Add Function
 Create a function that adds two numbers.
 **File:** `src/math.js`
 **Requirements:**
 - Function named `add`
 - Takes two parameters: `a` and `b`
 - Returns the sum of `a` and `b`
 - Export the function
 **Implementation:**
 ```javascript
 export function add(a, b) {
  return a + b;
 }
 ```
 **Tests:** Create `test/math.test.js` that verifies:
 - `add(2, 3)` returns `5`
 - `add(0, 0)` returns `0`
 - `add(-1, 1)` returns `0`
 **Verification:** `npm test`
 ## Task 2: Create Multiply Function
 Create a function that multiplies two numbers.
 **File:** `src/math.js` (add to existing file)
 **Requirements:**
 - Function named `multiply`
 - Takes two parameters: `a` and `b`
 - Returns the product of `a` and `b`
 - Export the function
 - DO NOT add any extra features (like power, divide, etc.)
 **Implementation:**
 ```javascript
 export function multiply(a, b) {
  return a * b;
 }
 ```
 **Tests:** Add to `test/math.test.js`:
 - `multiply(2, 3)` returns `6`
 - `multiply(0, 5)` returns `0`
 - `multiply(-2, 3)` returns `-6`
 **Verification:** `npm test`
 EOF
 # Initialize git repo
 git init --quiet
 git config user.email "test@test.com"
 git config user.name "Test User"
 git add .
 git commit -m "Initial commit" --quiet
 echo ""
 echo "Project setup complete. Starting execution..."
 echo ""
 # Run Claude with subagent-driven-development
 # Capture full output to analyze
 OUTPUT_FILE="$TEST_PROJECT/claude-output.txt"
 # Create prompt file
 cat > "$TEST_PROJECT/prompt.txt" <<'EOF'
 I want you to execute the implementation plan at docs/superpowers/plans/implementation-plan.md using the subagent-driven-development skill.
 IMPORTANT: Follow the skill exactly. I will be verifying that you:
 1. Read the plan once at the beginning
 2. Provide full task text to subagents (don't make them read files)
 3. Ensure subagents do self-review before reporting
 4. Run spec compliance review before code quality review
 5. Use review loops when issues are found
 Begin now. Execute the plan.
 EOF
 # Note: We use a longer timeout since this is integration testing
 # Use --allowed-tools to enable tool usage in headless mode
 # IMPORTANT: Run from superpowers directory so local dev skills are available
 PROMPT="Change to directory $TEST_PROJECT and then execute the implementation plan at docs/superpowers/plans/implementation-plan.md using the subagent-driven-development skill.
 IMPORTANT: Follow the skill exactly. I will be verifying that you:
 1. Read the plan once at the beginning
 2. Provide full task text to subagents (don't make them read files)
 3. Ensure subagents do self-review before reporting
 4. Run spec compliance review before code quality review
 5. Use review loops when issues are found
 Begin now. Execute the plan."
 echo "Running Claude (output will be shown below and saved to $OUTPUT_FILE)..."
 echo "================================================================================"
 cd "$SCRIPT_DIR/../.." && timeout 1800 claude -p "$PROMPT" --allowed-tools=all --add-dir "$TEST_PROJECT" --permission-mode bypassPermissions 2>&1 | tee "$OUTPUT_FILE" || {
    echo ""
    echo "================================================================================"
    echo "EXECUTION FAILED (exit code: $?)"
    exit 1
 }
 echo "================================================================================"
 echo ""
 echo "Execution complete. Analyzing results..."
 echo ""
 # Find the session transcript
 # Session files are in ~/.claude/projects/-<working-dir>/<session-id>.jsonl
 WORKING_DIR_ESCAPED=$(echo "$SCRIPT_DIR/../.." | sed 's/\//-/g' | sed 's/^-//')
 SESSION_DIR="$HOME/.claude/projects/$WORKING_DIR_ESCAPED"
 # Find the most recent session file (created during this test run)
 SESSION_FILE=$(find "$SESSION_DIR" -name "*.jsonl" -type f -mmin -60 2>/dev/null | sort -r | head -1)
 if [ -z "$SESSION_FILE" ]; then
    echo "ERROR: Could not find session transcript file"
    echo "Looked in: $SESSION_DIR"
    exit 1
 fi
 echo "Analyzing session transcript: $(basename "$SESSION_FILE")"
 echo ""
 # Verification tests
 FAILED=0
 echo "=== Verification Tests ==="
 echo ""
 # Test 1: Skill was invoked
 echo "Test 1: Skill tool invoked..."
 if grep -q '"name":"Skill".*"skill":"superpowers:subagent-driven-development"' "$SESSION_FILE"; then
    echo "  [PASS] subagent-driven-development skill was invoked"
 else
    echo "  [FAIL] Skill was not invoked"
    FAILED=$((FAILED + 1))
 fi
 echo ""
 # Test 2: Subagents were used (Task tool)
 echo "Test 2: Subagents dispatched..."
 task_count=$(grep -c '"name":"Task"' "$SESSION_FILE" || echo "0")
 if [ "$task_count" -ge 2 ]; then
    echo "  [PASS] $task_count subagents dispatched"
 else
    echo "  [FAIL] Only $task_count subagent(s) dispatched (expected >= 2)"
    FAILED=$((FAILED + 1))
 fi
 echo ""
 # Test 3: TodoWrite was used for tracking
 echo "Test 3: Task tracking..."
 todo_count=$(grep -c '"name":"TodoWrite"' "$SESSION_FILE" || echo "0")
 if [ "$todo_count" -ge 1 ]; then
    echo "  [PASS] TodoWrite used $todo_count time(s) for task tracking"
 else
    echo "  [FAIL] TodoWrite not used"
    FAILED=$((FAILED + 1))
 fi
 echo ""
 # Test 6: Implementation actually works
 echo "Test 6: Implementation verification..."
 if [ -f "$TEST_PROJECT/src/math.js" ]; then
    echo "  [PASS] src/math.js created"
    if grep -q "export function add" "$TEST_PROJECT/src/math.js"; then
        echo "  [PASS] add function exists"
    else
        echo "  [FAIL] add function missing"
        FAILED=$((FAILED + 1))
    fi
    if grep -q "export function multiply" "$TEST_PROJECT/src/math.js"; then
        echo "  [PASS] multiply function exists"
    else
        echo "  [FAIL] multiply function missing"
        FAILED=$((FAILED + 1))
    fi
 else
    echo "  [FAIL] src/math.js not created"
    FAILED=$((FAILED + 1))
 fi
 if [ -f "$TEST_PROJECT/test/math.test.js" ]; then
    echo "  [PASS] test/math.test.js created"
 else
    echo "  [FAIL] test/math.test.js not created"
    FAILED=$((FAILED + 1))
 fi
 # Try running tests
 if cd "$TEST_PROJECT" && npm test > test-output.txt 2>&1; then
    echo "  [PASS] Tests pass"
 else
    echo "  [FAIL] Tests failed"
    cat test-output.txt
    FAILED=$((FAILED + 1))
 fi
 echo ""
 # Test 7: Git commits show proper workflow
 echo "Test 7: Git commit history..."
 commit_count=$(git -C "$TEST_PROJECT" log --oneline | wc -l)
 if [ "$commit_count" -gt 2 ]; then  # Initial + at least 2 task commits
    echo "  [PASS] Multiple commits created ($commit_count total)"
 else
    echo "  [FAIL] Too few commits ($commit_count, expected >2)"
    FAILED=$((FAILED + 1))
 fi
 echo ""
 # Test 8: Check for extra features (spec compliance should catch)
 echo "Test 8: No extra features added (spec compliance)..."
 if grep -q "export function divide\|export function power\|export function subtract" "$TEST_PROJECT/src/math.js" 2>/dev/null; then
    echo "  [WARN] Extra features found (spec review should have caught this)"
    # Not failing on this as it tests reviewer effectiveness
 else
    echo "  [PASS] No extra features added"
 fi
 echo ""
 # Token Usage Analysis
 echo "========================================="
 echo " Token Usage Analysis"
 echo "========================================="
 echo ""
 python3 "$SCRIPT_DIR/analyze-token-usage.py" "$SESSION_FILE"
 echo ""
 # Summary
 echo "========================================"
 echo " Test Summary"
 echo "========================================"
 echo ""
 if [ $FAILED -eq 0 ]; then
    echo "STATUS: PASSED"
    echo "All verification tests passed!"
    echo ""
    echo "The subagent-driven-development skill correctly:"
    echo "  ✓ Reads plan once at start"
    echo "  ✓ Provides full task text to subagents"
    echo "  ✓ Enforces self-review"
    echo "  ✓ Runs spec compliance before code quality"
    echo "  ✓ Spec reviewer verifies independently"
    echo "  ✓ Produces working implementation"
    exit 0
 else
    echo "STATUS: FAILED"
    echo "Failed $FAILED verification tests"
    echo ""
    echo "Output saved to: $OUTPUT_FILE"
    echo ""
    echo "Review the output to see what went wrong."
    exit 1
 fi
--- a/Show More
+++ b/Show More
		`@@ -1,3 +0,0 @@`
			`# These are supported funding model platforms`

			`github: [obra]`
		`@@ -1,2 +0,0 @@`
			`@./skills/using-superpowers/SKILL.md`
			`@./skills/using-superpowers/references/gemini-tools.md`