docs(codex-tools): add named agent dispatch mapping for Codex (#647)

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>

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

@@ -237,18 +237,6 @@ If a third skill needs the same detection pattern, extract it into a shared `ref
 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.
 
-### Manual Test Results (2026-03-23)
-
-| Test | Result | Notes |
-|------|--------|-------|
-| 1. Detection in Worktree thread (workspace-write) | PASS | GIT_DIR != GIT_COMMON, BRANCH empty |
-| 2. Detection in Worktree thread (Full access) | PASS | Same detection; Full access allows `git checkout -b` |
-| 3. Finishing skill handoff format | PASS (after fix) | Initially FAILED — Step 1.5 was unreachable because Step 1 (test verification) halted first. Fixed by reordering: environment detection is now Step 1, test verification is Step 2. Path A skips tests entirely. |
-| 4. Full lifecycle | PASS | Detection → commit → handoff payload → no cleanup attempt |
-| 5. Sandbox fallback in Local thread | N/A | Local thread workspace-write sandbox does not block `git checkout -b`; Seatbelt restriction not triggered in current Codex App version |
-
-**Fix applied:** `c5d93ac` — moved environment detection before test verification in `finishing-a-development-branch/SKILL.md`. Step numbering changed: old Step 1.5 → new Step 1, old Step 1 → new Step 2, all downstream steps renumbered.
-
 ### Regression
 
 - Existing Claude Code skill-triggering tests still pass

skills/executing-plans/SKILL.md

@@ -65,6 +65,6 @@ After all tasks complete and verified:
 ## Integration
 
 **Required workflow skills:**
-- **superpowers:using-git-worktrees** - REQUIRED: Ensures isolated workspace (creates one or verifies existing)
+- **superpowers:using-git-worktrees** - REQUIRED: Set up isolated workspace before starting
 - **superpowers:writing-plans** - Creates the plan this skill executes
 - **superpowers:finishing-a-development-branch** - Complete development after all tasks

skills/finishing-a-development-branch/SKILL.md

@@ -15,55 +15,7 @@ Guide completion of development work by presenting clear options and handling ch
 
 ## The Process
 
-### Step 1: Detect Environment
-
-Run this FIRST, before test verification:
-
-````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):**
-
-This is a restricted sandbox environment (e.g., Codex App worktree thread). The test toolchain may not be available. Do NOT attempt test verification — skip directly to the handoff.
-
-First, ensure all work is staged and committed (`git add` + `git commit`). If staging/committing fails due to sandbox restrictions, note the uncommitted files in the handoff message.
-
-Then present this to the user (do NOT present the 4-option menu):
-
-```
-Implementation complete.
-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 6 (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 (verify tests, then 4-option menu).
-
-**Path C — `GIT_DIR` equals `GIT_COMMON` (normal environment):**
-
-Proceed to Step 2 (verify tests, then 4-option menu).
-
-### Step 2: Verify Tests
+### Step 1: Verify Tests
 
 **Before presenting options, verify tests pass:**
 
@@ -81,11 +33,11 @@ Tests failing (<N> failures). Must fix before completing:
 Cannot proceed with merge/PR until tests pass.
 ```
 
-Stop. Don't proceed to Step 3.
+Stop. Don't proceed to Step 2.
 
-**If tests pass:** Continue to Step 3.
+**If tests pass:** Continue to Step 2.
 
-### Step 3: Determine Base Branch
+### Step 2: Determine Base Branch
 
 ```bash
 # Try common base branches
@@ -94,7 +46,7 @@ git merge-base HEAD main 2>/dev/null || git merge-base HEAD master 2>/dev/null
 
 Or ask: "This branch split from main - is that correct?"
 
-### Step 4: Present Options
+### Step 3: Present Options
 
 Present exactly these 4 options:
 
@@ -111,7 +63,7 @@ Which option?
 
 **Don't add explanation** - keep options concise.
 
-### Step 5: Execute Choice
+### Step 4: Execute Choice
 
 #### Option 1: Merge Locally
 
@@ -132,7 +84,7 @@ git merge <feature-branch>
 git branch -d <feature-branch>
 ```
 
-Then: Cleanup worktree (Step 6)
+Then: Cleanup worktree (Step 5)
 
 #### Option 2: Push and Create PR
 
@@ -151,7 +103,7 @@ EOF
 )"
 ```
 
-Then: Cleanup worktree (Step 6)
+Then: Cleanup worktree (Step 5)
 
 #### Option 3: Keep As-Is
 
@@ -179,20 +131,11 @@ git checkout <base-branch>
 git branch -D <feature-branch>
 ```
 
-Then: Cleanup worktree (Step 6)
+Then: Cleanup worktree (Step 5)
 
-### Step 6: Cleanup Worktree
+### 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:**
+**For Options 1, 2, 4:**
 
 Check if in worktree:
 ```bash

skills/subagent-driven-development/SKILL.md

@@ -265,7 +265,7 @@ Done!
 ## Integration
 
 **Required workflow skills:**
-- **superpowers:using-git-worktrees** - REQUIRED: Ensures isolated workspace (creates one or verifies existing)
+- **superpowers:using-git-worktrees** - REQUIRED: Set up isolated workspace before starting
 - **superpowers:writing-plans** - Creates the plan this skill executes
 - **superpowers:requesting-code-review** - Code review template for reviewer subagents
 - **superpowers:finishing-a-development-branch** - Complete development after all tasks

skills/using-git-worktrees/SKILL.md

@@ -13,30 +13,6 @@ Git worktrees create isolated workspaces sharing the same repository, allowing w
 
 **Announce at start:** "I'm using the using-git-worktrees skill to set up an isolated workspace."
 
-## 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.
-
 ## Directory Selection Process
 
 Follow this priority order:
@@ -233,9 +209,9 @@ Ready to implement auth feature
 ## Integration
 
 **Called by:**
-- **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)
+- **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
 - Any skill needing isolated workspace
 
 **Pairs with:**

skills/writing-skills/SKILL.md

@@ -93,7 +93,7 @@ skills/
 ## SKILL.md Structure
 
 **Frontmatter (YAML):**
-- Two required fields: `name` and `description` (see [agentskills.io/specification](https://agentskills.io/specification) for all supported fields)
+- Only two fields supported: `name` and `description`
 - 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 required `name` and `description` fields (max 1024 chars; see [spec](https://agentskills.io/specification))
+- [ ] YAML frontmatter with only name and description (max 1024 chars)
 - [ ] 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 requires two fields:
+  **YAML Frontmatter**: The SKILL.md frontmatter supports 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 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.
+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.
 
 ### Token budgets
 

tests/codex-app-compat/test-environment-detection.sh

@@ -1,94 +0,0 @@
-#!/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