superpowers-mcp 6.0.1 → 6.0.3

package/package.json

@@ -2,7 +2,7 @@
   "name": "superpowers-mcp",
   "displayName": "Superpowers MCP",
   "description": "Superpowers skills library (TDD, debugging, collaboration workflows) as an MCP server for VSCode and Antigravity",
-  "version": "6.0.1",
+  "version": "6.0.3",
   "publisher": "superpowers",
   "license": "MIT",
   "repository": {
@@ -29,6 +29,10 @@
     "out/server.js",
     "skills"
   ],
+  "overrides": {
+    "@hono/node-server": ">=2.0.5",
+    "fast-uri": ">=3.1.4"
+  },
   "scripts": {
     "build": "node esbuild.js --production",
     "watch": "node esbuild.js --watch",

package/skills/brainstorming/scripts/helper.js

@@ -57,6 +57,7 @@
     el.style.setProperty('--status-color', color);
   }
 
+  // Self-styled so it works on framed and full-document screens alike.
   function showTombstone() {
     if (tombstoneShown) return;
     tombstoneShown = true;
@@ -132,6 +133,7 @@
     }
   }
 
+  // Capture clicks on choice elements
   document.addEventListener('click', (e) => {
     const target = e.target.closest('[data-choice]');
     if (!target) return;
@@ -145,6 +147,7 @@
 
   });
 
+  // Frame UI: selection tracking
   window.selectedChoice = null;
 
   window.toggleSelect = function(el) {
@@ -161,6 +164,7 @@
     window.selectedChoice = el.dataset.choice;
   };
 
+  // Expose API for explicit use
   window.brainstorm = {
     send: sendEvent,
     choice: (value, metadata = {}) => sendEvent({ type: 'choice', value, ...metadata })

package/skills/brainstorming/scripts/server.cjs

@@ -62,6 +62,10 @@ function decodeFrame(buffer) {
     offset = 10;
   }
 
+  if (payloadLen > MAX_FRAME_PAYLOAD_BYTES) {
+    throw new Error('WebSocket frame payload exceeds maximum allowed size');
+  }
+
   const maskOffset = offset;
   const dataOffset = offset + 4;
   const totalLen = dataOffset + payloadLen;
@@ -227,9 +231,16 @@ function isTruthyEnv(value) {
   return !['0', 'false', 'no', 'off'].includes(normalized);
 }
 
+function escapeHtmlText(value) {
+  return String(value)
+    .replace(/&/g, '&')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;');
+}
+
 function brandMarkup() {
-  const escHtml = (v) => String(v).replace(/&/g,'&amp;').replace(/</g,'&lt;').replace(/>/g,'&gt;').replace(/"/g,'&quot;');
-  const version = escHtml(SUPERPOWERS_VERSION);
+  const version = escapeHtmlText(SUPERPOWERS_VERSION);
   const text = SUPERPOWERS_TELEMETRY_DISABLED
     ? 'Prime Radiant Superpowers v' + version
     : 'Superpowers v' + version;
@@ -296,6 +307,7 @@ function isRegularFileInsideContentDir(filePath) {
     stat = fs.lstatSync(filePath);
     if (stat.isSymbolicLink()) return false;
     if (!stat.isFile()) return false;
+    if (stat.nlink !== 1) return false;
     realContentDir = fs.realpathSync(CONTENT_DIR);
     realFilePath = fs.realpathSync(filePath);
   } catch (e) {
@@ -340,6 +352,17 @@ function isAuthorized(req) {
   return false;
 }
 
+function pathnameOf(url) {
+  const q = url.indexOf('?');
+  return q >= 0 ? url.slice(0, q) : url;
+}
+
+function queryKey(url) {
+  const q = url.indexOf('?');
+  if (q < 0) return null;
+  return new URLSearchParams(url.slice(q + 1)).get('key');
+}
+
 function securityHeaders(headers = {}) {
   return {
     'Referrer-Policy': 'no-referrer',
@@ -375,9 +398,8 @@ function handleRequest(req, res) {
   res.setHeader('Set-Cookie',
     COOKIE_NAME + '=' + TOKEN + '; HttpOnly; SameSite=Strict; Path=/');
 
-  const qIdx = req.url.indexOf('?');
-  const pathname = qIdx >= 0 ? req.url.slice(0, qIdx) : req.url;
-  const keyFromQuery = qIdx >= 0 ? new URLSearchParams(req.url.slice(qIdx + 1)).get('key') : null;
+  const pathname = pathnameOf(req.url);
+  const keyFromQuery = queryKey(req.url);
   if (req.method === 'GET' && pathname === '/' && keyFromQuery && timingSafeEqualStr(keyFromQuery, TOKEN)) {
     res.writeHead(200, securityHeaders({ 'Content-Type': 'text/html; charset=utf-8' }));
     res.end(bootstrapPage(TOKEN));
@@ -513,9 +535,10 @@ function maybeOpenBrowser() {
   if (clients.size > 0) return; // the user already opened it
   const url = companionUrl(); // must carry the key or the gate 403s it
   const cp = require('child_process');
-  // Operator-provided launcher: run as given (this env var is trusted operator input).
+  // Operator-provided launcher: run via execFile (no shell) so a malicious env var
+  // cannot inject commands through shell metacharacters.
   if (process.env.BRAINSTORM_OPEN_CMD) {
-    try { cp.exec(process.env.BRAINSTORM_OPEN_CMD + ' ' + JSON.stringify(url), () => {}); } catch (e) { /* best effort */ }
+    try { cp.execFile(process.env.BRAINSTORM_OPEN_CMD, [url], () => {}); } catch (e) { /* best effort */ }
     return;
   }
   // Platform launchers: pass the URL as an argv element via execFile (no shell),

package/skills/brainstorming/scripts/start-server.ps1

@@ -0,0 +1,232 @@
+#!/usr/bin/env pwsh
+# Start the brainstorm server and output connection info.
+# Usage: ./start-server.ps1 [--project-dir <path>] [--host <bind-host>] [--url-host <display-host>] [--foreground] [--background]
+
+$ErrorActionPreference = "Stop"
+
+function Write-JsonError {
+    param([string]$Message)
+    [pscustomobject]@{ error = $Message } | ConvertTo-Json -Compress
+}
+
+function New-ServerId {
+    $bytes = New-Object byte[] 24
+    $rng = [System.Security.Cryptography.RandomNumberGenerator]::Create()
+    try {
+        $rng.GetBytes($bytes)
+    } finally {
+        $rng.Dispose()
+    }
+    -join ($bytes | ForEach-Object { $_.ToString("x2") })
+}
+
+function Set-ProcessEnvironment {
+    param([hashtable]$Values)
+    foreach ($key in $Values.Keys) {
+        Set-Item -Path "Env:$key" -Value ([string]$Values[$key])
+    }
+}
+
+function Protect-PathForCurrentUser {
+    param([string]$Path)
+    if ([System.Environment]::OSVersion.Platform -ne [System.PlatformID]::Win32NT) {
+        return
+    }
+    try {
+        $item = Get-Item -LiteralPath $Path -ErrorAction Stop
+        $acl = Get-Acl -LiteralPath $item.FullName
+        $acl.SetAccessRuleProtection($true, $false)
+        $identity = [System.Security.Principal.WindowsIdentity]::GetCurrent().Name
+        $rights = [System.Security.AccessControl.FileSystemRights]::FullControl
+        if ($item.PSIsContainer) {
+            $inheritance = [System.Security.AccessControl.InheritanceFlags]"ContainerInherit,ObjectInherit"
+        } else {
+            $inheritance = [System.Security.AccessControl.InheritanceFlags]::None
+        }
+        $propagation = [System.Security.AccessControl.PropagationFlags]::None
+        $rule = [System.Security.AccessControl.FileSystemAccessRule]::new(
+            $identity,
+            $rights,
+            $inheritance,
+            $propagation,
+            [System.Security.AccessControl.AccessControlType]::Allow
+        )
+        $acl.SetAccessRule($rule)
+        Set-Acl -LiteralPath $item.FullName -AclObject $acl
+    } catch {
+        # Best-effort parity with the Unix helper's umask 077.
+    }
+}
+
+$scriptDir = Split-Path -Parent $PSCommandPath
+$projectDir = ""
+$foreground = $false
+$forceBackground = $false
+$bindHost = "127.0.0.1"
+$urlHost = ""
+$idleTimeoutMinutes = ""
+
+for ($i = 0; $i -lt $args.Count; $i++) {
+    switch ($args[$i]) {
+        "--project-dir" {
+            $i++
+            if ($i -ge $args.Count) { Write-JsonError "Missing value for --project-dir"; exit 1 }
+            $projectDir = $args[$i]
+        }
+        "--host" {
+            $i++
+            if ($i -ge $args.Count) { Write-JsonError "Missing value for --host"; exit 1 }
+            $bindHost = $args[$i]
+        }
+        "--url-host" {
+            $i++
+            if ($i -ge $args.Count) { Write-JsonError "Missing value for --url-host"; exit 1 }
+            $urlHost = $args[$i]
+        }
+        "--idle-timeout-minutes" {
+            $i++
+            if ($i -ge $args.Count) { Write-JsonError "Missing value for --idle-timeout-minutes"; exit 1 }
+            $idleTimeoutMinutes = $args[$i]
+        }
+        "--open" {
+            $env:BRAINSTORM_OPEN = "1"
+        }
+        { $_ -eq "--foreground" -or $_ -eq "--no-daemon" } {
+            $foreground = $true
+        }
+        { $_ -eq "--background" -or $_ -eq "--daemon" } {
+            $forceBackground = $true
+        }
+        default {
+            Write-JsonError "Unknown argument: $($args[$i])"
+            exit 1
+        }
+    }
+}
+
+if ($urlHost -eq "") {
+    if ($bindHost -eq "127.0.0.1" -or $bindHost -eq "localhost") {
+        $urlHost = "localhost"
+    } else {
+        $urlHost = $bindHost
+    }
+}
+
+if ($idleTimeoutMinutes -ne "") {
+    $parsedIdle = 0
+    if ((-not [int]::TryParse($idleTimeoutMinutes, [ref]$parsedIdle)) -or $parsedIdle -lt 1) {
+        Write-JsonError "--idle-timeout-minutes must be a positive integer"
+        exit 1
+    }
+    $env:BRAINSTORM_IDLE_TIMEOUT_MS = [string]($parsedIdle * 60 * 1000)
+}
+
+if ($env:CODEX_CI -and -not $foreground -and -not $forceBackground) {
+    $foreground = $true
+}
+
+$sessionId = "$PID-$([DateTimeOffset]::UtcNow.ToUnixTimeSeconds())"
+$brainstormRoot = ""
+if ($projectDir -ne "") {
+    $brainstormRoot = Join-Path $projectDir ".superpowers/brainstorm"
+    $sessionDir = Join-Path $brainstormRoot $sessionId
+    $env:BRAINSTORM_PORT_FILE = Join-Path $brainstormRoot ".last-port"
+    $env:BRAINSTORM_TOKEN_FILE = Join-Path $brainstormRoot ".last-token"
+} else {
+    $sessionDir = Join-Path ([System.IO.Path]::GetTempPath()) "brainstorm-$sessionId"
+}
+
+$stateDir = Join-Path $sessionDir "state"
+$contentDir = Join-Path $sessionDir "content"
+$pidFile = Join-Path $stateDir "server.pid"
+$logFile = Join-Path $stateDir "server.log"
+$serverIdFile = Join-Path $stateDir "server-instance-id"
+
+New-Item -ItemType Directory -Force -Path $contentDir, $stateDir | Out-Null
+if ($brainstormRoot -ne "") {
+    Protect-PathForCurrentUser -Path $brainstormRoot
+}
+Protect-PathForCurrentUser -Path $sessionDir
+Protect-PathForCurrentUser -Path $contentDir
+Protect-PathForCurrentUser -Path $stateDir
+
+$serverId = New-ServerId
+Set-Content -Path $serverIdFile -Value $serverId -NoNewline -Encoding utf8
+Protect-PathForCurrentUser -Path $serverIdFile
+
+if (Test-Path -LiteralPath $pidFile) {
+    $oldPid = (Get-Content -LiteralPath $pidFile -ErrorAction SilentlyContinue | Select-Object -First 1)
+    if ($oldPid) {
+        Stop-Process -Id ([int]$oldPid) -ErrorAction SilentlyContinue
+    }
+    Remove-Item -LiteralPath $pidFile -Force -ErrorAction SilentlyContinue
+}
+
+$envValues = @{
+    BRAINSTORM_DIR = $sessionDir
+    BRAINSTORM_HOST = $bindHost
+    BRAINSTORM_URL_HOST = $urlHost
+    BRAINSTORM_OWNER_PID = ""
+    BRAINSTORM_PORT_FILE = $env:BRAINSTORM_PORT_FILE
+    BRAINSTORM_TOKEN_FILE = $env:BRAINSTORM_TOKEN_FILE
+    BRAINSTORM_IDLE_TIMEOUT_MS = $env:BRAINSTORM_IDLE_TIMEOUT_MS
+    BRAINSTORM_OPEN = $env:BRAINSTORM_OPEN
+}
+
+if ($foreground) {
+    foreach ($key in $envValues.Keys) {
+        Set-Item -Path "Env:$key" -Value ([string]$envValues[$key])
+    }
+    $psi = [System.Diagnostics.ProcessStartInfo]::new()
+    $psi.FileName = "node"
+    $psi.WorkingDirectory = $scriptDir
+    $psi.UseShellExecute = $false
+    $psi.RedirectStandardOutput = $false
+    $psi.RedirectStandardError = $false
+    $psi.Arguments = "server.cjs --brainstorm-server-id=$serverId"
+    $process = [System.Diagnostics.Process]::new()
+    $process.StartInfo = $psi
+    $null = $process.Start()
+    Set-Content -Path $pidFile -Value ([string]$process.Id) -NoNewline -Encoding ascii
+    Protect-PathForCurrentUser -Path $pidFile
+    try {
+        $process.WaitForExit()
+        exit $process.ExitCode
+    } finally {
+        Remove-Item -LiteralPath $pidFile -Force -ErrorAction SilentlyContinue
+    }
+}
+
+Set-ProcessEnvironment -Values $envValues
+$errFile = Join-Path $stateDir "server.err"
+$process = Start-Process `
+    -FilePath "node" `
+    -ArgumentList @("server.cjs", "--brainstorm-server-id=$serverId") `
+    -WorkingDirectory $scriptDir `
+    -RedirectStandardOutput $logFile `
+    -RedirectStandardError $errFile `
+    -PassThru
+Set-Content -Path $pidFile -Value ([string]$process.Id) -NoNewline -Encoding ascii
+Protect-PathForCurrentUser -Path $pidFile
+
+$deadline = (Get-Date).AddSeconds(5)
+$reported = $false
+while ((Get-Date) -lt $deadline) {
+    if ($process.HasExited) {
+        Write-JsonError "Server exited before startup"
+        exit 1
+    }
+
+    Start-Sleep -Milliseconds 100
+    $infoFile = Join-Path $stateDir "server-info"
+    if (Test-Path -LiteralPath $infoFile) {
+        Get-Content -LiteralPath $infoFile | Select-Object -First 1
+        $reported = $true
+        break
+    }
+}
+
+if (-not $reported) {
+    Write-JsonError "Server failed to start within 5 seconds"
+    exit 1
+}

package/skills/brainstorming/scripts/stop-server.ps1

@@ -0,0 +1,84 @@
+#!/usr/bin/env pwsh
+# Stop the brainstorm server and clean up.
+# Usage: ./stop-server.ps1 <session_dir>
+
+$ErrorActionPreference = "Stop"
+
+if ($args.Count -ne 1) {
+    [pscustomobject]@{ error = "Usage: stop-server.ps1 <session_dir>" } | ConvertTo-Json -Compress
+    exit 1
+}
+
+$sessionDir = $args[0]
+$stateDir = Join-Path $sessionDir "state"
+$pidFile = Join-Path $stateDir "server.pid"
+$serverIdFile = Join-Path $stateDir "server-instance-id"
+
+function Mark-Stopped {
+    param([string]$Reason)
+    Remove-Item -LiteralPath (Join-Path $stateDir "server-info") -Force -ErrorAction SilentlyContinue
+    [pscustomobject]@{
+        reason = $Reason
+        timestamp = [DateTimeOffset]::UtcNow.ToUnixTimeSeconds()
+    } | ConvertTo-Json -Compress | Set-Content -Path (Join-Path $stateDir "server-stopped") -Encoding utf8
+}
+
+function Read-ExpectedServerId {
+    if (-not (Test-Path -LiteralPath $serverIdFile)) { return $null }
+    $id = (Get-Content -LiteralPath $serverIdFile -Raw).Trim()
+    if ($id -match '^[A-Za-z0-9_-]{32,64}$') { return $id }
+    return $null
+}
+
+function Test-BrainstormServer {
+    param([int]$ProcessId)
+    $expected = Read-ExpectedServerId
+    if (-not $expected) { return $false }
+    $process = Get-CimInstance Win32_Process -Filter "ProcessId = $ProcessId" -ErrorAction SilentlyContinue
+    if (-not $process) { return $false }
+    return ($process.CommandLine -like "*--brainstorm-server-id=$expected*")
+}
+
+if (Test-Path -LiteralPath $pidFile) {
+    $pidText = (Get-Content -LiteralPath $pidFile -ErrorAction SilentlyContinue | Select-Object -First 1)
+    $serverPid = 0
+    if ((-not [int]::TryParse($pidText, [ref]$serverPid)) -or -not (Test-BrainstormServer -ProcessId $serverPid)) {
+        Remove-Item -LiteralPath $pidFile, $serverIdFile -Force -ErrorAction SilentlyContinue
+        Mark-Stopped "stale_pid"
+        [pscustomobject]@{ status = "stale_pid" } | ConvertTo-Json -Compress
+        exit 0
+    }
+
+    Stop-Process -Id $serverPid -ErrorAction SilentlyContinue
+    $deadline = (Get-Date).AddSeconds(2)
+    while ((Get-Date) -lt $deadline -and (Get-Process -Id $serverPid -ErrorAction SilentlyContinue)) {
+        Start-Sleep -Milliseconds 100
+    }
+    if (Get-Process -Id $serverPid -ErrorAction SilentlyContinue) {
+        Stop-Process -Id $serverPid -Force -ErrorAction SilentlyContinue
+        Start-Sleep -Milliseconds 100
+    }
+    if (Get-Process -Id $serverPid -ErrorAction SilentlyContinue) {
+        [pscustomobject]@{ status = "failed"; error = "process still running" } | ConvertTo-Json -Compress
+        exit 1
+    }
+
+    Remove-Item -LiteralPath $pidFile, $serverIdFile, (Join-Path $stateDir "server.log") -Force -ErrorAction SilentlyContinue
+    Mark-Stopped "stop-server.ps1"
+
+    $tempRoot = [System.IO.Path]::GetFullPath([System.IO.Path]::GetTempPath())
+    if (-not $tempRoot.EndsWith([string][System.IO.Path]::DirectorySeparatorChar)) {
+        $tempRoot += [System.IO.Path]::DirectorySeparatorChar
+    }
+    $resolvedSession = (Resolve-Path -LiteralPath $sessionDir -ErrorAction SilentlyContinue).Path
+    if ($resolvedSession) {
+        $resolvedSession = [System.IO.Path]::GetFullPath($resolvedSession)
+    }
+    if ($resolvedSession -and $resolvedSession.StartsWith($tempRoot, [System.StringComparison]::OrdinalIgnoreCase)) {
+        Remove-Item -LiteralPath $sessionDir -Recurse -Force -ErrorAction SilentlyContinue
+    }
+
+    [pscustomobject]@{ status = "stopped" } | ConvertTo-Json -Compress
+} else {
+    [pscustomobject]@{ status = "not_running" } | ConvertTo-Json -Compress
+}

package/skills/brainstorming/visual-companion.md

@@ -37,6 +37,9 @@ The server watches a directory for HTML files and serves the newest one to the b
 # the first screen; --project-dir persists mockups and enables same-port restart.
 scripts/start-server.sh --project-dir /path/to/project --open
 
+# Windows PowerShell:
+scripts/start-server.ps1 --project-dir C:\path\to\project --open
+
 # Returns: {"type":"server-started","port":52341,
 #           "url":"http://localhost:52341/?key=ab12…",
 #           "screen_dir":"/path/to/project/.superpowers/brainstorm/12345-1706000000/content",
@@ -67,6 +70,8 @@ scripts/start-server.sh --project-dir /path/to/project --open
 
 On Windows, the script auto-detects and switches to foreground mode (which blocks the tool call). Use `run_in_background: true` on the Bash tool call so the server survives across conversation turns, then read `$STATE_DIR/server-info` on the next turn to get the URL and port.
 
+For native PowerShell, use `scripts/start-server.ps1` with the same flags. It writes the same `server-info` file and supports `--project-dir`, `--host`, `--url-host`, `--idle-timeout-minutes`, `--open`, `--foreground`, and `--background`.
+
 **Codex:**
 ```bash
 # Codex reaps background processes. The script auto-detects CODEX_CI and
@@ -281,6 +286,9 @@ If `$STATE_DIR/events` doesn't exist, the user didn't interact with the browser
 
 ```bash
 scripts/stop-server.sh $SESSION_DIR
+
+# Windows PowerShell:
+scripts/stop-server.ps1 $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/skills/finishing-a-development-branch/SKILL.md

@@ -44,6 +44,9 @@ Stop. Don't proceed to Step 2.
 ```bash
 GIT_DIR=$(cd "$(git rev-parse --git-dir)" 2>/dev/null && pwd -P)
 GIT_COMMON=$(cd "$(git rev-parse --git-common-dir)" 2>/dev/null && pwd -P)
+# Capture now, while still inside the workspace — Step 5 changes directory
+# before cleanup (Step 6) needs this value
+WORKTREE_PATH=$(git rev-parse --show-toplevel)
 ```
 
 This determines which menu to show and how cleanup works:
@@ -123,6 +126,8 @@ git branch -d <feature-branch>
 ```bash
 # Push branch
 git push -u origin <feature-branch>
+# From a detached HEAD, name the new branch on the remote:
+# git push origin HEAD:refs/heads/<new-branch>
 ```
 
 **Do NOT clean up worktree** — user needs it alive to iterate on PR feedback.
@@ -160,21 +165,17 @@ git branch -D <feature-branch>
 
 ### Step 6: Cleanup Workspace
 
-**Only runs for Options 1 and 4.** Options 2 and 3 always preserve the worktree.
-
-```bash
-GIT_DIR=$(cd "$(git rev-parse --git-dir)" 2>/dev/null && pwd -P)
-GIT_COMMON=$(cd "$(git rev-parse --git-common-dir)" 2>/dev/null && pwd -P)
-WORKTREE_PATH=$(git rev-parse --show-toplevel)
-```
+**Only runs for Options 1 and 4.** Options 2 and 3 always preserve the worktree. Both callers have already changed directory to the
+main repo root — worktree removal must run from outside the worktree —
+and use the `GIT_DIR`/`GIT_COMMON`/`WORKTREE_PATH` values captured in
+Step 2, from before that directory change.
 
 **If `GIT_DIR == GIT_COMMON`:** Normal repo, no worktree to clean up. Done.
 
-**If worktree path is under `.worktrees/` or `worktrees/`:** Superpowers created this worktree — we own cleanup.
+**If `WORKTREE_PATH` is under `.worktrees/` or `worktrees/`:** Superpowers
+created this worktree — we own cleanup:
 
 ```bash
-MAIN_ROOT=$(git -C "$(git rev-parse --git-common-dir)/.." rev-parse --show-toplevel)
-cd "$MAIN_ROOT"
 git worktree remove "$WORKTREE_PATH"
 git worktree prune  # Self-healing: clean up any stale registrations
 ```

package/skills/subagent-driven-development/SKILL.md

@@ -133,7 +133,7 @@ that implementer. Single-file mechanical fixes also take the cheapest tier.
 
 Implementer subagents report one of four statuses. Handle each appropriately:
 
-**DONE:** Generate the review package (`scripts/review-package BASE HEAD`, from this skill's directory — it prints the unique file path it wrote; BASE is the commit you recorded before dispatching the implementer — never `HEAD~1`, which silently drops all but the last commit of a multi-commit task), then dispatch the task reviewer with the printed path.
+**DONE:** Generate the review package (`scripts/review-package BASE HEAD`, or `scripts/review-package.ps1 BASE HEAD` on Windows PowerShell, from this skill's directory — it prints the unique file path it wrote; BASE is the commit you recorded before dispatching the implementer — never `HEAD~1`, which silently drops all but the last commit of a multi-commit task), then dispatch the task reviewer with the printed path.
 
 **DONE_WITH_CONCERNS:** The implementer completed the work but flagged doubts. Read the concerns before proceeding. If the concerns are about correctness or scope, address them before review. If they're observations (e.g., "this file is getting large"), note them and proceed to review.
 
@@ -179,7 +179,7 @@ final whole-branch review. When you fill a reviewer template:
   test hygiene, review method) — the constraints block is for what THIS
   project's spec demands.
 - Hand the reviewer its diff as a file: run this skill's
-  `scripts/review-package BASE HEAD` and pass the reviewer the file path
+  `scripts/review-package BASE HEAD` (or `scripts/review-package.ps1 BASE HEAD` on Windows PowerShell) and pass the reviewer the file path
   it prints (or, without bash: `git log --oneline`, `git diff --stat`,
   and `git diff -U10` for the range, redirected to one uniquely named
   file). The output never enters your own context, and the reviewer sees
@@ -194,14 +194,14 @@ final whole-branch review. When you fill a reviewer template:
 - Dispatch fix subagents for Critical and Important findings. Record Minor
   findings in the progress ledger as you go, and point the final
   whole-branch review at that list so it can triage which must be fixed
-  before merge.
+  before merge. A roll-up nobody reads is a silent discard.
 - A finding labeled plan-mandated — or any finding that conflicts with
   what the plan's text requires — is the human's decision, like any plan
   contradiction: present the finding and the plan text, ask which governs.
   Do not dismiss the finding because the plan mandates it, and do not
   dispatch a fix that contradicts the plan without asking.
 - The final whole-branch review gets a package too: run
-  `scripts/review-package MERGE_BASE HEAD` (MERGE_BASE = the commit the
+  `scripts/review-package MERGE_BASE HEAD` (or `scripts/review-package.ps1 MERGE_BASE HEAD` on Windows PowerShell; MERGE_BASE = the commit the
   branch started from, e.g. `git merge-base main HEAD`) and include the
   printed path in the final review dispatch, so the final reviewer reads
   one file instead of re-deriving the branch diff with git commands.
@@ -223,7 +223,7 @@ prints back — stays resident in your context for the rest of the session
 and is re-read on every later turn. Hand artifacts over as files:
 
 - **Task brief:** before dispatching an implementer, run this skill's
-  `scripts/task-brief PLAN_FILE N` — it extracts the task's full text to a
+  `scripts/task-brief PLAN_FILE N` (or `scripts/task-brief.ps1 PLAN_FILE N` on Windows PowerShell) — it extracts the task's full text to a
   uniquely named file and prints the path. Compose the dispatch so the
   brief stays the single source of requirements. Your dispatch should
   contain: (1) one line on where this task fits in the project; (2) the
@@ -372,7 +372,7 @@ Done!
 - Proceed with unfixed issues
 - Dispatch multiple implementation subagents in parallel (conflicts)
 - Make a subagent read the whole plan file (hand it its task brief —
-  `scripts/task-brief` — instead)
+  `scripts/task-brief` / `scripts/task-brief.ps1` — instead)
 - Skip scene-setting context (subagent needs to understand where task fits)
 - Ignore subagent questions (answer before letting them proceed)
 - Accept "close enough" on spec compliance (reviewer found spec issues = not done)
@@ -382,7 +382,7 @@ Done!
   dispatch prompt ("treat it as Minor at most") — the plan's example code is
   a starting point, not evidence that its weaknesses were chosen
 - Dispatch a task reviewer without a diff file — generate it first
-  (`scripts/review-package BASE HEAD`) and name the printed path in the
+  (`scripts/review-package BASE HEAD`, or `scripts/review-package.ps1 BASE HEAD` on Windows PowerShell) and name the printed path in the
   prompt
 - Move to next task while the review has open Critical/Important issues
 - Re-dispatch a task the progress ledger already marks complete — check

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

@@ -23,7 +23,7 @@ git rev-parse --verify --quiet "$head" >/dev/null || { echo "bad HEAD: $head" >&
 if [ $# -eq 3 ]; then
   out=$3
 else
-  dir=$("$(dirname "$0")"/sdd-workspace)
+  dir=$("$(cd "$(dirname "$0")" && pwd)/sdd-workspace")
   out="$dir/review-$(git rev-parse --short "$base")..$(git rev-parse --short "$head").diff"
 fi
 

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

@@ -0,0 +1,52 @@
+#!/usr/bin/env pwsh
+# Generate a review package: commit list, stat summary, and net diff.
+# Usage: ./review-package.ps1 BASE HEAD [OUTFILE]
+
+$ErrorActionPreference = "Stop"
+
+if ($args.Count -lt 2 -or $args.Count -gt 3) {
+    Write-Error "usage: review-package.ps1 BASE HEAD [OUTFILE]"
+    exit 2
+}
+
+$base = $args[0]
+$head = $args[1]
+
+& git rev-parse --verify --quiet $base *> $null
+if ($LASTEXITCODE -ne 0) {
+    Write-Error "bad BASE: $base"
+    exit 2
+}
+
+& git rev-parse --verify --quiet $head *> $null
+if ($LASTEXITCODE -ne 0) {
+    Write-Error "bad HEAD: $head"
+    exit 2
+}
+
+if ($args.Count -eq 3) {
+    $out = $args[2]
+} else {
+    $scriptDir = Split-Path -Parent $PSCommandPath
+    $dir = (& (Join-Path $scriptDir "sdd-workspace.ps1")).Trim()
+    $baseShort = (& git rev-parse --short $base).Trim()
+    $headShort = (& git rev-parse --short $head).Trim()
+    $out = Join-Path $dir "review-$baseShort..$headShort.diff"
+}
+
+$content = New-Object System.Collections.Generic.List[string]
+$content.Add("# Review package: ${base}..${head}")
+$content.Add("")
+$content.Add("## Commits")
+(& git log --oneline "${base}..${head}") | ForEach-Object { $content.Add($_) }
+$content.Add("")
+$content.Add("## Files changed")
+(& git diff --stat "${base}..${head}") | ForEach-Object { $content.Add($_) }
+$content.Add("")
+$content.Add("## Diff")
+(& git diff -U10 "${base}..${head}") | ForEach-Object { $content.Add($_) }
+
+Set-Content -Path $out -Value $content -Encoding utf8
+$commits = (& git rev-list --count "${base}..${head}").Trim()
+$bytes = (Get-Item -LiteralPath $out).Length
+Write-Output "wrote ${out}: $commits commit(s), $bytes bytes"

package/skills/subagent-driven-development/scripts/sdd-workspace.ps1

@@ -0,0 +1,11 @@
+#!/usr/bin/env pwsh
+# Resolve and ensure the working-tree directory SDD uses for short-lived artifacts.
+# Usage: ./sdd-workspace.ps1
+
+$ErrorActionPreference = "Stop"
+
+$root = (& git rev-parse --show-toplevel).Trim()
+$dir = Join-Path $root ".superpowers/sdd"
+New-Item -ItemType Directory -Force -Path $dir | Out-Null
+Set-Content -Path (Join-Path $dir ".gitignore") -Value "*" -NoNewline -Encoding ascii
+(Resolve-Path $dir).Path