fix(writing-skills): correct false 'only two fields' frontmatter claim (#882)

8 tasks covering: environment detection in using-git-worktrees,
Step 1.5 + cleanup guard in finishing-a-development-branch,
Integration line updates, codex-tools.md docs, automated tests,
and final verification.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

.claude-plugin/marketplace.json

@@ -9,7 +9,7 @@
     {
       "name": "superpowers",
       "description": "Core skills library for Claude Code: TDD, debugging, collaboration patterns, and proven techniques",
-      "version": "5.0.4",
+      "version": "5.0.5",
       "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": "5.0.4",
+  "version": "5.0.5",
   "author": {
     "name": "Jesse Vincent",
     "email": "jesse@fsck.com"

CHANGELOG.md

@@ -1,20 +1,13 @@
 # Changelog
 
-## Unreleased
+## [5.0.5] - 2026-03-17
 
 ### Fixed
 
-- **Brainstorm server on Windows**: Auto-detect Windows/Git Bash (`OSTYPE=msys*`, `MSYSTEM`) and switch to foreground mode, fixing silent server failure caused by `nohup`/`disown` process reaping. Applies to all Windows shells (CMD, PowerShell, Git Bash) since they all route through Git Bash. ([#737](https://github.com/obra/superpowers/issues/737), based on [#740](https://github.com/obra/superpowers/pull/740))
-- **Portable shebangs**: Replace `#!/bin/bash` with `#!/usr/bin/env bash` in all 13 shell scripts. Fixes execution on NixOS, FreeBSD, and macOS with Homebrew bash where `/bin/bash` is outdated or missing. ([#700](https://github.com/obra/superpowers/pull/700), dupes: [#747](https://github.com/obra/superpowers/pull/747))
-- **POSIX-safe hook script**: Replace `${BASH_SOURCE[0]:-$0}` with `$0` in `hooks/session-start` and polyglot-hooks docs. Fixes 'Bad substitution' error on Ubuntu/Debian where `/bin/sh` is dash. ([#553](https://github.com/obra/superpowers/pull/553))
-- **Bash 5.3+ hook hang**: Replace heredoc (`cat <<EOF`) with `printf` in `hooks/session-start`. Fixes indefinite hang on macOS with Homebrew bash 5.3+ caused by a bash regression with large variable expansion in heredocs. ([#572](https://github.com/obra/superpowers/pull/572), [#571](https://github.com/obra/superpowers/issues/571))
-- **Cursor hooks support**: Add `hooks/hooks-cursor.json` with Cursor's camelCase format (`sessionStart`, `version: 1`) and update `.cursor-plugin/plugin.json` to reference it. Fix platform detection in `session-start` to check `CURSOR_PLUGIN_ROOT` first (Cursor may also set `CLAUDE_PLUGIN_ROOT`). (Based on [#709](https://github.com/obra/superpowers/pull/709))
+- **Brainstorm server ESM fix**: Renamed `server.js` → `server.cjs` so the brainstorming server starts correctly on Node.js 22+ where the root `package.json` `"type": "module"` caused `require()` to fail. ([PR #784](https://github.com/obra/superpowers/pull/784) by @sarbojitrana, fixes [#774](https://github.com/obra/superpowers/issues/774), [#780](https://github.com/obra/superpowers/issues/780), [#783](https://github.com/obra/superpowers/issues/783))
+- **Brainstorm owner-PID on Windows**: Skip `BRAINSTORM_OWNER_PID` lifecycle monitoring on Windows/MSYS2 where the PID namespace is invisible to Node.js. Prevents the server from self-terminating after 60 seconds. The 30-minute idle timeout remains as the safety net. ([#770](https://github.com/obra/superpowers/issues/770), docs from [PR #768](https://github.com/obra/superpowers/pull/768) by @lucasyhzhu-debug)
+- **stop-server.sh reliability**: Verify the server process actually died before reporting success. Waits up to 2 seconds for graceful shutdown, escalates to `SIGKILL`, and reports failure if the process survives. ([#723](https://github.com/obra/superpowers/issues/723))
 
-### Already fixed on dev (closed PRs)
+### Changed
 
-- **Windows hook quoting** ([#630](https://github.com/obra/superpowers/pull/630), [#529](https://github.com/obra/superpowers/issues/529)): `hooks.json` already uses escaped double quotes on dev.
-- **Windows symlink path** ([#539](https://github.com/obra/superpowers/pull/539)): Closed — the PR introduced a bug (literal `~` in path alongside `$env:USERPROFILE`). Current docs are correct.
-
-### Known Issues
-
-- **`BRAINSTORM_OWNER_PID` on Windows (main branch only)**: The main branch's `server.js` uses `process.kill(OWNER_PID, 0)` for lifecycle checks, but receives MSYS2 PIDs which are invisible to Node.js (different PID namespace). This causes the server to self-terminate after 60 seconds. Fix: resolve `OWNER_PID` via `/proc/$PPID/winpid` to get the Windows-native PID. The dev branch's `index.js` does not have this issue since it has no OWNER_PID lifecycle check.
+- **Execution handoff**: Restore user choice between subagent-driven-development and executing-plans after plan writing. Subagent-driven is recommended but no longer mandatory. (Reverts `5e51c3e`)

RELEASE-NOTES.md

@@ -1,5 +1,17 @@
 # Superpowers Release Notes
 
+## v5.0.5 (2026-03-17)
+
+### Bug Fixes
+
+- **Brainstorm server ESM fix** — renamed `server.js` → `server.cjs` so the brainstorming server starts correctly on Node.js 22+ where the root `package.json` `"type": "module"` caused `require()` to fail. (PR #784 by @sarbojitrana, fixes #774, #780, #783)
+- **Brainstorm owner-PID on Windows** — skip PID lifecycle monitoring on Windows/MSYS2 where the PID namespace is invisible to Node.js, preventing the server from self-terminating after 60 seconds. (#770, docs from PR #768 by @lucasyhzlu-debug)
+- **stop-server.sh reliability** — verify the server process actually died before reporting success. SIGTERM + 2s wait + SIGKILL fallback. (#723)
+
+### Changed
+
+- **Execution handoff** — restore user choice between subagent-driven and inline execution after plan writing. Subagent-driven is recommended but no longer mandatory.
+
 ## v5.0.4 (2026-03-16)
 
 ### Review Loop Refinements

docs/superpowers/plans/2026-03-23-codex-app-compatibility.md

@@ -0,0 +1,564 @@
+# Codex App Compatibility Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Make `using-git-worktrees`, `finishing-a-development-branch`, and related skills work in the Codex App's sandboxed worktree environment without breaking existing behavior.
+
+**Architecture:** Read-only environment detection (`git-dir` vs `git-common-dir`) at the start of two skills. If already in a linked worktree, skip creation. If on detached HEAD, emit a handoff payload instead of the 4-option menu. Sandbox fallback catches permission errors during worktree creation.
+
+**Tech Stack:** Git, Markdown (skill files are instruction documents, not executable code)
+
+**Spec:** `docs/superpowers/specs/2026-03-23-codex-app-compatibility-design.md`
+
+---
+
+## File Structure
+
+| File | Responsibility | Action |
+|---|---|---|
+| `skills/using-git-worktrees/SKILL.md` | Worktree creation + isolation | Add Step 0 detection + sandbox fallback |
+| `skills/finishing-a-development-branch/SKILL.md` | Branch finishing workflow | Add Step 1.5 detection + cleanup guard |
+| `skills/subagent-driven-development/SKILL.md` | Plan execution with subagents | Update Integration description |
+| `skills/executing-plans/SKILL.md` | Plan execution inline | Update Integration description |
+| `skills/using-superpowers/references/codex-tools.md` | Codex platform reference | Add detection + finishing docs |
+
+---
+
+### Task 1: Add Step 0 to `using-git-worktrees`
+
+**Files:**
+- Modify: `skills/using-git-worktrees/SKILL.md:14-15` (insert after Overview, before Directory Selection Process)
+
+- [ ] **Step 1: Read the current skill file**
+
+Read `skills/using-git-worktrees/SKILL.md` in full. Identify the exact insertion point: after the "Announce at start" line (line 14) and before "## Directory Selection Process" (line 16).
+
+- [ ] **Step 2: Insert Step 0 section**
+
+Insert the following between the Overview section and "## Directory Selection Process":
+
+```markdown
+## Step 0: Check if Already in an Isolated Workspace
+
+Before creating a worktree, check if one already exists:
+
+```bash
+GIT_DIR=$(cd "$(git rev-parse --git-dir)" 2>/dev/null && pwd -P)
+GIT_COMMON=$(cd "$(git rev-parse --git-common-dir)" 2>/dev/null && pwd -P)
+BRANCH=$(git branch --show-current)
+```
+
+**If `GIT_DIR` differs from `GIT_COMMON`:** You are already inside a linked worktree (created by the Codex App, Claude Code's Agent tool, a previous skill run, or the user). Do NOT create another worktree. Instead:
+
+1. Run project setup (auto-detect package manager as in "Run Project Setup" below)
+2. Verify clean baseline (run tests as in "Verify Clean Baseline" below)
+3. Report with branch state:
+   - On a branch: "Already in an isolated workspace at `<path>` on branch `<name>`. Tests passing. Ready to implement."
+   - Detached HEAD: "Already in an isolated workspace at `<path>` (detached HEAD, externally managed). Tests passing. Note: branch creation needed at finish time. Ready to implement."
+
+After reporting, STOP. Do not continue to Directory Selection or Creation Steps.
+
+**If `GIT_DIR` equals `GIT_COMMON`:** Proceed with the full worktree creation flow below.
+
+**Sandbox fallback:** If you proceed to Creation Steps but `git worktree add -b` fails with a permission error (e.g., "Operation not permitted"), treat this as a late-detected restricted environment. Fall back to the behavior above — run setup and baseline tests in the current directory, report accordingly, and STOP.
+```
+
+- [ ] **Step 3: Verify the insertion**
+
+Read the file again. Confirm:
+- Step 0 appears between Overview and Directory Selection Process
+- The rest of the file (Directory Selection, Safety Verification, Creation Steps, etc.) is unchanged
+- No duplicate sections or broken markdown
+
+- [ ] **Step 4: Commit**
+
+```bash
+git add skills/using-git-worktrees/SKILL.md
+git commit -m "feat(using-git-worktrees): add Step 0 environment detection (PRI-823)
+
+Skip worktree creation when already in a linked worktree. Includes
+sandbox fallback for permission errors on git worktree add."
+```
+
+---
+
+### Task 2: Update `using-git-worktrees` Integration section
+
+**Files:**
+- Modify: `skills/using-git-worktrees/SKILL.md:211-215` (Integration > Called by)
+
+- [ ] **Step 1: Update the three "Called by" entries**
+
+Change lines 212-214 from:
+
+```markdown
+- **brainstorming** (Phase 4) - REQUIRED when design is approved and implementation follows
+- **subagent-driven-development** - REQUIRED before executing any tasks
+- **executing-plans** - REQUIRED before executing any tasks
+```
+
+To:
+
+```markdown
+- **brainstorming** - REQUIRED: Ensures isolated workspace (creates one or verifies existing)
+- **subagent-driven-development** - REQUIRED: Ensures isolated workspace (creates one or verifies existing)
+- **executing-plans** - REQUIRED: Ensures isolated workspace (creates one or verifies existing)
+```
+
+- [ ] **Step 2: Verify the Integration section**
+
+Read the Integration section. Confirm all three entries are updated, "Pairs with" is unchanged.
+
+- [ ] **Step 3: Commit**
+
+```bash
+git add skills/using-git-worktrees/SKILL.md
+git commit -m "docs(using-git-worktrees): update Integration descriptions (PRI-823)
+
+Clarify that skill ensures a workspace exists, not that it always creates one."
+```
+
+---
+
+### Task 3: Add Step 1.5 to `finishing-a-development-branch`
+
+**Files:**
+- Modify: `skills/finishing-a-development-branch/SKILL.md:38` (insert after Step 1, before Step 2)
+
+- [ ] **Step 1: Read the current skill file**
+
+Read `skills/finishing-a-development-branch/SKILL.md` in full. Identify the insertion point: after "**If tests pass:** Continue to Step 2." (line 38) and before "### Step 2: Determine Base Branch" (line 40).
+
+- [ ] **Step 2: Insert Step 1.5 section**
+
+Insert the following between Step 1 and Step 2:
+
+```markdown
+### Step 1.5: Detect Environment
+
+```bash
+GIT_DIR=$(cd "$(git rev-parse --git-dir)" 2>/dev/null && pwd -P)
+GIT_COMMON=$(cd "$(git rev-parse --git-common-dir)" 2>/dev/null && pwd -P)
+BRANCH=$(git branch --show-current)
+```
+
+**Path A — `GIT_DIR` differs from `GIT_COMMON` AND `BRANCH` is empty (externally managed worktree, detached HEAD):**
+
+First, ensure all work is staged and committed (`git add` + `git commit`).
+
+Then present this to the user (do NOT present the 4-option menu):
+
+```
+Implementation complete. All tests passing.
+Current HEAD: <full-commit-sha>
+
+This workspace is externally managed (detached HEAD).
+I cannot create branches, push, or open PRs from here.
+
+⚠ These commits are on a detached HEAD. If you do not create a branch,
+they may be lost when this workspace is cleaned up.
+
+If your host application provides these controls:
+- "Create branch" — to name a branch, then commit/push/PR
+- "Hand off to local" — to move changes to your local checkout
+
+Suggested branch name: <ticket-id/short-description>
+Suggested commit message: <summary-of-work>
+```
+
+Branch name: use ticket ID if available (e.g., `pri-823/codex-compat`), otherwise slugify the first 5 words of the plan title, otherwise omit. Avoid sensitive content in branch names.
+
+Skip to Step 5 (cleanup is a no-op — see guard below).
+
+**Path B — `GIT_DIR` differs from `GIT_COMMON` AND `BRANCH` exists (externally managed worktree, named branch):**
+
+Proceed to Step 2 and present the 4-option menu as normal.
+
+**Path C — `GIT_DIR` equals `GIT_COMMON` (normal environment):**
+
+Proceed to Step 2 and present the 4-option menu as normal.
+```
+
+- [ ] **Step 3: Verify the insertion**
+
+Read the file again. Confirm:
+- Step 1.5 appears between Step 1 and Step 2
+- Steps 2-5 are unchanged
+- Path A handoff includes commit SHA and data loss warning
+- Paths B and C proceed to Step 2 normally
+
+- [ ] **Step 4: Commit**
+
+```bash
+git add skills/finishing-a-development-branch/SKILL.md
+git commit -m "feat(finishing-a-development-branch): add Step 1.5 environment detection (PRI-823)
+
+Detect externally managed worktrees with detached HEAD and emit handoff
+payload instead of 4-option menu. Includes commit SHA and data loss warning."
+```
+
+---
+
+### Task 4: Add Step 5 cleanup guard to `finishing-a-development-branch`
+
+**Files:**
+- Modify: `skills/finishing-a-development-branch/SKILL.md` (Step 5: Cleanup Worktree — find by section heading, line numbers will have shifted after Task 3)
+
+- [ ] **Step 1: Read the current Step 5 section**
+
+Find the "### Step 5: Cleanup Worktree" section in `skills/finishing-a-development-branch/SKILL.md` (line numbers will have shifted after Task 3's insertion). The current Step 5 is:
+
+```markdown
+### Step 5: Cleanup Worktree
+
+**For Options 1, 2, 4:**
+
+Check if in worktree:
+```bash
+git worktree list | grep $(git branch --show-current)
+```
+
+If yes:
+```bash
+git worktree remove <worktree-path>
+```
+
+**For Option 3:** Keep worktree.
+```
+
+- [ ] **Step 2: Add the cleanup guard before existing logic**
+
+Replace the Step 5 section with:
+
+```markdown
+### Step 5: Cleanup Worktree
+
+**First, check if worktree is externally managed:**
+
+```bash
+GIT_DIR=$(cd "$(git rev-parse --git-dir)" 2>/dev/null && pwd -P)
+GIT_COMMON=$(cd "$(git rev-parse --git-common-dir)" 2>/dev/null && pwd -P)
+```
+
+If `GIT_DIR` differs from `GIT_COMMON`: skip worktree removal — the host environment owns this workspace.
+
+**Otherwise, for Options 1 and 4:**
+
+Check if in worktree:
+```bash
+git worktree list | grep $(git branch --show-current)
+```
+
+If yes:
+```bash
+git worktree remove <worktree-path>
+```
+
+**For Option 3:** Keep worktree.
+```
+
+Note: the original text said "For Options 1, 2, 4" but the Quick Reference table and Common Mistakes section say "Options 1 & 4 only." This edit aligns Step 5 with those sections.
+
+- [ ] **Step 3: Verify the replacement**
+
+Read Step 5. Confirm:
+- Cleanup guard (re-detection) appears first
+- Existing removal logic preserved for non-externally-managed worktrees
+- "Options 1 and 4" (not "1, 2, 4") matches Quick Reference and Common Mistakes
+
+- [ ] **Step 4: Commit**
+
+```bash
+git add skills/finishing-a-development-branch/SKILL.md
+git commit -m "feat(finishing-a-development-branch): add Step 5 cleanup guard (PRI-823)
+
+Re-detect externally managed worktree at cleanup time and skip removal.
+Also fixes pre-existing inconsistency: cleanup now correctly says
+Options 1 and 4 only, matching Quick Reference and Common Mistakes."
+```
+
+---
+
+### Task 5: Update Integration lines in `subagent-driven-development` and `executing-plans`
+
+**Files:**
+- Modify: `skills/subagent-driven-development/SKILL.md:268`
+- Modify: `skills/executing-plans/SKILL.md:68`
+
+- [ ] **Step 1: Update `subagent-driven-development`**
+
+Change line 268 from:
+```
+- **superpowers:using-git-worktrees** - REQUIRED: Set up isolated workspace before starting
+```
+To:
+```
+- **superpowers:using-git-worktrees** - REQUIRED: Ensures isolated workspace (creates one or verifies existing)
+```
+
+- [ ] **Step 2: Update `executing-plans`**
+
+Change line 68 from:
+```
+- **superpowers:using-git-worktrees** - REQUIRED: Set up isolated workspace before starting
+```
+To:
+```
+- **superpowers:using-git-worktrees** - REQUIRED: Ensures isolated workspace (creates one or verifies existing)
+```
+
+- [ ] **Step 3: Verify both files**
+
+Read line 268 of `skills/subagent-driven-development/SKILL.md` and line 68 of `skills/executing-plans/SKILL.md`. Confirm both say "Ensures isolated workspace (creates one or verifies existing)".
+
+- [ ] **Step 4: Commit**
+
+```bash
+git add skills/subagent-driven-development/SKILL.md skills/executing-plans/SKILL.md
+git commit -m "docs(sdd, executing-plans): update worktree Integration descriptions (PRI-823)
+
+Clarify that using-git-worktrees ensures a workspace exists rather than
+always creating one."
+```
+
+---
+
+### Task 6: Add environment detection docs to `codex-tools.md`
+
+**Files:**
+- Modify: `skills/using-superpowers/references/codex-tools.md:25` (append at end)
+
+- [ ] **Step 1: Read the current file**
+
+Read `skills/using-superpowers/references/codex-tools.md` in full. Confirm it ends at line 25-26 after the multi_agent section.
+
+- [ ] **Step 2: Append two new sections**
+
+Add at the end of the file:
+
+```markdown
+
+## Environment Detection
+
+Skills that create worktrees or finish branches should detect their
+environment with read-only git commands before proceeding:
+
+```bash
+GIT_DIR=$(cd "$(git rev-parse --git-dir)" 2>/dev/null && pwd -P)
+GIT_COMMON=$(cd "$(git rev-parse --git-common-dir)" 2>/dev/null && pwd -P)
+BRANCH=$(git branch --show-current)
+```
+
+- `GIT_DIR != GIT_COMMON` → already in a linked worktree (skip creation)
+- `BRANCH` empty → detached HEAD (cannot branch/push/PR from sandbox)
+
+See `using-git-worktrees` Step 0 and `finishing-a-development-branch`
+Step 1.5 for how each skill uses these signals.
+
+## Codex App Finishing
+
+When the sandbox blocks branch/push operations (detached HEAD in an
+externally managed worktree), the agent commits all work and informs
+the user to use the App's native controls:
+
+- **"Create branch"** — names the branch, then commit/push/PR via App UI
+- **"Hand off to local"** — transfers work to the user's local checkout
+
+The agent can still run tests, stage files, and output suggested branch
+names, commit messages, and PR descriptions for the user to copy.
+```
+
+- [ ] **Step 3: Verify the additions**
+
+Read the full file. Confirm:
+- Two new sections appear after the existing content
+- Bash code block renders correctly (not escaped)
+- Cross-references to Step 0 and Step 1.5 are present
+
+- [ ] **Step 4: Commit**
+
+```bash
+git add skills/using-superpowers/references/codex-tools.md
+git commit -m "docs(codex-tools): add environment detection and App finishing docs (PRI-823)
+
+Document the git-dir vs git-common-dir detection pattern and the Codex
+App's native finishing flow for skills that need to adapt."
+```
+
+---
+
+### Task 7: Automated test — environment detection
+
+**Files:**
+- Create: `tests/codex-app-compat/test-environment-detection.sh`
+
+- [ ] **Step 1: Create test directory**
+
+```bash
+mkdir -p tests/codex-app-compat
+```
+
+- [ ] **Step 2: Write the detection test script**
+
+Create `tests/codex-app-compat/test-environment-detection.sh`:
+
+```bash
+#!/usr/bin/env bash
+set -euo pipefail
+
+# Test environment detection logic from PRI-823
+# Tests the git-dir vs git-common-dir comparison used by
+# using-git-worktrees Step 0 and finishing-a-development-branch Step 1.5
+
+PASS=0
+FAIL=0
+TEMP_DIR=$(mktemp -d)
+trap "rm -rf $TEMP_DIR" EXIT
+
+log_pass() { echo "  PASS: $1"; PASS=$((PASS + 1)); }
+log_fail() { echo "  FAIL: $1"; FAIL=$((FAIL + 1)); }
+
+# Helper: run detection and return "linked" or "normal"
+detect_worktree() {
+  local git_dir git_common
+  git_dir=$(cd "$(git rev-parse --git-dir)" 2>/dev/null && pwd -P)
+  git_common=$(cd "$(git rev-parse --git-common-dir)" 2>/dev/null && pwd -P)
+  if [ "$git_dir" != "$git_common" ]; then
+    echo "linked"
+  else
+    echo "normal"
+  fi
+}
+
+echo "=== Test 1: Normal repo detection ==="
+cd "$TEMP_DIR"
+git init test-repo > /dev/null 2>&1
+cd test-repo
+git commit --allow-empty -m "init" > /dev/null 2>&1
+result=$(detect_worktree)
+if [ "$result" = "normal" ]; then
+  log_pass "Normal repo detected as normal"
+else
+  log_fail "Normal repo detected as '$result' (expected 'normal')"
+fi
+
+echo "=== Test 2: Linked worktree detection ==="
+git worktree add "$TEMP_DIR/test-wt" -b test-branch > /dev/null 2>&1
+cd "$TEMP_DIR/test-wt"
+result=$(detect_worktree)
+if [ "$result" = "linked" ]; then
+  log_pass "Linked worktree detected as linked"
+else
+  log_fail "Linked worktree detected as '$result' (expected 'linked')"
+fi
+
+echo "=== Test 3: Detached HEAD detection ==="
+git checkout --detach HEAD > /dev/null 2>&1
+branch=$(git branch --show-current)
+if [ -z "$branch" ]; then
+  log_pass "Detached HEAD: branch is empty"
+else
+  log_fail "Detached HEAD: branch is '$branch' (expected empty)"
+fi
+
+echo "=== Test 4: Linked worktree + detached HEAD (Codex App simulation) ==="
+result=$(detect_worktree)
+branch=$(git branch --show-current)
+if [ "$result" = "linked" ] && [ -z "$branch" ]; then
+  log_pass "Codex App simulation: linked + detached HEAD"
+else
+  log_fail "Codex App simulation: result='$result', branch='$branch'"
+fi
+
+echo "=== Test 5: Cleanup guard — linked worktree should NOT remove ==="
+cd "$TEMP_DIR/test-wt"
+result=$(detect_worktree)
+if [ "$result" = "linked" ]; then
+  log_pass "Cleanup guard: linked worktree correctly detected (would skip removal)"
+else
+  log_fail "Cleanup guard: expected 'linked', got '$result'"
+fi
+
+echo "=== Test 6: Cleanup guard — main repo SHOULD remove ==="
+cd "$TEMP_DIR/test-repo"
+result=$(detect_worktree)
+if [ "$result" = "normal" ]; then
+  log_pass "Cleanup guard: main repo correctly detected (would proceed with removal)"
+else
+  log_fail "Cleanup guard: expected 'normal', got '$result'"
+fi
+
+# Cleanup worktree before temp dir removal
+cd "$TEMP_DIR/test-repo"
+git worktree remove "$TEMP_DIR/test-wt" > /dev/null 2>&1 || true
+
+echo ""
+echo "=== Results: $PASS passed, $FAIL failed ==="
+if [ "$FAIL" -gt 0 ]; then
+  exit 1
+fi
+```
+
+- [ ] **Step 3: Make it executable and run it**
+
+```bash
+chmod +x tests/codex-app-compat/test-environment-detection.sh
+./tests/codex-app-compat/test-environment-detection.sh
+```
+
+Expected output: 6 passed, 0 failed.
+
+- [ ] **Step 4: Commit**
+
+```bash
+git add tests/codex-app-compat/test-environment-detection.sh
+git commit -m "test: add environment detection tests for Codex App compat (PRI-823)
+
+Tests git-dir vs git-common-dir comparison in normal repo, linked
+worktree, detached HEAD, and cleanup guard scenarios."
+```
+
+---
+
+### Task 8: Final verification
+
+**Files:**
+- Read: all 5 modified skill files
+
+- [ ] **Step 1: Run the automated detection tests**
+
+```bash
+./tests/codex-app-compat/test-environment-detection.sh
+```
+
+Expected: 6 passed, 0 failed.
+
+- [ ] **Step 2: Read each modified file and verify changes**
+
+Read each file end-to-end:
+- `skills/using-git-worktrees/SKILL.md` — Step 0 present, rest unchanged
+- `skills/finishing-a-development-branch/SKILL.md` — Step 1.5 present, cleanup guard present, rest unchanged
+- `skills/subagent-driven-development/SKILL.md` — line 268 updated
+- `skills/executing-plans/SKILL.md` — line 68 updated
+- `skills/using-superpowers/references/codex-tools.md` — two new sections at end
+
+- [ ] **Step 3: Verify no unintended changes**
+
+```bash
+git diff --stat HEAD~7
+```
+
+Should show exactly 6 files changed (5 skill files + 1 test file). No other files modified.
+
+- [ ] **Step 4: Run existing test suite**
+
+If test runner exists:
+```bash
+# Run skill-triggering tests
+./tests/skill-triggering/run-all.sh 2>/dev/null || echo "Skill triggering tests not available in this environment"
+
+# Run SDD integration test
+./tests/claude-code/test-subagent-driven-development-integration.sh 2>/dev/null || echo "SDD integration test not available in this environment"
+```
+
+Note: these tests require Claude Code with `--dangerously-skip-permissions`. If not available, document that regression tests should be run manually.

docs/superpowers/specs/2026-03-23-codex-app-compatibility-design.md

@@ -0,0 +1,244 @@
+# Codex App Compatibility: Worktree and Finishing Skill Adaptation
+
+Make superpowers skills work in the Codex App's sandboxed worktree environment without breaking existing Claude Code or Codex CLI behavior.
+
+**Ticket:** PRI-823
+
+## Motivation
+
+The Codex App runs agents inside git worktrees it manages — detached HEAD, located under `$CODEX_HOME/worktrees/`, with a Seatbelt sandbox that blocks `git checkout -b`, `git push`, and network access. Three superpowers skills assume unrestricted git access: `using-git-worktrees` creates manual worktrees with named branches, `finishing-a-development-branch` merges/pushes/PRs by branch name, and `subagent-driven-development` requires both.
+
+The Codex CLI (open source terminal tool) does NOT have this conflict — it has no built-in worktree management. Our manual worktree approach fills an isolation gap there. The problem is specifically with the Codex App.
+
+## Empirical Findings
+
+Tested in the Codex App on 2026-03-23:
+
+| Operation | workspace-write sandbox | Full access sandbox |
+|---|---|---|
+| `git add` | Works | Works |
+| `git commit` | Works | Works |
+| `git checkout -b` | **Blocked** (can't write `.git/refs/heads/`) | Works |
+| `git push` | **Blocked** (network + `.git/refs/remotes/`) | Works |
+| `gh pr create` | **Blocked** (network) | Works |
+| `git status/diff/log` | Works | Works |
+
+Additional findings:
+- `spawn_agent` subagents **share** the parent thread's filesystem (confirmed via marker file test)
+- "Create branch" button appears in the App header regardless of which branch the worktree was started from
+- The App's native finishing flow: Create branch → Commit modal → Commit and push / Commit and create PR
+- `network_access = true` config is silently broken on macOS (issue #10390)
+
+## Design: Read-Only Environment Detection
+
+Three read-only git commands detect the environment without side effects:
+
+```bash
+GIT_DIR=$(cd "$(git rev-parse --git-dir)" 2>/dev/null && pwd -P)
+GIT_COMMON=$(cd "$(git rev-parse --git-common-dir)" 2>/dev/null && pwd -P)
+BRANCH=$(git branch --show-current)
+```
+
+Two signals derived:
+
+- **IN_LINKED_WORKTREE:** `GIT_DIR != GIT_COMMON` — the agent is in a worktree created by something else (Codex App, Claude Code Agent tool, previous skill run, or the user)
+- **ON_DETACHED_HEAD:** `BRANCH` is empty — no named branch exists
+
+Why `git-dir != git-common-dir` instead of checking `show-toplevel`:
+- In a normal repo, both resolve to the same `.git` directory
+- In a linked worktree, `git-dir` is `.git/worktrees/<name>` while `git-common-dir` is `.git`
+- In a submodule, both are equal — avoiding a false positive that `show-toplevel` would produce
+- Resolving via `cd && pwd -P` handles the relative-path problem (`git-common-dir` returns `.git` relative in normal repos but absolute in worktrees) and symlinks (macOS `/tmp` → `/private/tmp`)
+
+### Decision Matrix
+
+| Linked Worktree? | Detached HEAD? | Environment | Action |
+|---|---|---|---|
+| No | No | Claude Code / Codex CLI / normal git | Full skill behavior (unchanged) |
+| Yes | Yes | Codex App worktree (workspace-write) | Skip worktree creation; handoff payload at finish |
+| Yes | No | Codex App (Full access) or manual worktree | Skip worktree creation; full finishing flow |
+| No | Yes | Unusual (manual detached HEAD) | Create worktree normally; warn at finish |
+
+## Changes
+
+### 1. `using-git-worktrees/SKILL.md` — Add Step 0 (~12 lines)
+
+New section between "Overview" and "Directory Selection Process":
+
+**Step 0: Check if Already in an Isolated Workspace**
+
+Run the detection commands. If `GIT_DIR != GIT_COMMON`, skip worktree creation entirely. Instead:
+1. Skip to "Run Project Setup" subsection under Creation Steps — `npm install` etc. is idempotent, worth running for safety
+2. Then "Verify Clean Baseline" — run tests
+3. Report with branch state:
+   - On a branch: "Already in an isolated workspace at `<path>` on branch `<name>`. Tests passing. Ready to implement."
+   - Detached HEAD: "Already in an isolated workspace at `<path>` (detached HEAD, externally managed). Tests passing. Note: branch creation needed at finish time. Ready to implement."
+
+If `GIT_DIR == GIT_COMMON`, proceed with the full worktree creation flow (unchanged).
+
+Safety verification (.gitignore check) is skipped when Step 0 fires — irrelevant for externally-created worktrees.
+
+Update the Integration section's "Called by" entries. Change the description on each from context-specific text to: "Ensures isolated workspace (creates one or verifies existing)". For example, the `subagent-driven-development` entry changes from "REQUIRED: Set up isolated workspace before starting" to "REQUIRED: Ensures isolated workspace (creates one or verifies existing)".
+
+**Sandbox fallback:** If `GIT_DIR == GIT_COMMON` and the skill proceeds to Creation Steps, but `git worktree add -b` fails with a permission error (e.g., Seatbelt sandbox denial), treat this as a late-detected restricted environment. Fall back to the Step 0 "already in workspace" behavior — skip creation, run setup and baseline tests in the current directory, report accordingly.
+
+After reporting in Step 0, STOP. Do not continue to Directory Selection or Creation Steps.
+
+**Everything else unchanged:** Directory Selection, Safety Verification, Creation Steps, Project Setup, Baseline Tests, Quick Reference, Common Mistakes, Red Flags.
+
+### 2. `finishing-a-development-branch/SKILL.md` — Add Step 1.5 + cleanup guard (~20 lines)
+
+**Step 1.5: Detect Environment** (after Step 1 "Verify Tests", before Step 2 "Determine Base Branch")
+
+Run the detection commands. Three paths:
+
+- **Path A** skips Steps 2 and 3 entirely (no base branch or options needed).
+- **Paths B and C** proceed through Step 2 (Determine Base Branch) and Step 3 (Present Options) as normal.
+
+**Path A — Externally managed worktree + detached HEAD** (`GIT_DIR != GIT_COMMON` AND `BRANCH` empty):
+
+First, ensure all work is staged and committed (`git add` + `git commit`). The Codex App's finishing controls operate on committed work.
+
+Then present this to the user (do NOT present the 4-option menu):
+
+```
+Implementation complete. All tests passing.
+Current HEAD: <full-commit-sha>
+
+This workspace is externally managed (detached HEAD).
+I cannot create branches, push, or open PRs from here.
+
+⚠ These commits are on a detached HEAD. If you do not create a branch,
+they may be lost when this workspace is cleaned up.
+
+If your host application provides these controls:
+- "Create branch" — to name a branch, then commit/push/PR
+- "Hand off to local" — to move changes to your local checkout
+
+Suggested branch name: <ticket-id/short-description>
+Suggested commit message: <summary-of-work>
+```
+
+Branch name derivation: use the ticket ID if available (e.g., `pri-823/codex-compat`), otherwise slugify the first 5 words of the plan title, otherwise omit the suggestion. Avoid including sensitive content (vulnerability descriptions, customer names) in branch names.
+
+Skip to Step 5 (cleanup is a no-op for externally managed worktrees).
+
+**Path B — Externally managed worktree + named branch** (`GIT_DIR != GIT_COMMON` AND `BRANCH` exists):
+
+Present the 4-option menu as normal. (The Step 5 cleanup guard will re-detect the externally managed state independently.)
+
+**Path C — Normal environment** (`GIT_DIR == GIT_COMMON`):
+
+Present the 4-option menu as today (unchanged).
+
+**Step 5 cleanup guard:**
+
+Re-run the `GIT_DIR` vs `GIT_COMMON` detection at cleanup time (do not rely on earlier skill output — the finishing skill may run in a different session). If `GIT_DIR != GIT_COMMON`, skip `git worktree remove` — the host environment owns this workspace.
+
+Otherwise, check and remove as today. Note: the existing Step 5 text says "For Options 1, 2, 4" but the Quick Reference table and Common Mistakes section say "Options 1 & 4 only." The new guard is added before this existing logic and does not change which options trigger cleanup.
+
+**Everything else unchanged:** Options 1-4 logic, Quick Reference, Common Mistakes, Red Flags.
+
+### 3. `subagent-driven-development/SKILL.md` and `executing-plans/SKILL.md` — 1 line edit each
+
+Both skills have an identical Integration section line. Change from:
+```
+- superpowers:using-git-worktrees - REQUIRED: Set up isolated workspace before starting
+```
+To:
+```
+- superpowers:using-git-worktrees - REQUIRED: Ensures isolated workspace (creates one or verifies existing)
+```
+
+**Everything else unchanged:** Dispatch/review loop, prompt templates, model selection, status handling, red flags.
+
+### 4. `codex-tools.md` — Add environment detection docs (~15 lines)
+
+Two new sections at the end:
+
+**Environment Detection:**
+
+```markdown
+## Environment Detection
+
+Skills that create worktrees or finish branches should detect their
+environment with read-only git commands before proceeding:
+
+\```bash
+GIT_DIR=$(cd "$(git rev-parse --git-dir)" 2>/dev/null && pwd -P)
+GIT_COMMON=$(cd "$(git rev-parse --git-common-dir)" 2>/dev/null && pwd -P)
+BRANCH=$(git branch --show-current)
+\```
+
+- `GIT_DIR != GIT_COMMON` → already in a linked worktree (skip creation)
+- `BRANCH` empty → detached HEAD (cannot branch/push/PR from sandbox)
+
+See `using-git-worktrees` Step 0 and `finishing-a-development-branch`
+Step 1.5 for how each skill uses these signals.
+```
+
+**Codex App Finishing:**
+
+```markdown
+## Codex App Finishing
+
+When the sandbox blocks branch/push operations (detached HEAD in an
+externally managed worktree), the agent commits all work and informs
+the user to use the App's native controls:
+
+- **"Create branch"** — names the branch, then commit/push/PR via App UI
+- **"Hand off to local"** — transfers work to the user's local checkout
+
+The agent can still run tests, stage files, and output suggested branch
+names, commit messages, and PR descriptions for the user to copy.
+```
+
+## What Does NOT Change
+
+- `implementer-prompt.md`, `spec-reviewer-prompt.md`, `code-quality-reviewer-prompt.md` — subagent prompts untouched
+- `executing-plans/SKILL.md` — only the 1-line Integration description changes (same as `subagent-driven-development`); all runtime behavior is unchanged
+- `dispatching-parallel-agents/SKILL.md` — no worktree or finishing operations
+- `.codex/INSTALL.md` — installation process unchanged
+- The 4-option finishing menu — preserved exactly for Claude Code and Codex CLI
+- The full worktree creation flow — preserved exactly for non-worktree environments
+- Subagent dispatch/review/iterate loop — unchanged (filesystem sharing confirmed)
+
+## Scope Summary
+
+| File | Change |
+|---|---|
+| `skills/using-git-worktrees/SKILL.md` | +12 lines (Step 0) |
+| `skills/finishing-a-development-branch/SKILL.md` | +20 lines (Step 1.5 + cleanup guard) |
+| `skills/subagent-driven-development/SKILL.md` | 1 line edit |
+| `skills/executing-plans/SKILL.md` | 1 line edit |
+| `skills/using-superpowers/references/codex-tools.md` | +15 lines |
+
+~50 lines added/changed across 5 files. Zero new files. Zero breaking changes.
+
+## Future Considerations
+
+If a third skill needs the same detection pattern, extract it into a shared `references/environment-detection.md` file (Approach B). Not needed now — only 2 skills use it.
+
+## Test Plan
+
+### Automated (run in Claude Code after implementation)
+
+1. Normal repo detection — assert IN_LINKED_WORKTREE=false
+2. Linked worktree detection — `git worktree add` test worktree, assert IN_LINKED_WORKTREE=true
+3. Detached HEAD detection — `git checkout --detach`, assert ON_DETACHED_HEAD=true
+4. Finishing skill handoff output — verify handoff message (not 4-option menu) in restricted environment
+5. **Step 5 cleanup guard** — create a linked worktree (`git worktree add /tmp/test-cleanup -b test-cleanup`), `cd` into it, run the Step 5 cleanup detection (`GIT_DIR` vs `GIT_COMMON`), assert it would NOT call `git worktree remove`. Then `cd` back to main repo, run the same detection, assert it WOULD call `git worktree remove`. Clean up test worktree afterward.
+
+### Manual Codex App Tests (5 tests)
+
+1. Detection in Worktree thread (workspace-write) — verify GIT_DIR != GIT_COMMON, empty branch
+2. Detection in Worktree thread (Full access) — same detection, different sandbox behavior
+3. Finishing skill handoff format — verify agent emits handoff payload, not 4-option menu
+4. Full lifecycle — detection → commit → finishing detection → correct behavior → cleanup
+5. **Sandbox fallback in Local thread** — Start a Codex App **Local thread** (workspace-write sandbox). Prompt: "Use the superpowers skill `using-git-worktrees` to set up an isolated workspace for implementing a small change." Pre-check: `git checkout -b test-sandbox-check` should fail with `Operation not permitted`. Expected: the skill detects `GIT_DIR == GIT_COMMON` (normal repo), attempts `git worktree add -b`, hits Seatbelt denial, falls back to Step 0 "already in workspace" behavior — runs setup, baseline tests, reports ready from current directory. Pass: agent recovers gracefully without cryptic error messages. Fail: agent prints raw Seatbelt error, retries, or gives up with confusing output.
+
+### Regression
+
+- Existing Claude Code skill-triggering tests still pass
+- Existing subagent-driven-development integration tests still pass
+- Normal Claude Code session: full worktree creation + 4-option finishing still works

skills/brainstorming/scripts/start-server.sh

@@ -106,16 +106,22 @@ 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.js
+  env BRAINSTORM_DIR="$SCREEN_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.js > "$LOG_FILE" 2>&1 &
+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 &
 SERVER_PID=$!
 disown "$SERVER_PID" 2>/dev/null
 echo "$SERVER_PID" > "$PID_FILE"

skills/brainstorming/visual-companion.md

@@ -48,12 +48,21 @@ Save `screen_dir` from the response. Tell user to open the URL.
 
 **Launching the server by platform:**
 
-**Claude Code:**
+**Claude Code (macOS / Linux):**
 ```bash
 # Default mode works — the script backgrounds the server itself
 scripts/start-server.sh --project-dir /path/to/project
 ```
 
+**Claude Code (Windows):**
+```bash
+# Windows auto-detects and uses foreground mode, which blocks the tool call.
+# Use run_in_background: true on the Bash tool call so the server survives
+# across conversation turns.
+scripts/start-server.sh --project-dir /path/to/project
+```
+When calling this via the Bash tool, set `run_in_background: true`. Then read `$SCREEN_DIR/.server-info` on the next turn to get the URL and port.
+
 **Codex:**
 ```bash
 # Codex reaps background processes. The script auto-detects CODEX_CI and
@@ -61,14 +70,6 @@ scripts/start-server.sh --project-dir /path/to/project
 scripts/start-server.sh --project-dir /path/to/project
 ```
 
-**Windows (Git Bash / CMD / PowerShell):**
-```bash
-# Windows/Git Bash reaps nohup background processes. The script auto-detects
-# this via OSTYPE/MSYSTEM and switches to foreground mode automatically.
-# No extra flags needed — all Windows shells route through Git Bash.
-scripts/start-server.sh --project-dir /path/to/project
-```
-
 **Gemini CLI:**
 ```bash
 # Use --foreground and set is_background: true on your shell tool call

skills/using-superpowers/references/codex-tools.md

@@ -4,7 +4,7 @@ Skills use Claude Code tool names. When you encounter these in a skill, use your
 
 | Skill references | Codex equivalent |
 |-----------------|------------------|
-| `Task` tool (dispatch subagent) | `spawn_agent` |
+| `Task` tool (dispatch subagent) | `spawn_agent` (see [Named agent dispatch](#named-agent-dispatch)) |
 | Multiple `Task` calls (parallel) | Multiple `spawn_agent` calls |
 | Task returns result | `wait` |
 | Task completes automatically | `close_agent` to free slot |
@@ -23,3 +23,78 @@ multi_agent = true
 ```
 
 This enables `spawn_agent`, `wait`, and `close_agent` for skills like `dispatching-parallel-agents` and `subagent-driven-development`.
+
+## Named agent dispatch
+
+Claude Code skills reference named agent types like `superpowers:code-reviewer`.
+Codex does not have a named agent registry — `spawn_agent` creates generic agents
+from built-in roles (`default`, `explorer`, `worker`).
+
+When a skill says to dispatch a named agent type:
+
+1. Find the agent's prompt file (e.g., `agents/code-reviewer.md` or the skill's
+   local prompt template like `code-quality-reviewer-prompt.md`)
+2. Read the prompt content
+3. Fill any template placeholders (`{BASE_SHA}`, `{WHAT_WAS_IMPLEMENTED}`, etc.)
+4. Spawn a `worker` agent with the filled content as the `message`
+
+| Skill instruction | Codex equivalent |
+|-------------------|------------------|
+| `Task tool (superpowers:code-reviewer)` | `spawn_agent(agent_type="worker", message=...)` with `code-reviewer.md` content |
+| `Task tool (general-purpose)` with inline prompt | `spawn_agent(message=...)` with the same prompt |
+
+### Message framing
+
+The `message` parameter is user-level input, not a system prompt. Structure it
+for maximum instruction adherence:
+
+```
+Your task is to perform the following. Follow the instructions below exactly.
+
+<agent-instructions>
+[filled prompt content from the agent's .md file]
+</agent-instructions>
+
+Execute this now. Output ONLY the structured response following the format
+specified in the instructions above.
+```
+
+- Use task-delegation framing ("Your task is...") rather than persona framing ("You are...")
+- Wrap instructions in XML tags — the model treats tagged blocks as authoritative
+- End with an explicit execution directive to prevent summarization of the instructions
+
+### When this workaround can be removed
+
+This approach compensates for Codex's plugin system not yet supporting an `agents`
+field in `plugin.json`. When `RawPluginManifest` gains an `agents` field, the
+plugin can symlink to `agents/` (mirroring the existing `skills/` symlink) and
+skills can dispatch named agent types directly.
+
+## Environment Detection
+
+Skills that create worktrees or finish branches should detect their
+environment with read-only git commands before proceeding:
+
+```bash
+GIT_DIR=$(cd "$(git rev-parse --git-dir)" 2>/dev/null && pwd -P)
+GIT_COMMON=$(cd "$(git rev-parse --git-common-dir)" 2>/dev/null && pwd -P)
+BRANCH=$(git branch --show-current)
+```
+
+- `GIT_DIR != GIT_COMMON` → already in a linked worktree (skip creation)
+- `BRANCH` empty → detached HEAD (cannot branch/push/PR from sandbox)
+
+See `using-git-worktrees` Step 0 and `finishing-a-development-branch`
+Step 1 for how each skill uses these signals.
+
+## Codex App Finishing
+
+When the sandbox blocks branch/push operations (detached HEAD in an
+externally managed worktree), the agent commits all work and informs
+the user to use the App's native controls:
+
+- **"Create branch"** — names the branch, then commit/push/PR via App UI
+- **"Hand off to local"** — transfers work to the user's local checkout
+
+The agent can still run tests, stage files, and output suggested branch
+names, commit messages, and PR descriptions for the user to copy.

skills/writing-plans/SKILL.md

@@ -49,7 +49,7 @@ This structure informs the task decomposition. Each task should produce self-con
 ```markdown
 # [Feature Name] Implementation Plan
 
-> **For agentic workers:** REQUIRED: Use superpowers:subagent-driven-development (if subagents available) or superpowers:executing-plans to implement this plan. Steps use checkbox (`- [ ]`) syntax for tracking.
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
 
 **Goal:** [One sentence describing what this builds]
 
@@ -126,17 +126,20 @@ After writing the complete plan:
 
 ## Execution Handoff
 
-After saving the plan:
+After saving the plan, offer execution choice:
 
-**"Plan complete and saved to `docs/superpowers/plans/<filename>.md`. Ready to execute?"**
+**"Plan complete and saved to `docs/superpowers/plans/<filename>.md`. Two execution options:**
 
-**Execution path depends on harness capabilities:**
+**1. Subagent-Driven (recommended)** - I dispatch a fresh subagent per task, review between tasks, fast iteration
 
-**If harness has subagents (Claude Code, etc.):**
-- **REQUIRED:** Use superpowers:subagent-driven-development
-- Do NOT offer a choice - subagent-driven is the standard approach
+**2. Inline Execution** - Execute tasks in this session using executing-plans, batch execution with checkpoints
+
+**Which approach?"**
+
+**If Subagent-Driven chosen:**
+- **REQUIRED SUB-SKILL:** Use superpowers:subagent-driven-development
 - Fresh subagent per task + two-stage review
 
-**If harness does NOT have subagents:**
-- Execute plan in current session using superpowers:executing-plans
+**If Inline Execution chosen:**
+- **REQUIRED SUB-SKILL:** Use superpowers:executing-plans
 - Batch execution with checkpoints for review

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)

skills/writing-skills/anthropic-best-practices.md

@@ -144,7 +144,7 @@ What works perfectly for Opus might need more detail for Haiku. If you plan to u
 ## Skill structure
 
 <Note>
-  **YAML Frontmatter**: The SKILL.md frontmatter supports two fields:
+  **YAML Frontmatter**: The SKILL.md frontmatter requires two fields:
 
   * `name` - Human-readable name of the Skill (64 characters maximum)
   * `description` - One-line description of what the Skill does and when to use it (1024 characters maximum)
@@ -1092,7 +1092,7 @@ reader = PdfReader("file.pdf")
 
 ### YAML frontmatter requirements
 
-The SKILL.md frontmatter includes only `name` (64 characters max) and `description` (1024 characters max) fields. See the [Skills overview](/en/docs/agents-and-tools/agent-skills/overview#skill-structure) for complete structure details.
+The SKILL.md frontmatter requires `name` (64 characters max) and `description` (1024 characters max) fields. See the [Skills overview](/en/docs/agents-and-tools/agent-skills/overview#skill-structure) for complete structure details.
 
 ### Token budgets
 

tests/brainstorm-server/server.test.js

@@ -15,7 +15,7 @@ const fs = require('fs');
 const path = require('path');
 const assert = require('assert');
 
-const SERVER_PATH = path.join(__dirname, '../../skills/brainstorming/scripts/server.js');
+const SERVER_PATH = path.join(__dirname, '../../skills/brainstorming/scripts/server.cjs');
 const TEST_PORT = 3334;
 const TEST_DIR = '/tmp/brainstorm-test';
 

tests/brainstorm-server/windows-lifecycle.test.sh

@@ -0,0 +1,351 @@
+#!/usr/bin/env bash
+# Windows lifecycle tests for the brainstorm server.
+#
+# Verifies that the brainstorm server survives the 60-second lifecycle
+# check on Windows, where OWNER_PID monitoring is disabled because the
+# MSYS2 PID namespace is invisible to Node.js.
+#
+# Requirements:
+#   - Node.js in PATH
+#   - Run from the repository root, or set SUPERPOWERS_ROOT
+#   - On Windows: Git Bash (OSTYPE=msys*)
+#
+# Usage:
+#   bash tests/brainstorm-server/windows-lifecycle.test.sh
+set -uo pipefail
+
+# ========== Configuration ==========
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+REPO_ROOT="${SUPERPOWERS_ROOT:-$(cd "$SCRIPT_DIR/../.." && pwd)}"
+START_SCRIPT="$REPO_ROOT/skills/brainstorming/scripts/start-server.sh"
+STOP_SCRIPT="$REPO_ROOT/skills/brainstorming/scripts/stop-server.sh"
+SERVER_JS="$REPO_ROOT/skills/brainstorming/scripts/server.js"
+
+TEST_DIR="${TMPDIR:-/tmp}/brainstorm-win-test-$$"
+
+passed=0
+failed=0
+skipped=0
+
+# ========== Helpers ==========
+
+cleanup() {
+  # Kill any server processes we started
+  for pidvar in SERVER_PID CONTROL_PID STOP_TEST_PID; do
+    pid="${!pidvar:-}"
+    if [[ -n "$pid" ]]; then
+      kill "$pid" 2>/dev/null || true
+      wait "$pid" 2>/dev/null || true
+    fi
+  done
+  if [[ -n "${TEST_DIR:-}" && -d "$TEST_DIR" ]]; then
+    rm -rf "$TEST_DIR"
+  fi
+}
+trap cleanup EXIT
+
+pass() {
+  echo "  PASS: $1"
+  passed=$((passed + 1))
+}
+
+fail() {
+  echo "  FAIL: $1"
+  echo "    $2"
+  failed=$((failed + 1))
+}
+
+skip() {
+  echo "  SKIP: $1 ($2)"
+  skipped=$((skipped + 1))
+}
+
+wait_for_server_info() {
+  local dir="$1"
+  for _ in $(seq 1 50); do
+    if [[ -f "$dir/.server-info" ]]; then
+      return 0
+    fi
+    sleep 0.1
+  done
+  return 1
+}
+
+get_port_from_info() {
+  # Read the port from .server-info. Use grep/sed instead of Node.js
+  # to avoid MSYS2-to-Windows path translation issues.
+  grep -o '"port":[0-9]*' "$1/.server-info" | head -1 | sed 's/"port"://'
+}
+
+http_check() {
+  local port="$1"
+  node -e "
+    const http = require('http');
+    http.get('http://localhost:$port/', (res) => {
+      process.exit(res.statusCode === 200 ? 0 : 1);
+    }).on('error', () => process.exit(1));
+  " 2>/dev/null
+}
+
+# ========== Platform Detection ==========
+
+echo ""
+echo "=== Brainstorm Server Windows Lifecycle Tests ==="
+echo "Platform: ${OSTYPE:-unknown}"
+echo "MSYSTEM: ${MSYSTEM:-unset}"
+echo "Node: $(node --version 2>/dev/null || echo 'not found')"
+echo ""
+
+is_windows="false"
+case "${OSTYPE:-}" in
+  msys*|cygwin*|mingw*) is_windows="true" ;;
+esac
+if [[ -n "${MSYSTEM:-}" ]]; then
+  is_windows="true"
+fi
+
+if [[ "$is_windows" != "true" ]]; then
+  echo "NOTE: Not running on Windows/MSYS2 (OSTYPE=${OSTYPE:-unset})."
+  echo "Windows-specific tests will be skipped. Tests 4-6 still run."
+  echo ""
+fi
+
+mkdir -p "$TEST_DIR"
+
+SERVER_PID=""
+CONTROL_PID=""
+STOP_TEST_PID=""
+
+# ========== Test 1: OWNER_PID is empty on Windows ==========
+
+echo "--- Owner PID Resolution ---"
+
+if [[ "$is_windows" == "true" ]]; then
+  # Replicate the PID resolution logic from start-server.sh lines 104-112
+  TEST_OWNER_PID="$(ps -o ppid= -p "$PPID" 2>/dev/null | tr -d ' ' || true)"
+  if [[ -z "$TEST_OWNER_PID" || "$TEST_OWNER_PID" == "1" ]]; then
+    TEST_OWNER_PID="$PPID"
+  fi
+  # The fix: clear on Windows
+  case "${OSTYPE:-}" in
+    msys*|cygwin*|mingw*) TEST_OWNER_PID="" ;;
+  esac
+
+  if [[ -z "$TEST_OWNER_PID" ]]; then
+    pass "OWNER_PID is empty on Windows after fix"
+  else
+    fail "OWNER_PID is empty on Windows after fix" \
+         "Expected empty, got '$TEST_OWNER_PID'"
+  fi
+else
+  skip "OWNER_PID is empty on Windows" "not on Windows"
+fi
+
+# ========== Test 2: start-server.sh passes empty BRAINSTORM_OWNER_PID ==========
+
+if [[ "$is_windows" == "true" ]]; then
+  # Use a fake 'node' that captures the env var and exits
+  FAKE_NODE_DIR="$TEST_DIR/fake-bin"
+  mkdir -p "$FAKE_NODE_DIR"
+  cat > "$FAKE_NODE_DIR/node" <<'FAKENODE'
+#!/usr/bin/env bash
+echo "CAPTURED_OWNER_PID=${BRAINSTORM_OWNER_PID:-__UNSET__}"
+exit 0
+FAKENODE
+  chmod +x "$FAKE_NODE_DIR/node"
+
+  captured=$(PATH="$FAKE_NODE_DIR:$PATH" bash "$START_SCRIPT" --project-dir "$TEST_DIR/session" --foreground 2>/dev/null || true)
+  owner_pid_value=$(echo "$captured" | grep "CAPTURED_OWNER_PID=" | head -1 | sed 's/CAPTURED_OWNER_PID=//')
+
+  if [[ "$owner_pid_value" == "" || "$owner_pid_value" == "__UNSET__" ]]; then
+    pass "start-server.sh passes empty BRAINSTORM_OWNER_PID on Windows"
+  else
+    fail "start-server.sh passes empty BRAINSTORM_OWNER_PID on Windows" \
+         "Expected empty or unset, got '$owner_pid_value'"
+  fi
+
+  rm -rf "$FAKE_NODE_DIR" "$TEST_DIR/session"
+else
+  skip "start-server.sh passes empty BRAINSTORM_OWNER_PID" "not on Windows"
+fi
+
+# ========== Test 3: Auto-foreground detection on Windows ==========
+
+echo ""
+echo "--- Foreground Mode Detection ---"
+
+if [[ "$is_windows" == "true" ]]; then
+  FAKE_NODE_DIR="$TEST_DIR/fake-bin"
+  mkdir -p "$FAKE_NODE_DIR"
+  cat > "$FAKE_NODE_DIR/node" <<'FAKENODE'
+#!/usr/bin/env bash
+echo "FOREGROUND_MODE=true"
+exit 0
+FAKENODE
+  chmod +x "$FAKE_NODE_DIR/node"
+
+  # Run WITHOUT --foreground flag — Windows should auto-detect
+  captured=$(PATH="$FAKE_NODE_DIR:$PATH" bash "$START_SCRIPT" --project-dir "$TEST_DIR/session2" 2>/dev/null || true)
+
+  if echo "$captured" | grep -q "FOREGROUND_MODE=true"; then
+    pass "Windows auto-detects foreground mode"
+  else
+    fail "Windows auto-detects foreground mode" \
+         "Expected foreground code path, output: $captured"
+  fi
+
+  rm -rf "$FAKE_NODE_DIR" "$TEST_DIR/session2"
+else
+  skip "Windows auto-detects foreground mode" "not on Windows"
+fi
+
+# ========== Test 4: Server survives past 60-second lifecycle check ==========
+
+echo ""
+echo "--- Server Survival (lifecycle check) ---"
+
+mkdir -p "$TEST_DIR/survival"
+
+echo "  Starting server (will wait ~75s to verify survival past lifecycle check)..."
+
+BRAINSTORM_DIR="$TEST_DIR/survival" \
+BRAINSTORM_HOST="127.0.0.1" \
+BRAINSTORM_URL_HOST="localhost" \
+BRAINSTORM_OWNER_PID="" \
+BRAINSTORM_PORT=$((49152 + RANDOM % 16383)) \
+  node "$SERVER_JS" > "$TEST_DIR/survival/.server.log" 2>&1 &
+SERVER_PID=$!
+
+if ! wait_for_server_info "$TEST_DIR/survival"; then
+  fail "Server starts successfully" "Server did not write .server-info within 5 seconds"
+  kill "$SERVER_PID" 2>/dev/null || true
+  SERVER_PID=""
+else
+  pass "Server starts successfully with empty OWNER_PID"
+
+  SERVER_PORT=$(get_port_from_info "$TEST_DIR/survival")
+
+  sleep 75
+
+  if kill -0 "$SERVER_PID" 2>/dev/null; then
+    pass "Server is still alive after 75 seconds"
+  else
+    fail "Server is still alive after 75 seconds" \
+         "Server died. Log tail: $(tail -5 "$TEST_DIR/survival/.server.log" 2>/dev/null)"
+  fi
+
+  if http_check "$SERVER_PORT"; then
+    pass "Server responds to HTTP after lifecycle check window"
+  else
+    fail "Server responds to HTTP after lifecycle check window" \
+         "HTTP request to port $SERVER_PORT failed"
+  fi
+
+  if grep -q "owner process exited" "$TEST_DIR/survival/.server.log" 2>/dev/null; then
+    fail "No 'owner process exited' in logs" \
+         "Found spurious owner-exit shutdown in log"
+  else
+    pass "No 'owner process exited' in logs"
+  fi
+
+  kill "$SERVER_PID" 2>/dev/null || true
+  wait "$SERVER_PID" 2>/dev/null || true
+  SERVER_PID=""
+fi
+
+# ========== Test 5: Bad OWNER_PID causes shutdown (control) ==========
+
+echo ""
+echo "--- Control: Bad OWNER_PID causes shutdown ---"
+
+mkdir -p "$TEST_DIR/control"
+
+# Find a PID that does not exist
+BAD_PID=99999
+while kill -0 "$BAD_PID" 2>/dev/null; do
+  BAD_PID=$((BAD_PID + 1))
+done
+
+BRAINSTORM_DIR="$TEST_DIR/control" \
+BRAINSTORM_HOST="127.0.0.1" \
+BRAINSTORM_URL_HOST="localhost" \
+BRAINSTORM_OWNER_PID="$BAD_PID" \
+BRAINSTORM_PORT=$((49152 + RANDOM % 16383)) \
+  node "$SERVER_JS" > "$TEST_DIR/control/.server.log" 2>&1 &
+CONTROL_PID=$!
+
+if ! wait_for_server_info "$TEST_DIR/control"; then
+  fail "Control server starts" "Server did not write .server-info within 5 seconds"
+  kill "$CONTROL_PID" 2>/dev/null || true
+  CONTROL_PID=""
+else
+  pass "Control server starts with bad OWNER_PID=$BAD_PID"
+
+  echo "  Waiting ~75s for lifecycle check to kill server..."
+  sleep 75
+
+  if kill -0 "$CONTROL_PID" 2>/dev/null; then
+    fail "Control server self-terminates with bad OWNER_PID" \
+         "Server is still alive (expected it to die)"
+    kill "$CONTROL_PID" 2>/dev/null || true
+  else
+    pass "Control server self-terminates with bad OWNER_PID"
+  fi
+
+  if grep -q "owner process exited" "$TEST_DIR/control/.server.log" 2>/dev/null; then
+    pass "Control server logs 'owner process exited'"
+  else
+    fail "Control server logs 'owner process exited'" \
+         "Log tail: $(tail -5 "$TEST_DIR/control/.server.log" 2>/dev/null)"
+  fi
+fi
+
+wait "$CONTROL_PID" 2>/dev/null || true
+CONTROL_PID=""
+
+# ========== Test 6: stop-server.sh cleanly stops the server ==========
+
+echo ""
+echo "--- Clean Shutdown ---"
+
+mkdir -p "$TEST_DIR/stop-test"
+
+BRAINSTORM_DIR="$TEST_DIR/stop-test" \
+BRAINSTORM_HOST="127.0.0.1" \
+BRAINSTORM_URL_HOST="localhost" \
+BRAINSTORM_OWNER_PID="" \
+BRAINSTORM_PORT=$((49152 + RANDOM % 16383)) \
+  node "$SERVER_JS" > "$TEST_DIR/stop-test/.server.log" 2>&1 &
+STOP_TEST_PID=$!
+echo "$STOP_TEST_PID" > "$TEST_DIR/stop-test/.server.pid"
+
+if ! wait_for_server_info "$TEST_DIR/stop-test"; then
+  fail "Stop-test server starts" "Server did not start"
+  kill "$STOP_TEST_PID" 2>/dev/null || true
+  STOP_TEST_PID=""
+else
+  bash "$STOP_SCRIPT" "$TEST_DIR/stop-test" >/dev/null 2>&1 || true
+  sleep 1
+
+  if ! kill -0 "$STOP_TEST_PID" 2>/dev/null; then
+    pass "stop-server.sh cleanly stops the server"
+  else
+    fail "stop-server.sh cleanly stops the server" \
+         "Server PID $STOP_TEST_PID is still alive after stop"
+    kill "$STOP_TEST_PID" 2>/dev/null || true
+  fi
+fi
+
+wait "$STOP_TEST_PID" 2>/dev/null || true
+STOP_TEST_PID=""
+
+# ========== Summary ==========
+
+echo ""
+echo "=== Results: $passed passed, $failed failed, $skipped skipped ==="
+
+if [[ $failed -gt 0 ]]; then
+  exit 1
+fi
+exit 0

tests/brainstorm-server/ws-protocol.test.js

@@ -16,7 +16,7 @@ const crypto = require('crypto');
 const path = require('path');
 
 // The module under test — will be the new zero-dep server file
-const SERVER_PATH = path.join(__dirname, '../../skills/brainstorming/scripts/server.js');
+const SERVER_PATH = path.join(__dirname, '../../skills/brainstorming/scripts/server.cjs');
 let ws;
 
 try {