Revert "Remove Gemini CLI support"

This reverts commit 711d895ce7.

.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",
@@ -27,7 +27,7 @@
     "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",

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

CLAUDE.md

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

README.md

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

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

scripts/package-codex-plugin.sh

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

skills/brainstorming/visual-companion.md

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

skills/executing-plans/SKILL.md

@@ -11,7 +11,7 @@ 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. The quality of its work will be significantly higher if run on a platform with subagent support (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
 

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

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

skills/writing-skills/SKILL.md

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

tests/codex/test-package-codex-plugin.sh

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