Merge dev-reorder10: Release v5.0.0

Executing-plans no longer pauses every 3 tasks for review. Also adds
a note encouraging users to use a subagent-capable platform for better
quality results.

.claude-plugin/marketplace.json

@@ -9,7 +9,7 @@
     {
       "name": "superpowers",
       "description": "Core skills library for Claude Code: TDD, debugging, collaboration patterns, and proven techniques",
-      "version": "4.3.0",
+      "version": "5.0.0",
       "source": "./",
       "author": {
         "name": "Jesse Vincent",

.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "superpowers",
   "description": "Core skills library for Claude Code: TDD, debugging, collaboration patterns, and proven techniques",
-  "version": "4.3.0",
+  "version": "5.0.0",
   "author": {
     "name": "Jesse Vincent",
     "email": "jesse@fsck.com"

.cursor-plugin/plugin.json

@@ -2,7 +2,7 @@
   "name": "superpowers",
   "displayName": "Superpowers",
   "description": "Core skills library: TDD, debugging, collaboration patterns, and proven techniques",
-  "version": "4.3.0",
+  "version": "4.3.1",
   "author": {
     "name": "Jesse Vincent",
     "email": "jesse@fsck.com"

.gitignore

@@ -1,6 +1,7 @@
 .worktrees/
 .private-journal/
 .claude/
+.DS_Store
 node_modules/
 inspo
 triage/

RELEASE-NOTES.md

@@ -1,93 +1,120 @@
 # Superpowers Release Notes
 
-## Unreleased
+## v5.0.0 (2026-03-09)
 
 ### Breaking Changes
 
 **Specs and plans directory restructured**
 
-- Specs (brainstorming output) now go to `docs/superpowers/specs/YYYY-MM-DD-<topic>-design.md`
-- Plans (writing-plans output) now go to `docs/superpowers/plans/YYYY-MM-DD-<feature-name>.md`
+- 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
 
-**Brainstorming → writing-plans transition enforced**
+**Subagent-driven development mandatory on capable harnesses**
 
-- After design approval, brainstorming now requires using writing-plans skill
-- Platform planning features (e.g., EnterPlanMode) should not be used
-- Direct implementation without writing-plans is not allowed
+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.
 
-**Subagent-driven development now mandatory on capable harnesses**
+**Executing-plans no longer batches**
 
-- On harnesses with subagent support (Claude Code), subagent-driven-development is now required after plan approval
-- No longer offers a choice between subagent-driven and executing-plans
-- Executing-plans is only used on harnesses without subagent capability
+Removed the "execute 3 tasks then stop for review" pattern. Plans now execute continuously, stopping only for blockers.
 
-**OpenCode: Switched to native skills system**
+**Slash commands deprecated**
 
-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
+`/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 companion for brainstorming skill**
+**Visual brainstorming companion**
 
-Added optional browser-based visual companion for brainstorming sessions. When users have a browser available, brainstorming can display interactive screens showing current phase, questions, and design decisions in a more readable format than terminal output.
+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.
 
-Components:
-- `lib/brainstorm-server/` - WebSocket server for real-time updates
-- `skills/brainstorming/visual-companion.md` - Integration guide
-- Helper scripts for session management with proper isolation
-- Browser helper library for event capture
+- `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/`
 
-The visual companion is opt-in and falls back gracefully to terminal-only operation.
+**Document review system**
 
-### Bug Fixes
+Automated review loops for spec and plan documents using subagent dispatch:
 
-**Fixed Windows hook execution for Claude Code 2.1.x**
+- `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/`
 
-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.
+**Architecture guidance across the skill pipeline**
 
-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).
+Design-for-isolation and file-size-awareness guidance added to brainstorming, writing-plans, and subagent-driven-development:
 
-**Brainstorming visual companion: reduced token cost and improved persistence**
+- **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
 
-The visual companion now generates much smaller HTML per screen. The server automatically wraps bare content fragments in the frame template (header, CSS theme, feedback footer, interactive JS), so Claude writes only the content portion (~30 lines instead of ~260). Full HTML documents are still served as-is when Claude needs complete control.
+**Subagent-driven development improvements**
 
-Other improvements:
-- `toggleSelect`/`send`/`selectedChoice` moved from inline template script to `helper.js` (auto-injected)
-- `start-server.sh --project-dir` persists mockups under `.superpowers/brainstorm/` instead of `/tmp`
-- `stop-server.sh` only deletes ephemeral `/tmp` sessions, preserving persistent ones
-- Dark mode fix: `sendToClaude` confirmation page now uses CSS variables instead of hardcoded colors
-- Skill restructured: SKILL.md is minimal (prompt + pointer); all visual companion details in progressive disclosure doc (`visual-companion.md`)
-- Prompt to user now notes the feature is new, token-intensive, and can be slow
-- Deleted redundant `CLAUDE-INSTRUCTIONS.md` (content folded into `visual-companion.md`)
-- Test fixes: correct env var (`BRAINSTORM_DIR`), polling-based startup wait, new tests for frame wrapping
+- **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 clarified in using-superpowers**
+**Instruction priority hierarchy**
 
-Added explicit instruction priority hierarchy to prevent conflicts with user preferences:
+Added explicit priority ordering to using-superpowers:
 
-1. User's explicit instructions (CLAUDE.md, direct requests) — highest priority
-2. Superpowers skills — override default system behavior where they conflict
+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
 
-This ensures users remain in control. If CLAUDE.md says "don't use TDD" and a skill says "always use TDD," CLAUDE.md wins.
+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)
 

commands/brainstorm.md

@@ -1,6 +1,5 @@
 ---
-description: "You MUST use this before any creative work - creating features, building components, adding functionality, or modifying behavior. Explores requirements and design before implementation."
-disable-model-invocation: true
+description: "Deprecated - use the superpowers:brainstorming skill instead"
 ---
 
-Invoke the superpowers:brainstorming skill and follow it exactly as presented to you
+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.

commands/execute-plan.md

@@ -1,6 +1,5 @@
 ---
-description: Execute plan in batches with review checkpoints
-disable-model-invocation: true
+description: "Deprecated - use the superpowers:executing-plans skill instead"
 ---
 
-Invoke the superpowers:executing-plans skill and follow it exactly as presented to you
+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.

commands/write-plan.md

@@ -1,6 +1,5 @@
 ---
-description: Create detailed implementation plan with bite-sized tasks
-disable-model-invocation: true
+description: "Deprecated - use the superpowers:writing-plans skill instead"
 ---
 
-Invoke the superpowers:writing-plans skill and follow it exactly as presented to you
+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.

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

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

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

@@ -1,6 +1,6 @@
 # Visual Brainstorming Companion Implementation Plan
 
-> **For Claude:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.
 
 **Goal:** Give Claude a browser-based visual companion for brainstorming sessions - show mockups, prototypes, and interactive choices alongside terminal conversation.
 

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

@@ -1,6 +1,6 @@
 # Document Review System Implementation Plan
 
-> **For Claude:** REQUIRED: Use superpowers:subagent-driven-development (if subagents available) or superpowers:executing-plans to implement this 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.
 
@@ -285,12 +285,12 @@ Run: `grep -A 20 "Plan Document Header" skills/writing-plans/SKILL.md`
 The plan header should note that tasks and steps use checkbox syntax. Update the header comment:
 
 ```markdown
-> **For Claude:** 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.
+> **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 Claude:" skills/writing-plans/SKILL.md`
+Run: `grep -A 5 "For agentic workers:" skills/writing-plans/SKILL.md`
 Expected: Shows updated header with checkbox syntax mention
 
 - [ ] **Step 4:** Commit

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

@@ -1,6 +1,6 @@
 # Visual Brainstorming Refactor Implementation Plan
 
-> **For Claude:** REQUIRED: Use superpowers:subagent-driven-development (if subagents available) or superpowers:executing-plans to implement this plan. Steps use checkbox (`- [ ]`) syntax for tracking.
+> **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.
 

hooks/hooks.json

@@ -6,7 +6,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "${CLAUDE_PLUGIN_ROOT}/hooks/run-hook.cmd session-start",
+            "command": "'${CLAUDE_PLUGIN_ROOT}/hooks/run-hook.cmd' session-start",
             "async": false
           }
         ]

hooks/run-hook.cmd

@@ -40,7 +40,7 @@ exit /b 0
 CMDBLOCK
 
 # Unix: run the named script directly
-SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]:-$0}")" && pwd)"
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
 SCRIPT_NAME="$1"
 shift
 exec bash "${SCRIPT_DIR}/${SCRIPT_NAME}" "$@"

lib/brainstorm-server/frame-template.html

@@ -1,7 +1,7 @@
 <!DOCTYPE html>
 <html>
 <head>
-  <title>Brainstorm Companion</title>
+  <title>Superpowers Brainstorming</title>
   <style>
     /*
      * BRAINSTORM COMPANION FRAME TEMPLATE
@@ -195,7 +195,7 @@
 </head>
 <body>
   <div class="header">
-    <h1>Brainstorm Companion</h1>
+    <h1><a href="https://github.com/obra/superpowers" style="color: inherit; text-decoration: none;">Superpowers Brainstorming</a></h1>
     <div class="status">Connected</div>
   </div>
 

skills/brainstorming/SKILL.md

@@ -1,76 +1,58 @@
 ---
 name: brainstorming
-description: "You MUST use this before any creative work - creating features, building components, adding functionality, or modifying behavior."
+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."
 ---
 
 # Brainstorming Ideas Into Designs
 
-## Overview
-
-Help turn ideas into fully formed designs and specs through natural collaborative dialogue. Scale your effort to the task — a link in a header needs a different process than a new subsystem — but always confirm you understand what the user wants before you build anything.
+Help turn ideas into fully formed designs and specs through natural collaborative dialogue.
 
 Start by understanding the current project context, then ask questions one at a time to refine the idea. Once you understand what you're building, present the design and get user approval.
 
 <HARD-GATE>
-Do NOT invoke any implementation skill, write any code, scaffold any project, or take any implementation action until:
-1. You have stated your understanding of the user's intent
-2. The user has confirmed that understanding
-
-This applies to every task regardless of size. The confirmation can be brief ("I'll add a GitHub icon-link to the header, styled to match the existing theme — sound right?"), but you must get it.
+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: Skipping Understanding
+## Anti-Pattern: "This Is Too Simple To Need A Design"
 
-The failure mode is not "too little ceremony." It is jumping to implementation with unchecked assumptions. Simple tasks are where this happens most — you assume you know what the user wants and start editing. Even when you're right about the *what*, you miss preferences about the *how*.
+Every project goes through this process. A todo list, a single-function utility, a config change — all of them. "Simple" projects are where unexamined assumptions cause the most wasted work. The design can be short (a few sentences for truly simple projects), but you MUST present it and get approval.
 
 ## Checklist
 
-Create tasks to track the steps you'll execute. For a small change, that might be steps 1–3 only. For a large project, all seven.
+You MUST create a task for each of these items and complete them in order:
 
 1. **Explore project context** — check files, docs, recent commits
 2. **Offer 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.
 3. **Ask clarifying questions** — one at a time, understand purpose/constraints/success criteria
-4. **Propose approaches** — with trade-offs and your recommendation
+4. **Propose 2-3 approaches** — with trade-offs and your recommendation
 5. **Present design** — in sections scaled to their complexity, get user approval after each section
 6. **Write design doc** — save to `docs/superpowers/specs/YYYY-MM-DD-<topic>-design.md` and commit
 7. **Transition to implementation** — invoke writing-plans skill to create implementation plan
 
-Steps 1–4 always happen. Steps 5–7 scale to the task. **GATE — when you believe a step can be safely elided, ask the user for permission.** Do not skip silently. For example: "This is straightforward — I don't think we need a design doc. Want me to go straight to planning?"
-
 ## Process Flow
 
 ```dot
 digraph brainstorming {
-    "Explore context" [shape=box];
-    "Visual questions?" [shape=diamond];
-    "Offer Visual Companion" [shape=box];
-    "Understand intent" [shape=box];
-    "User confirms understanding?" [shape=diamond];
-    "Propose approaches" [shape=box];
-    "Present design" [shape=box];
-    "User approves?" [shape=diamond];
-    "Design doc warranted?" [shape=diamond];
-    "Ask user permission\nto elide" [shape=box];
+    "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 review\n(when warranted)" [shape=box];
-    "Invoke writing-plans" [shape=doublecircle];
+    "Invoke writing-plans skill" [shape=doublecircle];
 
-    "Explore context" -> "Visual questions?";
-    "Visual questions?" -> "Offer Visual Companion" [label="yes"];
-    "Visual questions?" -> "Understand intent" [label="no"];
-    "Offer Visual Companion" -> "Understand intent";
-    "Understand intent" -> "User confirms understanding?";
-    "User confirms understanding?" -> "Understand intent" [label="no, refine"];
-    "User confirms understanding?" -> "Propose approaches" [label="yes"];
-    "Propose approaches" -> "Present design";
-    "Present design" -> "User approves?";
-    "User approves?" -> "Present design" [label="no, revise"];
-    "User approves?" -> "Design doc warranted?" [label="yes"];
-    "Design doc warranted?" -> "Write design doc" [label="yes"];
-    "Design doc warranted?" -> "Ask user permission\nto elide" [label="no — may be\noverkill"];
-    "Ask user permission\nto elide" -> "Invoke writing-plans";
-    "Write design doc" -> "Spec review\n(when warranted)";
-    "Spec review\n(when warranted)" -> "Invoke writing-plans";
+    "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" -> "Invoke writing-plans skill";
 }
 ```
 
@@ -102,31 +84,6 @@ digraph brainstorming {
 - Cover: architecture, components, data flow, error handling, testing
 - Be ready to go back and clarify if something doesn't make sense
 
-## After the Design
-
-**Documentation (when warranted):**
-
-- Write the validated design (spec) to `docs/superpowers/specs/YYYY-MM-DD-<topic>-design.md`
-  - (User preferences for spec location override this default)
-- Use elements-of-style:writing-clearly-and-concisely skill if available
-- Commit the design document to git
-- **GATE — for small changes, the design doc may be unnecessary.** Ask the user before skipping it.
-
-**Spec Review Loop (when warranted):**
-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
-
-**GATE — for small changes, the spec review may be unnecessary.** Ask the user before skipping it.
-
-**Implementation:**
-
-- Check in with the user before transitioning: "The design is ready. Want me to move on to writing the implementation plan?"
-- On confirmation, invoke the writing-plans skill
-- Do NOT invoke any other skill. writing-plans is the next step.
-
 **Design for isolation and clarity:**
 
 - Break the system into smaller units that each have one clear purpose, communicate through well-defined interfaces, and can be understood and tested independently
@@ -140,21 +97,42 @@ After writing the spec document:
 - Where existing code has problems that affect the work (e.g., a file that's grown too large, unclear boundaries, tangled responsibilities), include targeted improvements as part of the design - the way a good developer improves code they're working in.
 - Don't propose unrelated refactoring. Stay focused on what serves the current goal.
 
+## After the Design
+
+**Documentation:**
+
+- Write the validated design (spec) to `docs/superpowers/specs/YYYY-MM-DD-<topic>-design.md`
+  - (User preferences for spec location override this default)
+- Use elements-of-style:writing-clearly-and-concisely skill if available
+- Commit the design document to git
+
+**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, re-dispatch, repeat until Approved
+3. If loop exceeds 5 iterations, surface to human for guidance
+
+**Implementation:**
+
+- Invoke the writing-plans skill to create a detailed implementation plan
+- Do NOT invoke any other skill. writing-plans is the next step.
+
 ## Key Principles
 
-- **One question at a time** — don't overwhelm with multiple questions
-- **Multiple choice preferred** — easier to answer than open-ended when possible
-- **YAGNI ruthlessly** — remove unnecessary features from all designs
-- **Explore alternatives** — propose approaches before settling
-- **Incremental validation** — present, get approval, then move on
-- **Be flexible** — go back and clarify when something doesn't make sense
+- **One question at a time** - Don't overwhelm with multiple questions
+- **Multiple choice preferred** - Easier to answer than open-ended when possible
+- **YAGNI ruthlessly** - Remove unnecessary features from all designs
+- **Explore alternatives** - Always propose 2-3 approaches before settling
+- **Incremental validation** - Present design, get approval before moving on
+- **Be flexible** - Go back and clarify when something doesn't make sense
 
 ## Visual Companion
 
 A browser-based companion for showing mockups, diagrams, and visual options during brainstorming. Available as a tool — not a mode. Accepting the companion means it's available for questions that benefit from visual treatment; it does NOT mean every question goes through the browser.
 
 **Offering the companion:** When you anticipate that upcoming questions will involve visual content (mockups, layouts, diagrams), offer it once for consent:
-> "Some of the upcoming design questions would benefit from visual mockups. I can show those in a browser window so you can see and compare options visually. This feature is still new — it can be token-intensive and a bit slow, but it works well for layout and design questions. Want to try it? (Requires opening a local URL)"
+> "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.
 

skills/executing-plans/SKILL.md

@@ -7,12 +7,12 @@ description: Use when you have a written implementation plan to execute in a sep
 
 ## Overview
 
-Load plan, review critically, execute tasks in batches, report for review between batches.
-
-**Core principle:** Batch execution with checkpoints for architect review.
+Load plan, review critically, execute all tasks, report when complete.
 
 **Announce at start:** "I'm using the executing-plans skill to implement this plan."
 
+**Note:** Tell your human partner that Superpowers works much better with access to subagents. The quality of its work will be significantly higher if run on a platform with subagent support (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,8 +21,7 @@ Load plan, review critically, execute tasks in batches, report for review betwee
 3. If concerns: Raise them with your human partner before starting
 4. If no concerns: Create TodoWrite and proceed
 
-### Step 2: Execute Batch
-**Default: First 3 tasks**
+### Step 2: Execute Tasks
 
 For each task:
 1. Mark as in_progress
@@ -30,19 +29,7 @@ For each task:
 3. Run verifications as specified
 4. Mark as completed
 
-### Step 3: Report
-When batch complete:
-- Show what was implemented
-- Show verification output
-- Say: "Ready for feedback."
-
-### Step 4: Continue
-Based on feedback:
-- Apply changes if needed
-- Execute next batch
-- Repeat until complete
-
-### Step 5: Complete Development
+### Step 3: Complete Development
 
 After all tasks complete and verified:
 - Announce: "I'm using the finishing-a-development-branch skill to complete this work."
@@ -52,7 +39,7 @@ After all tasks complete and verified:
 ## When to Stop and Ask for Help
 
 **STOP executing immediately when:**
-- Hit a blocker mid-batch (missing dependency, test fails, instruction unclear)
+- Hit a blocker (missing dependency, test fails, instruction unclear)
 - Plan has critical gaps preventing starting
 - You don't understand an instruction
 - Verification fails repeatedly
@@ -72,7 +59,6 @@ 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
 

skills/subagent-driven-development/SKILL.md

@@ -7,8 +7,6 @@ description: Use when executing implementation plans with independent tasks in t
 
 Execute plan by dispatching fresh subagent per task, with two-stage review after each: spec compliance review first, then code quality review.
 
-Scale the review process to the task. A one-line config change doesn't need the same review rigor as a new subsystem. **GATE — when you believe review stages or the final reviewer can be safely collapsed or elided, ask the user for permission.** Do not elide silently, and do not replace a skipped review subagent with orchestrator judgment — the orchestrator never implements or reviews code.
-
 **Core principle:** Fresh subagent per task + two-stage review (spec then quality) = high quality, fast iteration
 
 ## When to Use
@@ -49,34 +47,26 @@ digraph process {
         "Implementer subagent asks questions?" [shape=diamond];
         "Answer questions, provide context" [shape=box];
         "Implementer subagent implements, tests, commits, self-reviews" [shape=box];
-        "Two-stage review warranted?" [shape=diamond];
-        "Ask user permission\nto elide or collapse 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 your task list" [shape=box];
+        "Mark task complete in TodoWrite" [shape=box];
     }
 
-    "Read plan, extract all tasks with full text, note context, create your task list" [shape=box];
+    "Read plan, extract all tasks with full text, note context, create TodoWrite" [shape=box];
     "More tasks remain?" [shape=diamond];
-    "Final reviewer warranted?" [shape=diamond];
-    "Ask user permission\nto elide final review" [shape=box];
     "Dispatch final code reviewer subagent for entire implementation" [shape=box];
-    "Check in with user\nbefore finishing" [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 your task list" -> "Dispatch implementer subagent (./implementer-prompt.md)";
+    "Read plan, extract all tasks with full text, note context, create TodoWrite" -> "Dispatch implementer subagent (./implementer-prompt.md)";
     "Dispatch implementer subagent (./implementer-prompt.md)" -> "Implementer subagent asks questions?";
     "Implementer subagent asks questions?" -> "Answer questions, provide context" [label="yes"];
     "Answer questions, provide context" -> "Dispatch implementer subagent (./implementer-prompt.md)";
     "Implementer subagent asks questions?" -> "Implementer subagent implements, tests, commits, self-reviews" [label="no"];
-    "Implementer subagent implements, tests, commits, self-reviews" -> "Two-stage review warranted?";
-    "Two-stage review warranted?" -> "Dispatch spec reviewer subagent (./spec-reviewer-prompt.md)" [label="yes"];
-    "Two-stage review warranted?" -> "Ask user permission\nto elide or collapse reviews" [label="no — may be\noverkill"];
-    "Ask user permission\nto elide or collapse reviews" -> "Mark task complete in your task list";
+    "Implementer subagent implements, tests, commits, self-reviews" -> "Dispatch spec reviewer subagent (./spec-reviewer-prompt.md)";
     "Dispatch spec reviewer subagent (./spec-reviewer-prompt.md)" -> "Spec reviewer subagent confirms code matches spec?";
     "Spec reviewer subagent confirms code matches spec?" -> "Implementer subagent fixes spec gaps" [label="no"];
     "Implementer subagent fixes spec gaps" -> "Dispatch spec reviewer subagent (./spec-reviewer-prompt.md)" [label="re-review"];
@@ -84,15 +74,11 @@ digraph process {
     "Dispatch code quality reviewer subagent (./code-quality-reviewer-prompt.md)" -> "Code quality reviewer subagent approves?";
     "Code quality reviewer subagent approves?" -> "Implementer subagent fixes quality issues" [label="no"];
     "Implementer subagent fixes quality issues" -> "Dispatch code quality reviewer subagent (./code-quality-reviewer-prompt.md)" [label="re-review"];
-    "Code quality reviewer subagent approves?" -> "Mark task complete in your task list" [label="yes"];
-    "Mark task complete in your task list" -> "More tasks remain?";
+    "Code quality reviewer subagent approves?" -> "Mark task complete in TodoWrite" [label="yes"];
+    "Mark task complete in TodoWrite" -> "More tasks remain?";
     "More tasks remain?" -> "Dispatch implementer subagent (./implementer-prompt.md)" [label="yes"];
-    "More tasks remain?" -> "Final reviewer warranted?" [label="no"];
-    "Final reviewer warranted?" -> "Dispatch final code reviewer subagent for entire implementation" [label="yes"];
-    "Final reviewer warranted?" -> "Ask user permission\nto elide final review" [label="no — may be\noverkill"];
-    "Ask user permission\nto elide final review" -> "Check in with user\nbefore finishing";
-    "Dispatch final code reviewer subagent for entire implementation" -> "Check in with user\nbefore finishing";
-    "Check in with user\nbefore finishing" -> "Use superpowers:finishing-a-development-branch";
+    "More tasks remain?" -> "Dispatch final code reviewer subagent for entire implementation" [label="no"];
+    "Dispatch final code reviewer subagent for entire implementation" -> "Use superpowers:finishing-a-development-branch";
 }
 ```
 
@@ -142,7 +128,7 @@ You: I'm using Subagent-Driven Development to execute this plan.
 
 [Read plan file once: docs/superpowers/plans/feature-plan.md]
 [Extract all 5 tasks with full text and context]
-[Create your task list with all tasks]
+[Create TodoWrite with all tasks]
 
 Task 1: Hook installation script
 
@@ -247,7 +233,7 @@ Done!
 
 **Never:**
 - Start implementation on main/master branch without explicit user consent
-- Skip any review without explicit user permission
+- Skip reviews (spec compliance OR code quality)
 - Proceed with unfixed issues
 - Dispatch multiple implementation subagents in parallel (conflicts)
 - Make subagent read plan file (provide full text instead)
@@ -272,7 +258,7 @@ Done!
 
 **If subagent fails task:**
 - Dispatch fix subagent with specific instructions
-- Don't try to fix manually — the orchestrator never implements or reviews code (context pollution)
+- Don't try to fix manually (context pollution)
 
 ## Integration
 

skills/using-superpowers/SKILL.md

@@ -19,11 +19,11 @@ This is not negotiable. This is not optional. You cannot rationalize your way ou
 
 Superpowers skills override default system prompt behavior, but **user instructions always take precedence**:
 
-1. **User's explicit instructions** (CLAUDE.md, direct requests) — highest priority
+1. **User's explicit instructions** (CLAUDE.md, AGENTS.md, direct requests) — highest priority
 2. **Superpowers skills** — override default system behavior where they conflict
 3. **Default system prompt** — lowest priority
 
-If CLAUDE.md says "don't use TDD" and a skill says "always use TDD," follow CLAUDE.md. The user is in control.
+If CLAUDE.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.
 
 ## How to Access Skills
 

skills/writing-plans/SKILL.md

@@ -7,8 +7,6 @@ description: Use when you have a spec or requirements for a multi-step task, bef
 
 ## Overview
 
-Scale the plan to the task. A one-file change doesn't need the same plan as a new subsystem. When you believe steps can be safely elided, ask the user for permission — don't elide silently, and don't follow the full process rigidly when it doesn't serve the work.
-
 Write comprehensive implementation plans assuming the engineer has zero context for our codebase and questionable taste. Document everything they need to know: which files to touch for each task, code, testing, docs they might need to check, how to test it. Give them the whole plan as bite-sized tasks. DRY. YAGNI. TDD. Frequent commits.
 
 Assume they are a skilled developer, but know almost nothing about our toolset or problem domain. Assume they don't know good test design very well.
@@ -51,7 +49,7 @@ This structure informs the task decomposition. Each task should produce self-con
 ```markdown
 # [Feature Name] Implementation Plan
 
-> **For Claude:** REQUIRED: Use superpowers:subagent-driven-development (if subagents available) or superpowers:executing-plans to implement this plan. Steps use checkbox (`- [ ]`) syntax for tracking.
+> **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:** [One sentence describing what this builds]
 
@@ -112,39 +110,8 @@ git commit -m "feat: add specific feature"
 - Reference relevant skills with @ syntax
 - DRY, YAGNI, TDD, frequent commits
 
-## Process Flow
-
-```dot
-digraph writing_plans {
-    rankdir=TB;
-    node [shape=box];
-
-    announce [label="Announce skill usage"];
-    scope [label="Scope check"];
-    file_structure [label="Map file structure"];
-    write_tasks [label="Write bite-sized tasks\n(header, task structure, code)"];
-    review_needed [label="Review loop warranted?" shape=diamond];
-    ask_user [label="Ask user permission\nto elide review loop" shape=box];
-    user_says [label="User approves\neliding?" shape=diamond];
-    review_loop [label="Dispatch plan-document-reviewer\nper chunk; fix until ✅"];
-    save_plan [label="Save plan to\ndocs/superpowers/plans/"];
-    handoff [label="Execution handoff:\n\"Ready to execute?\""];
-
-    announce -> scope -> file_structure -> write_tasks -> review_needed;
-    review_needed -> review_loop [label="yes"];
-    review_needed -> ask_user [label="no — may be\noverkill"];
-    ask_user -> user_says;
-    user_says -> review_loop [label="no, do the review"];
-    user_says -> save_plan [label="yes, elide it"];
-    review_loop -> save_plan;
-    save_plan -> handoff;
-}
-```
-
 ## Plan Review Loop
 
-**GATE — Do not elide without permission.** For small, single-file changes, the review loop may be unnecessary. If you believe it can be safely elided, you MUST ask the user before proceeding without it. Do not silently skip the review loop. Do not treat this as optional. Present your reasoning and wait for the user's answer.
-
 After completing each chunk of the plan:
 
 1. Dispatch plan-document-reviewer subagent (see plan-document-reviewer-prompt.md) for the current chunk
@@ -166,19 +133,15 @@ After completing each chunk of the plan:
 
 After saving the plan:
 
-**1. Record context.** Before anything else, verify all artifacts are saved and the plan is self-contained:
-- Spec document path (if one was written)
-- Plan document path
-- Key architectural decisions, constraints, or user preferences that affect implementation but aren't captured in the plan — add them to the plan now
+**"Plan complete and saved to `docs/superpowers/plans/<filename>.md`. Ready to execute?"**
 
-**2. Advise compaction.** Execution works better with a fresh window. Tell the user:
+**Execution path depends on harness capabilities:**
 
-> "The plan is saved to `docs/superpowers/plans/<filename>.md`. Before we start implementation, I recommend compacting this session — execution works better with a fresh window."
+**If harness has subagents (Claude Code, etc.):**
+- **REQUIRED:** Use superpowers:subagent-driven-development
+- Do NOT offer a choice - subagent-driven is the standard approach
+- Fresh subagent per task + two-stage review
 
-**3. Give exact continuation prompt.** Tell the user exactly what to say after compacting. Use the actual filename, not a placeholder.
-
-If you can dispatch subagents (Claude Code, etc.):
-
-> "After compacting, say: **Execute the plan at `docs/superpowers/plans/<filename>.md` using subagent-driven-development.**"
-
-If you cannot dispatch subagents, ask the user: "The plan is ready. I can't dispatch subagents in this environment — should I execute the tasks in this thread?"
+**If harness does NOT have subagents:**
+- Execute plan in current session using superpowers:executing-plans
+- Batch execution with checkpoints for review

skills/writing-skills/SKILL.md

@@ -306,7 +306,6 @@ digraph when_flowchart {
 - Non-obvious decision points
 - Process loops where you might stop too early
 - "When to use A vs B" decisions
-- **Behavioral gates** — decision diamonds in process flows act as enforcement mechanisms, not just documentation. Testing showed agents follow graphviz gates more reliably than prose instructions alone (writing-plans: 2/5 → 5/5 compliance after adding a process diagram with a gate diamond).
 
 **Never use flowcharts for:**
 - Reference material → Tables, lists
@@ -485,18 +484,6 @@ Write code before test? Delete it. Start over.
 ```
 </Good>
 
-### Use GATE Markers for Non-Optional Decision Points
-
-Label decision points that must not be silently bypassed with `**GATE —**` followed by the constraint:
-
-```markdown
-**GATE — Do not elide without permission.** If you believe
-the review loop can be safely skipped, you MUST ask the user
-before proceeding. Present your reasoning and wait for their answer.
-```
-
-Agents treat GATE-marked instructions as harder constraints than unmarked prose. Pair with a decision diamond in the process flow diagram for strongest effect.
-
 ### Address "Spirit vs Letter" Arguments
 
 Add foundational principle early: