docs: document packaging a release for the Codex portal

The portal zip flow (scripts/package-codex-plugin.sh) had no release
docs: how to seed the OpenAI-owned openai.yaml metadata source, build
the rootless archive from the release tag, verify it, and what breaks
when a release adds a new skill. Written after packaging v6.2.0.

README.md

@@ -3,6 +3,12 @@
 Superpowers is a complete software development methodology for your coding agents, built on top of a set of composable skills and some initial instructions that make sure your agent uses them.
 
 
+## We're Hiring!
+
+We're hiring someone to help out full time with Superpowers community and code work. 
+You can read about the job at https://primeradiant.com/jobs/superpowers-community-engineer/
+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), [Gemini CLI](#gemini-cli), [GitHub Copilot CLI](#github-copilot-cli), [Kimi Code](#kimi-code), [OpenCode](#opencode), [Pi](#pi).

docs/releasing-to-codex.md

@@ -0,0 +1,85 @@
+# Releasing to the Codex portal
+
+How to package a Superpowers release as the zip artifact OpenAI's Codex
+plugin portal expects, and what to check before handing it over.
+
+This is distinct from the older flow of syncing files into a fork of
+`openai/plugins` and opening a PR, which
+`scripts/sync-to-codex-plugin.sh` still implements — see the distribution
+table in [porting-to-a-new-harness.md](porting-to-a-new-harness.md). The portal
+artifact is a standalone, rootless archive: `.codex-plugin/`, `assets/`,
+`skills/`, `README.md`, `LICENSE`, and `CODE_OF_CONDUCT.md` sit at the
+archive root. Hooks, tests, docs, scripts, and other harnesses' manifests
+are deliberately not shipped.
+
+## Prerequisite: the OpenAI metadata source
+
+Each packaged skill must carry `skills/<name>/agents/openai.yaml`. That
+metadata is OpenAI-owned — it does not live in this repo — so the packaging
+script seeds it from a prior official package. By default it looks for, in
+order:
+
+1. `../_tmp/sup-codex-packaging/superpowers/` (an unpacked package)
+2. `../_tmp/sup-codex-packaging/superpowers.zip`
+3. `../_tmp/sup-codex-packaging/superpowers.tar.gz`
+
+or pass `--metadata-source <dir|.zip|.tar.gz>` explicitly.
+
+If you have no prior package on disk, extract one from `openai/plugins`
+(the upstream repo still carries the plugin, including the metadata):
+
+```bash
+# from a clone with an `upstream` remote pointing at github.com/openai/plugins
+git fetch upstream
+mkdir -p ../_tmp/sup-codex-packaging/superpowers
+git archive upstream/main -- plugins/superpowers |
+  tar -x --strip-components 2 -C ../_tmp/sup-codex-packaging/superpowers
+```
+
+**New skills fail the build.** The script requires one `openai.yaml` per
+skill directory; otherwise it prints `Missing OpenAI agent metadata for
+skill: <name>` for each gap and dies with `metadata source is incomplete`.
+If a release adds a skill, there is no metadata for it yet;
+you need an updated official package (or metadata added upstream in
+`openai/plugins`) before you can package. Don't hand-invent the yaml.
+
+## Build the archive
+
+From a clean working tree, package the release tag:
+
+```bash
+scripts/package-codex-plugin.sh --ref vX.X.X
+```
+
+The script reads the version from `.codex-plugin/plugin.json` (bumped by
+`scripts/bump-version.sh`, so it matches the release tag), stages the tree
+from the git ref — never from the working copy — and writes
+`../_tmp/sup-codex-packaging/superpowers-VERSION.zip`, printing entry
+count, skill count, and a SHA-256. Timestamps and file order are pinned so
+rebuilding the same ref reproduces the same archive.
+
+Useful flags: `--output PATH`, `--format zip|tar.gz`, `--allow-dirty`
+(archive still comes from `--ref`), `--keep-stage` (inspect the staging
+dir). `--help` has the full list.
+
+## Verify
+
+The script already refuses archives containing source-only paths and
+mismatched metadata counts. Sanity-check the result anyway:
+
+```bash
+unzip -Z1 ../_tmp/sup-codex-packaging/superpowers-X.X.X.zip | head
+unzip -Z1 ../_tmp/sup-codex-packaging/superpowers-X.X.X.zip | grep -c 'agents/openai.yaml'
+unzip -p  ../_tmp/sup-codex-packaging/superpowers-X.X.X.zip .codex-plugin/plugin.json | jq -r .version
+```
+
+Expect: rootless top-level entries (`.codex-plugin/`, `assets/`,
+`skills/`), one `openai.yaml` per skill, and the release version.
+
+The script itself is covered by `tests/codex/test-package-codex-plugin.sh`.
+
+## Upload
+
+Upload the zip through OpenAI's Codex plugin portal. This is a manual step
+outside this repo; record the SHA-256 the script printed so the uploaded
+artifact can be matched to the build.

skills/subagent-driven-development/SKILL.md

@@ -193,14 +193,6 @@ that implementer. Single-file mechanical fixes also take the cheapest tier.
 
 ## The Task Loop
 
-**Batch small same-shape work.** When the plan lists several tasks that are
-each a small, independent edit of the same kind — the same one-line fix,
-constant change, or field addition repeated across files — do not dispatch
-one subagent per task. Compose ONE dispatch brief listing every file and
-its change, send the whole batch to a single subagent, and review its diff
-as one unit. Reserve one-dispatch-per-task for work that needs its own
-judgment, its own tests, or its own review surface.
-
 Everything you paste into a dispatch prompt — and everything a subagent
 prints back — stays resident in your context for the rest of the session
 and is re-read on every later turn. Hand artifacts over as files.

skills/subagent-driven-development/task-reviewer-prompt.md

@@ -86,12 +86,6 @@ Subagent (general-purpose):
     - **Misunderstood:** right feature built the wrong way, wrong problem
       solved
 
-    If the brief lists several files each with its own change (a batched
-    dispatch), check the diff against that list file by file: every listed
-    file must have its corresponding hunk. A listed file the diff never
-    touches is a Missing finding, no matter how clean the rest of the
-    batch looks.
-
     If a requirement cannot be verified from this diff alone (it lives in
     unchanged code or spans tasks), report it as a ⚠️ item instead of
     broadening your search.