diff --git a/superpowers/.claude-plugin/marketplace.json b/superpowers/.claude-plugin/marketplace.json index 7fc26ce..b0bc973 100644 --- a/superpowers/.claude-plugin/marketplace.json +++ b/superpowers/.claude-plugin/marketplace.json @@ -9,7 +9,7 @@ { "name": "superpowers", "description": "Core skills library for Claude Code: TDD, debugging, collaboration patterns, and proven techniques", - "version": "5.0.2", + "version": "5.0.4", "source": "./", "author": { "name": "Jesse Vincent", diff --git a/superpowers/.claude-plugin/plugin.json b/superpowers/.claude-plugin/plugin.json index 4ca21c8..aa0897f 100644 --- a/superpowers/.claude-plugin/plugin.json +++ b/superpowers/.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.2", + "version": "5.0.4", "author": { "name": "Jesse Vincent", "email": "jesse@fsck.com" diff --git a/superpowers/.cursor-plugin/plugin.json b/superpowers/.cursor-plugin/plugin.json index 6a27dec..18e4295 100644 --- a/superpowers/.cursor-plugin/plugin.json +++ b/superpowers/.cursor-plugin/plugin.json @@ -14,5 +14,5 @@ "skills": "./skills/", "agents": "./agents/", "commands": "./commands/", - "hooks": "./hooks/hooks.json" + "hooks": "./hooks/hooks-cursor.json" } diff --git a/superpowers/.opencode/INSTALL.md b/superpowers/.opencode/INSTALL.md index 0cbda07..2dc2b23 100644 --- a/superpowers/.opencode/INSTALL.md +++ b/superpowers/.opencode/INSTALL.md @@ -3,107 +3,71 @@ ## Prerequisites - [OpenCode.ai](https://opencode.ai) installed -- Git installed -## Installation Steps +## Installation -### 1. Clone Superpowers +Add superpowers to the `plugin` array in your `opencode.json` (global or project-level): -```bash -git clone https://github.com/obra/superpowers.git ~/.config/opencode/superpowers +```json +{ + "plugin": ["superpowers@git+https://github.com/obra/superpowers.git"] +} ``` -### 2. Register the Plugin +Restart OpenCode. That's it — the plugin auto-installs and registers all skills. -Create a symlink so OpenCode discovers the plugin: +Verify by asking: "Tell me about your superpowers" + +## Migrating from the old symlink-based install + +If you previously installed superpowers using `git clone` and symlinks, remove the old setup: ```bash -mkdir -p ~/.config/opencode/plugins +# Remove old symlinks rm -f ~/.config/opencode/plugins/superpowers.js -ln -s ~/.config/opencode/superpowers/.opencode/plugins/superpowers.js ~/.config/opencode/plugins/superpowers.js -``` - -### 3. Symlink Skills - -Create a symlink so OpenCode's native skill tool discovers superpowers skills: - -```bash -mkdir -p ~/.config/opencode/skills rm -rf ~/.config/opencode/skills/superpowers -ln -s ~/.config/opencode/superpowers/skills ~/.config/opencode/skills/superpowers + +# Optionally remove the cloned repo +rm -rf ~/.config/opencode/superpowers + +# Remove skills.paths from opencode.json if you added one for superpowers ``` -### 4. Restart OpenCode - -Restart OpenCode. The plugin will automatically inject superpowers context. - -Verify by asking: "do you have superpowers?" +Then follow the installation steps above. ## Usage -### Finding Skills - -Use OpenCode's native `skill` tool to list available skills: +Use OpenCode's native `skill` tool: ``` use skill tool to list skills -``` - -### Loading a Skill - -Use OpenCode's native `skill` tool to load a specific skill: - -``` use skill tool to load superpowers/brainstorming ``` -### Personal Skills - -Create your own skills in `~/.config/opencode/skills/`: - -```bash -mkdir -p ~/.config/opencode/skills/my-skill -``` - -Create `~/.config/opencode/skills/my-skill/SKILL.md`: - -```markdown ---- -name: my-skill -description: Use when [condition] - [what it does] ---- - -# My Skill - -[Your skill content here] -``` - -### Project Skills - -Create project-specific skills in `.opencode/skills/` within your project. - -**Skill Priority:** Project skills > Personal skills > Superpowers skills - ## Updating -```bash -cd ~/.config/opencode/superpowers -git pull +Superpowers updates automatically when you restart OpenCode. + +To pin a specific version: + +```json +{ + "plugin": ["superpowers@git+https://github.com/obra/superpowers.git#v5.0.3"] +} ``` ## Troubleshooting ### Plugin not loading -1. Check plugin symlink: `ls -l ~/.config/opencode/plugins/superpowers.js` -2. Check source exists: `ls ~/.config/opencode/superpowers/.opencode/plugins/superpowers.js` -3. Check OpenCode logs for errors +1. Check logs: `opencode run --print-logs "hello" 2>&1 | grep -i superpowers` +2. Verify the plugin line in your `opencode.json` +3. Make sure you're running a recent version of OpenCode ### Skills not found -1. Check skills symlink: `ls -l ~/.config/opencode/skills/superpowers` -2. Verify it points to: `~/.config/opencode/superpowers/skills` -3. Use `skill` tool to list what's discovered +1. Use `skill` tool to list what's discovered +2. Check that the plugin is loading (see above) ### Tool mapping diff --git a/superpowers/.opencode/plugins/superpowers.js b/superpowers/.opencode/plugins/superpowers.js index 886669b..5e7833b 100644 --- a/superpowers/.opencode/plugins/superpowers.js +++ b/superpowers/.opencode/plugins/superpowers.js @@ -2,7 +2,7 @@ * Superpowers plugin for OpenCode.ai * * Injects superpowers bootstrap context via system prompt transform. - * Skills are discovered via OpenCode's native skill tool from symlinked directory. + * Auto-registers skills directory via config hook (no symlinks needed). */ import path from 'path'; @@ -84,6 +84,18 @@ ${toolMapping} }; return { + // Inject skills path into live config so OpenCode discovers superpowers skills + // without requiring manual symlinks or config file edits. + // This works because Config.get() returns a cached singleton — modifications + // here are visible when skills are lazily discovered later. + config: async (config) => { + config.skills = config.skills || {}; + config.skills.paths = config.skills.paths || []; + if (!config.skills.paths.includes(superpowersSkillsDir)) { + config.skills.paths.push(superpowersSkillsDir); + } + }, + // Use system prompt transform to inject bootstrap (fixes #226 agent reset bug) 'experimental.chat.system.transform': async (_input, output) => { const bootstrap = getBootstrapContent(); diff --git a/superpowers/CHANGELOG.md b/superpowers/CHANGELOG.md new file mode 100644 index 0000000..c2f15fc --- /dev/null +++ b/superpowers/CHANGELOG.md @@ -0,0 +1,20 @@ +# Changelog + +## Unreleased + +### Fixed + +- **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. Applies to all Windows shells (CMD, PowerShell, Git Bash) since they all route through Git Bash. ([#737](https://github.com/obra/superpowers/issues/737), based on [#740](https://github.com/obra/superpowers/pull/740)) +- **Portable shebangs**: Replace `#!/bin/bash` with `#!/usr/bin/env bash` in all 13 shell scripts. Fixes execution on NixOS, FreeBSD, and macOS with Homebrew bash where `/bin/bash` is outdated or missing. ([#700](https://github.com/obra/superpowers/pull/700), dupes: [#747](https://github.com/obra/superpowers/pull/747)) +- **POSIX-safe hook script**: Replace `${BASH_SOURCE[0]:-$0}` with `$0` in `hooks/session-start` and polyglot-hooks docs. Fixes 'Bad substitution' error on Ubuntu/Debian where `/bin/sh` is dash. ([#553](https://github.com/obra/superpowers/pull/553)) +- **Bash 5.3+ hook hang**: Replace heredoc (`cat <nul -mkdir "%USERPROFILE%\.config\opencode\skills" 2>nul - -:: 3. Remove existing links (safe for reinstalls) -del "%USERPROFILE%\.config\opencode\plugins\superpowers.js" 2>nul -rmdir "%USERPROFILE%\.config\opencode\skills\superpowers" 2>nul - -:: 4. Create plugin symlink (requires Developer Mode or Admin) -mklink "%USERPROFILE%\.config\opencode\plugins\superpowers.js" "%USERPROFILE%\.config\opencode\superpowers\.opencode\plugins\superpowers.js" - -:: 5. Create skills junction (works without special privileges) -mklink /J "%USERPROFILE%\.config\opencode\skills\superpowers" "%USERPROFILE%\.config\opencode\superpowers\skills" - -:: 6. Restart OpenCode -``` - -#### PowerShell - -Run as Administrator, or with Developer Mode enabled: - -```powershell -# 1. Install Superpowers -git clone https://github.com/obra/superpowers.git "$env:USERPROFILE\.config\opencode\superpowers" - -# 2. Create directories -New-Item -ItemType Directory -Force -Path "$env:USERPROFILE\.config\opencode\plugins" -New-Item -ItemType Directory -Force -Path "$env:USERPROFILE\.config\opencode\skills" - -# 3. Remove existing links (safe for reinstalls) -Remove-Item "$env:USERPROFILE\.config\opencode\plugins\superpowers.js" -Force -ErrorAction SilentlyContinue -Remove-Item "$env:USERPROFILE\.config\opencode\skills\superpowers" -Force -ErrorAction SilentlyContinue - -# 4. Create plugin symlink (requires Developer Mode or Admin) -New-Item -ItemType SymbolicLink -Path "$env:USERPROFILE\.config\opencode\plugins\superpowers.js" -Target "$env:USERPROFILE\.config\opencode\superpowers\.opencode\plugins\superpowers.js" - -# 5. Create skills junction (works without special privileges) -New-Item -ItemType Junction -Path "$env:USERPROFILE\.config\opencode\skills\superpowers" -Target "$env:USERPROFILE\.config\opencode\superpowers\skills" - -# 6. Restart OpenCode -``` - -#### Git Bash - -Note: Git Bash's native `ln` command copies files instead of creating symlinks. Use `cmd //c mklink` instead (the `//c` is Git Bash syntax for `/c`). - -```bash -# 1. Install Superpowers -git clone https://github.com/obra/superpowers.git ~/.config/opencode/superpowers - -# 2. Create directories -mkdir -p ~/.config/opencode/plugins ~/.config/opencode/skills - -# 3. Remove existing links (safe for reinstalls) -rm -f ~/.config/opencode/plugins/superpowers.js 2>/dev/null -rm -rf ~/.config/opencode/skills/superpowers 2>/dev/null - -# 4. Create plugin symlink (requires Developer Mode or Admin) -cmd //c "mklink \"$(cygpath -w ~/.config/opencode/plugins/superpowers.js)\" \"$(cygpath -w ~/.config/opencode/superpowers/.opencode/plugins/superpowers.js)\"" - -# 5. Create skills junction (works without special privileges) -cmd //c "mklink /J \"$(cygpath -w ~/.config/opencode/skills/superpowers)\" \"$(cygpath -w ~/.config/opencode/superpowers/skills)\"" - -# 6. Restart OpenCode -``` - -#### WSL Users - -If running OpenCode inside WSL, use the [macOS / Linux](#macos--linux) instructions instead. - -#### Verify Installation - -**Command Prompt:** -```cmd -dir /AL "%USERPROFILE%\.config\opencode\plugins" -dir /AL "%USERPROFILE%\.config\opencode\skills" -``` - -**PowerShell:** -```powershell -Get-ChildItem "$env:USERPROFILE\.config\opencode\plugins" | Where-Object { $_.LinkType } -Get-ChildItem "$env:USERPROFILE\.config\opencode\skills" | Where-Object { $_.LinkType } -``` - -Look for `` or `` in the output. - -#### Troubleshooting Windows - -**"You do not have sufficient privilege" error:** -- Enable Developer Mode in Windows Settings, OR -- Right-click your terminal → "Run as Administrator" - -**"Cannot create a file when that file already exists":** -- Run the removal commands (step 3) first, then retry - -**Symlinks not working after git clone:** -- Run `git config --global core.symlinks true` and re-clone +Then follow the installation steps above. ## Usage @@ -178,8 +45,6 @@ use skill tool to list skills ### Loading a Skill -Use OpenCode's native `skill` tool to load a specific skill: - ``` use skill tool to load superpowers/brainstorming ``` @@ -207,124 +72,59 @@ description: Use when [condition] - [what it does] ### Project Skills -Create project-specific skills in your OpenCode project: +Create project-specific skills in `.opencode/skills/` within your project. -```bash -# In your OpenCode project -mkdir -p .opencode/skills/my-project-skill +**Skill Priority:** Project skills > Personal skills > Superpowers skills + +## Updating + +Superpowers updates automatically when you restart OpenCode. The plugin is re-installed from the git repository on each launch. + +To pin a specific version, use a branch or tag: + +```json +{ + "plugin": ["superpowers@git+https://github.com/obra/superpowers.git#v5.0.3"] +} ``` -Create `.opencode/skills/my-project-skill/SKILL.md`: +## How It Works -```markdown ---- -name: my-project-skill -description: Use when [condition] - [what it does] ---- +The plugin does two things: -# My Project Skill - -[Your skill content here] -``` - -## Skill Locations - -OpenCode discovers skills from these locations: - -1. **Project skills** (`.opencode/skills/`) - Highest priority -2. **Personal skills** (`~/.config/opencode/skills/`) -3. **Superpowers skills** (`~/.config/opencode/skills/superpowers/`) - via symlink - -## Features - -### Automatic Context Injection - -The plugin automatically injects superpowers context via the `experimental.chat.system.transform` hook. This adds the "using-superpowers" skill content to the system prompt on every request. - -### Native Skills Integration - -Superpowers uses OpenCode's native `skill` tool for skill discovery and loading. Skills are symlinked into `~/.config/opencode/skills/superpowers/` so they appear alongside your personal and project skills. +1. **Injects bootstrap context** via the `experimental.chat.system.transform` hook, adding superpowers awareness to every conversation. +2. **Registers the skills directory** via the `config` hook, so OpenCode discovers all superpowers skills without symlinks or manual config. ### Tool Mapping -Skills written for Claude Code are automatically adapted for OpenCode. The bootstrap provides mapping instructions: +Skills written for Claude Code are automatically adapted for OpenCode: - `TodoWrite` → `todowrite` - `Task` with subagents → OpenCode's `@mention` system - `Skill` tool → OpenCode's native `skill` tool - File operations → Native OpenCode tools -## Architecture - -### Plugin Structure - -**Location:** `~/.config/opencode/superpowers/.opencode/plugins/superpowers.js` - -**Components:** -- `experimental.chat.system.transform` hook for bootstrap injection -- Reads and injects the "using-superpowers" skill content - -### Skills - -**Location:** `~/.config/opencode/skills/superpowers/` (symlink to `~/.config/opencode/superpowers/skills/`) - -Skills are discovered by OpenCode's native skill system. Each skill has a `SKILL.md` file with YAML frontmatter. - -## Updating - -```bash -cd ~/.config/opencode/superpowers -git pull -``` - -Restart OpenCode to load the updates. - ## Troubleshooting ### Plugin not loading -1. Check plugin exists: `ls ~/.config/opencode/superpowers/.opencode/plugins/superpowers.js` -2. Check symlink/junction: `ls -l ~/.config/opencode/plugins/` (macOS/Linux) or `dir /AL %USERPROFILE%\.config\opencode\plugins` (Windows) -3. Check OpenCode logs: `opencode run "test" --print-logs --log-level DEBUG` -4. Look for plugin loading message in logs +1. Check OpenCode logs: `opencode run --print-logs "hello" 2>&1 | grep -i superpowers` +2. Verify the plugin line in your `opencode.json` is correct +3. Make sure you're running a recent version of OpenCode ### Skills not found -1. Verify skills symlink: `ls -l ~/.config/opencode/skills/superpowers` (should point to superpowers/skills/) -2. Use OpenCode's `skill` tool to list available skills -3. Check skill structure: each skill needs a `SKILL.md` file with valid frontmatter - -### Windows: Module not found error - -If you see `Cannot find module` errors on Windows: -- **Cause:** Git Bash `ln -sf` copies files instead of creating symlinks -- **Fix:** Use `mklink /J` directory junctions instead (see Windows installation steps) +1. Use OpenCode's `skill` tool to list available skills +2. Check that the plugin is loading (see above) +3. Each skill needs a `SKILL.md` file with valid YAML frontmatter ### Bootstrap not appearing -1. Verify using-superpowers skill exists: `ls ~/.config/opencode/superpowers/skills/using-superpowers/SKILL.md` -2. Check OpenCode version supports `experimental.chat.system.transform` hook -3. Restart OpenCode after plugin changes +1. Check OpenCode version supports `experimental.chat.system.transform` hook +2. Restart OpenCode after config changes ## Getting Help - Report issues: https://github.com/obra/superpowers/issues - Main documentation: https://github.com/obra/superpowers - OpenCode docs: https://opencode.ai/docs/ - -## Testing - -Verify your installation: - -```bash -# Check plugin loads -opencode run --print-logs "hello" 2>&1 | grep -i superpowers - -# Check skills are discoverable -opencode run "use skill tool to list all skills" 2>&1 | grep -i superpowers - -# Check bootstrap injection -opencode run "what superpowers do you have?" -``` - -The agent should mention having superpowers and be able to list skills from `superpowers/`. diff --git a/superpowers/docs/windows/polyglot-hooks.md b/superpowers/docs/windows/polyglot-hooks.md index 6878f66..5e26ca4 100644 --- a/superpowers/docs/windows/polyglot-hooks.md +++ b/superpowers/docs/windows/polyglot-hooks.md @@ -148,7 +148,7 @@ exit /b CMDBLOCK # Unix shell runs from here -SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]:-$0}")" && pwd)" +SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)" SCRIPT_NAME="$1" shift "${SCRIPT_DIR}/${SCRIPT_NAME}" "$@" diff --git a/superpowers/hooks/hooks-cursor.json b/superpowers/hooks/hooks-cursor.json new file mode 100644 index 0000000..6df4461 --- /dev/null +++ b/superpowers/hooks/hooks-cursor.json @@ -0,0 +1,10 @@ +{ + "version": 1, + "hooks": { + "sessionStart": [ + { + "command": "./hooks/session-start" + } + ] + } +} diff --git a/superpowers/hooks/hooks.json b/superpowers/hooks/hooks.json index 7e3d30d..79d8cee 100644 --- a/superpowers/hooks/hooks.json +++ b/superpowers/hooks/hooks.json @@ -2,7 +2,7 @@ "hooks": { "SessionStart": [ { - "matcher": "startup|resume|clear|compact", + "matcher": "startup|clear|compact", "hooks": [ { "type": "command", diff --git a/superpowers/hooks/session-start b/superpowers/hooks/session-start index f9e94dd..2371935 100755 --- a/superpowers/hooks/session-start +++ b/superpowers/hooks/session-start @@ -4,7 +4,7 @@ set -euo pipefail # Determine plugin root directory -SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]:-$0}")" && pwd)" +SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)" PLUGIN_ROOT="$(cd "${SCRIPT_DIR}/.." && pwd)" # Check if legacy skills directory exists and build warning @@ -39,23 +39,19 @@ session_context="\nYou have superpowers.\n\n**Below is the # 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. -if [ -n "${CLAUDE_PLUGIN_ROOT:-}" ]; then +# +# Uses printf instead of heredoc (cat <-design.md` and commit -7. **Spec review loop** — dispatch spec-document-reviewer subagent with precisely crafted review context (never your session history); fix issues and re-dispatch until approved (max 5 iterations, then surface to human) +7. **Spec review loop** — dispatch spec-document-reviewer subagent with precisely crafted review context (never your session history); fix issues and re-dispatch until approved (max 3 iterations, then surface to human) 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 @@ -121,7 +121,7 @@ After writing the spec document: 1. Dispatch spec-document-reviewer subagent (see spec-document-reviewer-prompt.md) 2. If Issues Found: fix, re-dispatch, repeat until Approved -3. If loop exceeds 5 iterations, surface to human for guidance +3. If loop exceeds 3 iterations, surface to human for guidance **User Review Gate:** After the spec review loop passes, ask the user to review the written spec before proceeding: diff --git a/superpowers/skills/brainstorming/scripts/server.js b/superpowers/skills/brainstorming/scripts/server.js index dec2f7a..86c3080 100644 --- a/superpowers/skills/brainstorming/scripts/server.js +++ b/superpowers/skills/brainstorming/scripts/server.js @@ -94,7 +94,7 @@ const WAITING_PAGE = ` h1 { color: #333; } p { color: #666; }

Brainstorm Companion

-

Waiting for Claude to push a screen...

`; +

Waiting for the agent to push a screen...

`; const frameTemplate = fs.readFileSync(path.join(__dirname, 'frame-template.html'), 'utf-8'); const helperScript = fs.readFileSync(path.join(__dirname, 'helper.js'), 'utf-8'); diff --git a/superpowers/skills/brainstorming/scripts/start-server.sh b/superpowers/skills/brainstorming/scripts/start-server.sh index b5f5a75..a60025c 100755 --- a/superpowers/skills/brainstorming/scripts/start-server.sh +++ b/superpowers/skills/brainstorming/scripts/start-server.sh @@ -1,4 +1,4 @@ -#!/bin/bash +#!/usr/bin/env bash # Start the brainstorm server and output connection info # Usage: start-server.sh [--project-dir ] [--host ] [--url-host ] [--foreground] [--background] # @@ -64,6 +64,16 @@ if [[ -n "${CODEX_CI:-}" && "$FOREGROUND" != "true" && "$FORCE_BACKGROUND" != "t 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)" diff --git a/superpowers/skills/brainstorming/scripts/stop-server.sh b/superpowers/skills/brainstorming/scripts/stop-server.sh index c3724de..2e5973d 100755 --- a/superpowers/skills/brainstorming/scripts/stop-server.sh +++ b/superpowers/skills/brainstorming/scripts/stop-server.sh @@ -1,4 +1,4 @@ -#!/bin/bash +#!/usr/bin/env bash # Stop the brainstorm server and clean up # Usage: stop-server.sh # @@ -17,7 +17,31 @@ PID_FILE="${SCREEN_DIR}/.server.pid" if [[ -f "$PID_FILE" ]]; then pid=$(cat "$PID_FILE") - kill "$pid" 2>/dev/null + + # 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" "${SCREEN_DIR}/.server.log" # Only delete ephemeral /tmp directories diff --git a/superpowers/skills/brainstorming/spec-document-reviewer-prompt.md b/superpowers/skills/brainstorming/spec-document-reviewer-prompt.md index 212b36c..35acbb6 100644 --- a/superpowers/skills/brainstorming/spec-document-reviewer-prompt.md +++ b/superpowers/skills/brainstorming/spec-document-reviewer-prompt.md @@ -19,32 +19,31 @@ Task tool (general-purpose): | 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 | + | Clarity | Requirements ambiguous enough to cause someone to build the wrong thing | | Scope | Focused enough for a single plan — not covering multiple independent subsystems | - | Architecture | Units with clear boundaries, well-defined interfaces, independently understandable and testable | + | YAGNI | Unrequested features, over-engineering | - ## CRITICAL + ## Calibration - 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 - - Units that lack clear boundaries or interfaces — can you understand what each unit does without reading its internals? + **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 + **Status:** Approved | Issues Found **Issues (if any):** - - [Section X]: [specific issue] - [why it matters] + - [Section X]: [specific issue] - [why it matters for planning] - **Recommendations (advisory):** - - [suggestions that don't block approval] + **Recommendations (advisory, do not block approval):** + - [suggestions for improvement] ``` **Reviewer returns:** Status, Issues (if any), Recommendations diff --git a/superpowers/skills/brainstorming/visual-companion.md b/superpowers/skills/brainstorming/visual-companion.md index a25e85a..2c35d5d 100644 --- a/superpowers/skills/brainstorming/visual-companion.md +++ b/superpowers/skills/brainstorming/visual-companion.md @@ -61,6 +61,14 @@ scripts/start-server.sh --project-dir /path/to/project scripts/start-server.sh --project-dir /path/to/project ``` +**Windows (Git Bash / CMD / PowerShell):** +```bash +# Windows/Git Bash reaps nohup background processes. The script auto-detects +# this via OSTYPE/MSYSTEM and switches to foreground mode automatically. +# No extra flags needed — all Windows shells route through Git Bash. +scripts/start-server.sh --project-dir /path/to/project +``` + **Gemini CLI:** ```bash # Use --foreground and set is_background: true on your shell tool call diff --git a/superpowers/skills/using-superpowers/references/codex-tools.md b/superpowers/skills/using-superpowers/references/codex-tools.md index eb23075..86f58fa 100644 --- a/superpowers/skills/using-superpowers/references/codex-tools.md +++ b/superpowers/skills/using-superpowers/references/codex-tools.md @@ -13,13 +13,13 @@ Skills use Claude Code tool names. When you encounter these in a skill, use your | `Read`, `Write`, `Edit` (files) | Use your native file tools | | `Bash` (run commands) | Use your native shell tools | -## Subagent dispatch requires collab +## Subagent dispatch requires multi-agent support Add to your Codex config (`~/.codex/config.toml`): ```toml [features] -collab = true +multi_agent = true ``` This enables `spawn_agent`, `wait`, and `close_agent` for skills like `dispatching-parallel-agents` and `subagent-driven-development`. diff --git a/superpowers/skills/writing-plans/SKILL.md b/superpowers/skills/writing-plans/SKILL.md index ed67c5e..26bae9a 100644 --- a/superpowers/skills/writing-plans/SKILL.md +++ b/superpowers/skills/writing-plans/SKILL.md @@ -112,22 +112,17 @@ git commit -m "feat: add specific feature" ## Plan Review Loop -After completing each chunk of the plan: +After writing the complete plan: -1. Dispatch plan-document-reviewer subagent (see plan-document-reviewer-prompt.md) with precisely crafted review context — never your session history. This keeps the reviewer focused on the plan, not your thought process. - - Provide: chunk content, path to spec document -2. If ❌ Issues Found: - - 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: ` headings to delimit chunks. Each chunk should be ≤1000 lines and logically self-contained. +1. Dispatch a single plan-document-reviewer subagent (see plan-document-reviewer-prompt.md) with precisely crafted review context — never your session history. This keeps the reviewer focused on the plan, not your thought process. + - Provide: path to the plan document, path to spec document +2. If ❌ Issues Found: fix the issues, re-dispatch reviewer for the whole plan +3. If ✅ Approved: proceed to execution handoff **Review loop guidance:** - Same agent that wrote the plan fixes it (preserves context) -- If loop exceeds 5 iterations, surface to human for guidance -- Reviewers are advisory - explain disagreements if you believe feedback is incorrect +- If loop exceeds 3 iterations, surface to human for guidance +- Reviewers are advisory — explain disagreements if you believe feedback is incorrect ## Execution Handoff diff --git a/superpowers/skills/writing-plans/plan-document-reviewer-prompt.md b/superpowers/skills/writing-plans/plan-document-reviewer-prompt.md index ce36cba..2db2806 100644 --- a/superpowers/skills/writing-plans/plan-document-reviewer-prompt.md +++ b/superpowers/skills/writing-plans/plan-document-reviewer-prompt.md @@ -2,17 +2,17 @@ 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. +**Purpose:** Verify the plan is complete, matches the spec, and has proper task decomposition. -**Dispatch after:** Each plan chunk is written +**Dispatch after:** The complete plan is written. ``` Task tool (general-purpose): - description: "Review plan chunk N" + description: "Review plan document" prompt: | - You are a plan document reviewer. Verify this plan chunk is complete and ready for implementation. + You are a plan document reviewer. Verify this plan is complete and ready for implementation. - **Plan chunk to review:** [PLAN_FILE_PATH] - Chunk N only + **Plan to review:** [PLAN_FILE_PATH] **Spec for reference:** [SPEC_FILE_PATH] ## What to Check @@ -20,33 +20,30 @@ Task tool (general-purpose): | 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 | - | File Structure | Files have clear single responsibilities, split by responsibility not layer | - | File Size | Would any new or modified file likely grow large enough to be hard to reason about as a whole? | - | Task Syntax | Checkbox syntax (`- [ ]`) on steps for tracking | - | Chunk Size | Each chunk under 1000 lines | + | 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? | - ## CRITICAL + ## Calibration - 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 - - Files planned to hold multiple responsibilities or likely to grow unwieldy + **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 - Chunk N + ## Plan Review **Status:** Approved | Issues Found **Issues (if any):** - - [Task X, Step Y]: [specific issue] - [why it matters] + - [Task X, Step Y]: [specific issue] - [why it matters for implementation] - **Recommendations (advisory):** - - [suggestions that don't block approval] + **Recommendations (advisory, do not block approval):** + - [suggestions for improvement] ``` **Reviewer returns:** Status, Issues (if any), Recommendations diff --git a/superpowers/tests/explicit-skill-requests/run-all.sh b/superpowers/tests/explicit-skill-requests/run-all.sh index a37b85d..b4c5707 100755 --- a/superpowers/tests/explicit-skill-requests/run-all.sh +++ b/superpowers/tests/explicit-skill-requests/run-all.sh @@ -1,4 +1,4 @@ -#!/bin/bash +#!/usr/bin/env bash # Run all explicit skill request tests # Usage: ./run-all.sh diff --git a/superpowers/tests/explicit-skill-requests/run-claude-describes-sdd.sh b/superpowers/tests/explicit-skill-requests/run-claude-describes-sdd.sh index 6debe40..c646bc9 100755 --- a/superpowers/tests/explicit-skill-requests/run-claude-describes-sdd.sh +++ b/superpowers/tests/explicit-skill-requests/run-claude-describes-sdd.sh @@ -1,4 +1,4 @@ -#!/bin/bash +#!/usr/bin/env bash # Test where Claude explicitly describes subagent-driven-development before user requests it # This mimics the original failure scenario diff --git a/superpowers/tests/explicit-skill-requests/run-extended-multiturn-test.sh b/superpowers/tests/explicit-skill-requests/run-extended-multiturn-test.sh index affd05a..69ccd0a 100755 --- a/superpowers/tests/explicit-skill-requests/run-extended-multiturn-test.sh +++ b/superpowers/tests/explicit-skill-requests/run-extended-multiturn-test.sh @@ -1,4 +1,4 @@ -#!/bin/bash +#!/usr/bin/env bash # Extended multi-turn test with more conversation history # This tries to reproduce the failure by building more context diff --git a/superpowers/tests/explicit-skill-requests/run-haiku-test.sh b/superpowers/tests/explicit-skill-requests/run-haiku-test.sh index e1413f1..9079e9d 100755 --- a/superpowers/tests/explicit-skill-requests/run-haiku-test.sh +++ b/superpowers/tests/explicit-skill-requests/run-haiku-test.sh @@ -1,4 +1,4 @@ -#!/bin/bash +#!/usr/bin/env bash # Test with haiku model and user's CLAUDE.md # This tests whether a cheaper/faster model fails more easily diff --git a/superpowers/tests/explicit-skill-requests/run-multiturn-test.sh b/superpowers/tests/explicit-skill-requests/run-multiturn-test.sh index 8476026..b926d65 100755 --- a/superpowers/tests/explicit-skill-requests/run-multiturn-test.sh +++ b/superpowers/tests/explicit-skill-requests/run-multiturn-test.sh @@ -1,4 +1,4 @@ -#!/bin/bash +#!/usr/bin/env bash # Test explicit skill requests in multi-turn conversations # Usage: ./run-multiturn-test.sh # diff --git a/superpowers/tests/explicit-skill-requests/run-test.sh b/superpowers/tests/explicit-skill-requests/run-test.sh index 1975381..d0e7ab2 100755 --- a/superpowers/tests/explicit-skill-requests/run-test.sh +++ b/superpowers/tests/explicit-skill-requests/run-test.sh @@ -1,4 +1,4 @@ -#!/bin/bash +#!/usr/bin/env bash # Test explicit skill requests (user names a skill directly) # Usage: ./run-test.sh # diff --git a/superpowers/tests/skill-triggering/run-all.sh b/superpowers/tests/skill-triggering/run-all.sh index bab5c2d..1a35dd9 100755 --- a/superpowers/tests/skill-triggering/run-all.sh +++ b/superpowers/tests/skill-triggering/run-all.sh @@ -1,4 +1,4 @@ -#!/bin/bash +#!/usr/bin/env bash # Run all skill triggering tests # Usage: ./run-all.sh diff --git a/superpowers/tests/skill-triggering/run-test.sh b/superpowers/tests/skill-triggering/run-test.sh index 553a0e9..ba91995 100755 --- a/superpowers/tests/skill-triggering/run-test.sh +++ b/superpowers/tests/skill-triggering/run-test.sh @@ -1,4 +1,4 @@ -#!/bin/bash +#!/usr/bin/env bash # Test skill triggering with naive prompts # Usage: ./run-test.sh # diff --git a/superpowers/tests/subagent-driven-dev/go-fractals/scaffold.sh b/superpowers/tests/subagent-driven-dev/go-fractals/scaffold.sh index d11ea74..646a615 100755 --- a/superpowers/tests/subagent-driven-dev/go-fractals/scaffold.sh +++ b/superpowers/tests/subagent-driven-dev/go-fractals/scaffold.sh @@ -1,4 +1,4 @@ -#!/bin/bash +#!/usr/bin/env bash # Scaffold the Go Fractals test project # Usage: ./scaffold.sh /path/to/target/directory diff --git a/superpowers/tests/subagent-driven-dev/run-test.sh b/superpowers/tests/subagent-driven-dev/run-test.sh index 02f4aca..807cb2d 100755 --- a/superpowers/tests/subagent-driven-dev/run-test.sh +++ b/superpowers/tests/subagent-driven-dev/run-test.sh @@ -1,4 +1,4 @@ -#!/bin/bash +#!/usr/bin/env bash # Run a subagent-driven-development test # Usage: ./run-test.sh [--plugin-dir ] # diff --git a/superpowers/tests/subagent-driven-dev/svelte-todo/scaffold.sh b/superpowers/tests/subagent-driven-dev/svelte-todo/scaffold.sh index f58129d..f7bef04 100755 --- a/superpowers/tests/subagent-driven-dev/svelte-todo/scaffold.sh +++ b/superpowers/tests/subagent-driven-dev/svelte-todo/scaffold.sh @@ -1,4 +1,4 @@ -#!/bin/bash +#!/usr/bin/env bash # Scaffold the Svelte Todo test project # Usage: ./scaffold.sh /path/to/target/directory