agy-superpowers 5.1.7 → 5.1.8

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agy-superpowers",
-  "version": "5.1.7",
+  "version": "5.1.8",
   "description": "Superpowers skills library for Google Antigravity agent — scaffold .agent/ with one command",
   "type": "module",
   "bin": {

package/template/agent/skills/brainstorming/SKILL.md

@@ -25,10 +25,9 @@ You MUST create a task for each of these items and complete them in order:
 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 2-3 approaches** — with trade-offs and your recommendation
-   - *UI/visual tasks only:* Before proposing, run `search.py` to gather style, typography, color, and UX data so proposals are grounded in real design patterns. See the [UI/UX Intelligence](#uiux-intelligence) section below.
 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 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)
+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
 
@@ -44,8 +43,7 @@ digraph brainstorming {
     "Present design sections" [shape=box];
     "User approves design?" [shape=diamond];
     "Write design doc" [shape=box];
-    "Spec review loop" [shape=box];
-    "Spec review passed?" [shape=diamond];
+    "Spec self-review\n(fix inline)" [shape=box];
     "User reviews spec?" [shape=diamond];
     "Invoke writing-plans skill" [shape=doublecircle];
 
@@ -58,10 +56,8 @@ digraph brainstorming {
     "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 review loop";
-    "Spec review loop" -> "Spec review passed?";
-    "Spec review passed?" -> "Spec review loop" [label="issues found,\nfix and re-dispatch"];
-    "Spec review passed?" -> "User reviews spec?" [label="approved"];
+    "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"];
 }
@@ -87,62 +83,6 @@ digraph brainstorming {
 - Present options conversationally with your recommendation and reasoning
 - Lead with your recommended option and explain why
 
-## UI/UX Intelligence
-
-**When the task involves any visual/UI work** (landing pages, dashboards, components, screens, design systems), run the UI/UX Pro Max search tool **before** presenting the design. This grounds your proposals in a curated knowledge base rather than generic defaults.
-
-**How to trigger:**
-
-```bash
-python3 .agent/.shared/ui-ux-pro-max/scripts/search.py "<keyword>" --domain <domain>
-```
-
-**Recommended search sequence** (run in parallel where possible):
-
-| # | Domain | What to search | Example |
-|---|--------|----------------|---------|
-| 1 | `product` | Product type + industry | `"SaaS dashboard"`, `"beauty landing page"` |
-| 2 | `style` | Desired visual style | `"glassmorphism dark"`, `"minimal clean"` |
-| 3 | `typography` | Mood/personality | `"elegant modern"`, `"playful friendly"` |
-| 4 | `color` | Industry or product type | `"fintech"`, `"healthcare"`, `"beauty spa"` |
-| 5 | `landing` | Page structure type | `"hero-centric social-proof"` |
-| 6 | `ux` | `"animation"`, `"accessibility"`, `"z-index"` | Always check these three |
-| 7 | `stack` | Target framework | `--stack react-native`, `--stack flutter` |
-
-**When to use each domain:**
-- Always run `product` + `style` + `ux` as a baseline for any UI task
-- Add `typography` + `color` when presenting a full design system
-- Add `landing` only for marketing/landing pages
-- Add `chart` only for analytics dashboards
-- Use `--stack` flag to get implementation-specific patterns (e.g., `--stack react-native` for mobile)
-
-**Synthesize results before presenting design:** Do not dump raw search output to the user. Summarize what you found and explain how it informs your design choices.
-
-> **Skip this step** for purely backend, data-model, or logic-only tasks where no UI is involved.
-
-### Mobile UI/UX Intelligence (Extended Layer)
-
-**When the request is for a mobile app** — detect keywords like: `iOS`, `Android`, `React Native`, `Flutter`, `SwiftUI`, `Jetpack Compose`, `mobile`, `app screen`, `native app` — run the **mobile-uiux-promax workflow** IN ADDITION to the web tool above.
-
-Read the workflow file first: `.agent/workflows/mobile-uiux-promax.md`
-
-The mobile workflow adds 3 more steps after the web style layer:
-
-```bash
-# Step 2: Mobile behavior
-python3 .agent/.shared/mobile-uiux-promax/scripts/mobile-search.py "<nav pattern>" --domain navigation
-python3 .agent/.shared/mobile-uiux-promax/scripts/mobile-search.py "<component>" --domain components
-python3 .agent/.shared/mobile-uiux-promax/scripts/mobile-search.py "<platform topic>" --domain platform
-python3 .agent/.shared/mobile-uiux-promax/scripts/mobile-search.py "<animation>" --domain animation
-
-# Step 3: Stack guidelines (react-native / flutter / swiftui / jetpack-compose)
-python3 .agent/.shared/mobile-uiux-promax/scripts/mobile-search.py "<topic>" --stack react-native
-
-# Step 4: Synthesize style + mobile behavior + stack patterns → present design
-```
-
-Read and apply the mobile-uiux-promax skill: `.agent/skills/mobile-uiux-promax/SKILL.md`
-
 **Presenting the design:**
 
 - Once you believe you understand what you're building, present the design
@@ -175,12 +115,15 @@ Read and apply the mobile-uiux-promax skill: `.agent/skills/mobile-uiux-promax/S
     - If `auto_commit: true` (default): run `git add <path> && git commit -m "docs: add <topic> design spec"`
     - If `auto_commit: false`: skip commit and staging entirely. Print: "Skipping commit (auto_commit: false in .agent/config.yml). File is ready for manual commit."
 
-**Spec Review Loop:**
-After writing the spec document:
+**Spec Self-Review:**
+After writing the spec document, look at it with fresh eyes:
+
+1. **Placeholder scan:** Any "TBD", "TODO", incomplete sections, or vague requirements? Fix them.
+2. **Internal consistency:** Do any sections contradict each other? Does the architecture match the feature descriptions?
+3. **Scope check:** Is this focused enough for a single implementation plan, or does it need decomposition?
+4. **Ambiguity check:** Could any requirement be interpreted two different ways? If so, pick one and make it explicit.
 
-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 3 iterations, surface to human for guidance
+Fix any issues inline. No need to re-review — just fix and move on.
 
 **User Review Gate:**
 After the spec review loop passes, ask the user to review the written spec before proceeding:

package/template/agent/skills/brainstorming/scripts/server.cjs

@@ -76,8 +76,10 @@ function decodeFrame(buffer) {
 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 OWNER_PID = process.env.BRAINSTORM_OWNER_PID ? Number(process.env.BRAINSTORM_OWNER_PID) : null;
+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',
@@ -112,10 +114,10 @@ function wrapInFrame(content) {
 }
 
 function getNewestScreen() {
-  const files = fs.readdirSync(SCREEN_DIR)
+  const files = fs.readdirSync(CONTENT_DIR)
     .filter(f => f.endsWith('.html'))
     .map(f => {
-      const fp = path.join(SCREEN_DIR, f);
+      const fp = path.join(CONTENT_DIR, f);
       return { path: fp, mtime: fs.statSync(fp).mtime.getTime() };
     })
     .sort((a, b) => b.mtime - a.mtime);
@@ -142,7 +144,7 @@ function handleRequest(req, res) {
     res.end(html);
   } else if (req.method === 'GET' && req.url.startsWith('/files/')) {
     const fileName = req.url.slice(7);
-    const filePath = path.join(SCREEN_DIR, path.basename(fileName));
+    const filePath = path.join(CONTENT_DIR, path.basename(fileName));
     if (!fs.existsSync(filePath)) {
       res.writeHead(404);
       res.end('Not found');
@@ -230,7 +232,7 @@ function handleMessage(text) {
   touchActivity();
   console.log(JSON.stringify({ source: 'user-event', ...event }));
   if (event.choice) {
-    const eventsFile = path.join(SCREEN_DIR, '.events');
+    const eventsFile = path.join(STATE_DIR, 'events');
     fs.appendFileSync(eventsFile, JSON.stringify(event) + '\n');
   }
 }
@@ -258,32 +260,33 @@ const debounceTimers = new Map();
 // ========== Server Startup ==========
 
 function startServer() {
-  if (!fs.existsSync(SCREEN_DIR)) fs.mkdirSync(SCREEN_DIR, { recursive: true });
+  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(SCREEN_DIR).filter(f => f.endsWith('.html'))
+    fs.readdirSync(CONTENT_DIR).filter(f => f.endsWith('.html'))
   );
 
   const server = http.createServer(handleRequest);
   server.on('upgrade', handleUpgrade);
 
-  const watcher = fs.watch(SCREEN_DIR, (eventType, filename) => {
+  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(SCREEN_DIR, 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(SCREEN_DIR, '.events');
+        const eventsFile = path.join(STATE_DIR, 'events');
         if (fs.existsSync(eventsFile)) fs.unlinkSync(eventsFile);
         console.log(JSON.stringify({ type: 'screen-added', file: filePath }));
       } else {
@@ -297,10 +300,10 @@ function startServer() {
 
   function shutdown(reason) {
     console.log(JSON.stringify({ type: 'server-stopped', reason }));
-    const infoFile = path.join(SCREEN_DIR, '.server-info');
+    const infoFile = path.join(STATE_DIR, 'server-info');
     if (fs.existsSync(infoFile)) fs.unlinkSync(infoFile);
     fs.writeFileSync(
-      path.join(SCREEN_DIR, '.server-stopped'),
+      path.join(STATE_DIR, 'server-stopped'),
       JSON.stringify({ reason, timestamp: Date.now() }) + '\n'
     );
     watcher.close();
@@ -309,8 +312,8 @@ function startServer() {
   }
 
   function ownerAlive() {
-    if (!OWNER_PID) return true;
-    try { process.kill(OWNER_PID, 0); return true; } catch (e) { return false; }
+    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
@@ -320,14 +323,27 @@ function startServer() {
   }, 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: SCREEN_DIR
+      screen_dir: CONTENT_DIR, state_dir: STATE_DIR
     });
     console.log(info);
-    fs.writeFileSync(path.join(SCREEN_DIR, '.server-info'), info + '\n');
+    fs.writeFileSync(path.join(STATE_DIR, 'server-info'), info + '\n');
   });
 }
 

package/template/agent/skills/brainstorming/scripts/start-server.sh

@@ -78,16 +78,17 @@ fi
 SESSION_ID="$$-$(date +%s)"
 
 if [[ -n "$PROJECT_DIR" ]]; then
-  SCREEN_DIR="${PROJECT_DIR}/.superpowers/brainstorm/${SESSION_ID}"
+  SESSION_DIR="${PROJECT_DIR}/.superpowers/brainstorm/${SESSION_ID}"
 else
-  SCREEN_DIR="/tmp/brainstorm-${SESSION_ID}"
+  SESSION_DIR="/tmp/brainstorm-${SESSION_ID}"
 fi
 
-PID_FILE="${SCREEN_DIR}/.server.pid"
-LOG_FILE="${SCREEN_DIR}/.server.log"
+STATE_DIR="${SESSION_DIR}/state"
+PID_FILE="${STATE_DIR}/server.pid"
+LOG_FILE="${STATE_DIR}/server.log"
 
-# Create fresh session directory
-mkdir -p "$SCREEN_DIR"
+# 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
@@ -106,22 +107,16 @@ if [[ -z "$OWNER_PID" || "$OWNER_PID" == "1" ]]; then
   OWNER_PID="$PPID"
 fi
 
-# On Windows/MSYS2, the MSYS2 PID namespace is invisible to Node.js.
-# Skip owner-PID monitoring — the 30-minute idle timeout prevents orphans.
-case "${OSTYPE:-}" in
-  msys*|cygwin*|mingw*) OWNER_PID="" ;;
-esac
-
 # Foreground mode for environments that reap detached/background processes.
 if [[ "$FOREGROUND" == "true" ]]; then
   echo "$$" > "$PID_FILE"
-  env BRAINSTORM_DIR="$SCREEN_DIR" BRAINSTORM_HOST="$BIND_HOST" BRAINSTORM_URL_HOST="$URL_HOST" BRAINSTORM_OWNER_PID="$OWNER_PID" node server.cjs
+  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="$SCREEN_DIR" BRAINSTORM_HOST="$BIND_HOST" BRAINSTORM_URL_HOST="$URL_HOST" BRAINSTORM_OWNER_PID="$OWNER_PID" node server.cjs > "$LOG_FILE" 2>&1 &
+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"

package/template/agent/skills/brainstorming/scripts/stop-server.sh

@@ -1,19 +1,20 @@
 #!/usr/bin/env bash
 # Stop the brainstorm server and clean up
-# Usage: stop-server.sh <screen_dir>
+# 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.
 
-SCREEN_DIR="$1"
+SESSION_DIR="$1"
 
-if [[ -z "$SCREEN_DIR" ]]; then
-  echo '{"error": "Usage: stop-server.sh <screen_dir>"}'
+if [[ -z "$SESSION_DIR" ]]; then
+  echo '{"error": "Usage: stop-server.sh <session_dir>"}'
   exit 1
 fi
 
-PID_FILE="${SCREEN_DIR}/.server.pid"
+STATE_DIR="${SESSION_DIR}/state"
+PID_FILE="${STATE_DIR}/server.pid"
 
 if [[ -f "$PID_FILE" ]]; then
   pid=$(cat "$PID_FILE")
@@ -42,11 +43,11 @@ if [[ -f "$PID_FILE" ]]; then
     exit 1
   fi
 
-  rm -f "$PID_FILE" "${SCREEN_DIR}/.server.log"
+  rm -f "$PID_FILE" "${STATE_DIR}/server.log"
 
   # Only delete ephemeral /tmp directories
-  if [[ "$SCREEN_DIR" == /tmp/* ]]; then
-    rm -rf "$SCREEN_DIR"
+  if [[ "$SESSION_DIR" == /tmp/* ]]; then
+    rm -rf "$SESSION_DIR"
   fi
 
   echo '{"status": "stopped"}'

package/template/agent/skills/brainstorming/visual-companion.md

@@ -26,7 +26,7 @@ A question *about* a UI topic is not automatically a visual question. "What kind
 
 ## How It Works
 
-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.
+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.
 
@@ -37,12 +37,13 @@ The server watches a directory for HTML files and serves the newest one to the b
 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"}
+#           "screen_dir":"/path/to/project/.superpowers/brainstorm/12345-1706000000/content",
+#           "state_dir":"/path/to/project/.superpowers/brainstorm/12345-1706000000/state"}
 ```
 
-Save `screen_dir` from the response. Tell user to open the URL.
+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 `$SCREEN_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.
+**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.
 
@@ -70,7 +71,7 @@ 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 `$SCREEN_DIR/.server-info` exists. If it doesn't (or `.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.
+   - 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)
@@ -82,9 +83,9 @@ Use `--url-host` to control what hostname is printed in the returned URL JSON.
    - 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
+   - 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; `.events` provides structured interaction data
+   - 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.
 
@@ -221,7 +222,7 @@ The frame template provides these CSS classes for your content:
 
 ## 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.
+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}
@@ -231,7 +232,7 @@ When the user clicks options in the browser, their interactions are recorded to
 
 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.
+If `$STATE_DIR/events` doesn't exist, the user didn't interact with the browser — use only their terminal text.
 
 ## Design Tips
 
@@ -252,7 +253,7 @@ If `.events` doesn't exist, the user didn't interact with the browser — use on
 ## Cleaning Up
 
 ```bash
-scripts/stop-server.sh $SCREEN_DIR
+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.

package/template/agent/skills/executing-plans/SKILL.md

@@ -16,6 +16,7 @@ Load plan, review critically, execute all tasks, report when complete.
 ## The Process
 
 ### Step 1: Load and Review Plan
+
 1. Read plan file
 2. Review critically - identify any questions or concerns about the plan
 3. If concerns: Raise them with your human partner before starting
@@ -24,6 +25,7 @@ Load plan, review critically, execute all tasks, report when complete.
 ### Step 2: Execute Tasks
 
 For each task:
+
 1. Mark as in_progress
 2. **Check for domain skills** — before writing any code, identify which domain skill applies to this task's context (e.g. `mobile-developer` for React Native work, `backend-developer` for API work, `frontend-developer` for web UI). Read only the relevant SKILL.md (not all references); load specific references on demand as the task requires them.
 3. Follow each step exactly (plan has bite-sized steps)
@@ -33,6 +35,7 @@ For each task:
 ### Step 3: Complete Development
 
 After all tasks complete and verified:
+
 - Announce: "I'm using the finishing-a-development-branch skill to complete this work."
 - **REQUIRED SUB-SKILL:** Use superpowers:finishing-a-development-branch
 - Follow that skill to verify tests, present options, execute choice
@@ -40,6 +43,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)
 - Plan has critical gaps preventing starting
 - You don't understand an instruction
@@ -50,12 +54,14 @@ After all tasks complete and verified:
 ## When to Revisit Earlier Steps
 
 **Return to Review (Step 1) when:**
+
 - Partner updates the plan based on your feedback
 - Fundamental approach needs rethinking
 
 **Don't force through blockers** - stop and ask.
 
 ## Remember
+
 - Review plan critically first
 - Follow plan steps exactly
 - Don't skip verifications
@@ -66,6 +72,7 @@ After all tasks complete and verified:
 ## 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

package/template/agent/skills/subagent-driven-development/implementer-prompt.md

@@ -28,7 +28,6 @@ Task tool (general-purpose):
 
     ## 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

package/template/agent/skills/systematic-debugging/SKILL.md

@@ -24,6 +24,7 @@ If you haven't completed Phase 1, you cannot propose fixes.
 ## When to Use
 
 Use for ANY technical issue:
+
 - Test failures
 - Bugs in production
 - Unexpected behavior
@@ -32,6 +33,7 @@ Use for ANY technical issue:
 - Integration issues
 
 **Use this ESPECIALLY when:**
+
 - Under time pressure (emergencies make guessing tempting)
 - "Just one quick fix" seems obvious
 - You've already tried multiple fixes
@@ -39,6 +41,7 @@ Use for ANY technical issue:
 - You don't fully understand the issue
 
 **Don't skip when:**
+
 - Issue seems simple (simple bugs have root causes too)
 - You're in a hurry (rushing guarantees rework)
 - Manager wants it fixed NOW (systematic is faster than thrashing)
@@ -74,6 +77,7 @@ You MUST complete each phase before proceeding to the next.
    **WHEN system has multiple components (CI → build → signing, API → service → database):**
 
    **BEFORE proposing fixes, add diagnostic instrumentation:**
+
    ```
    For EACH component boundary:
      - Log what data enters component
@@ -87,6 +91,7 @@ You MUST complete each phase before proceeding to the next.
    ```
 
    **Example (multi-layer system):**
+
    ```bash
    # Layer 1: Workflow
    echo "=== Secrets available in workflow: ==="
@@ -174,6 +179,7 @@ You MUST present your complete analysis to the user and get explicit confirmatio
 BEFORE proceeding to Phase 4 (Implementation).
 
 **Present a summary containing:**
+
 1. **Root Cause** — from Phase 1
 2. **Pattern Analysis** — key differences found in Phase 2
 3. **Hypothesis** — your confirmed theory from Phase 3
@@ -232,6 +238,7 @@ Wait for user confirmation. Do NOT proceed to Phase 4 until confirmed.
 ## Red Flags - STOP and Follow Process
 
 If you catch yourself thinking:
+
 - "Quick fix for now, investigate later"
 - "Just try changing X and see if it works"
 - "Add multiple changes, run tests"
@@ -251,6 +258,7 @@ If you catch yourself thinking:
 ## your human partner's Signals You're Doing It Wrong
 
 **Watch for these redirections:**
+
 - "Is that not happening?" - You assumed without verifying
 - "Will it show us...?" - You should have added evidence gathering
 - "Stop guessing" - You're proposing fixes without understanding
@@ -261,25 +269,25 @@ If you catch yourself thinking:
 
 ## Common Rationalizations
 
-| Excuse | Reality |
-|--------|---------|
-| "Issue is simple, don't need process" | Simple issues have root causes too. Process is fast for simple bugs. |
-| "Emergency, no time for process" | Systematic debugging is FASTER than guess-and-check thrashing. |
-| "Just try this first, then investigate" | First fix sets the pattern. Do it right from the start. |
-| "I'll write test after confirming fix works" | Untested fixes don't stick. Test first proves it. |
-| "Multiple fixes at once saves time" | Can't isolate what worked. Causes new bugs. |
-| "Reference too long, I'll adapt the pattern" | Partial understanding guarantees bugs. Read it completely. |
-| "I see the problem, let me fix it" | Seeing symptoms ≠ understanding root cause. |
-| "One more fix attempt" (after 2+ failures) | 3+ failures = architectural problem. Question pattern, don't fix again. |
+| Excuse                                       | Reality                                                                 |
+| -------------------------------------------- | ----------------------------------------------------------------------- |
+| "Issue is simple, don't need process"        | Simple issues have root causes too. Process is fast for simple bugs.    |
+| "Emergency, no time for process"             | Systematic debugging is FASTER than guess-and-check thrashing.          |
+| "Just try this first, then investigate"      | First fix sets the pattern. Do it right from the start.                 |
+| "I'll write test after confirming fix works" | Untested fixes don't stick. Test first proves it.                       |
+| "Multiple fixes at once saves time"          | Can't isolate what worked. Causes new bugs.                             |
+| "Reference too long, I'll adapt the pattern" | Partial understanding guarantees bugs. Read it completely.              |
+| "I see the problem, let me fix it"           | Seeing symptoms ≠ understanding root cause.                             |
+| "One more fix attempt" (after 2+ failures)   | 3+ failures = architectural problem. Question pattern, don't fix again. |
 
 ## Quick Reference
 
-| Phase | Key Activities | Success Criteria |
-|-------|---------------|------------------|
-| **1. Root Cause** | Read errors, reproduce, check changes, gather evidence | Understand WHAT and WHY |
-| **2. Pattern** | Find working examples, compare | Identify differences |
-| **3. Hypothesis** | Form theory, test minimally | Confirmed or new hypothesis |
-| **4. Implementation** | Create test, fix, verify | Bug resolved, tests pass |
+| Phase                 | Key Activities                                         | Success Criteria            |
+| --------------------- | ------------------------------------------------------ | --------------------------- |
+| **1. Root Cause**     | Read errors, reproduce, check changes, gather evidence | Understand WHAT and WHY     |
+| **2. Pattern**        | Find working examples, compare                         | Identify differences        |
+| **3. Hypothesis**     | Form theory, test minimally                            | Confirmed or new hypothesis |
+| **4. Implementation** | Create test, fix, verify                               | Bug resolved, tests pass    |
 
 ## When Process Reveals "No Root Cause"
 
@@ -301,12 +309,14 @@ These techniques are part of systematic debugging and available in this director
 - **`condition-based-waiting.md`** - Replace arbitrary timeouts with condition polling
 
 **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
 
 From debugging sessions:
+
 - Systematic approach: 15-30 minutes to fix
 - Random fixes approach: 2-3 hours of thrashing
 - First-time fix rate: 95% vs 40%

package/template/agent/skills/verification-before-completion/SKILL.md

@@ -99,17 +99,6 @@ Skip any step = lying, not verifying
 ❌ "Tests pass, phase complete"
 ```
 
-**`.agent/.tests/` check (if applicable):**
-
-If work involved modifying any `.agent/skills/<skill>/` or `.agent/.shared/<tool>/`, run tests before claiming done:
-```bash
-python3 .agent/.tests/run_tests.py <skill-name>
-```
-```
-✅ Run command → Paste full verbose output → All pass → Claim done
-❌ "Should still pass" / Skip running because "I didn't change the data"
-```
-
 **Agent delegation:**
 ```
 ✅ Agent reports success → Check VCS diff → Verify changes → Report actual state

package/template/agent/skills/writing-plans/SKILL.md

@@ -106,26 +106,33 @@ git commit -m "feat: add specific feature"
 - If `auto_commit: false`: skip commit and staging. Print: "Skipping commit (auto_commit: false)."
 ````
 
+## 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 plan (not "add validation")
+- Complete code in every step — if a step changes code, show the code
 - Exact commands with expected output
-- Reference relevant skills with @ syntax
 - DRY, YAGNI, TDD, frequent commits
 
-## Plan Review Loop
+## 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.
 
-After writing the complete plan:
+**2. Placeholder scan:** Search your plan for red flags — any of the patterns from the "No Placeholders" section above. Fix them.
 
-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
+**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.
 
-**Review loop guidance:**
-- Same agent that wrote the plan fixes it (preserves context)
-- If loop exceeds 3 iterations, surface to human for guidance
-- Reviewers are advisory — explain disagreements if you believe feedback is incorrect
+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
 

package/template/agent/skills/writing-skills/SKILL.md

@@ -93,7 +93,7 @@ skills/
 ## SKILL.md Structure
 
 **Frontmatter (YAML):**
-- Only two fields supported: `name` and `description`
+- Two required fields: `name` and `description` (see [agentskills.io/specification](https://agentskills.io/specification) for all supported fields)
 - 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)
@@ -604,7 +604,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 only name and description (max 1024 chars)
+- [ ] YAML frontmatter with required `name` and `description` fields (max 1024 chars; see [spec](https://agentskills.io/specification))
 - [ ] Description starts with "Use when..." and includes specific triggers/symptoms
 - [ ] Description written in third person
 - [ ] Keywords throughout for search (errors, symptoms, tools)

package/template/agent/superpowers-version.json

@@ -1,5 +1,5 @@
 {
-  "tag": "v5.0.5",
-  "updated_at": "2026-03-21T03:01:32Z",
+  "tag": "v5.0.6",
+  "updated_at": "2026-03-28T11:32:19Z",
   "source": "https://github.com/obra/superpowers"
 }

package/template/agent/workflows/brainstorm.md

@@ -1,20 +1,5 @@
 ---
-description: Start the brainstorming process before writing any code - uses superpowers brainstorming skill
+description: "Deprecated - use the superpowers:brainstorming skill instead"
 ---
 
-Read and follow the `brainstorming` skill completely:
-
-// turbo
-1. Read the skill: `view_file` `.agent/skills/brainstorming/SKILL.md`
-
-2. Explore current project context (files, docs, recent git log)
-
-3. Execute the full skill checklist in order:
-   - Offer visual companion if upcoming questions involve visuals
-   - Ask clarifying questions one at a time
-   - Propose 2-3 approaches with trade-offs and a recommendation
-   - Present design section by section, wait for approval after each
-   - Write design doc to `docs/superpowers/specs/YYYY-MM-DD-<topic>-design.md`
-   - Run spec review loop (dispatch spec-document-reviewer, fix issues, repeat max 3x)
-   - Ask user to review the written spec
-   - Transition to `writing-plans` skill
+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.

package/template/agent/workflows/execute-plan.md

@@ -1,25 +1,5 @@
 ---
-description: Execute an implementation plan task by task with TDD and code review - uses superpowers executing-plans skill
+description: "Deprecated - use the superpowers:executing-plans skill instead"
 ---
 
-Read and follow the `executing-plans` skill completely:
-
-// turbo
-1. Read the skill: `view_file` `.agent/skills/executing-plans/SKILL.md`
-
-// turbo
-2. Read the TDD skill: `view_file` `.agent/skills/test-driven-development/SKILL.md`
-
-3. Locate the plan in `docs/superpowers/plans/` or as specified by the user
-
-4. For each task in the plan:
-   a. Read the task spec carefully
-   b. Write a failing test first (RED) — run it, confirm it fails
-   c. Write the minimal code to make the test pass (GREEN) — run it, confirm it passes
-   d. Refactor if needed, keeping tests green (REFACTOR)
-   e. Commit with a clear, descriptive message
-
-5. After each batch of tasks, pause for a human checkpoint
-
-6. When all tasks are complete, read and follow the `verification-before-completion` skill:
-   `view_file` `.agent/skills/verification-before-completion/SKILL.md`
+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.

package/template/agent/workflows/write-plan.md

@@ -1,17 +1,5 @@
 ---
-description: Write a detailed implementation plan from an approved design - uses superpowers writing-plans skill
+description: "Deprecated - use the superpowers:writing-plans skill instead"
 ---
 
-Read and follow the `writing-plans` skill completely:
-
-// turbo
-1. Read the skill: `view_file` `.agent/skills/writing-plans/SKILL.md`
-
-2. Locate the most recent design doc in `docs/superpowers/specs/` as the foundation
-
-3. Execute the full skill process:
-   - Break the design into tasks of 2-5 minutes each
-   - Each task must include: exact file paths, complete code, and verification steps
-   - Save the plan to `docs/superpowers/plans/YYYY-MM-DD-<topic>-plan.md`
-   - Commit the plan to git
-   - Wait for user approval before execution begins
+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.