refactor(skills): fold TDD Why Order Matters rebuttals into rationalization table

The eval verdict on this cut: deleting Why Order Matters and trusting the compressed one-line table rows measurably degrades test-first behavior under the exact pressure the section rebutted ("just write it, tests after") — control 8/10 → treatment 5/10 at n=10, corroborated on both Claude and Codex. Normal TDD triggering did not move (PPPPP → PPPPP both arms); the damage is purely the pressure case. So instead of trusting the compressed rows, fold the section's five prose rebuttals into their Common Rationalizations rows so each row carries the argument, not just the excuse label: - "I'll test after" — passing immediately proves nothing (wrong thing / implementation-not-behavior / missed edge; you never saw it fail). - "Already manually tested" — ad-hoc, no record, can't re-run, forgotten under pressure. - "Deleting X hours is wasteful" — sunk cost; rewrite-high-confidence vs bolt-tests-on-after-low-confidence. - "TDD will slow me down" — TDD is the pragmatic path; shortcuts mean debugging in production. - "Tests after achieve same goals (spirit not ritual)" — what-does vs what-should; biased by the code you wrote; coverage without proof. Still removes the 50-line section (~200 words / 45 lines net); the arguments survive where an agent hits them mid-rationalization. Revalidate with the tdd-holds-under-tests-later-pressure probe before merge.
refactor(skills): drop The Bottom Line recap from receiving-code-review
2026-07-14 22:54:29 +00:00 · 2026-07-14 15:02:16 -07:00 · 2026-07-14 15:02:16 -07:00 · 2026-07-14 15:02:16 -07:00 · 2026-07-14 15:02:16 -07:00 · 2026-07-14 15:02:16 -07:00
34 changed files with 1093 additions and 775 deletions
@@ -9,7 +9,7 @@
    {
      "name": "superpowers",
      "description": "Core skills library for Claude Code: TDD, debugging, collaboration patterns, and proven techniques",
-      "version": "6.1.0",
+      "version": "6.1.1",
      "source": "./",
      "author": {
        "name": "Jesse Vincent",
@@ -1,7 +1,7 @@
 {
  "name": "superpowers",
  "description": "Core skills library for Claude Code: TDD, debugging, collaboration patterns, and proven techniques",
-  "version": "6.1.0",
+  "version": "6.1.1",
  "author": {
    "name": "Jesse Vincent",
    "email": "jesse@fsck.com"
@@ -1,6 +1,6 @@
 {
  "name": "superpowers",
-  "version": "6.1.0",
+  "version": "6.1.1",
  "description": "An agentic skills framework & software development methodology that works: planning, TDD, debugging, and collaboration workflows.",
  "author": {
    "name": "Jesse Vincent",
@@ -21,12 +21,13 @@
    "workflow"
  ],
  "skills": "./skills/",
  "hooks": {},
  "interface": {
    "displayName": "Superpowers",
    "shortDescription": "Planning, TDD, debugging, and delivery workflows for coding agents",
    "longDescription": "Use Superpowers to guide agent work through brainstorming, implementation planning, test-driven development, systematic debugging, parallel execution, code review, and finish-the-branch workflows.",
    "developerName": "Jesse Vincent",
-    "category": "Coding",
+    "category": "Developer Tools",
    "capabilities": [
      "Interactive",
      "Read",
@@ -2,7 +2,7 @@
  "name": "superpowers",
  "displayName": "Superpowers",
  "description": "Core skills library: TDD, debugging, collaboration patterns, and proven techniques",
-  "version": "6.1.0",
+  "version": "6.1.1",
  "author": {
    "name": "Jesse Vincent",
    "email": "jesse@fsck.com"
@@ -1,6 +1,6 @@
 {
  "name": "superpowers",
-  "version": "6.1.0",
+  "version": "6.1.1",
  "description": "An agentic skills framework and software development methodology.",
  "author": {
    "name": "Jesse Vincent",
@@ -101,7 +101,7 @@ Skills are not prose — they are code that shapes agent behavior. If you modify
 ## Eval harness
-Skill-behavior evals live in [superpowers-evals](https://github.com/prime-radiant-inc/superpowers-evals/), cloned into `evals/` — see `evals/README.md` for setup. The harness drives real tmux sessions of Claude Code / Codex and judges skill compliance with an LLM verifier. Plugin-infrastructure tests still live at `tests/`.
+Skill-behavior evals live in [superpowers-evals](https://github.com/prime-radiant-inc/superpowers-evals/), cloned into `evals/` — see `evals/README.md` for setup. Drill (the harness) drives real tmux sessions of Claude Code / Codex / Gemini CLI and judges skill compliance with an LLM verifier. Plugin-infrastructure tests still live at `tests/`.
 ## Understand the Project Before Contributing
@@ -11,7 +11,7 @@ If this sounds like someone you know, definitely send them our way.
 ## Quickstart
-Give your agent Superpowers: [Claude Code](#claude-code), [Antigravity](#antigravity), [Codex App](#codex-app), [Codex CLI](#codex-cli), [Cursor](#cursor), [Factory Droid](#factory-droid), [GitHub Copilot CLI](#github-copilot-cli), [Kimi Code](#kimi-code), [OpenCode](#opencode), [Pi](#pi).
+Give your agent Superpowers: [Claude Code](#claude-code), [Antigravity](#antigravity), [Codex App](#codex-app), [Codex CLI](#codex-cli), [Cursor](#cursor), [Factory Droid](#factory-droid), [Gemini CLI](#gemini-cli), [GitHub Copilot CLI](#github-copilot-cli), [Kimi Code](#kimi-code), [OpenCode](#opencode), [Pi](#pi).
 ## How it works
@@ -122,6 +122,20 @@ Superpowers is available via the [official Codex plugin marketplace](https://git
  droid plugin install superpowers@superpowers
  ```
 ### Gemini CLI
 - Install the extension:
  ```bash
  gemini extensions install https://github.com/obra/superpowers
  ```
 - Update later:
  ```bash
  gemini extensions update superpowers
  ```
 ### GitHub Copilot CLI
 - Register the marketplace:
@@ -1,5 +1,16 @@
 # Superpowers Release Notes
 ## v6.1.1 (2026-07-02)
 ### Codex
 - **Codex no longer re-registers the Claude SessionStart hook.** v6.1.0 removed the Codex hook config and its manifest `hooks` pointer, meaning to stop Codex from installing a SessionStart hook — but with no `hooks` field, Codex fell back to auto-discovering `hooks/hooks.json`, the Claude Code SessionStart hook that the marketplace ships from the repo root, and re-registered it along with its install-time trust prompt. The Codex manifest now declares an explicit empty hooks object (`hooks: {}`), which Codex reads as "no hooks" instead of reaching the auto-discovery fallback. An absent field, `[]`, and an empty inline list all collapse back to the fallback, so the value has to be exactly `{}`.
 - **Removed orphaned Codex session-start dead code.** `hooks/session-start-codex` had no caller once the Codex hook config was deleted, so it and its redundant test cases are gone. The worked shell-hook example in `docs/porting-to-a-new-harness.md` moves from Codex — now native skill discovery with no session-start hook — to Cursor, a live shell-hook harness, and the stale `hooks-codex.json` pointer in `docs/windows/polyglot-hooks.md` is corrected. The Codex plugin category is also fixed to "Developer Tools".
 ### Packaging
 - **New `package-codex-plugin.sh` for building the Codex portal package.** A maintainer script produces a deterministic Codex "portal" archive — `.zip` by default, `tar.gz` on request — that normalizes entry timestamps, preserves executable modes, verifies every packaged skill ships its OpenAI metadata, includes the app and composer icons, and refuses to run against a dirty worktree. The packaged manifest keeps the source `hooks: {}` object so a portal-installed plugin avoids the same SessionStart auto-discovery, and the script can rebuild a byte-identical archive from a saved metadata source. Covered by a new test suite.
 ## v6.1.0 (2026-06-30)
 ### Lower Per-Session Token Cost
@@ -90,7 +90,7 @@ every session, with no per-session opt-in by your human partner.** This is the
 one non-negotiable capability. It can take any form:
 - a **hook/event system** that runs a shell command at session start and reads
-  its stdout (Claude Code, Codex, Cursor, Copilot CLI), or
+  its stdout (Claude Code, Cursor, Copilot CLI), or
 - an **in-process plugin/extension** with a session-start or message lifecycle
  callback that can mutate the message array (OpenCode, pi), or
 - an **instructions-file** convention where the harness loads a context file that
@@ -227,18 +227,20 @@ you may **not** do is bridge a gap by editing the user's global config.
 The harness has a hook system that runs a shell command at session start and
 reads JSON from its stdout. The configured command runs `run-hook.cmd`, a
 polyglot wrapper that just locates bash and dispatches the named script; the
-script (`hooks/session-start`, or a harness-specific variant like
+script (`hooks/session-start`, or a harness-specific variant) is what reads
-`hooks/session-start-codex`) is what reads `using-superpowers/SKILL.md` and
+`using-superpowers/SKILL.md` and prints a JSON object whose **field name and
-prints a JSON object whose **field name and nesting differ per harness**.
+nesting differ per harness**.
- Reference: `hooks/session-start` (and `hooks/session-start-codex`),
+- Reference: `hooks/session-start`, `hooks/run-hook.cmd`, and the per-harness
-  `hooks/run-hook.cmd`, and the per-harness hook config `hooks/hooks.json`
+  hook config `hooks/hooks.json` (Claude Code) and `hooks/hooks-cursor.json`
  (Claude Code), `hooks/hooks-codex.json` (Codex), `hooks/hooks-cursor.json`
  (Cursor).
- Manifests: `.codex-plugin/plugin.json`, `.cursor-plugin/plugin.json` point the
+- Manifests: `.cursor-plugin/plugin.json` is the Shape A manifest example that
-  harness at `./skills/` and the right `hooks-*.json`. (Claude Code's
+  points the harness at `./skills/` and the right `hooks-*.json`. Claude Code's
  `.claude-plugin/plugin.json` sets neither field — it auto-discovers `skills/`
-  and `hooks/hooks.json` by convention.)
+  and `hooks/hooks.json` by convention. Do **not** copy Codex's
  `.codex-plugin/plugin.json` for Shape A: it declares an empty `hooks` object
  specifically to suppress Codex's `hooks/hooks.json` auto-discovery, because
  Codex surfaces skills natively and runs no session-start hook.
 > **A hook *system* is not a session-start *event*.** A harness can have a
 > `hooks.json` mechanism — and even contain the literal string `SessionStart` in
@@ -287,7 +289,7 @@ part of the installed extension** — never substitute "edit the user's global
 | If the harness… | Use shape | Copy from |
 |---|---|---|
-| runs a shell command at session start and reads its stdout | A (shell-hook) | Codex (`hooks/session-start-codex` + `hooks/hooks-codex.json` + `.codex-plugin/`) |
+| runs a shell command at session start and reads its stdout | A (shell-hook) | Cursor (`hooks/session-start` + `hooks/hooks-cursor.json` + `.cursor-plugin/`) |
 | is a JS/TS plugin host with session/message lifecycle callbacks | B (in-process) | OpenCode (`.opencode/`) — or pi (`.pi/`) if it has no native skill tool |
 | ships an extension-declared context file it always loads | C (instructions-file) | Gemini (`gemini-extension.json` + `GEMINI.md` + `references/gemini-tools.md`) |
 | has a plugin install command and a manifest `contextFileName` (or equivalent) the installer keeps | C via the plugin installer | Antigravity (`.antigravity-plugin/` — `agy plugin install` ships a generated context file; verify the installer preserves it — Part 6) |
@@ -309,7 +311,7 @@ patterns below are summaries; the code is the spec.
 Create whatever the harness uses to recognize the plugin. Match the existing
 ones in spirit:
- **Shape A:** a `*-plugin/plugin.json` (see `.codex-plugin/plugin.json`) with
+- **Shape A:** a `*-plugin/plugin.json` (see `.cursor-plugin/plugin.json`) with
  `name`, `version`, `description`, author/license/keywords, `"skills":
  "./skills/"`, and `"hooks": "./hooks/hooks-<harness>.json"`. Plus the
  `hooks-<harness>.json` itself, registering a session-start hook whose command
@@ -375,25 +377,24 @@ both double-injects). Find the
 exact field, nesting, and event-matcher values your harness expects. Then
 decide: add a fourth branch to `hooks/session-start`, or — if the harness needs
 a different bootstrap message or env contract — add a dedicated
-`hooks/session-start-<harness>` script, the way Codex did. If you add a branch
+`hooks/session-start-<harness>` script. If you add a branch
 and your harness *also* sets an env var an earlier branch keys on (some harnesses
 set `CLAUDE_PLUGIN_ROOT` too), order your branch before the one that would
 otherwise shadow it. Match the harness's
-own event-matcher strings (Claude Code uses `startup|clear|compact`, Codex
+own event-matcher strings (Claude Code uses `startup|clear|compact`, Cursor
-`startup|resume|clear`, Cursor `sessionStart`); wrong matchers mean the hook
+`sessionStart`); wrong matchers mean the hook silently never fires.
 silently never fires.
 The **hook-config schema itself varies per harness** — don't assume the
-Claude/Codex shape is universal. Compare `hooks/hooks.json`,
+Claude Code shape is universal. Compare `hooks/hooks.json` and
-`hooks/hooks-codex.json`, and `hooks/hooks-cursor.json`: Cursor's uses
+`hooks/hooks-cursor.json`: Cursor's uses
 `"version": 1`, a lowercase `sessionStart` key, a relative
-`./hooks/run-hook.cmd` command, and omits the `matcher`/`type`/`async` fields the
+`./hooks/run-hook.cmd` command, and omits the `matcher`/`type`/`async` fields
-others use. Match your `hooks-<harness>.json` to whichever existing file is
+Claude Code uses. Match your `hooks-<harness>.json` to whichever existing file is
 closest, not to a single canonical template.
 The hook **command string references a harness-provided plugin-root variable**,
 and its name differs per harness: `hooks.json` uses `${CLAUDE_PLUGIN_ROOT}`,
-`hooks-codex.json` uses `${PLUGIN_ROOT}`, Cursor uses a relative path. Use
+`hooks-cursor.json` uses a relative path. Use
 whatever your harness exports. (The `session-start` script re-derives the root
 itself via `dirname`, so the script body doesn't depend on this — but the
 command in the manifest does.)
@@ -784,7 +785,7 @@ Use this as the live index; when in doubt, read the files, not this table.
 | Harness | Entry point | Bootstrap mechanism | Tool mapping | Tests | Distribution |
 |---|---|---|---|---|---|
 | Claude Code | `.claude-plugin/plugin.json` + `hooks/hooks.json` | shell hook → `hooks/session-start` (`hookSpecificOutput.additionalContext`) | native `Skill` tool; `references/claude-code-tools.md` | `tests/hooks/` | marketplace |
-| Codex | `.codex-plugin/plugin.json` + `hooks/hooks-codex.json` | shell hook → `hooks/session-start-codex` | `references/codex-tools.md` | `tests/codex-plugin-sync/`, `tests/hooks/` | fork sync (`scripts/sync-to-codex-plugin.sh`) |
+| Codex | `.codex-plugin/plugin.json` (declares empty `hooks`) | native skill discovery (no session-start hook) | `references/codex-tools.md` | `tests/codex/`, `tests/codex-plugin-sync/` | fork sync (`scripts/sync-to-codex-plugin.sh`) |
 | Cursor | `.cursor-plugin/plugin.json` + `hooks/hooks-cursor.json` | shell hook → `hooks/session-start` (`additional_context`) | `references/claude-code-tools.md` | `tests/hooks/` | hand-authored |
 | Copilot CLI | (shares Claude Code hook path; `COPILOT_CLI` env) | shell hook → `hooks/session-start` (`additionalContext`) | `references/copilot-tools.md` | `tests/hooks/` | — |
 | Gemini CLI | `gemini-extension.json` + `GEMINI.md` | instructions file `@`-includes bootstrap + mapping | `references/gemini-tools.md` | — | `gemini extensions install` |
@@ -799,10 +800,10 @@ Use this as the live index; when in doubt, read the files, not this table.
 - **Wrong JSON field → silent failure or double injection.** Shape A only.
  Confirm the exact field/nesting; Claude Code reads two fields without dedup.
 - **Hook-config schema varies per harness.** Shape A. Cursor's `hooks-cursor.json`
-  looks nothing like the Claude/Codex one (`version`, lowercase `sessionStart`,
+  looks nothing like the Claude Code one (`version`, lowercase `sessionStart`,
  relative command, no `matcher`/`type`/`async`). Match the closest existing file.
 - **Plugin-root env var differs per harness.** Shape A. The hook command uses
-  `${CLAUDE_PLUGIN_ROOT}` (Claude), `${PLUGIN_ROOT}` (Codex), or a relative path
+  `${CLAUDE_PLUGIN_ROOT}` (Claude) or a relative path
  (Cursor). Use what your harness exports; the script re-derives the root itself.
 - **System-message injection.** Shape B injects a *user* message on purpose
  (#750, #894). Don't "fix" it to a system message.
@@ -140,7 +140,7 @@ Check that the script filename is **extensionless** in `hooks.json`. A command l
 ### Hook doesn't fire at all
-Verify the `matcher` in `hooks.json` matches the event type your harness emits. Claude Code uses `startup|clear|compact`; Codex uses `startup|resume|clear`. Check `hooks-codex.json` for the Codex variant.
+Verify the `matcher` in `hooks.json` matches the event type your harness emits. Claude Code uses `startup|clear|compact`; Cursor uses `sessionStart`. Check `hooks-cursor.json` for the Cursor variant.
 ## Related Issues
@@ -1,6 +1,6 @@
 {
  "name": "superpowers",
  "description": "Core skills library: TDD, debugging, collaboration patterns, and proven techniques",
-  "version": "6.1.0",
+  "version": "6.1.1",
  "contextFileName": "GEMINI.md"
 }
@@ -1,26 +0,0 @@
 #!/usr/bin/env bash
 # Codex SessionStart hook for superpowers plugin
 set -euo pipefail
 SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
 PLUGIN_ROOT="$(cd "${SCRIPT_DIR}/.." && pwd)"
 using_superpowers_content=$(cat "${PLUGIN_ROOT}/skills/using-superpowers/SKILL.md" 2>&1 || echo "Error reading using-superpowers skill")
 escape_for_json() {
    local s="$1"
    s="${s//\\/\\\\}"
    s="${s//\"/\\\"}"
    s="${s//$'\n'/\\n}"
    s="${s//$'\r'/\\r}"
    s="${s//$'\t'/\\t}"
    printf '%s' "$s"
 }
 using_superpowers_escaped=$(escape_for_json "$using_superpowers_content")
 session_context="<EXTREMELY_IMPORTANT>\nYou have superpowers.\n\n**Below is the full content of your 'superpowers:using-superpowers' skill - your introduction to using skills. For all other skills, follow the Codex skill-loading instructions in that skill:**\n\n${using_superpowers_escaped}\n</EXTREMELY_IMPORTANT>"
 printf '{\n  "hookSpecificOutput": {\n    "hookEventName": "SessionStart",\n    "additionalContext": "%s"\n  }\n}\n' "$session_context" | cat
 exit 0
@@ -1,6 +1,6 @@
 {
  "name": "superpowers",
-  "version": "6.1.0",
+  "version": "6.1.1",
  "description": "Superpowers skills and runtime bootstrap for coding agents",
  "type": "module",
  "main": ".opencode/plugins/superpowers.js",
@@ -0,0 +1,342 @@
 #!/usr/bin/env bash
 #
 # Package the Superpowers Codex plugin as a rootless archive for portal upload.
 #
 # The Codex portal artifact differs from the old openai/plugins sync flow:
 # it is a standalone archive, but it still needs the OpenAI-owned
 # skills/*/agents/openai.yaml metadata that used to be preserved from the
 # destination plugin repo. Seed that metadata from a prior official package.
 set -euo pipefail
 SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
 REPO_ROOT="$(cd "$SCRIPT_DIR/.." && pwd)"
 REF="HEAD"
 OUTPUT=""
 FORMAT=""
 METADATA_SOURCE=""
 ALLOW_DIRTY=0
 KEEP_STAGE=0
 usage() {
  cat <<'EOF'
 Usage:
  scripts/package-codex-plugin.sh [options]
 Options:
  --output PATH            Write archive to PATH.
                           Default: ../_tmp/sup-codex-packaging/superpowers-VERSION.zip
  --format FORMAT          Archive format: zip or tar.gz. Default: zip.
                           If --output ends in .zip, .tar.gz, or .tgz, that
                           extension is used when --format is omitted.
  --metadata-source PATH   Prior official package directory, .zip, or .tar.gz used to
                           seed skills/*/agents/openai.yaml.
                           Default: ../_tmp/sup-codex-packaging/superpowers,
                           falling back to superpowers.zip, then superpowers.tar.gz
  --ref REF                Git ref to package. Default: HEAD.
  --allow-dirty            Permit a dirty working tree. The archive still uses --ref.
  --keep-stage             Print and keep the temporary staging directory.
  -h, --help               Show this help.
 The archive is rootless: .codex-plugin/, assets/, skills/, README.md, LICENSE,
 and CODE_OF_CONDUCT.md sit at the archive root. Source-only repo files, hooks, tests,
 docs, and other harness manifests are intentionally not shipped.
 EOF
 }
 die() {
  echo "ERROR: $*" >&2
  exit 1
 }
 while [[ $# -gt 0 ]]; do
  case "$1" in
    --output)
      [[ $# -ge 2 ]] || die "--output requires a path"
      OUTPUT="$2"
      shift 2
      ;;
    --format)
      [[ $# -ge 2 ]] || die "--format requires a value"
      case "$2" in
        zip)
          FORMAT="zip"
          ;;
        tar.gz|tgz)
          FORMAT="tar.gz"
          ;;
        *)
          die "--format must be zip or tar.gz"
          ;;
      esac
      shift 2
      ;;
    --metadata-source)
      [[ $# -ge 2 ]] || die "--metadata-source requires a path"
      METADATA_SOURCE="$2"
      shift 2
      ;;
    --ref)
      [[ $# -ge 2 ]] || die "--ref requires a value"
      REF="$2"
      shift 2
      ;;
    --allow-dirty)
      ALLOW_DIRTY=1
      shift
      ;;
    --keep-stage)
      KEEP_STAGE=1
      shift
      ;;
    -h|--help)
      usage
      exit 0
      ;;
    *)
      echo "Unknown arg: $1" >&2
      usage >&2
      exit 2
      ;;
  esac
 done
 infer_format_from_output() {
  local output_path="$1"
  case "$output_path" in
    *.tar.gz|*.tgz)
      printf '%s\n' "tar.gz"
      ;;
    *.zip)
      printf '%s\n' "zip"
      ;;
    *)
      return 1
      ;;
  esac
 }
 if [[ -z "$FORMAT" ]]; then
  FORMAT="$(infer_format_from_output "$OUTPUT" || true)"
  if [[ -z "$FORMAT" ]]; then
    FORMAT="zip"
  fi
 else
  output_format="$(infer_format_from_output "$OUTPUT" || true)"
  if [[ -n "$output_format" && "$output_format" != "$FORMAT" ]]; then
    die "--output extension does not match --format $FORMAT: $OUTPUT"
  fi
 fi
 command -v git >/dev/null || die "git not found in PATH"
 command -v jq >/dev/null || die "jq not found in PATH"
 command -v tar >/dev/null || die "tar not found in PATH"
 command -v gzip >/dev/null || die "gzip not found in PATH"
 command -v shasum >/dev/null || die "shasum not found in PATH"
 if [[ "$FORMAT" == "zip" ]]; then
  command -v zip >/dev/null || die "zip not found in PATH"
  command -v unzip >/dev/null || die "unzip not found in PATH"
 fi
 [[ -d "$REPO_ROOT/.git" ]] || die "repo root is not a git checkout: $REPO_ROOT"
 git -C "$REPO_ROOT" rev-parse --verify "$REF^{commit}" >/dev/null ||
  die "git ref does not resolve to a commit: $REF"
 if [[ "$ALLOW_DIRTY" -ne 1 ]]; then
  dirty_status="$(git -C "$REPO_ROOT" status --porcelain --untracked-files=all)"
  if [[ -n "$dirty_status" ]]; then
    echo "Working tree has uncommitted changes:" >&2
    printf '%s\n' "$dirty_status" | sed 's/^/  /' >&2
    die "commit or stash changes first, or pass --allow-dirty to package $REF anyway"
  fi
 fi
 if [[ -z "$METADATA_SOURCE" ]]; then
  if [[ -d "$REPO_ROOT/../_tmp/sup-codex-packaging/superpowers" ]]; then
    METADATA_SOURCE="$REPO_ROOT/../_tmp/sup-codex-packaging/superpowers"
  elif [[ -f "$REPO_ROOT/../_tmp/sup-codex-packaging/superpowers.zip" ]]; then
    METADATA_SOURCE="$REPO_ROOT/../_tmp/sup-codex-packaging/superpowers.zip"
  elif [[ -f "$REPO_ROOT/../_tmp/sup-codex-packaging/superpowers.tar.gz" ]]; then
    METADATA_SOURCE="$REPO_ROOT/../_tmp/sup-codex-packaging/superpowers.tar.gz"
  else
    die "no metadata source found; pass --metadata-source <prior package dir, zip, or tar.gz>"
  fi
 fi
 WORK_DIR="$(mktemp -d "${TMPDIR:-/tmp}/superpowers-codex-package.XXXXXX")"
 STAGE="$WORK_DIR/payload"
 METADATA_WORK="$WORK_DIR/metadata"
 ARCHIVE_LIST="$WORK_DIR/archive-list"
 cleanup() {
  if [[ "$KEEP_STAGE" -eq 1 ]]; then
    echo "Keeping staging directory: $WORK_DIR" >&2
  else
    rm -rf "$WORK_DIR"
  fi
 }
 trap cleanup EXIT
 mkdir -p "$STAGE" "$METADATA_WORK"
 metadata_root_from_dir() {
  local candidate="$1"
  local nested
  if [[ -d "$candidate/skills" ]]; then
    printf '%s\n' "$candidate"
    return 0
  fi
  nested="$(find "$candidate" -mindepth 2 -maxdepth 2 -type d -name skills -print -quit)"
  if [[ -n "$nested" ]]; then
    dirname "$nested"
    return 0
  fi
  return 1
 }
 prepare_metadata_root() {
  local source="$1"
  local root
  if [[ -d "$source" ]]; then
    root="$(cd "$source" && pwd)"
  elif [[ -f "$source" ]]; then
    case "$source" in
      *.tar.gz|*.tgz)
        tar -xzf "$source" -C "$METADATA_WORK"
        root="$METADATA_WORK"
        ;;
      *.zip)
        command -v unzip >/dev/null || die "unzip not found in PATH"
        unzip -q "$source" -d "$METADATA_WORK"
        root="$METADATA_WORK"
        ;;
      *)
        die "metadata source must be a directory, .zip, or .tar.gz: $source"
        ;;
    esac
  else
    die "metadata source does not exist: $source"
  fi
  metadata_root_from_dir "$root" ||
    die "metadata source does not contain a skills/ directory: $source"
 }
 METADATA_ROOT="$(prepare_metadata_root "$METADATA_SOURCE")"
 git -C "$REPO_ROOT" archive --format=tar "$REF" -- \
  .codex-plugin \
  CODE_OF_CONDUCT.md \
  LICENSE \
  README.md \
  assets \
  skills \
  | tar -xf - -C "$STAGE"
 VERSION="$(jq -r '.version // empty' "$STAGE/.codex-plugin/plugin.json")"
 [[ -n "$VERSION" ]] || die "could not read version from .codex-plugin/plugin.json"
 if [[ -z "$OUTPUT" ]]; then
  case "$FORMAT" in
    zip)
      OUTPUT="$REPO_ROOT/../_tmp/sup-codex-packaging/superpowers-$VERSION.zip"
      ;;
    tar.gz)
      OUTPUT="$REPO_ROOT/../_tmp/sup-codex-packaging/superpowers-$VERSION.tar.gz"
      ;;
  esac
 fi
 mkdir -p "$(dirname "$OUTPUT")"
 OUTPUT="$(cd "$(dirname "$OUTPUT")" && pwd)/$(basename "$OUTPUT")"
 missing_metadata=0
 while IFS= read -r skill_dir; do
  skill_name="${skill_dir##*/}"
  metadata_file="$METADATA_ROOT/skills/$skill_name/agents/openai.yaml"
  if [[ ! -f "$metadata_file" ]]; then
    echo "Missing OpenAI agent metadata for skill: $skill_name" >&2
    missing_metadata=1
    continue
  fi
  mkdir -p "$skill_dir/agents"
  cp "$metadata_file" "$skill_dir/agents/openai.yaml"
 done < <(find "$STAGE/skills" -mindepth 1 -maxdepth 1 -type d -print | sort)
 if [[ "$missing_metadata" -ne 0 ]]; then
  die "metadata source is incomplete"
 fi
 skill_count="$(find "$STAGE/skills" -mindepth 1 -maxdepth 1 -type d | wc -l | tr -d ' ')"
 metadata_count="$(find "$STAGE/skills" -path '*/agents/openai.yaml' -type f | wc -l | tr -d ' ')"
 [[ "$skill_count" == "$metadata_count" ]] ||
  die "metadata count mismatch: $metadata_count metadata files for $skill_count skills"
 (
  cd "$STAGE"
  {
    find . -mindepth 1 -type d | sed 's#^\./##' | LC_ALL=C sort
    find . -mindepth 1 -type f | sed 's#^\./##' | LC_ALL=C sort
  } >"$ARCHIVE_LIST"
 )
 case "$FORMAT" in
  zip)
    # ZIP cannot represent dates earlier than 1980.
    TZ=UTC find "$STAGE" -exec touch -t 198001010000 {} +
    (
      cd "$STAGE"
      rm -f "$OUTPUT"
      COPYFILE_DISABLE=1 zip -X -q - -@ <"$ARCHIVE_LIST" >"$OUTPUT"
    )
    ;;
  tar.gz)
    # Match the prior official archive's deterministic tar entry metadata.
    TZ=UTC find "$STAGE" -exec touch -t 197001010000 {} +
    (
      cd "$STAGE"
      rm -f "$OUTPUT"
      COPYFILE_DISABLE=1 tar -cf - --no-recursion --format ustar --uid 0 --gid 0 --uname '' --gname '' -T "$ARCHIVE_LIST" |
        gzip -9n >"$OUTPUT"
    )
    ;;
 esac
 if command -v xattr >/dev/null 2>&1; then
  xattr -c "$OUTPUT" 2>/dev/null || true
 fi
 case "$FORMAT" in
  zip)
    archive_paths="$(unzip -Z1 "$OUTPUT" | sed 's#/$##')"
    ;;
  tar.gz)
    archive_paths="$(tar -tzf "$OUTPUT")"
    ;;
 esac
 unexpected_paths="$(
  printf '%s\n' "$archive_paths" |
    grep -E '(^superpowers/|^\.agents/|^hooks/|package\.json$|^\.git|^\.pytest_cache|^\.ruff_cache|^scripts/|^tests/|^docs/|^evals/|^lib/|^\.claude|^\.cursor|^\.kimi|^\.opencode|^\.pi|^AGENTS\.md$|^CLAUDE\.md$|^GEMINI\.md$|^RELEASE-NOTES\.md$|^CHANGELOG\.md$)' || true
 )"
 if [[ -n "$unexpected_paths" ]]; then
  printf '%s\n' "$unexpected_paths" | sed 's/^/  /' >&2
  die "archive contains source-only paths"
 fi
 entry_count="$(printf '%s\n' "$archive_paths" | wc -l | tr -d ' ')"
 checksum="$(shasum -a 256 "$OUTPUT" | awk '{print $1}')"
 echo "Archive: $OUTPUT"
 echo "Format:  $FORMAT"
 echo "Version: $VERSION"
 echo "Entries: $entry_count"
 echo "Skills:  $skill_count"
 echo "SHA-256: $checksum"
@@ -77,6 +77,7 @@ digraph brainstorming {
 - Propose 2-3 different approaches with trade-offs
 - Present options conversationally with your recommendation and reasoning
 - Lead with your recommended option and explain why
 - YAGNI ruthlessly - remove unnecessary features from every approach and design
 **Presenting the design:**
@@ -130,15 +131,6 @@ Wait for the user's response. If they request changes, make them and re-run the
 - Invoke the writing-plans skill to create a detailed implementation plan
 - Do NOT invoke any other skill. writing-plans is the next step.
 ## Key Principles
 - **One question at a time** - Don't overwhelm with multiple questions
 - **Multiple choice preferred** - Easier to answer than open-ended when possible
 - **YAGNI ruthlessly** - Remove unnecessary features from all designs
 - **Explore alternatives** - Always propose 2-3 approaches before settling
 - **Incremental validation** - Present design, get approval before moving on
 - **Be flexible** - Go back and clarify when something doesn't make sense
 ## Visual Companion
 A browser-based companion for showing mockups, diagrams, and visual options during brainstorming. Available as a tool — not a mode. Accepting the companion means it's available for questions that benefit from visual treatment; it does NOT mean every question goes through the browser.
@@ -74,6 +74,13 @@ On Windows, the script auto-detects and switches to foreground mode (which block
 scripts/start-server.sh --project-dir /path/to/project --open
 ```
 **Gemini CLI:**
 ```bash
 # Use --foreground and set is_background: true on your shell tool call
 # so the process survives across turns
 scripts/start-server.sh --project-dir /path/to/project --open --foreground
 ```
 **Copilot CLI:**
 ```bash
 # Use --foreground and start the server via the bash tool with mode: "async"
@@ -158,15 +158,6 @@ Agent 3 → Fix tool-approval-race-conditions.test.ts
 **Integration:** All fixes independent, no conflicts, full suite green
 **Time saved:** 3 problems solved in parallel vs sequentially
 ## Key Benefits
 1. **Parallelization** - Multiple investigations happen simultaneously
 2. **Focus** - Each agent has narrow scope, less context to track
 3. **Independence** - Agents don't interfere with each other
 4. **Speed** - 3 problems solved in time of 1
 ## Verification
 After agents return:
@@ -174,12 +165,3 @@ After agents return:
 2. **Check for conflicts** - Did agents edit same code?
 3. **Run full suite** - Verify all fixes work together
 4. **Spot check** - Agents can make systematic errors
 ## Real-World Impact
 From debugging session (2025-10-03):
 - 6 failures across 3 files
 - 3 agents dispatched in parallel
 - All investigations completed concurrently
 - All fixes integrated successfully
 - Zero conflicts between agent changes
@@ -11,15 +11,16 @@ Load plan, review critically, execute all tasks, report when complete.
 **Announce at start:** "I'm using the executing-plans skill to implement this plan."
-**Note:** Tell your human partner that Superpowers works much better with access to subagents. The quality of its work will be significantly higher if run on a platform with subagent support (Claude Code, Codex CLI, Codex App, and Copilot CLI all qualify; see the per-platform tool refs in `../using-superpowers/references/`). If subagents are available, use superpowers:subagent-driven-development instead of this skill.
+**Note:** Tell your human partner that Superpowers works much better with access to subagents (Claude Code, Codex CLI, Codex App, Copilot CLI, and Gemini CLI all qualify; see the per-platform tool refs in `../using-superpowers/references/`). If subagents are available, use superpowers:subagent-driven-development instead of this skill.
 ## The Process
 ### Step 1: Load and Review Plan
-1. Read plan file
+1. Ensure an isolated workspace: use superpowers:using-git-worktrees to create one or verify the existing one
-2. Review critically - identify any questions or concerns about the plan
+2. Read plan file
-3. If concerns: Raise them with your human partner before starting
+3. Review critically - identify any questions or concerns about the plan
-4. If no concerns: Create todos for the plan items and proceed
+4. If concerns: Raise them with your human partner before starting
 5. If no concerns: Create todos for the plan items and proceed
 ### Step 2: Execute Tasks
@@ -61,10 +62,3 @@ After all tasks complete and verified:
 - Reference skills when plan says to
 - Stop when blocked, don't guess
 - Never start implementation on main/master branch without explicit user consent
 ## Integration
 **Required workflow skills:**
 - **superpowers:using-git-worktrees** - Ensures isolated workspace (creates one or verifies existing)
 - **superpowers:writing-plans** - Creates the plan this skill executes
 - **superpowers:finishing-a-development-branch** - Complete development after all tasks
@@ -1,71 +1,58 @@
 ---
 name: finishing-a-development-branch
-description: Use when implementation is complete, all tests pass, and you need to decide how to integrate the work - guides completion of development work by presenting structured options for merge, PR, or cleanup
+description: Use when implementation is complete, all tests pass, and you need to decide how to integrate the work
 ---
 # Finishing a Development Branch
 ## Overview
 Guide completion of development work by presenting clear options and handling chosen workflow.
 **Core principle:** Verify tests → Detect environment → Present options → Execute choice → Clean up.
 **Announce at start:** "I'm using the finishing-a-development-branch skill to complete this work."
-## The Process
+## Step 1: Verify Tests
-### Step 1: Verify Tests
+Run the project's full test suite (`npm test` / `cargo test` / `pytest` / `go test ./...`).
-**Before presenting options, verify tests pass:**
+**If tests fail**, report the failures and stop — the menu comes after a green suite:
 ```bash
 # Run project's test suite
 npm test / cargo test / pytest / go test ./...
 ```
 **If tests fail:**
 ```
 Tests failing (<N> failures). Must fix before completing:
 [Show failures]
 Cannot proceed with merge/PR until tests pass.
 ```
-Stop. Don't proceed to Step 2.
+**If tests pass:** continue to Step 2.
-**If tests pass:** Continue to Step 2.
+## Step 2: Detect Environment
 ### Step 2: Detect Environment
 **Determine workspace state before presenting options:**
 ```bash
 GIT_DIR=$(cd "$(git rev-parse --git-dir)" 2>/dev/null && pwd -P)
 GIT_COMMON=$(cd "$(git rev-parse --git-common-dir)" 2>/dev/null && pwd -P)
 # Capture now, while still inside the workspace — Step 5 changes directory
 # before cleanup (Step 6) needs this value
 WORKTREE_PATH=$(git rev-parse --show-toplevel)
 ```
 This determines which menu to show and how cleanup works:
 | State | Menu | Cleanup |
 |-------|------|---------|
-| `GIT_DIR == GIT_COMMON` (normal repo) | Standard 4 options | No worktree to clean up |
+| `GIT_DIR == GIT_COMMON` (normal repo) | Standard 3 options | No worktree to clean up |
-| `GIT_DIR != GIT_COMMON`, named branch | Standard 4 options | Provenance-based (see Step 6) |
+| `GIT_DIR != GIT_COMMON`, named branch | Standard 3 options | Provenance-based (see Step 6) |
-| `GIT_DIR != GIT_COMMON`, detached HEAD | Reduced 3 options (no merge) | No cleanup (externally managed) |
+| `GIT_DIR != GIT_COMMON`, detached HEAD | Reduced 2 options (no merge) | Externally managed — leave in place |
-### Step 3: Determine Base Branch
+## Step 3: Determine Base Branch
-```bash
+The base branch is whatever this work forked from — usually named in the
-# Try common base branches
+plan, the conversation, or the branch's upstream. If it is not already
-git merge-base HEAD main 2>/dev/null || git merge-base HEAD master 2>/dev/null
+known, ask: "This branch split from <your best guess> - is that correct?"
-```
+Confirm before merging: merging into the wrong base is expensive to undo.
-Or ask: "This branch split from main - is that correct?"
+## Step 4: Present Options
-### Step 4: Present Options
+**Normal repo and named-branch worktree — present exactly these 3 options:**
 **Normal repo and named-branch worktree — present exactly these 4 options:**
 ```
 Implementation complete. What would you like to do?
@@ -73,28 +60,30 @@ Implementation complete. What would you like to do?
 1. Merge back to <base-branch> locally
 2. Push and create a Pull Request
 3. Keep the branch as-is (I'll handle it later)
 4. Discard this work
 Which option?
 ```
-**Detached HEAD — present exactly these 3 options:**
+**Detached HEAD — present exactly these 2 options:**
 ```
 Implementation complete. You're on a detached HEAD (externally managed workspace).
 1. Push as new branch and create a Pull Request
 2. Keep as-is (I'll handle it later)
 3. Discard this work
 Which option?
 ```
-**Don't add explanation** - keep options concise.
+Present the menu exactly as written — concise, with every option coming
 from the list above. Discarding the work happens only in response to your
 human partner explicitly asking for it (see "If your human partner asks to
 discard the work" below). Wait for their answer; the integration decision
 is theirs.
-### Step 5: Execute Choice
+## Step 5: Execute Choice
-#### Option 1: Merge Locally
+### Option 1: Merge Locally
 ```bash
 # Get main repo root for CWD safety
@@ -108,34 +97,43 @@ git merge <feature-branch>
 # Verify tests on merged result
 <test command>
 # Only after merge succeeds: cleanup worktree (Step 6), then delete branch
 ```
-Then: Cleanup worktree (Step 6), then delete branch:
+If tests fail on the merged result: stop, leave the worktree and branch in
 place, and investigate — nothing has been pushed, so the merge is local
 and recoverable.
 Once the merged result is green: clean up the worktree (Step 6), then
 delete the branch:
 ```bash
 git branch -d <feature-branch>
 ```
-#### Option 2: Push and Create PR
+### Option 2: Push and Create PR
 ```bash
 # Push branch
 git push -u origin <feature-branch>
 # From a detached HEAD, name the new branch on the remote:
 # git push origin HEAD:refs/heads/<new-branch>
 ```
-**Do NOT clean up worktree** — user needs it alive to iterate on PR feedback.
+Then create the pull/merge request against <base-branch> with the forge's
 tooling — its CLI if one is available, or the creation URL most forges
 print when you push — following the repo's PR template and conventions if
 present, and report the URL to your human partner.
-#### Option 3: Keep As-Is
+Keep the worktree — your human partner iterates on PR feedback there.
 ### Option 3: Keep As-Is
 Report: "Keeping branch <name>. Worktree preserved at <path>."
-**Don't cleanup worktree.**
+### If your human partner asks to discard the work
-#### Option 4: Discard
+This path exists only as a response to an explicit request to throw the
 work away. Confirm first:
 **Confirm first:**
 ```
 This will permanently delete:
 - Branch <name>
@@ -145,41 +143,39 @@ This will permanently delete:
 Type 'discard' to confirm.
 ```
-Wait for exact confirmation.
+Wait for that exact confirmation. When it arrives:
 If confirmed:
 ```bash
 MAIN_ROOT=$(git -C "$(git rev-parse --git-common-dir)/.." rev-parse --show-toplevel)
 cd "$MAIN_ROOT"
 ```
-Then: Cleanup worktree (Step 6), then force-delete branch:
+Then clean up the worktree (Step 6) and force-delete the branch:
 ```bash
 git branch -D <feature-branch>
 ```
-### Step 6: Cleanup Workspace
+## Step 6: Cleanup Workspace
-**Only runs for Options 1 and 4.** Options 2 and 3 always preserve the worktree.
+**Runs for Option 1 and confirmed discards.** Options 2 and 3 always
-
+preserve the worktree. Both callers have already changed directory to the
-```bash
+main repo root — worktree removal must run from outside the worktree —
-GIT_DIR=$(cd "$(git rev-parse --git-dir)" 2>/dev/null && pwd -P)
+and use the `GIT_DIR`/`GIT_COMMON`/`WORKTREE_PATH` values captured in
-GIT_COMMON=$(cd "$(git rev-parse --git-common-dir)" 2>/dev/null && pwd -P)
+Step 2, from before that directory change.
 WORKTREE_PATH=$(git rev-parse --show-toplevel)
 ```
 **If `GIT_DIR == GIT_COMMON`:** Normal repo, no worktree to clean up. Done.
-**If worktree path is under `.worktrees/` or `worktrees/`:** Superpowers created this worktree — we own cleanup.
+**If `WORKTREE_PATH` is under `.worktrees/` or `worktrees/`:** Superpowers
 created this worktree — we own cleanup:
 ```bash
 MAIN_ROOT=$(git -C "$(git rev-parse --git-common-dir)/.." rev-parse --show-toplevel)
 cd "$MAIN_ROOT"
 git worktree remove "$WORKTREE_PATH"
 git worktree prune  # Self-healing: clean up any stale registrations
 ```
-**Otherwise:** The host environment (harness) owns this workspace. Do NOT remove it. If your platform provides a workspace-exit tool, use it. Otherwise, leave the workspace in place.
+**Otherwise:** The host environment owns this workspace — leave it in
 place. If your platform provides a workspace-exit tool, use it.
 ## Quick Reference
@@ -188,54 +184,18 @@ git worktree prune  # Self-healing: clean up any stale registrations
 | 1. Merge locally | yes | - | - | yes |
 | 2. Create PR | - | yes | yes | - |
 | 3. Keep as-is | - | - | yes | - |
-| 4. Discard | - | - | - | yes (force) |
+| Discard (explicit request only) | - | - | - | yes (force) |
-## Common Mistakes
+## Common Rationalizations
-**Skipping test verification**
+| Excuse | Reality |
- **Problem:** Merge broken code, create failing PR
+|--------|---------|
- **Fix:** Always verify tests before offering options
+| "Tests passed earlier this session" | Run the suite on the tree you are about to integrate. A green run only proves the tree it ran on. |
-
+| "They obviously want it merged" | Integration is your human partner's decision. Present the menu and wait. |
-**Open-ended questions**
+| "They seem done with this feature — I'll offer to discard it" | The menu is complete as written. Discard happens only when your human partner asks for it in so many words. |
- **Problem:** "What should I do next?" is ambiguous
+| "'Yeah, get rid of it' counts as confirmation" | Only the typed word `discard` authorizes deletion. |
- **Fix:** Present exactly 4 structured options (or 3 for detached HEAD)
+| "The PR is up, so the worktree is clutter now" | PR feedback gets fixed in that worktree. It stays until the work lands. |
-
+| "This other worktree looks stale — I'll clean it too" | Clean up only worktrees under `.worktrees/` or `worktrees/`. Everything else belongs to the host. |
-**Cleaning up worktree for Option 2**
+| "The merged-result failure is probably flaky" | A failing merged result stops everything. Branch and worktree stay put while you investigate. |
- **Problem:** Remove worktree user needs for PR iteration
+| "The base branch is obviously main" | Confirm the fork point or ask. Merging into the wrong base is expensive to undo. |
- **Fix:** Only cleanup for Options 1 and 4
+| "The push was rejected — force-push will fix it" | A rejected push means the remote moved. Investigate; force-push only on your human partner's explicit request. |
 **Deleting branch before removing worktree**
 - **Problem:** `git branch -d` fails because worktree still references the branch
 - **Fix:** Merge first, remove worktree, then delete branch
 **Running git worktree remove from inside the worktree**
 - **Problem:** Command fails silently when CWD is inside the worktree being removed
 - **Fix:** Always `cd` to main repo root before `git worktree remove`
 **Cleaning up harness-owned worktrees**
 - **Problem:** Removing a worktree the harness created causes phantom state
 - **Fix:** Only clean up worktrees under `.worktrees/` or `worktrees/`
 **No confirmation for discard**
 - **Problem:** Accidentally delete work
 - **Fix:** Require typed "discard" confirmation
 ## Red Flags
 **Never:**
 - Proceed with failing tests
 - Merge without verifying tests on result
 - Delete work without confirmation
 - Force-push without explicit request
 - Remove a worktree before confirming merge success
 - Clean up worktrees you didn't create (provenance check)
 - Run `git worktree remove` from inside the worktree
 **Always:**
 - Verify tests before offering options
 - Detect environment before presenting menu
 - Present exactly 4 options (or 3 for detached HEAD)
 - Get typed confirmation for Option 4
 - Clean up worktree for Options 1 & 4 only
 - `cd` to main repo root before worktree removal
 - Run `git worktree prune` after removal
@@ -203,11 +203,3 @@ You understand 1,2,3,6. Unclear on 4,5.
 ## GitHub Thread Replies
 When replying to inline review comments on GitHub, reply in the comment thread (`gh api repos/{owner}/{repo}/pulls/{pr}/comments/{id}/replies`), not as a top-level PR comment.
 ## The Bottom Line
 **External feedback = suggestions to evaluate, not orders to follow.**
 Verify. Question. Then implement.
 No performative agreement. Technical rigor always.
@@ -5,7 +5,7 @@ description: Use when completing tasks, implementing major features, or before m
 # Requesting Code Review
-Dispatch a code reviewer subagent to catch issues before they cascade. The reviewer gets precisely crafted context for evaluation — never your session's history. This keeps the reviewer focused on the work product, not your thought process, and preserves your own context for continued work.
+Dispatch a code reviewer subagent to catch issues before they cascade. The reviewer gets precisely crafted context for evaluation — never your session's history.
 **Core principle:** Review early, review often.
@@ -72,20 +72,12 @@ You: [Fix progress indicators]
 [Continue to Task 3]
 ```
-## Integration with Workflows
+## Common Rationalizations
-**Subagent-Driven Development:**
+| Excuse | Reality |
- Review after EACH task
+|--------|---------|
- Catch issues before they compound
+| "I'll just review the diff myself instead of dispatching a reviewer" | You're the coordinator — reviewing the diff inline burns the context window you need to keep driving the work. Dispatch a reviewer subagent: the diff and the evaluation live in its context, and only the findings come back to you. |
- Fix before moving to next task
+| "The reviewer needs my whole session history to understand the change" | Hand it precisely crafted context, never your session's history. That keeps the reviewer on the work product, not your thought process. |
 **Executing Plans:**
 - Review after each task or at natural checkpoints
 - Get feedback, apply, continue
 **Ad-Hoc Development:**
 - Review before merge
 - Review when stuck
 ## Red Flags
@@ -84,6 +84,9 @@ digraph process {
 ## Pre-Flight Plan Review
 Ensure the work happens in an isolated workspace: use
 superpowers:using-git-worktrees to create one or verify the existing one.
 Before dispatching Task 1, scan the plan once for conflicts:
 - tasks that contradict each other or the plan's Global Constraints
@@ -332,38 +335,6 @@ Final reviewer: All requirements met, ready to merge
 Done!
 ```
 ## Advantages
 **vs. Manual execution:**
 - Subagents follow TDD naturally
 - Fresh context per task (no confusion)
 - Parallel-safe (subagents don't interfere)
 - Subagent can ask questions (before AND during work)
 **vs. Executing Plans:**
 - Same session (no handoff)
 - Continuous progress (no waiting)
 - Review checkpoints automatic
 **Efficiency gains:**
 - Controller curates exactly what context is needed; bulk artifacts move
  as files, not pasted text
 - Subagent gets complete information upfront
 - Questions surfaced before work begins (not after)
 **Quality gates:**
 - Self-review catches issues before handoff
 - Task review carries two verdicts: spec compliance and code quality
 - Review loops ensure fixes actually work
 - Spec compliance prevents over/under-building
 - Code quality ensures implementation is well-built
 **Cost:**
 - More subagent invocations (implementer + reviewer per task)
 - Controller does more prep work (extracting all tasks upfront)
 - Review loops add iterations
 - But catches issues early (cheaper than debugging later)
 ## Red Flags
 **Never:**
@@ -402,17 +373,3 @@ Done!
 **If subagent fails task:**
 - Dispatch fix subagent with specific instructions
 - Don't try to fix manually (context pollution)
 ## Integration
 **Required workflow skills:**
 - **superpowers:using-git-worktrees** - Ensures isolated workspace (creates one or verifies existing)
 - **superpowers:writing-plans** - Creates the plan this skill executes
 - **superpowers:requesting-code-review** - Code review template for the final whole-branch review
 - **superpowers:finishing-a-development-branch** - Complete development after all tasks
 **Subagents should use:**
 - **superpowers:test-driven-development** - Subagents follow TDD for each task
 **Alternative workflow:**
 - **superpowers:executing-plans** - Use for parallel session instead of same-session execution
@@ -7,8 +7,6 @@ description: Use when encountering any bug, test failure, or unexpected behavior
 ## Overview
 Random fixes waste time and create new bugs. Quick patches mask underlying issues.
 **Core principle:** ALWAYS find root cause before attempting fixes. Symptom fixes are failure.
 **Violating the letter of this process is violating the spirit of debugging.**
@@ -188,6 +186,7 @@ You MUST complete each phase before proceeding to the next.
   - Test passes now?
   - No other tests broken?
   - Issue actually resolved?
   - Use the `superpowers:verification-before-completion` skill before claiming success
 4. **If Fix Doesn't Work**
   - STOP
@@ -282,15 +281,3 @@ These techniques are part of systematic debugging and available in this director
 - **`root-cause-tracing.md`** - Trace bugs backward through call stack to find original trigger
 - **`defense-in-depth.md`** - Add validation at multiple layers after finding root cause
 - **`condition-based-waiting.md`** - Replace arbitrary timeouts with condition polling
 **Related skills:**
 - **superpowers:test-driven-development** - For creating failing test case (Phase 4, Step 1)
 - **superpowers:verification-before-completion** - Verify fix worked before claiming success
 ## Real-World Impact
 From debugging sessions:
 - Systematic approach: 15-30 minutes to fix
 - Random fixes approach: 2-3 hours of thrashing
 - First-time fix rate: 95% vs 40%
 - New bugs introduced: Near zero vs common
@@ -203,69 +203,25 @@ Next failing test for next feature.
 | **Clear** | Name describes behavior | `test('test1')` |
 | **Shows intent** | Demonstrates desired API | Obscures what code should do |
-## Why Order Matters
+When writing or changing any test, read [writing-good-tests.md](writing-good-tests.md) for the rules that keep tests honest:
-
+- Name the production change that would make the test fail — before writing it
-**"I'll write tests after to verify it works"**
+- Assert on real behavior, never on mock behavior
-
+- Keep test-only code in test utilities, out of production classes
-Tests written after code pass immediately. Passing immediately proves nothing:
+- Understand a dependency's side effects before mocking it
 - Might test wrong thing
 - Might test implementation, not behavior
 - Might miss edge cases you forgot
 - You never saw it catch the bug
 Test-first forces you to see the test fail, proving it actually tests something.
 **"I already manually tested all the edge cases"**
 Manual testing is ad-hoc. You think you tested everything but:
 - No record of what you tested
 - Can't re-run when code changes
 - Easy to forget cases under pressure
 - "It worked when I tried it" ≠ comprehensive
 Automated tests are systematic. They run the same way every time.
 **"Deleting X hours of work is wasteful"**
 Sunk cost fallacy. The time is already gone. Your choice now:
 - Delete and rewrite with TDD (X more hours, high confidence)
 - Keep it and add tests after (30 min, low confidence, likely bugs)
 The "waste" is keeping code you can't trust. Working code without real tests is technical debt.
 **"TDD is dogmatic, being pragmatic means adapting"**
 TDD IS pragmatic:
 - Finds bugs before commit (faster than debugging after)
 - Prevents regressions (tests catch breaks immediately)
 - Documents behavior (tests show how to use code)
 - Enables refactoring (change freely, tests catch breaks)
 "Pragmatic" shortcuts = debugging in production = slower.
 **"Tests after achieve the same goals - it's spirit not ritual"**
 No. Tests-after answer "What does this do?" Tests-first answer "What should this do?"
 Tests-after are biased by your implementation. You test what you built, not what's required. You verify remembered edge cases, not discovered ones.
 Tests-first force edge case discovery before implementing. Tests-after verify you remembered everything (you didn't).
 30 minutes of tests after ≠ TDD. You get coverage, lose proof tests work.
 ## Common Rationalizations
 | Excuse | Reality |
 |--------|---------|
 | "Too simple to test" | Simple code breaks. Test takes 30 seconds. |
-| "I'll test after" | Tests passing immediately prove nothing. |
+| "I'll test after" | Tests written after pass immediately — which proves nothing. They may test the wrong thing, test the implementation instead of the behavior, or miss the edge case you forgot. You never watched it fail, so you never proved it can catch the bug. Test-first forces that failure. |
-| "Tests after achieve same goals" | Tests-after = "what does this do?" Tests-first = "what should this do?" |
+| "Tests after achieve same goals (spirit not ritual)" | Tests-after answer "what does this do?"; tests-first answer "what should this do?" Tests written after are biased by the code you already wrote — you verify the cases you remembered, not the ones you'd have discovered. Coverage without proof the tests work. |
-| "Already manually tested" | Ad-hoc ≠ systematic. No record, can't re-run. |
+| "Already manually tested" | Manual testing is ad-hoc: no record of what you covered, no way to re-run it when the code changes, easy to forget cases under pressure. "Worked when I tried it" ≠ comprehensive. Automated tests run the same way every time. |
-| "Deleting X hours is wasteful" | Sunk cost fallacy. Keeping unverified code is technical debt. |
+| "Deleting X hours is wasteful" | Sunk cost fallacy — that time is already spent either way. The real choice: rewrite with TDD (high confidence) vs. keep it and bolt tests on after (low confidence, likely bugs). Keeping code you can't trust is the waste. |
 | "Keep as reference, write tests first" | You'll adapt it. That's testing after. Delete means delete. |
 | "Need to explore first" | Fine. Throw away exploration, start with TDD. |
 | "Test hard = design unclear" | Listen to test. Hard to test = hard to use. |
-| "TDD will slow me down" | TDD faster than debugging. Pragmatic = test-first. |
+| "TDD will slow me down" | TDD IS the pragmatic path: catches bugs before commit, prevents regressions, lets you refactor without fear. "Pragmatic" shortcuts mean debugging in production — slower, not faster. |
 | "Manual test faster" | Manual doesn't prove edge cases. You'll re-test every change. |
 | "Existing code has no tests" | You're improving it. Add tests for existing code. |
@@ -354,13 +310,6 @@ Bug found? Write failing test reproducing it. Follow TDD cycle. Test proves fix
 Never fix bugs without a test.
 ## Testing Anti-Patterns
 When adding mocks or test utilities, read [testing-anti-patterns.md](testing-anti-patterns.md) to avoid common pitfalls:
 - Testing mock behavior instead of real behavior
 - Adding test-only methods to production classes
 - Mocking without understanding dependencies
 ## Final Rule
 ```
@@ -1,299 +0,0 @@
 # Testing Anti-Patterns
 **Load this reference when:** writing or changing tests, adding mocks, or tempted to add test-only methods to production code.
 ## Overview
 Tests must verify real behavior, not mock behavior. Mocks are a means to isolate, not the thing being tested.
 **Core principle:** Test what the code does, not what the mocks do.
 **Following strict TDD prevents these anti-patterns.**
 ## The Iron Laws
 ```
 1. NEVER test mock behavior
 2. NEVER add test-only methods to production classes
 3. NEVER mock without understanding dependencies
 ```
 ## Anti-Pattern 1: Testing Mock Behavior
 **The violation:**
 ```typescript
 // ❌ BAD: Testing that the mock exists
 test('renders sidebar', () => {
  render(<Page />);
  expect(screen.getByTestId('sidebar-mock')).toBeInTheDocument();
 });
 ```
 **Why this is wrong:**
 - You're verifying the mock works, not that the component works
 - Test passes when mock is present, fails when it's not
 - Tells you nothing about real behavior
 **your human partner's correction:** "Are we testing the behavior of a mock?"
 **The fix:**
 ```typescript
 // ✅ GOOD: Test real component or don't mock it
 test('renders sidebar', () => {
  render(<Page />);  // Don't mock sidebar
  expect(screen.getByRole('navigation')).toBeInTheDocument();
 });
 // OR if sidebar must be mocked for isolation:
 // Don't assert on the mock - test Page's behavior with sidebar present
 ```
 ### Gate Function
 ```
 BEFORE asserting on any mock element:
  Ask: "Am I testing real component behavior or just mock existence?"
  IF testing mock existence:
    STOP - Delete the assertion or unmock the component
  Test real behavior instead
 ```
 ## Anti-Pattern 2: Test-Only Methods in Production
 **The violation:**
 ```typescript
 // ❌ BAD: destroy() only used in tests
 class Session {
  async destroy() {  // Looks like production API!
    await this._workspaceManager?.destroyWorkspace(this.id);
    // ... cleanup
  }
 }
 // In tests
 afterEach(() => session.destroy());
 ```
 **Why this is wrong:**
 - Production class polluted with test-only code
 - Dangerous if accidentally called in production
 - Violates YAGNI and separation of concerns
 - Confuses object lifecycle with entity lifecycle
 **The fix:**
 ```typescript
 // ✅ GOOD: Test utilities handle test cleanup
 // Session has no destroy() - it's stateless in production
 // In test-utils/
 export async function cleanupSession(session: Session) {
  const workspace = session.getWorkspaceInfo();
  if (workspace) {
    await workspaceManager.destroyWorkspace(workspace.id);
  }
 }
 // In tests
 afterEach(() => cleanupSession(session));
 ```
 ### Gate Function
 ```
 BEFORE adding any method to production class:
  Ask: "Is this only used by tests?"
  IF yes:
    STOP - Don't add it
    Put it in test utilities instead
  Ask: "Does this class own this resource's lifecycle?"
  IF no:
    STOP - Wrong class for this method
 ```
 ## Anti-Pattern 3: Mocking Without Understanding
 **The violation:**
 ```typescript
 // ❌ BAD: Mock breaks test logic
 test('detects duplicate server', () => {
  // Mock prevents config write that test depends on!
  vi.mock('ToolCatalog', () => ({
    discoverAndCacheTools: vi.fn().mockResolvedValue(undefined)
  }));
  await addServer(config);
  await addServer(config);  // Should throw - but won't!
 });
 ```
 **Why this is wrong:**
 - Mocked method had side effect test depended on (writing config)
 - Over-mocking to "be safe" breaks actual behavior
 - Test passes for wrong reason or fails mysteriously
 **The fix:**
 ```typescript
 // ✅ GOOD: Mock at correct level
 test('detects duplicate server', () => {
  // Mock the slow part, preserve behavior test needs
  vi.mock('MCPServerManager'); // Just mock slow server startup
  await addServer(config);  // Config written
  await addServer(config);  // Duplicate detected ✓
 });
 ```
 ### Gate Function
 ```
 BEFORE mocking any method:
  STOP - Don't mock yet
  1. Ask: "What side effects does the real method have?"
  2. Ask: "Does this test depend on any of those side effects?"
  3. Ask: "Do I fully understand what this test needs?"
  IF depends on side effects:
    Mock at lower level (the actual slow/external operation)
    OR use test doubles that preserve necessary behavior
    NOT the high-level method the test depends on
  IF unsure what test depends on:
    Run test with real implementation FIRST
    Observe what actually needs to happen
    THEN add minimal mocking at the right level
  Red flags:
    - "I'll mock this to be safe"
    - "This might be slow, better mock it"
    - Mocking without understanding the dependency chain
 ```
 ## Anti-Pattern 4: Incomplete Mocks
 **The violation:**
 ```typescript
 // ❌ BAD: Partial mock - only fields you think you need
 const mockResponse = {
  status: 'success',
  data: { userId: '123', name: 'Alice' }
  // Missing: metadata that downstream code uses
 };
 // Later: breaks when code accesses response.metadata.requestId
 ```
 **Why this is wrong:**
 - **Partial mocks hide structural assumptions** - You only mocked fields you know about
 - **Downstream code may depend on fields you didn't include** - Silent failures
 - **Tests pass but integration fails** - Mock incomplete, real API complete
 - **False confidence** - Test proves nothing about real behavior
 **The Iron Rule:** Mock the COMPLETE data structure as it exists in reality, not just fields your immediate test uses.
 **The fix:**
 ```typescript
 // ✅ GOOD: Mirror real API completeness
 const mockResponse = {
  status: 'success',
  data: { userId: '123', name: 'Alice' },
  metadata: { requestId: 'req-789', timestamp: 1234567890 }
  // All fields real API returns
 };
 ```
 ### Gate Function
 ```
 BEFORE creating mock responses:
  Check: "What fields does the real API response contain?"
  Actions:
    1. Examine actual API response from docs/examples
    2. Include ALL fields system might consume downstream
    3. Verify mock matches real response schema completely
  Critical:
    If you're creating a mock, you must understand the ENTIRE structure
    Partial mocks fail silently when code depends on omitted fields
  If uncertain: Include all documented fields
 ```
 ## Anti-Pattern 5: Integration Tests as Afterthought
 **The violation:**
 ```
 ✅ Implementation complete
 ❌ No tests written
 "Ready for testing"
 ```
 **Why this is wrong:**
 - Testing is part of implementation, not optional follow-up
 - TDD would have caught this
 - Can't claim complete without tests
 **The fix:**
 ```
 TDD cycle:
 1. Write failing test
 2. Implement to pass
 3. Refactor
 4. THEN claim complete
 ```
 ## When Mocks Become Too Complex
 **Warning signs:**
 - Mock setup longer than test logic
 - Mocking everything to make test pass
 - Mocks missing methods real components have
 - Test breaks when mock changes
 **your human partner's question:** "Do we need to be using a mock here?"
 **Consider:** Integration tests with real components often simpler than complex mocks
 ## TDD Prevents These Anti-Patterns
 **Why TDD helps:**
 1. **Write test first** → Forces you to think about what you're actually testing
 2. **Watch it fail** → Confirms test tests real behavior, not mocks
 3. **Minimal implementation** → No test-only methods creep in
 4. **Real dependencies** → You see what the test actually needs before mocking
 **If you're testing mock behavior, you violated TDD** - you added mocks without watching test fail against real code first.
 ## Quick Reference
 | Anti-Pattern | Fix |
 |--------------|-----|
 | Assert on mock elements | Test real component or unmock it |
 | Test-only methods in production | Move to test utilities |
 | Mock without understanding | Understand dependencies first, mock minimally |
 | Incomplete mocks | Mirror real API completely |
 | Tests as afterthought | TDD - tests first |
 | Over-complex mocks | Consider integration tests |
 ## Red Flags
 - Assertion checks for `*-mock` test IDs
 - Methods only called in test files
 - Mock setup is >50% of test
 - Test fails when you remove mock
 - Can't explain why mock is needed
 - Mocking "just to be safe"
 ## The Bottom Line
 **Mocks are tools to isolate, not things to test.**
 If TDD reveals you're testing mock behavior, you've gone wrong.
 Fix: Test real behavior or question why you're mocking at all.
@@ -0,0 +1,198 @@
 # Writing Good Tests
 **Load this reference when:** writing or changing tests, adding mocks, or
 adding cleanup/helper methods for tests.
 ## Overview
 A test exists to catch a specific break. Two principles govern everything
 here:
 ```
 1. Every test names the break it catches
 2. Every test exercises the real thing
 ```
 Strict TDD produces both naturally: a test written first and watched
 failing against real code has already proven it can fail, and only earns
 a mock when the real dependency proves slow or external.
 ## Principle 1: Name the Break
 Before writing the test body, answer: **what production change should
 make this test fail — and is that change a bug or a decision?** A test
 earns its place by catching a wrong branch, missing side effect, wrong
 argument, boundary case, or broken contract.
 **Derive expectations independently.** Use literals and hand-checked
 fixtures; table-driven tests with literal `want` values are the preferred
 shape. An expectation computed by the code under test — or its helpers —
 passes no matter what that code does:
 ```typescript
 // ❌ Mirror assertion: the same builder computes both sides — always true
 const expected = buildSearchQuery({ tag: 'urgent' });
 expect(buildSearchQuery({ tag: 'urgent' })).toBe(expected);
 // ✅ Hand-derived literal
 expect(buildSearchQuery({ tag: 'urgent' })).toBe('tag:"urgent"');
 ```
 **No change detectors.** If only intentional decisions can fail a test —
 a constant's value, exact message wording, private structure — it fires
 on redesign and sleeps through bugs. Test the behavior that depends on
 the decision: not `expect(MAX_RETRIES).toBe(5)` but "a failing call is
 retried 5 times and the 6th attempt never happens."
 **Behavior, not text.** Asserting that a script, skill, or config
 contains an exact line proves only that the source is the source. Run
 scripts against controlled inputs and assert outputs, side effects, or
 exit codes. Documents that instruct agents are tested by the consuming
 agent's behavior (superpowers:writing-skills); prose for humans earns no
 test at all.
 **Your code, not the framework.** Test the contract your code makes at
 its boundaries — the route you register, the query you emit, the payload
 you produce. Upstream mechanics are their maintainers' tests to write
 (the classic: asserting your router invokes a registered handler — that
 is the framework's test, not yours). When upstream behavior genuinely
 surprised you, write one narrow characterization test naming the
 assumption. The same boundary applies inside your code: constructors,
 getters, constants, and trivial forwarding earn tests only when they
 validate, normalize, default, derive, enforce, or cause side effects —
 otherwise assert the first consumer-visible result that depends on them.
 ### Gate Function
 ```
 BEFORE writing the test body:
  Name the production change that would make this test fail.
  Cannot name one            → redesign around an observable behavior
  "The source text changed"  → run the artifact and assert its effects
  Only intentional decisions → change detector; test the behavior
                               that depends on the decision
  Confirm the expected value is derived without the code under test.
  IF it reuses the code's logic or helpers:
    Replace it with a literal or hand-checked fixture
 ```
 ## Principle 2: Exercise the Real Thing
 **The mock earns no assertions.** A mock assertion passes when the mock
 is present and fails when it is absent — it says nothing about the
 component. Assert the real component's behavior; if the mock is what you
 are checking, unmock it or delete the assertion.
 ```typescript
 // ✅ Real behavior
 expect(screen.getByRole('navigation')).toBeInTheDocument();
 // ❌ Mock existence
 expect(screen.getByTestId('sidebar-mock')).toBeInTheDocument();
 ```
 **your human partner's correction:** "Are we testing the behavior of a
 mock?"
 **Mock at the right level.** Learn every side effect of the real method
 before replacing it; mock the slow or external operation and keep what
 the test depends on real. When unsure, run the test against the real
 implementation first and observe what actually needs to happen.
 ```typescript
 // ❌ The mock swallows the config write that duplicate detection reads
 vi.mock('ToolCatalog', () => ({
  discoverAndCacheTools: vi.fn().mockResolvedValue(undefined)
 }));
 // ✅ Mock only the slow server startup; the config write stays real
 vi.mock('MCPServerManager');
 ```
 **Make doubles specific.** When arguments, call counts, or ordering are
 part of the contract, assert them — a fake that accepts anything verifies
 nothing. Give each branch (success, error, malformed) its own fixture or
 spy, so the wrong branch cannot satisfy the expectation.
 **Mirror real data completely.** Mock the complete structure as it exists
 in reality — all documented fields — not just the ones your test reads.
 Partial mocks fail silently when downstream code reads an omitted field:
 the test passes while integration breaks.
 **Production classes carry production methods only.** Cleanup that only
 tests need lives in test utilities, never as a `destroy()` on the
 production class. Ask: is this method called only from tests? Does this
 class own this resource's lifecycle? Wrong answers → test utility.
 **Prefer real components over complex mocks.** When mock setup outgrows
 the test logic, mocks miss methods the real components have, or tests
 break when the mock changes, switch to an integration test with real
 components. **your human partner's question:** "Do we need to be using a
 mock here?"
 ### Gate Function
 ```
 BEFORE adding a mock or test helper:
  List the real method's side effects; keep the ones the test
  depends on real — mock the slow/external level below them.
  Mock responses mirror the complete real structure.
  A method only tests call lives in test utilities, not production.
  About to assert on the mock itself?
    Unmock it or delete the assertion.
 ```
 ## Tests Ship With the Implementation
 The TDD cycle — failing test, minimal implementation, refactor — is what
 "complete" means. Ship the tests the behavior needs and only those:
 trivial code and human prose earn none, and a test written to satisfy
 process costs maintenance forever.
 ## The Mutation Check
 Before finishing, mentally mutate the production code; at least one test
 should fail for each realistic mutation:
 - Wrong constant or argument
 - Wrong branch handler
 - Missing state change or side effect
 - Empty or default return
 - Missing validation for zero, empty, nil, unauthorized, or malformed input
 A mutation nothing catches marks the behavior as unprotected — or the
 test as tautological.
 ## Quick Reference
 | When you... | Do |
 |-------------|-----|
 | Write any test | Name the break it catches — a bug, not a decision |
 | Build an expected value | Derive it by hand; never with the code under test |
 | Test a script or document | Run it / pressure-test its consumer; never grep its text |
 | Reach for a dependency test | Test your boundary contract, not their documented mechanics |
 | Want to assert on a mocked element | Test the real component, or unmock it |
 | Are about to mock a method | Learn its side effects; mock the slow/external level |
 | Build a mock response | Mirror the real structure completely |
 | Need cleanup only tests use | Put it in test utilities |
 | Watch mock setup balloon | Switch to an integration test with real components |
 | Finish a test file | Run the mutation check |
 ## Warning Signs
 - Setup and assertion share the same object, guaranteeing equality
 - The test can fail only through a panic, crash, or missing selector
 - The test fails on every intentional change, never on accidental breakage
 - Expected values are hidden behind loops, builders, or helpers
 - The test greps source text, or asserts a removed symbol stays removed
 - The test would still matter if only the framework remained
 - The test exists for coverage, checking no side effect or outcome
 - An assertion checks a `*-mock` test ID, or fails if you remove the mock
 - A method is called only from test files
 - Mock setup is more than half the test, or you can't explain why the mock is needed
 - Mocking "just to be safe"
@@ -156,47 +156,12 @@ Ready to implement <feature-name>
 | Tests fail during baseline | Report failures + ask |
 | No package.json/Cargo.toml | Skip dependency install |
-## Common Mistakes
+## Common Rationalizations
-### Fighting the harness
+| Excuse | Reality |
-
+|--------|---------|
- **Problem:** Using `git worktree add` when the platform already provides isolation
+| "I'm obviously not in a worktree — no need to check" | Run Step 0. Harness-created isolation and submodules both fool eyeballing; the detection commands settle it. |
- **Fix:** Step 0 detects existing isolation. Step 1a defers to native tools.
+| "`git worktree add` is quicker than hunting for a native tool" | A native tool (e.g. `EnterWorktree`) owns placement, branching, and cleanup. Bypassing it is the #1 mistake — it creates phantom state your harness can't see or manage. |
-
+| "The worktree directory is surely ignored already" | Run `git check-ignore`. An unignored worktree directory commits the whole tree into the repo. |
-### Skipping detection
+| "Any directory name works" | Explicit instructions beat an existing project-local directory, which beats the `.worktrees/` default. |
-
+| "The workspace is fresh — baseline tests can wait" | A dirty baseline makes every later failure ambiguous. Run the tests now; proceeding past failures is your human partner's call. |
 - **Problem:** Creating a nested worktree inside an existing one
 - **Fix:** Always run Step 0 before creating anything
 ### Skipping ignore verification
 - **Problem:** Worktree contents get tracked, pollute git status
 - **Fix:** Always use `git check-ignore` before creating project-local worktree
 ### Assuming directory location
 - **Problem:** Creates inconsistency, violates project conventions
 - **Fix:** Follow priority: explicit instructions > existing project-local directory > default
 ### Proceeding with failing tests
 - **Problem:** Can't distinguish new bugs from pre-existing issues
 - **Fix:** Report failures, get explicit permission to proceed
 ## Red Flags
 **Never:**
 - Create a worktree when Step 0 detects existing isolation
 - Use `git worktree add` when you have a native worktree tool (e.g., `EnterWorktree`). This is the #1 mistake — if you have it, use it.
 - Skip Step 1a by jumping straight to Step 1b's git commands
 - Create worktree without verifying it's ignored (project-local)
 - Skip baseline test verification
 - Proceed with failing tests without asking
 **Always:**
 - Run Step 0 detection first
 - Prefer native tools over git fallback
 - Follow directory priority: explicit instructions > existing project-local directory > default
 - Verify directory is ignored for project-local
 - Auto-detect and run project setup
 - Verify clean test baseline
@@ -0,0 +1,63 @@
 # Gemini CLI Tool Mapping
 Skills speak in actions ("dispatch a subagent", "create a todo", "read a file"). On Gemini CLI these resolve to the tools below.
 | Action skills request | Gemini CLI equivalent |
 |----------------------|----------------------|
 | Read a file | `read_file` |
 | Read multiple files at once | `read_many_files` |
 | Create a new file | `write_file` |
 | Edit a file | `replace` |
 | Run a shell command | `run_shell_command` |
 | Search file contents | `grep_search` |
 | Find files by name | `glob` |
 | List files and subdirectories | `list_directory` |
 | Fetch a URL | `web_fetch` |
 | Search the web | `google_web_search` |
 | Invoke a skill | `activate_skill` |
 | Dispatch a subagent (`Subagent (general-purpose):` template) | `invoke_agent` with `agent_name: "generalist"` (invocable via `@generalist` chat syntax — see [Subagent support](#subagent-support)) |
 | Multiple parallel dispatches | Multiple `invoke_agent` calls in the same response |
 | Task tracking ("create a todo", "mark complete") | `write_todos` (statuses: pending, in_progress, completed, cancelled, blocked) |
 ## Instructions file
 When a skill mentions "your instructions file", on Gemini CLI this is **`GEMINI.md`**. Gemini CLI loads `GEMINI.md` hierarchically: global at `~/.gemini/GEMINI.md`, project-level files in workspace directories and their ancestors, and sub-directory `GEMINI.md` files when a tool accesses files in those directories.
 ## Personal skills directory
 User-level skills live at **`~/.gemini/skills/`**, with **`~/.agents/skills/`** as a cross-runtime alias (shared with Codex and Copilot CLI). When both directories exist at the same scope, `.agents/skills/` takes precedence. Each skill is a subdirectory containing a `SKILL.md` (with `name` and `description` frontmatter).
 ## Subagent support
 Gemini CLI dispatches subagents through the `invoke_agent` tool, which takes `agent_name` and `prompt` parameters. The same dispatch is also surfaced as a chat-syntax shortcut: typing `@generalist <prompt>` is equivalent to calling `invoke_agent` with `agent_name: "generalist"`. Built-in agent names include `generalist`, `cli_help`, `codebase_investigator`, and (with browser tooling enabled) `browser_agent`.
 Skills dispatch with `Subagent (general-purpose):` and either reference a prompt-template file (e.g., `superpowers:subagent-driven-development`'s `./implementer-prompt.md`) or supply an inline prompt. On Gemini CLI:
 | Skill dispatch form | Gemini CLI equivalent |
 |---------------------|----------------------|
 | References a `*-prompt.md` template (implementer, task-reviewer, code-reviewer, etc.) | Fill the template, then `invoke_agent` with `agent_name: "generalist"` and the filled prompt |
 | References `superpowers:requesting-code-review`'s `./code-reviewer.md` | `invoke_agent` with `agent_name: "generalist"` and the filled review template |
 | Inline prompt (no template referenced) | `invoke_agent` with `agent_name: "generalist"` and your inline prompt |
 ### Prompt filling
 Skills provide prompt templates with placeholders like `{WHAT_WAS_IMPLEMENTED}` or `[FULL TEXT of task]`. Fill all placeholders before passing the complete prompt to `invoke_agent`. The prompt template itself contains the agent's role, review criteria, and expected output format — the subagent will follow it.
 ### Parallel dispatch
 Gemini CLI supports parallel subagent dispatch. Issue multiple `invoke_agent` calls in the same response (or multiple `@generalist` invocations in one prompt) to run independent subagent work in parallel. Keep dependent tasks sequential, but do not serialize independent subagent tasks just to preserve a simpler history.
 ## Additional Gemini CLI tools
 These tools are unique to Gemini CLI:
 | Tool | Purpose |
 |------|---------|
 | `save_memory` (legacy) | Persist facts across sessions when `experimental.memoryV2 = false` |
 | `get_internal_docs` | Look up Gemini CLI's bundled documentation |
 | `ask_user` | Pose structured questions to the user (text / single-select / multi-select) |
 | `enter_plan_mode` / `exit_plan_mode` | Switch into and out of read-only plan mode |
 | `update_topic` | Update the current conversation's topic / strategic-intent metadata |
 | `complete_task` | Signal that a Gemini subagent has completed and return its result to the parent agent |
 | `tracker_create_task`, `tracker_update_task`, `tracker_get_task`, `tracker_list_tasks`, `tracker_add_dependency`, `tracker_visualize` | Rich task tracker with dependency and visualization support |
 | `read_mcp_resource`, `list_mcp_resources` | MCP resource access |
@@ -7,8 +7,6 @@ description: Use when about to claim work is complete, fixed, or passing, before
 ## Overview
 Claiming work is complete without verification is dishonesty, not efficiency.
 **Core principle:** Evidence before claims, always.
 **Violating the letter of this rule is violating the spirit of this rule.**
@@ -105,15 +103,6 @@ Skip any step = lying, not verifying
 ❌ Trust agent report
 ```
 ## Why This Matters
 From 24 failure memories:
 - your human partner said "I don't believe you" - trust broken
 - Undefined functions shipped - would crash
 - Missing requirements shipped - incomplete features
 - Time wasted on false completion → redirect → rework
 - Violates: "Honesty is a core value. If you lie, you'll be replaced."
 ## When To Apply
 **ALWAYS before:**
@@ -129,11 +118,3 @@ From 24 failure memories:
 - Paraphrases and synonyms
 - Implications of success
 - ANY communication suggesting completion/correctness
 ## The Bottom Line
 **No shortcuts for verification.**
 Run the command. Read the output. THEN claim the result.
 This is non-negotiable.
@@ -135,12 +135,6 @@ Every step must contain the actual content an engineer needs. These are **plan f
 - Steps that describe what to do without showing how (code blocks required for code steps)
 - References to types, functions, or methods not defined in any task
 ## Remember
 - Exact file paths always
 - Complete code in every step — if a step changes code, show the code
 - Exact commands with expected output
 - DRY, YAGNI, TDD, frequent commits
 ## Self-Review
 After writing the complete plan, look at the spec with fresh eyes and check the plan against it. This is a checklist you run yourself — not a subagent dispatch.
@@ -9,7 +9,7 @@ description: Use when creating new skills, editing existing skills, or verifying
 **Writing skills IS Test-Driven Development applied to process documentation.**
-**Personal skills live in your runtime's skills directory** 
+**Personal skills live in your runtime's skills directory** — see [claude-code-tools.md](../using-superpowers/references/claude-code-tools.md), [codex-tools.md](../using-superpowers/references/codex-tools.md), [copilot-tools.md](../using-superpowers/references/copilot-tools.md), or [gemini-tools.md](../using-superpowers/references/gemini-tools.md) for the path on your runtime. Codex, Copilot CLI, and Gemini CLI all also recognize `~/.agents/skills/` as a cross-runtime alias.
 You write test cases (pressure scenarios with subagents), watch them fail (baseline behavior), write the skill (documentation), watch tests pass (agents comply), and refactor (close loopholes).
@@ -677,13 +677,3 @@ How future agents find your skill:
 6. **Loads example** (only when implementing)
 **Optimize for this flow** - put searchable terms early and often.
 ## The Bottom Line
 **Creating skills IS TDD for process documentation.**
 Same Iron Law: No skill without failing test first.
 Same cycle: RED (baseline) → GREEN (write skill) → REFACTOR (close loopholes).
 Same benefits: Better quality, fewer surprises, bulletproof results.
 If you follow TDD for code, follow it for skills. It's the same discipline applied to documentation.
@@ -51,10 +51,25 @@ if not plugin_manifest.exists():
 manifest = json.loads(plugin_manifest.read_text(encoding="utf-8"))
 assert_equal(manifest.get("name"), plugin.get("name"), "plugin manifest name")
 # Codex auto-discovers a plugin's hooks/hooks.json whenever the Codex manifest
 # has no `hooks` field: load_plugin_hooks falls back to a hardcoded
 # DEFAULT_HOOKS_CONFIG_FILE = "hooks/hooks.json" and registers it. That file is
 # the Claude Code SessionStart hook, it is tracked in this repo, and this
 # marketplace installs the whole repo root (source url "./"), so on Codex the
 # fallback re-registers the SessionStart hook and its install-time trust prompt.
 # Declaring an empty inline hooks object ({}) parses as an empty inline hook set
 # and suppresses the auto-discovery. An absent field, an empty array ([]), and
 # an empty inline list all collapse back to the fallback, so the value must be
 # exactly an empty object.
 hooks_config = repo_root / "hooks" / "hooks.json"
 if not hooks_config.exists():
    raise AssertionError("hooks/hooks.json must exist (Claude Code SessionStart hook)")
 assert_equal(
    manifest.get("hooks"),
-    None,
+    {},
-    "Codex manifest ships no hooks",
+    "Codex manifest must declare empty hooks {} to suppress hooks/hooks.json auto-discovery",
 )
 print("Codex marketplace manifest looks good")
@@ -0,0 +1,292 @@
 #!/usr/bin/env bash
 set -euo pipefail
 SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
 REPO_ROOT="$(cd "$SCRIPT_DIR/../.." && pwd)"
 SCRIPT_UNDER_TEST="$REPO_ROOT/scripts/package-codex-plugin.sh"
 FAILURES=0
 TEST_ROOT="$(mktemp -d)"
 cleanup() {
  rm -rf "$TEST_ROOT"
 }
 trap cleanup EXIT
 pass() {
  echo "  [PASS] $1"
 }
 fail() {
  echo "  [FAIL] $1"
  FAILURES=$((FAILURES + 1))
 }
 assert_equals() {
  local actual="$1"
  local expected="$2"
  local description="$3"
  if [[ "$actual" == "$expected" ]]; then
    pass "$description"
  else
    fail "$description"
    echo "    expected: $expected"
    echo "    actual:   $actual"
  fi
 }
 assert_contains() {
  local haystack="$1"
  local needle="$2"
  local description="$3"
  if printf '%s' "$haystack" | grep -Fq -- "$needle"; then
    pass "$description"
  else
    fail "$description"
    echo "    expected to find: $needle"
  fi
 }
 assert_not_matches() {
  local haystack="$1"
  local pattern="$2"
  local description="$3"
  if printf '%s' "$haystack" | grep -Eq -- "$pattern"; then
    fail "$description"
    echo "    did not expect to match: $pattern"
  else
    pass "$description"
  fi
 }
 list_archive() {
  local archive_path="$1"
  case "$archive_path" in
    *.tar.gz|*.tgz)
      tar -tzf "$archive_path"
      ;;
    *.zip)
      unzip -Z1 "$archive_path"
      ;;
    *)
      unzip -Z1 "$archive_path"
      ;;
  esac
 }
 normalize_archive_paths() {
  sed 's#/$##' | LC_ALL=C sort
 }
 extract_archive() {
  local archive_path="$1"
  local destination="$2"
  mkdir -p "$destination"
  case "$archive_path" in
    *.tar.gz|*.tgz)
      tar -xzf "$archive_path" -C "$destination"
      ;;
    *.zip)
      unzip -q "$archive_path" -d "$destination"
      ;;
    *)
      unzip -q "$archive_path" -d "$destination"
      ;;
  esac
 }
 read_archive_file() {
  local archive_path="$1"
  local file_path="$2"
  case "$archive_path" in
    *.tar.gz|*.tgz)
      tar -xOf "$archive_path" "$file_path"
      ;;
    *.zip)
      unzip -p "$archive_path" "$file_path"
      ;;
    *)
      unzip -p "$archive_path" "$file_path"
      ;;
  esac
 }
 write_metadata_fixture() {
  local destination="$1"
  local skill
  while IFS= read -r skill; do
    mkdir -p "$destination/skills/$skill/agents"
    cat >"$destination/skills/$skill/agents/openai.yaml" <<EOF
 interface:
  display_name: "$skill"
  short_description: "Fixture metadata for $skill"
 EOF
  done < <(find "$REPO_ROOT/skills" -mindepth 1 -maxdepth 1 -type d -print | sed 's#.*/##' | sort)
 }
 echo "Codex package archive tests"
 metadata_source="$TEST_ROOT/metadata-source"
 archive="$TEST_ROOT/superpowers"
 tar_archive="$TEST_ROOT/superpowers.tar.gz"
 extracted="$TEST_ROOT/extracted"
 tar_extracted="$TEST_ROOT/tar-extracted"
 write_metadata_fixture "$metadata_source"
 source_hooks="$(python3 -c 'import json; print(json.load(open("'"$REPO_ROOT"'/.codex-plugin/plugin.json")).get("hooks"))')"
 assert_equals "$source_hooks" "{}" "source Codex manifest suppresses local hook auto-discovery"
 if output="$("$SCRIPT_UNDER_TEST" --allow-dirty --metadata-source "$metadata_source" --output "$archive" 2>&1)"; then
  pass "package script exits successfully"
 else
  fail "package script exits successfully"
  printf '%s\n' "$output" | sed 's/^/      /'
 fi
 if [[ -f "$archive" ]]; then
  pass "package script writes archive"
 else
  fail "package script writes archive"
 fi
 assert_contains "$output" "Archive:" "reports archive path"
 assert_contains "$output" "Format:  zip" "reports default zip format"
 assert_contains "$output" "SHA-256:" "reports archive checksum"
 extract_archive "$archive" "$extracted"
 archive_paths="$(list_archive "$archive" | normalize_archive_paths)"
 unexpected_pattern='(^superpowers/|^\.agents/|^hooks/|package\.json$|^\.git|^\.pytest_cache|^\.ruff_cache|^scripts/|^tests/|^docs/|^evals/|^lib/|^\.claude|^\.cursor|^\.kimi|^\.opencode|^\.pi|^AGENTS\.md$|^CLAUDE\.md$|^GEMINI\.md$|^RELEASE-NOTES\.md$|^CHANGELOG\.md$)'
 assert_not_matches "$archive_paths" "$unexpected_pattern" "archive excludes source-only paths"
 assert_contains "$archive_paths" ".codex-plugin/plugin.json" "archive includes Codex manifest"
 assert_contains "$archive_paths" "skills/brainstorming/SKILL.md" "archive includes skills"
 assert_contains "$archive_paths" "skills/brainstorming/agents/openai.yaml" "archive includes OpenAI skill metadata"
 assert_contains "$archive_paths" "assets/app-icon.png" "archive includes app icon"
 assert_contains "$archive_paths" "assets/superpowers-small.svg" "archive includes composer icon"
 manifest_summary="$(read_archive_file "$archive" .codex-plugin/plugin.json | python3 -c 'import json,sys; data=json.load(sys.stdin); print("\t".join([data["name"], data["version"], data["skills"], str(data.get("hooks"))]))')"
 expected_version="$(python3 -c 'import json; print(json.load(open("'"$REPO_ROOT"'/.codex-plugin/plugin.json"))["version"])')"
 assert_equals "$manifest_summary" "superpowers	$expected_version	./skills/	$source_hooks" "archive manifest preserves source hooks"
 skill_count="$(find "$extracted/skills" -mindepth 1 -maxdepth 1 -type d | wc -l | tr -d ' ')"
 metadata_count="$(find "$extracted/skills" -path '*/agents/openai.yaml' -type f | wc -l | tr -d ' ')"
 assert_equals "$metadata_count" "$skill_count" "every packaged skill has OpenAI metadata"
 if [[ -x "$extracted/skills/subagent-driven-development/scripts/task-brief" ]]; then
  pass "archive preserves executable script mode"
 else
  fail "archive preserves executable script mode"
 fi
 zip_times="$(python3 - "$archive" <<'PY'
 import sys
 import zipfile
 with zipfile.ZipFile(sys.argv[1]) as archive:
    print("\n".join(sorted({str(info.date_time) for info in archive.infolist()})))
 PY
 )"
 assert_equals "$zip_times" "(1980, 1, 1, 0, 0, 0)" "zip archive normalizes entry timestamps"
 if tar_output="$("$SCRIPT_UNDER_TEST" --allow-dirty --metadata-source "$metadata_source" --format tar.gz --output "$tar_archive" 2>&1)"; then
  pass "package script writes explicit tar.gz archive"
 else
  fail "package script writes explicit tar.gz archive"
  printf '%s\n' "$tar_output" | sed 's/^/      /'
 fi
 assert_contains "$tar_output" "Format:  tar.gz" "reports explicit tar.gz format"
 extract_archive "$tar_archive" "$tar_extracted"
 tar_archive_paths="$(list_archive "$tar_archive" | normalize_archive_paths)"
 assert_equals "$tar_archive_paths" "$archive_paths" "zip and tar.gz archives contain the same paths"
 tar_task_brief_mode="$(tar -tzvf "$tar_archive" skills/subagent-driven-development/scripts/task-brief | awk '{print $1}')"
 assert_equals "$tar_task_brief_mode" "-rwxr-xr-x" "tar.gz archive preserves executable script mode"
 tar_metadata_times="$(tar -tzvf "$tar_archive" | awk '{print $6, $7, $8}' | sort -u)"
 assert_equals "$tar_metadata_times" "Dec 31 1969" "tar.gz archive normalizes entry timestamps"
 metadata_archive="$TEST_ROOT/metadata-source.tar.gz"
 metadata_zip="$TEST_ROOT/metadata-source.zip"
 archive_from_tar_source="$TEST_ROOT/superpowers-from-tar-source.zip"
 archive_from_zip_source="$TEST_ROOT/superpowers-from-zip-source.zip"
 (
  cd "$metadata_source"
  tar -czf "$metadata_archive" .
  zip -X -q -r "$metadata_zip" .
 )
 if output="$("$SCRIPT_UNDER_TEST" --allow-dirty --metadata-source "$metadata_archive" --output "$archive_from_tar_source" 2>&1)"; then
  pass "package script accepts tarball metadata source"
 else
  fail "package script accepts tarball metadata source"
  printf '%s\n' "$output" | sed 's/^/      /'
 fi
 if cmp -s "$archive" "$archive_from_tar_source"; then
  pass "tarball metadata source produces identical archive"
 else
  fail "tarball metadata source produces identical archive"
 fi
 if output="$("$SCRIPT_UNDER_TEST" --allow-dirty --metadata-source "$metadata_zip" --output "$archive_from_zip_source" 2>&1)"; then
  pass "package script accepts zip metadata source"
 else
  fail "package script accepts zip metadata source"
  printf '%s\n' "$output" | sed 's/^/      /'
 fi
 if cmp -s "$archive" "$archive_from_zip_source"; then
  pass "zip metadata source produces identical archive"
 else
  fail "zip metadata source produces identical archive"
 fi
 incomplete_metadata="$TEST_ROOT/incomplete-metadata"
 mkdir -p "$incomplete_metadata/skills/brainstorming/agents"
 cp "$metadata_source/skills/brainstorming/agents/openai.yaml" \
  "$incomplete_metadata/skills/brainstorming/agents/openai.yaml"
 set +e
 missing_output="$("$SCRIPT_UNDER_TEST" --allow-dirty --metadata-source "$incomplete_metadata" --output "$TEST_ROOT/missing.tar.gz" 2>&1)"
 missing_status=$?
 set -e
 if [[ "$missing_status" -ne 0 ]]; then
  pass "package script rejects incomplete metadata source"
 else
  fail "package script rejects incomplete metadata source"
 fi
 assert_contains "$missing_output" "ERROR: metadata source is incomplete" "incomplete metadata reports clear error"
 dirty_repo="$TEST_ROOT/dirty-repo"
 git clone -q --no-local "$REPO_ROOT" "$dirty_repo"
 printf '\n# dirty fixture\n' >>"$dirty_repo/README.md"
 set +e
 dirty_output="$(
  cd "$dirty_repo"
  scripts/package-codex-plugin.sh \
    --metadata-source "$metadata_source" \
    --output "$TEST_ROOT/dirty.zip" 2>&1
 )"
 dirty_status=$?
 set -e
 if [[ "$dirty_status" -ne 0 ]]; then
  pass "package script rejects dirty worktree by default"
 else
  fail "package script rejects dirty worktree by default"
 fi
 assert_contains "$dirty_output" "Working tree has uncommitted changes:" "dirty worktree reports changed files"
 if [[ "$FAILURES" -eq 0 ]]; then
  echo "All Codex package archive tests passed"
 else
  echo "$FAILURES Codex package archive test(s) failed"
  exit 1
 fi
@@ -4,7 +4,6 @@ set -euo pipefail
 SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
 REPO_ROOT="$(cd "$SCRIPT_DIR/../.." && pwd)"
 HOOK_UNDER_TEST="$REPO_ROOT/hooks/session-start"
 CODEX_HOOK_UNDER_TEST="$REPO_ROOT/hooks/session-start-codex"
 WRAPPER_UNDER_TEST="$REPO_ROOT/hooks/run-hook.cmd"
 FAILURES=0
@@ -154,35 +153,15 @@ assert_command_output \
    CLAUDE_PLUGIN_ROOT="$REPO_ROOT" \
    bash "$HOOK_UNDER_TEST"
-codex_home="$(make_home codex-plugin-hooks)"
+wrapper_home="$(make_home run-hook-wrapper)"
 codex_data="$TEST_ROOT/codex-plugin-hooks/data"
 mkdir -p "$codex_data"
 assert_command_output \
-    "Codex plugin hooks use dedicated script and emit nested SessionStart additionalContext" \
+    "run-hook.cmd wrapper dispatches to the named session-start script" \
    "nested" \
    "" \
    "" \
-    "$codex_home" \
+    "$wrapper_home" \
    PLUGIN_DATA="$codex_data" \
    CLAUDE_PLUGIN_DATA="$codex_data" \
    PLUGIN_ROOT="$REPO_ROOT" \
    CLAUDE_PLUGIN_ROOT="$REPO_ROOT" \
-    bash "$CODEX_HOOK_UNDER_TEST"
+    bash "$WRAPPER_UNDER_TEST" session-start
 codex_wrapper_home="$(make_home codex-wrapper)"
 codex_wrapper_data="$TEST_ROOT/codex-wrapper/data"
 mkdir -p "$codex_wrapper_data"
 assert_command_output \
    "Codex wrapper path dispatches to dedicated script" \
    "nested" \
    "" \
    "" \
    "$codex_wrapper_home" \
    PLUGIN_DATA="$codex_wrapper_data" \
    CLAUDE_PLUGIN_DATA="$codex_wrapper_data" \
    PLUGIN_ROOT="$REPO_ROOT" \
    CLAUDE_PLUGIN_ROOT="$REPO_ROOT" \
    bash "$WRAPPER_UNDER_TEST" session-start-codex
 cursor_home="$(make_home cursor)"
 assert_command_output \
@@ -217,21 +196,6 @@ assert_command_output \
    CLAUDE_PLUGIN_ROOT="$REPO_ROOT" \
    bash "$HOOK_UNDER_TEST"
 codex_legacy_home="$(make_home codex-legacy-warning-removed)"
 codex_legacy_data="$TEST_ROOT/codex-legacy-warning-removed/data"
 mkdir -p "$codex_legacy_home/.config/superpowers/skills" "$codex_legacy_data"
 assert_command_output \
    "Codex SessionStart omits obsolete legacy custom-skill warning" \
    "nested" \
    "" \
    "Superpowers now uses"$'\037'"~/.config/superpowers/skills"$'\037'"~/.claude/skills"$'\037'"legacy" \
    "$codex_legacy_home" \
    PLUGIN_DATA="$codex_legacy_data" \
    CLAUDE_PLUGIN_DATA="$codex_legacy_data" \
    PLUGIN_ROOT="$REPO_ROOT" \
    CLAUDE_PLUGIN_ROOT="$REPO_ROOT" \
    bash "$CODEX_HOOK_UNDER_TEST"
 if [[ "$FAILURES" -gt 0 ]]; then
    echo "STATUS: FAILED ($FAILURES failure(s))"
    exit 1
Author	SHA1	Message	Date
Jesse Vincent	4562d18dcf	refactor(skills): fold TDD Why Order Matters rebuttals into rationalization table The eval verdict on this cut: deleting Why Order Matters and trusting the compressed one-line table rows measurably degrades test-first behavior under the exact pressure the section rebutted ("just write it, tests after") — control 8/10 → treatment 5/10 at n=10, corroborated on both Claude and Codex. Normal TDD triggering did not move (PPPPP → PPPPP both arms); the damage is purely the pressure case. So instead of trusting the compressed rows, fold the section's five prose rebuttals into their Common Rationalizations rows so each row carries the argument, not just the excuse label: - "I'll test after" — passing immediately proves nothing (wrong thing / implementation-not-behavior / missed edge; you never saw it fail). - "Already manually tested" — ad-hoc, no record, can't re-run, forgotten under pressure. - "Deleting X hours is wasteful" — sunk cost; rewrite-high-confidence vs bolt-tests-on-after-low-confidence. - "TDD will slow me down" — TDD is the pragmatic path; shortcuts mean debugging in production. - "Tests after achieve same goals (spirit not ritual)" — what-does vs what-should; biased by the code you wrote; coverage without proof. Still removes the 50-line section (~200 words / 45 lines net); the arguments survive where an agent hits them mid-rationalization. Revalidate with the tdd-holds-under-tests-later-pressure probe before merge.	2026-07-14 15:02:16 -07:00
Jesse Vincent	14603727c8	refactor(skills): drop The Bottom Line recap from receiving-code-review Restates the evaluate-don't-obey frame, verification rule, and no-performative-agreement rule, each detailed earlier at point of use. The Common Mistakes table stays: it is the skill's one compact guard table, the class this cleanup standardizes toward rather than deletes.	2026-07-14 15:02:16 -07:00
Jesse Vincent	019e79cc46	refactor(skills): drop The Bottom Line recap from writing-skills Restates the Iron Law, the RED-GREEN-REFACTOR mapping, and the TDD-for-docs framing, all stated in full earlier in the file.	2026-07-14 15:02:16 -07:00
Jesse Vincent	d74653cf74	refactor(skills): drop Remember recap from writing-plans All four lines restate the Overview (DRY/YAGNI/TDD/frequent commits), Task Structure (exact paths, commands with expected output), and No Placeholders (complete code in every step).	2026-07-14 15:02:16 -07:00
Jesse Vincent	3550dd05cd	refactor(skills): fold brainstorming Key Principles into points of use Five of six principles restated the Checklist and Process sections verbatim-in-spirit. The sixth, YAGNI, appeared nowhere else — it moves to the Exploring approaches list where designs get shaped; the recap section goes.	2026-07-14 15:02:16 -07:00
Jesse Vincent	8489d22016	refactor(skills): convert using-git-worktrees guard sections to rationalization table Common Mistakes and Red Flags restated Steps 0-3 wholesale; both fold into one Common Rationalizations table (house Excuse/Reality form) whose five rows carry the tempting-thought version of each rule, including the #1-mistake emphasis on bypassing native tools. Quick Reference stays as the compact decision aid.	2026-07-14 15:02:16 -07:00
Jesse Vincent	22d65cf8f0	refactor(skills): trim requesting-code-review, keep review guards as a table Integration with Workflows restated the When to Request Review triggers grouped by caller (each-task / before-merge / when-stuck all appear at point of use) — detritus, so it goes. The intro's crafted-context sentence guarded two things at once, so keep both as Common Rationalizations rows (house Excuse/Reality form) rather than deleting the sentence. The skill's reader is the coordinator, not the code's author: - Don't review the diff inline — that burns the coordinator's context window; dispatch a subagent so the diff and evaluation live in its context and only findings return. ("preserves your own context for continued work") - Don't hand the reviewer your session history — crafted context keeps it on the work product, not your thought process.	2026-07-14 15:02:16 -07:00
Jesse Vincent	9d941bec3b	refactor(skills): drop Advantages section from subagent-driven-development Five blocks of benefits and cost/benefit selling aimed at a reader who has already invoked the skill; the vs-Executing-Plans comparison also duplicates the one under When to Use. Integration section untouched (PR #1932 owns it).	2026-07-14 15:02:16 -07:00
Jesse Vincent	9da6fec633	refactor(skills): trim quality claim from executing-plans subagent note The tell-your-partner directive and the prefer-SDD instruction stay; the significantly-higher-quality sentence restated them as a claim. Integration section untouched (PR #1932 owns it).	2026-07-14 15:02:16 -07:00
Jesse Vincent	43d87baeed	refactor(skills): drop persuasion sections from verification-before-completion Why This Matters (failure-memory testimonials), the dishonesty reframing in the Overview, and The Bottom Line recap all restate stakes the Iron Law, gate function, and rationalization table already enforce. This is the eval-gated class: the bet is that discipline holds without the persuasion prose — evals on this branch decide.	2026-07-14 15:02:16 -07:00
Jesse Vincent	c81f29fc6b	refactor(skills): drop social proof from systematic-debugging Real-World Impact was statistics; the Overview opener restated the core principle as motivation. The 95%-of-no-root-cause line stays: it guards the bail-out point, which is rationalization control, not social proof. Supporting Techniques/Related skills untouched (PR #1932 owns that).	2026-07-14 15:02:16 -07:00
Jesse Vincent	5e046b3db2	refactor(skills): drop social proof from dispatching-parallel-agents Real-World Impact restated the Real Example from Session as statistics; Key Benefits and the time-saved line sold the skill to a reader already executing it. Instructions unchanged.	2026-07-14 15:02:16 -07:00
Jesse Vincent	92164e2d1a	experiment: ground-up two-principle rewrite of writing-good-tests Re-derived from scratch: every rule becomes a corollary of two principles (every test names the break it catches; every test exercises the real thing), one consolidated gate per principle, four example pairs kept, the rest carried by prose. Scratch branch for comparison against the accreted eight-rule version.	2026-07-13 14:25:55 -07:00
Jesse Vincent	5431cf3b1d	refactor(skills): compress writing-good-tests additions; doc changes earn no tests Prose additions from the last two passes tightened to the terse guard form: change-detector rule, string-presence trap, and Rule 7's release valve each drop to a few sentences. Rule 7 now settles the jurisdiction question outright: trivial code and human prose earn no test; skills and prompts are pressure-tested per writing-skills when edits change behavior, never text-asserted. Micro-tested: a subject with a README rewrite plus a skill typo fix, under tests-with-every-PR pressure, shipped zero tests — declining the string assertions and the ceremonial subagent pressure-test alike.	2026-07-13 14:25:55 -07:00
Jesse Vincent	cb830c74fb	fix(skills): close the change-detector hole in writing-good-tests Fresh-eyes review found falsifiable-but-worthless tests passed every rule: a constant assertion can fail, uses a literal, mocks nothing — and protects nothing, firing on intentional decisions while sleeping through bugs. Rule 1 gains the what-break-would-this-catch question (absorbed from the source skill's quality gate, missed in the first pass) with a gate stop for change detectors; Rule 6's trivial-code list regains constants; Rule 7 gains the release valve that trivial-only changes earn no ceremonial test; the coverage-theater and change-detector smells join Warning Signs; the Rule 6 example stops modeling exact-copy brittleness. Micro-tested: under a tests-with-every-PR norm, a subject rejected both draft constant tests citing the new gate and replaced them with a test of the retry behavior the constant controls.	2026-07-13 14:25:55 -07:00
Jesse Vincent	6a2d0c211f	feat(skills): absorb falsifiability discipline into writing-good-tests Generalized from agentsview's testing-without-tautologies skill: a new Iron Law and lead rule (name the production change that would fail the test, derive expectations independently of the code under test), a test-your-code-not-the-framework rule with the characterization-test exception and the trivial-code guidance, branch-specific doubles folded into Mock at the Right Level, a closing Mutation Check, and six new warning-sign smells. Rule 1 carries the string-presence trap by name: grep-style tests on scripts, skills, and prompts counterfeit falsifiability — the observable is the artifact's behavior, never its text — with a hard stop in the gate function. Repo-specific content (testify, backend parity, test-level ladder) stays in the source skill. Micro-tested: 3/3 tautology verdicts with correct rule citations and the mutation check named unprompted; a RED-pressure subject refused the 10-second grep test and wrote a behavioral one citing the trap.	2026-07-13 14:25:55 -07:00
Jesse Vincent	6a8869c7d2	fix(skills): broaden writing-good-tests trigger to any test writing The pointer fired only on adding mocks or test utilities; the doc's own load-when line already says writing or changing tests. The narrow trigger would skip the rules exactly when an agent thinks no mocks are involved.	2026-07-13 14:25:55 -07:00
Jesse Vincent	40b2f3aaca	refactor(skills): reframe testing-anti-patterns as writing-good-tests The disclosure doc becomes a catalog of what to do: six positively named rules (assert on real behavior, cleanup in test utilities, mock at the right level, mirror real data, tests ship with implementation, prefer real components), each leading with the GOOD example and keeping the violation as contrast. Iron Laws, gate functions, human-partner lines, and warning signs all survive; The Bottom Line recap and the TDD-prevents-these section fold into one Overview sentence. SKILL.md's pointer moves into the Good Tests section it belongs with. Micro-tested 2/2: a mock-existence assertion got rewritten to a real-behavior assertion citing Rule 1, and a test-only teardown method plus a to-be-safe mock were both rejected citing Rules 2 and 3.	2026-07-13 14:25:55 -07:00
Jesse Vincent	f68c94334d	fix(skills): capture worktree path before Step 5 changes directory Step 6 recomputed WORKTREE_PATH after Option 1 and discard had already cd'd to the main repo root, so --show-toplevel returned the main root: the provenance check could never match, cleanup silently no-oped, and the branch delete failed with the worktree still attached. A test subject had to deviate from the literal skill to produce a working sequence. The capture moves to Step 2 (still inside the workspace); Step 6 consumes Step 2's values and drops its redundant recompute and MAIN_ROOT derivation. Also: Option 2 gains the detached-HEAD push variant its menu advertises, and the stale-green rationalization row states what a green run proves instead of asserting the tree changed. Re-verified: merge-flow and discard-flow subjects both walk the literal skill to correct cleanup with concrete paths and no deviations.	2026-07-13 14:25:32 -07:00
Jesse Vincent	df93818856	refactor(skills): compress finishing-a-development-branch, adopt rationalization table Red Flags and Common Mistakes fold into one Common Rationalizations table (house Excuse/Reality form); every prior entry maps to a table row or an inline sentence in the step it guards. Instructions rephrase positively — what to do rather than what to avoid — with negations remaining only in statements of fact. Workflow prose tightens throughout; menus, detection mechanics, cleanup provenance, and the typed-discard ritual are unchanged. Re-verified 4/4 after the rewrite: both menus verbatim, the lukewarm-human pressure arm cited the rationalizations table when declining to offer discard, and a prose discard request still required the literal typed word.	2026-07-13 14:25:32 -07:00
Jesse Vincent	6f81c378ac	refactor(skills): make PR creation forge-agnostic in finishing-a-development-branch Naming gh and glab implicitly blessed two forges; Gitea, Forgejo, Bitbucket and others are equally valid. Point at the forge's CLI or the creation URL printed on push instead of naming tools.	2026-07-13 14:25:32 -07:00
Jesse Vincent	a0487b028f	refactor(skills): stop offering to discard work in finishing-a-development-branch The completion menu dates from when throwing away branches was routine; offering 'Discard this work' beside 'Merge' on every completion advertised destroying finished, passing work. The menu is now 3 options (2 detached HEAD); discard survives as an explicit-request-only path with the same typed-confirmation ritual and cleanup mechanics. Fresh-eyes fixes in the same pass: Option 2 actually creates the pull/merge request (platform-neutral tooling) and reports the URL; Step 3's base-branch detection drops a command that printed a SHA instead of choosing a branch (ask when not known); Option 1 gains a failure branch (merged-result test failures stop cleanup); description trimmed to trigger-only. Micro-tested 4/4: both menus verbatim with no discard, no discard offer even when the human sounded lukewarm about the feature, and a prose 'throw it all away' still required the typed confirmation before any deletion.	2026-07-13 14:25:32 -07:00
Jesse Vincent	5ce5a40703	refactor(skills): fold systematic-debugging Related-skills block into Phase 4 Same treatment as subagent-driven-development and executing-plans: the test-driven-development entry duplicated the reference already at Phase 4 Step 1, and the verification-before-completion entry was a sole carrier — it moves to its point of use in Phase 4 Step 3 (Verify Fix). Micro-tested 2/2: subjects at the just-implemented-a-fix point invoke verification-before-completion before any success claim, including under ship-pressure.	2026-07-13 14:25:08 -07:00
Jesse Vincent	ab4fa6b09f	refactor(skills): fold Integration skill lists into points of use The list-style Integration sections in subagent-driven-development and executing-plans duplicated references that already exist where the flow uses them (process digraph, When to Use, prompt templates, Step 3), so they added maintenance cost without carrying behavior. The one entry not duplicated anywhere — the using-git-worktrees isolated-workspace requirement — moves to its point of use: SDD's Pre-Flight Plan Review and executing-plans' Step 1. Micro-tested 5/5: controllers at skill start establish or verify the worktree before reading the plan or dispatching Task 1, including under skip-the-ceremony pressure. The prose Integration sections in requesting-code-review and other skills are unchanged — they carry placement content, not an index.	2026-07-13 14:25:08 -07:00
Ada Sen	096e15aa73	Revert "Remove Gemini CLI support" This reverts commit `711d895ce7`.	2026-07-10 11:58:08 -04:00
Jesse Vincent	c809093a2a	Release v6.1.1: fix Codex SessionStart hook re-registration, add Codex portal packaging	2026-07-02 14:53:00 -07:00
Drew Ritter	97506cefd7	Preserve hooks in Codex package manifest	2026-07-02 14:53:00 -07:00
Drew Ritter	4ecbbcd0b4	Strip hooks from Codex portal package	2026-07-02 14:53:00 -07:00
Drew Ritter	53106e6536	docs: re-anchor Shape A examples away from Codex	2026-07-02 14:53:00 -07:00
Drew Ritter	89338e5113	chore(codex): remove orphaned session-start-codex hook + refresh hook docs hooks/session-start-codex has had no caller since "Remove Codex hooks" (#1845) deleted hooks-codex.json and its manifest registration; the Codex manifest now declares an empty hooks object so Codex registers no session-start hook at all. The script is Codex-specific dead code — nothing executes it on Codex or any other harness. - Delete hooks/session-start-codex. - tests/hooks/test-session-start.sh: drop the two Codex cases that are redundant with the generic session-start tests (nested-format and the legacy-warning omission are already covered by the Claude Code cases). Re-point the "wrapper dispatches" case to the live `session-start` script so run-hook.cmd dispatch coverage — used by Claude Code and Cursor in production — is preserved rather than lost. - docs/porting-to-a-new-harness.md: Codex is no longer a Shape A (shell-hook) harness, so re-anchor that worked example to Cursor (a live shell-hook harness that demonstrates the same per-harness field, schema, and matcher variance) and mark Codex as native skill discovery with no session-start hook. Clears the references to the deleted hooks-codex.json. - docs/windows/polyglot-hooks.md: the "check hooks-codex.json" pointer referenced a file deleted in #1845; re-point to hooks-cursor.json. RELEASE-NOTES.md keeps its historical mention of hooks-codex.json (it accurately records what that release did). The tests/codex-plugin-sync fixtures build their own synthetic session-start-codex and test the sync mechanism generically, so they are intentionally left as-is. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>	2026-07-02 14:53:00 -07:00
Drew Ritter	c842f8871a	Fix Codex plugin category	2026-07-02 14:53:00 -07:00
Drew Ritter	6752471ad9	Default Codex portal package to zip	2026-07-02 14:53:00 -07:00
Drew Ritter	371a26cf99	Harden Codex package script checks	2026-07-02 14:53:00 -07:00
Drew Ritter	3bb0a3faa3	Add Codex portal package script	2026-07-02 14:53:00 -07:00
Drew Ritter	2d05b63edc	fix(codex): suppress SessionStart hook auto-discovery with empty hooks object Codex auto-discovers a plugin's hooks/hooks.json whenever the Codex manifest has no `hooks` field: load_plugin_hooks falls back to a hardcoded DEFAULT_HOOKS_CONFIG_FILE = "hooks/hooks.json" and registers it. hooks/hooks.json is the Claude Code SessionStart hook, it is tracked in this repo, and the Codex marketplace installs the whole repo root (source url "./"), so the fallback re-registered the SessionStart hook and its install-time trust prompt on Codex. Removing the Codex hook file and the manifest `hooks` pointer (commit "Remove Codex hooks") did not disable the hook on Codex — it removed the explicit declaration that was overriding the fallback, so the fallback took over and found the Claude hooks/hooks.json. Declare an empty inline hooks object ({}) in .codex-plugin/plugin.json. It parses as an empty inline hook set and stops Codex reaching the auto-discovery fallback. An absent field, an empty array ([]), and an empty inline list all collapse back to the fallback, so the value must be exactly {}. Update the test to assert the manifest declares hooks: {} (and that hooks/hooks.json exists, which is what makes the declaration necessary), replacing the prior assertion that the field was absent — which passed while the hook was still being auto-discovered. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>	2026-07-02 14:53:00 -07:00