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.

.claude-plugin/marketplace.json

@@ -9,7 +9,7 @@
     {
       "name": "superpowers",
       "description": "Core skills library for Claude Code: TDD, debugging, collaboration patterns, and proven techniques",
-      "version": "6.1.0",
+      "version": "6.1.1",
       "source": "./",
       "author": {
         "name": "Jesse Vincent",

.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "superpowers",
   "description": "Core skills library for Claude Code: TDD, debugging, collaboration patterns, and proven techniques",
-  "version": "6.1.0",
+  "version": "6.1.1",
   "author": {
     "name": "Jesse Vincent",
     "email": "jesse@fsck.com"

.codex-plugin/plugin.json

@@ -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",

.cursor-plugin/plugin.json

@@ -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"

.kimi-plugin/plugin.json

@@ -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",

RELEASE-NOTES.md

@@ -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

gemini-extension.json

@@ -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"
 }

package.json

@@ -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",

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

@@ -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

skills/writing-skills/render-graphs.js

@@ -13,9 +13,9 @@
  * Requires: graphviz (dot) installed on system
  */
 
-import * as fs from 'fs';
+const fs = require('fs');
-import * as path from 'path';
+const path = require('path');
-import { execFileSync } from 'child_process';
+const { execSync } = require('child_process');
 
 function extractDotBlocks(markdown) {
   const blocks = [];
@@ -69,7 +69,7 @@ ${bodies.join('\n\n')}
 
 function renderToSvg(dotContent) {
   try {
-    return execFileSync('dot', ['-Tsvg'], {
+    return execSync('dot -Tsvg', {
       input: dotContent,
       encoding: 'utf-8',
       maxBuffer: 10 * 1024 * 1024
@@ -107,10 +107,9 @@ function main() {
     process.exit(1);
   }
 
-  // Check if dot is available. Run the binary directly rather than probing
+  // Check if dot is available
-  // with `which`, which is not a command on Windows.
   try {
-    execFileSync('dot', ['-V'], { stdio: 'ignore' });
+    execSync('which dot', { encoding: 'utf-8' });
   } catch {
     console.error('Error: graphviz (dot) not found. Install with:');
     console.error('  brew install graphviz    # macOS');

tests/writing-skills/test-render-graphs.sh

@@ -1,113 +0,0 @@
-#!/usr/bin/env bash
-set -u
-
-SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
-REPO_ROOT="$(cd "$SCRIPT_DIR/../.." && pwd)"
-SCRIPT_UNDER_TEST="$REPO_ROOT/skills/writing-skills/render-graphs.js"
-NODE_BIN="$(command -v node)"
-
-PASSES=0
-FAILURES=0
-TEST_ROOT="$(mktemp -d)"
-
-cleanup() {
-  rm -rf "$TEST_ROOT"
-}
-trap cleanup EXIT
-
-pass() {
-  echo "  [PASS] $1"
-  PASSES=$((PASSES + 1))
-}
-
-fail() {
-  echo "  [FAIL] $1"
-  FAILURES=$((FAILURES + 1))
-}
-
-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_contains() {
-  local haystack="$1"
-  local needle="$2"
-  local description="$3"
-
-  if printf '%s' "$haystack" | grep -Fq -- "$needle"; then
-    fail "$description"
-    echo "    did not expect to find: $needle"
-  else
-    pass "$description"
-  fi
-}
-
-fixture="$TEST_ROOT/fixture-skill"
-mkdir -p "$fixture" "$TEST_ROOT/empty-path"
-cat >"$fixture/SKILL.md" <<'EOF'
----
-name: fixture-skill
----
-
-# Fixture Skill
-
-```dot
-digraph fixture_graph {
-  start -> end;
-}
-```
-EOF
-
-echo "Writing-skills render-graphs tests"
-
-missing_dot_output="$(PATH="$TEST_ROOT/empty-path" "$NODE_BIN" "$SCRIPT_UNDER_TEST" "$fixture" 2>&1)"
-missing_dot_status=$?
-
-if [[ "$missing_dot_status" -ne 0 ]]; then
-  pass "missing Graphviz exits non-zero"
-else
-  fail "missing Graphviz exits non-zero"
-fi
-assert_contains "$missing_dot_output" "Error: graphviz (dot) not found." "missing Graphviz reports install guidance"
-assert_not_contains "$missing_dot_output" "ReferenceError: require is not defined" "script runs as an ES module"
-
-render_output="$("$NODE_BIN" "$SCRIPT_UNDER_TEST" "$fixture" 2>&1)"
-render_status=$?
-
-if [[ "$render_status" -eq 0 ]]; then
-  pass "fixture diagram renders"
-else
-  fail "fixture diagram renders"
-  printf '%s\n' "$render_output"
-fi
-
-assert_contains "$render_output" "Found 1 diagram(s)" "reports discovered diagram"
-assert_contains "$render_output" "Rendered: fixture_graph.svg" "reports rendered SVG"
-
-if [[ -f "$fixture/diagrams/fixture_graph.svg" ]]; then
-  pass "writes SVG output"
-else
-  fail "writes SVG output"
-fi
-
-if [[ -f "$fixture/diagrams/fixture_graph.svg" ]] && grep -Fq "<svg" "$fixture/diagrams/fixture_graph.svg"; then
-  pass "SVG output has SVG markup"
-else
-  fail "SVG output has SVG markup"
-fi
-
-echo
-echo "Results: $PASSES passed, $FAILURES failed"
-
-if [[ "$FAILURES" -gt 0 ]]; then
-  exit 1
-fi