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/requesting-code-review/code-reviewer.md

@@ -34,15 +34,6 @@ Subagent (general-purpose):
 
     Your review is read-only on this checkout. Do not mutate the working tree, the index, HEAD, or branch state in any way. Use tools like `git show`, `git diff`, and `git log` to inspect history. If you need a working copy of a different revision, check it out into a separate temporary directory (e.g. `git worktree add /tmp/review-[SHA] [SHA]`) — never move HEAD on this checkout.
 
-    ## You Do Not Dispatch Subagents
-
-    Do all of this review yourself. Never spawn a subagent to review part
-    of the diff, and never spawn another reviewer for a second opinion.
-    This process already provides every review seat the work gets; a
-    reviewer you spawn duplicates one of them at full cost, and its
-    verdict counts for nothing. If the diff feels too large for one
-    pass, review it in passes yourself and say so in your report.
-
     ## What to Check
 
     **Plan alignment:**

skills/subagent-driven-development/SKILL.md

@@ -223,12 +223,6 @@ and fix-round diffs need it.
   later dispatches — a real session's dispatch hit 42k chars of which 99%
   was pasted history. A fresh subagent needs its task, the interfaces it
   touches, and the global constraints. Nothing else.
-- The dispatch carries the no-subagents contract (it is in the
-  implementer template): the implementer never dispatches subagents —
-  not helpers, and never a reviewer. Review arrives from you, after the
-  report. In real sessions, every reviewer a worker spawned duplicated
-  the task review the controller dispatched anyway — a full extra
-  review seat per task.
 - If an earlier task parked a finding in the area this task touches, carry
   a pointer to that ledger entry in the dispatch.
 - Record the implementer's agent identity from the dispatch result —
@@ -440,7 +434,6 @@ Use superpowers:finishing-a-development-branch.
 | "The fix was small, skip the re-review" | Unreviewed fixes are how regressions land. Every round ends with a scoped re-review. |
 | "Reviews slow the loop down" | The loop without reviews is just unverified churn. Reviews are the loop's brakes and steering. |
 | "Ledger bookkeeping is overhead" | The ledger is what survives compaction. Controllers without one have re-dispatched entire completed task sequences. |
-| "The implementer spawned its own reviewer — free extra assurance" | It's a duplicate seat reviewing the same diff; the task review is the gate. A worker-spawned reviewer is a defect to flag, not rigor. |
 
 ## Example Workflow
 

skills/subagent-driven-development/implementer-prompt.md

@@ -47,18 +47,6 @@ Subagent (general-purpose):
     While iterating, run the focused test for what you're changing; run the
     full suite once before committing, not after every edit.
 
-    ## You Do Not Dispatch Subagents
-
-    Do all of this task's work yourself. Never spawn a subagent to
-    implement part of the task, and above all never spawn a reviewer to
-    check your work. Self-review (below) means reading your own diff.
-    Review is the controller's job: after you report, it dispatches a
-    fresh reviewer against your diff. A reviewer you spawn duplicates
-    that review at full cost, and its approval counts for nothing in
-    the process. If you catch yourself thinking "an independent review
-    would strengthen my report" — that review is already scheduled.
-    Report instead.
-
     ## Code Organization
 
     You reason best about code you can hold in context at once, and your edits are more

skills/subagent-driven-development/re-review-prompt.md

@@ -43,15 +43,6 @@ Subagent (general-purpose):
     Your review is read-only on this checkout. Do not mutate the working
     tree, the index, HEAD, or branch state in any way.
 
-    ## You Do Not Dispatch Subagents
-
-    Do all of this review yourself. Never spawn a subagent to review part
-    of the diff, and never spawn another reviewer for a second opinion.
-    This process already provides every review seat the work gets; a
-    reviewer you spawn duplicates one of them at full cost, and its
-    verdict counts for nothing. If the diff feels too large for one
-    pass, review it in passes yourself and say so in your report.
-
     ## Scope
 
     Your scope is the findings list and the fix diff. Verdict every finding.

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

@@ -52,15 +52,6 @@ Subagent (general-purpose):
     Your review is read-only on this checkout. Do not mutate the working
     tree, the index, HEAD, or branch state in any way.
 
-    ## You Do Not Dispatch Subagents
-
-    Do all of this review yourself. Never spawn a subagent to review part
-    of the diff, and never spawn another reviewer for a second opinion.
-    This process already provides every review seat the work gets; a
-    reviewer you spawn duplicates one of them at full cost, and its
-    verdict counts for nothing. If the diff feels too large for one
-    pass, review it in passes yourself and say so in your report.
-
     ## Do Not Trust the Report
 
     Treat the implementer's report as unverified claims about the code. It