@dtt_siye/atool 1.1.0

package/skills/_superpowers/docs/superpowers/specs/2026-02-19-visual-brainstorming-refactor-design.md

@@ -0,0 +1,162 @@
+# Visual Brainstorming Refactor: Browser Displays, Terminal Commands
+
+**Date:** 2026-02-19
+**Status:** Approved
+**Scope:** `lib/brainstorm-server/`, `skills/brainstorming/visual-companion.md`, `tests/brainstorm-server/`
+
+## Problem
+
+During visual brainstorming, Claude runs `wait-for-feedback.sh` as a background task and blocks on `TaskOutput(block=true, timeout=600s)`. This seizes the TUI entirely — the user cannot type to Claude while visual brainstorming is running. The browser becomes the only input channel.
+
+Claude Code's execution model is turn-based. There is no way for Claude to listen on two channels simultaneously within a single turn. The blocking `TaskOutput` pattern was the wrong primitive — it simulates event-driven behavior the platform doesn't support.
+
+## Design
+
+### Core Model
+
+**Browser = interactive display.** Shows mockups, lets the user click to select options. Selections are recorded server-side.
+
+**Terminal = conversation channel.** Always unblocked, always available. The user talks to Claude here.
+
+### The Loop
+
+1. Claude writes an HTML file to the session directory
+2. Server detects it via chokidar, pushes WebSocket reload to the browser (unchanged)
+3. Claude ends its turn — tells the user to check the browser and respond in the terminal
+4. User looks at browser, optionally clicks to select an option, then types feedback in the terminal
+5. On the next turn, Claude reads `$SCREEN_DIR/.events` for the browser interaction stream (clicks, selections), merges with the terminal text
+6. Iterate or advance
+
+No background tasks. No `TaskOutput` blocking. No polling scripts.
+
+### Key Deletion: `wait-for-feedback.sh`
+
+Deleted entirely. Its purpose was to bridge "server logs events to stdout" and "Claude needs to receive those events." The `.events` file replaces this — the server writes user interaction events directly, and Claude reads them with whatever file-reading mechanism the platform provides.
+
+### Key Addition: `.events` File (Per-Screen Event Stream)
+
+The server writes all user interaction events to `$SCREEN_DIR/.events`, one JSON object per line. This gives Claude the full interaction stream for the current screen — not just the final selection, but the user's exploration path (clicked A, then B, settled on C).
+
+Example contents after a user explores options:
+
+```jsonl
+{"type":"click","choice":"a","text":"Option A - Preset-First Wizard","timestamp":1706000101}
+{"type":"click","choice":"c","text":"Option C - Manual Config","timestamp":1706000108}
+{"type":"click","choice":"b","text":"Option B - Hybrid Approach","timestamp":1706000115}
+```
+
+- Append-only within a screen. Each user event is appended as a new line.
+- The file is cleared (deleted) when chokidar detects a new HTML file (new screen pushed), preventing stale events from carrying over.
+- If the file doesn't exist when Claude reads it, no browser interaction occurred — Claude uses only the terminal text.
+- The file contains only user events (`click`, etc.) — not server lifecycle events (`server-started`, `screen-added`). This keeps it small and focused.
+- Claude can read the full stream to understand the user's exploration pattern, or just look at the last `choice` event for the final selection.
+
+## Changes by File
+
+### `index.js` (server)
+
+**A. Write user events to `.events` file.**
+
+In the WebSocket `message` handler, after logging the event to stdout: append the event as a JSON line to `$SCREEN_DIR/.events` via `fs.appendFileSync`. Only write user interaction events (those with `source: 'user-event'`), not server lifecycle events.
+
+**B. Clear `.events` on new screen.**
+
+In the chokidar `add` handler (new `.html` file detected), delete `$SCREEN_DIR/.events` if it exists. This is the definitive "new screen" signal — better than clearing on GET `/` which fires on every reload.
+
+**C. Replace `wrapInFrame` content injection.**
+
+The current regex anchors on `<div class="feedback-footer">`, which is being removed. Replace with a comment placeholder: remove the existing default content inside `#claude-content` (the `<h2>Visual Brainstorming</h2>` and subtitle paragraph) and replace with a single `<!-- CONTENT -->` marker. Content injection becomes `frameTemplate.replace('<!-- CONTENT -->', content)`. Simpler and won't break if template formatting changes.
+
+### `frame-template.html` (UI frame)
+
+**Remove:**
+- The `feedback-footer` div (textarea, Send button, label, `.feedback-row`)
+- Associated CSS (`.feedback-footer`, `.feedback-footer label`, `.feedback-row`, textarea and button styles within it)
+
+**Add:**
+- `<!-- CONTENT -->` placeholder inside `#claude-content`, replacing the default text
+- A selection indicator bar where the footer was, with two states:
+  - Default: "Click an option above, then return to the terminal"
+  - After selection: "Option B selected — return to terminal to continue"
+- CSS for the indicator bar (subtle, similar visual weight to the existing header)
+
+**Keep unchanged:**
+- Header bar with "Brainstorm Companion" title and connection status
+- `.main` wrapper and `#claude-content` container
+- All component CSS (`.options`, `.cards`, `.mockup`, `.split`, `.pros-cons`, placeholders, mock elements)
+- Dark/light theme variables and media query
+
+### `helper.js` (client-side script)
+
+**Remove:**
+- `sendToClaude()` function and the "Sent to Claude" page takeover
+- `window.send()` function (was tied to the removed Send button)
+- Form submission handler — no purpose without the feedback textarea, adds log noise
+- Input change handler — same reason
+- `pageshow` event listener (was added to fix textarea persistence — no textarea anymore)
+
+**Keep:**
+- WebSocket connection, reconnect logic, event queue
+- Reload handler (`window.location.reload()` on server push)
+- `window.toggleSelect()` for selection highlighting
+- `window.selectedChoice` tracking
+- `window.brainstorm.send()` and `window.brainstorm.choice()` — these are distinct from the removed `window.send()`. They call `sendEvent` which logs to the server via WebSocket. Useful for custom full-document pages.
+
+**Narrow:**
+- Click handler: capture only `[data-choice]` clicks, not all buttons/links. The broad capture was needed when the browser was a feedback channel; now it's just for selection tracking.
+
+**Add:**
+- On `data-choice` click, update the selection indicator bar text to show which option was selected.
+
+**Remove from `window.brainstorm` API:**
+- `brainstorm.sendToClaude` — no longer exists
+
+### `visual-companion.md` (skill instructions)
+
+**Rewrite "The Loop" section** to the non-blocking flow described above. Remove all references to:
+- `wait-for-feedback.sh`
+- `TaskOutput` blocking
+- Timeout/retry logic (600s timeout, 30-minute cap)
+- "User Feedback Format" section describing `send-to-claude` JSON
+
+**Replace with:**
+- The new loop (write HTML → end turn → user responds in terminal → read `.events` → iterate)
+- `.events` file format documentation
+- Guidance that the terminal message is the primary feedback; `.events` provides the full browser interaction stream for additional context
+
+**Keep:**
+- Server startup/shutdown instructions
+- Content fragment vs full document guidance
+- CSS class reference and available components
+- Design tips (scale fidelity to the question, 2-4 options per screen, etc.)
+
+### `wait-for-feedback.sh`
+
+**Deleted entirely.**
+
+### `tests/brainstorm-server/server.test.js`
+
+Tests that need updating:
+- Test asserting `feedback-footer` presence in fragment responses — update to assert the selection indicator bar or `<!-- CONTENT -->` replacement
+- Test asserting `helper.js` contains `send` — update to reflect narrowed API
+- Test asserting `sendToClaude` CSS variable usage — remove (function no longer exists)
+
+## Platform Compatibility
+
+The server code (`index.js`, `helper.js`, `frame-template.html`) is fully platform-agnostic — pure Node.js and browser JavaScript. No Claude Code-specific references. Already proven to work on Codex via background terminal interaction.
+
+The skill instructions (`visual-companion.md`) are the platform-adaptive layer. Each platform's Claude uses its own tools to start the server, read `.events`, etc. The non-blocking model works naturally across platforms since it doesn't depend on any platform-specific blocking primitive.
+
+## What This Enables
+
+- **TUI always responsive** during visual brainstorming
+- **Mixed input** — click in browser + type in terminal, naturally merged
+- **Graceful degradation** — browser down or user doesn't open it? Terminal still works
+- **Simpler architecture** — no background tasks, no polling scripts, no timeout management
+- **Cross-platform** — same server code works on Claude Code, Codex, and any future platform
+
+## What This Drops
+
+- **Pure-browser feedback workflow** — user must return to the terminal to continue. The selection indicator bar guides them, but it's one extra step compared to the old click-Send-and-wait flow.
+- **Inline text feedback from browser** — the textarea is gone. All text feedback goes through the terminal. This is intentional — the terminal is a better text input channel than a small textarea in a frame.
+- **Immediate response on browser Send** — the old system had Claude respond the moment the user clicked Send. Now there's a gap while the user switches to the terminal. In practice this is seconds, and the user gets to add context in their terminal message.

package/skills/_superpowers/docs/superpowers/specs/2026-03-11-zero-dep-brainstorm-server-design.md

@@ -0,0 +1,118 @@
+# Zero-Dependency Brainstorm Server
+
+Replace the brainstorm companion server's vendored node_modules (express, ws, chokidar — 714 tracked files) with a single zero-dependency `server.js` using only Node.js built-ins.
+
+## Motivation
+
+Vendoring node_modules into the git repo creates a supply chain risk: frozen dependencies don't get security patches, 714 files of third-party code are committed without audit, and modifications to vendored code look like normal commits. While the actual risk is low (localhost-only dev server), eliminating it is straightforward.
+
+## Architecture
+
+A single `server.js` file (~250-300 lines) using `http`, `crypto`, `fs`, and `path`. The file serves two roles:
+
+- **When run directly** (`node server.js`): starts the HTTP/WebSocket server
+- **When required** (`require('./server.js')`): exports WebSocket protocol functions for unit testing
+
+### WebSocket Protocol
+
+Implements RFC 6455 for text frames only:
+
+**Handshake:** Compute `Sec-WebSocket-Accept` from client's `Sec-WebSocket-Key` using SHA-1 + the RFC 6455 magic GUID. Return 101 Switching Protocols.
+
+**Frame decoding (client to server):** Handle three masked length encodings:
+- Small: payload < 126 bytes
+- Medium: 126-65535 bytes (16-bit extended)
+- Large: > 65535 bytes (64-bit extended)
+
+XOR-unmask payload using 4-byte mask key. Return `{ opcode, payload, bytesConsumed }` or `null` for incomplete buffers. Reject unmasked frames.
+
+**Frame encoding (server to client):** Unmasked frames with the same three length encodings.
+
+**Opcodes handled:** TEXT (0x01), CLOSE (0x08), PING (0x09), PONG (0x0A). Unrecognized opcodes get a close frame with status 1003 (Unsupported Data).
+
+**Deliberately skipped:** Binary frames, fragmented messages, extensions (permessage-deflate), subprotocols. These are unnecessary for small JSON text messages between localhost clients. Extensions and subprotocols are negotiated in the handshake — by not advertising them, they are never active.
+
+**Buffer accumulation:** Each connection maintains a buffer. On `data`, append and loop `decodeFrame` until it returns null or buffer is empty.
+
+### HTTP Server
+
+Three routes:
+
+1. **`GET /`** — Serve newest `.html` from screen directory by mtime. Detect full documents vs fragments, wrap fragments in frame template, inject helper.js. Return `text/html`. When no `.html` files exist, serve a hardcoded waiting page ("Waiting for Claude to push a screen...") with helper.js injected.
+2. **`GET /files/*`** — Serve static files from screen directory with MIME type lookup from a hardcoded extension map (html, css, js, png, jpg, gif, svg, json). Return 404 if not found.
+3. **Everything else** — 404.
+
+WebSocket upgrade handled via the `'upgrade'` event on the HTTP server, separate from the request handler.
+
+### Configuration
+
+Environment variables (all optional):
+
+- `BRAINSTORM_PORT` — port to bind (default: random high port 49152-65535)
+- `BRAINSTORM_HOST` — interface to bind (default: `127.0.0.1`)
+- `BRAINSTORM_URL_HOST` — hostname for the URL in startup JSON (default: `localhost` when host is `127.0.0.1`, otherwise same as host)
+- `BRAINSTORM_DIR` — screen directory path (default: `/tmp/brainstorm`)
+
+### Startup Sequence
+
+1. Create `SCREEN_DIR` if it doesn't exist (`mkdirSync` recursive)
+2. Load frame template and helper.js from `__dirname`
+3. Start HTTP server on configured host/port
+4. Start `fs.watch` on `SCREEN_DIR`
+5. On successful listen, log `server-started` JSON to stdout: `{ type, port, host, url_host, url, screen_dir }`
+6. Write the same JSON to `SCREEN_DIR/.server-info` so agents can find connection details when stdout is hidden (background execution)
+
+### Application-Level WebSocket Messages
+
+When a TEXT frame arrives from a client:
+
+1. Parse as JSON. If parsing fails, log to stderr and continue.
+2. Log to stdout as `{ source: 'user-event', ...event }`.
+3. If the event contains a `choice` property, append the JSON to `SCREEN_DIR/.events` (one line per event).
+
+### File Watching
+
+`fs.watch(SCREEN_DIR)` replaces chokidar. On HTML file events:
+
+- On new file (`rename` event for a file that exists): delete `.events` file if present (`unlinkSync`), log `screen-added` to stdout as JSON
+- On file change (`change` event): log `screen-updated` to stdout as JSON (do NOT clear `.events`)
+- Both events: send `{ type: 'reload' }` to all connected WebSocket clients
+
+Debounce per-filename with ~100ms timeout to prevent duplicate events (common on macOS and Linux).
+
+### Error Handling
+
+- Malformed JSON from WebSocket clients: log to stderr, continue
+- Unhandled opcodes: close with status 1003
+- Client disconnects: remove from broadcast set
+- `fs.watch` errors: log to stderr, continue
+- No graceful shutdown logic — shell scripts handle process lifecycle via SIGTERM
+
+## What Changes
+
+| Before | After |
+|---|---|
+| `index.js` + `package.json` + `package-lock.json` + 714 `node_modules` files | `server.js` (single file) |
+| express, ws, chokidar dependencies | none |
+| No static file serving | `/files/*` serves from screen directory |
+
+## What Stays the Same
+
+- `helper.js` — no changes
+- `frame-template.html` — no changes
+- `start-server.sh` — one-line update: `index.js` to `server.js`
+- `stop-server.sh` — no changes
+- `visual-companion.md` — no changes
+- All existing server behavior and external contract
+
+## Platform Compatibility
+
+- `server.js` uses only cross-platform Node built-ins
+- `fs.watch` is reliable for single flat directories on macOS, Linux, and Windows
+- Shell scripts require bash (Git Bash on Windows, which is required for Claude Code)
+
+## Testing
+
+**Unit tests** (`ws-protocol.test.js`): Test WebSocket frame encoding/decoding, handshake computation, and protocol edge cases directly by requiring `server.js` exports.
+
+**Integration tests** (`server.test.js`): Test full server behavior — HTTP serving, WebSocket communication, file watching, brainstorming workflow. Uses `ws` npm package as a test-only client dependency (not shipped to end users).

package/skills/_superpowers/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