mirror of
https://github.com/obra/superpowers.git
synced 2026-08-01 23:21:34 +08:00
Compare commits
3 Commits
docs/codex
...
fix/t1-sdd
| Author | SHA1 | Date | |
|---|---|---|---|
|
|
7c560e048b | ||
|
|
2e7d681591 | ||
|
|
bb2a34b2a0 |
@@ -3,12 +3,6 @@
|
|||||||
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.
|
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
|
## 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).
|
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).
|
||||||
|
|||||||
@@ -1,85 +0,0 @@
|
|||||||
# 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.
|
|
||||||
@@ -34,6 +34,15 @@ 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.
|
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
|
## What to Check
|
||||||
|
|
||||||
**Plan alignment:**
|
**Plan alignment:**
|
||||||
|
|||||||
@@ -223,6 +223,12 @@ and fix-round diffs need it.
|
|||||||
later dispatches — a real session's dispatch hit 42k chars of which 99%
|
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
|
was pasted history. A fresh subagent needs its task, the interfaces it
|
||||||
touches, and the global constraints. Nothing else.
|
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
|
- If an earlier task parked a finding in the area this task touches, carry
|
||||||
a pointer to that ledger entry in the dispatch.
|
a pointer to that ledger entry in the dispatch.
|
||||||
- Record the implementer's agent identity from the dispatch result —
|
- Record the implementer's agent identity from the dispatch result —
|
||||||
@@ -434,6 +440,7 @@ 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. |
|
| "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. |
|
| "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. |
|
| "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
|
## Example Workflow
|
||||||
|
|
||||||
|
|||||||
@@ -47,6 +47,18 @@ Subagent (general-purpose):
|
|||||||
While iterating, run the focused test for what you're changing; run the
|
While iterating, run the focused test for what you're changing; run the
|
||||||
full suite once before committing, not after every edit.
|
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
|
## Code Organization
|
||||||
|
|
||||||
You reason best about code you can hold in context at once, and your edits are more
|
You reason best about code you can hold in context at once, and your edits are more
|
||||||
|
|||||||
@@ -43,6 +43,15 @@ Subagent (general-purpose):
|
|||||||
Your review is read-only on this checkout. Do not mutate the working
|
Your review is read-only on this checkout. Do not mutate the working
|
||||||
tree, the index, HEAD, or branch state in any way.
|
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
|
## Scope
|
||||||
|
|
||||||
Your scope is the findings list and the fix diff. Verdict every finding.
|
Your scope is the findings list and the fix diff. Verdict every finding.
|
||||||
|
|||||||
@@ -52,6 +52,15 @@ Subagent (general-purpose):
|
|||||||
Your review is read-only on this checkout. Do not mutate the working
|
Your review is read-only on this checkout. Do not mutate the working
|
||||||
tree, the index, HEAD, or branch state in any way.
|
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
|
## Do Not Trust the Report
|
||||||
|
|
||||||
Treat the implementer's report as unverified claims about the code. It
|
Treat the implementer's report as unverified claims about the code. It
|
||||||
|
|||||||
Reference in New Issue
Block a user