OpenSpec and Superpowers Together: Two Recorded superpowers-bridge Runs
superpowers-bridge is the community schema that lets OpenSpec plan a change and Superpowers build it. Its README lists OpenSpec 1.4.1 and Superpowers v5.1.0 as the versions it was written against and calls that "a historical snapshot, not an end-to-end compatibility guarantee". On 17 November 2026 we ran it end to end twice, on OpenSpec 2.1.0 and Superpowers 7.0.2, from the same one-line request, and scored both results with a test suite the agent never saw. The schema still works, with a few changes to the setup. The score depended on the person answering its questions: 8 of 8 hidden checks when they knew the rules, 6 of 8 when they approved everything.
Spec Coding is not affiliated with OpenSpec (Fission AI), Superpowers (Jesse Vincent) or the bridge's maintainer. This is two runs on one small fixture with one controller model, and the person in both runs was a member of our team following a written protocol. Every message, artifact, diff and score is in the run pack. For what each tool is and how they differ, see OpenSpec vs Superpowers vs Spec Kit.
Results at a glance
The fixture is tasks-api, a small Node API (142 lines with its tests and docs) from our API error envelope case. The request was one line: "Our API error responses are all over the place. Clean them up so they're consistent." The two left columns are the single-prompt runs we recorded on the same fixture on 28 September with the same model, Claude Opus 5.5.
| One prompt, vague (3 runs) | One prompt, spec (3 runs) | Bridge run A: informed reviewer | Bridge run B: approves everything | |
|---|---|---|---|---|
| Hidden checks passed | 7/8 in all three | 8/8 in all three | 8/8 | 6/8 |
| Messages from the person | 1 | 1 | 8 | 8 to merge, 15 to archive |
| Agent working time | 42 to 44 s | 60 to 67 s | 21 min 25 s | 10 min 16 s to merge, 16 min 3 s in total |
| Cost reported by Claude Code | $0.17 to $0.19 | $0.19 to $0.26 | $6.28 | $3.12 to merge, $5.18 in total |
| Tests in the repo afterwards | 13 | 15 to 17 | 40 | 32 at merge, 35 at the end |
Ids such as __proto__ rejected | 0 of 3 | 1 of 3 | Yes | Yes |
| Planning record left in the repo | None | None | 8 artifacts, archived, spec synced | 8 artifacts, archived, spec synced |
Three things stand out. The bridge did not make a vague request safe on its own: with a person who approved everything, it scored one check lower than a plain vague prompt and cost about 17 times as much before the merge. With a person who knew the rules it matched the spec prompt's score, at about 27 times the cost. And in both bridge runs the whole-branch review at the end found a bug that was already in the fixture and that five of the six single-prompt runs left in place.
The setup that worked on OpenSpec 2.1.0 and Superpowers 7.0.2
npm install @fission-ai/[email protected] # ff, new, continue and verify are not in the default "core" profile openspec config set profile custom openspec config set workflows '["propose","explore","new","continue","apply","ff","sync","archive","verify"]' openspec init --tools claude --scope project # 2.1 installs skills globally without --scope project git clone https://github.com/JiangWay/openspec-schemas /tmp/oss cp -R /tmp/oss/superpowers-bridge openspec/schemas/superpowers-bridge openspec schema validate superpowers-bridge # ✓ Schema 'superpowers-bridge' is valid # openspec/config.yaml: schema: superpowers-bridge git clone --branch v7.0.2 https://github.com/obra/superpowers claude --plugin-dir ./superpowers
We loaded Superpowers from a checkout of the v7.0.2 tag so the version is pinned; the bridge's README installs it with claude plugin install superpowers@claude-plugins-official. The fixture has no CLAUDE.md, so we skipped the bridge's optional routing fragment, as its README says to. Both runs start from the same commit, made right after these steps.
What changed since the bridge's baseline
The bridge bundle is version 1.0.0, and the last commit to it is from June 2026. These are the differences we hit, or did not hit, five months and two major versions later.
| Area | What the bridge's README assumes | What we saw |
|---|---|---|
| Schema structure | openspec schema validate superpowers-bridge passes | Still passes on 2.1.0, and openspec schemas lists it as a project schema |
| Commands | /opsx:ff, /opsx:apply, /opsx:verify, /opsx:continue, /opsx:archive | OpenSpec 2.0 removed the /opsx:* commands; each one has a matching skill. Our install created nine skills and no commands. The same steps are /openspec-ff-change, /openspec-apply-change, /openspec-verify-change, /openspec-continue-change and /openspec-archive-change |
| Workflow profile | ff, new, continue and verify are available | The default core profile installs propose, explore, apply, update, sync and archive only. The others need the custom profile shown above, set before openspec init |
| Skill names | brainstorming, writing-plans, using-git-worktrees, subagent-driven-development, finishing-a-development-branch | All present under the same names in 7.0.2, and the schema's skill prechecks passed |
| Output redirection | The brainstorm goes to the change's brainstorm.md and the plan to plan.md, not to docs/superpowers/ | Held in both runs. Nothing was written under docs/superpowers/ |
| Worktree | using-git-worktrees creates the workspace | It used Claude Code's own worktree under .claude/worktrees/. The planning files were still untracked on main, so they were missing from the new worktree. In both runs the agent copied them in, committed them as the branch's first commit, and deleted the untracked copy before merging |
| Execution | subagent-driven-development only. The schema says it does not support executing-plans | Since 6.4.1, Superpowers has rebuilt executing-plans as "Native" execution, and its plan handoff offers both. Run A never showed the choice. Run B did, recommended Native, and used it. See run B |
| Verify precheck | Counts commits against origin/main | Our throwaway repo has no remote, so the command as written reports nothing. In run B the agent said so and counted from the commit before the change instead |
One practical note on openspec init: version 2.1.0 installs its skills with Vercel's skills package, which clones the OpenSpec repository from GitHub at the release tag. On our connection the clone stopped at the built-in 300-second limit. With SKILLS_CLONE_TIMEOUT_MS=1500000 set, it finished in 6 minutes 42 seconds.
How the person answered
The workflow asks questions, so someone has to answer them, and the answers decide a lot. We wrote the rules down before each run.
- Run A, the informed reviewer. The person knows what the case's spec says. That spec was written in September, before any recorded run, and it is in the pack as
answer-sheet.md. They answer a question only with what the spec says about it, approve a proposal unless it contradicts the spec, correct only the point that contradicts it, and never mention something a proposal leaves out. - Run B, the approver. The person knows the one-line request and nothing else. They answer "No preference, your call" and approve every proposal as written.
In both runs, process choices take the agent's recommendation, offers to skip the conversation are declined, and no turn is re-run or edited. Each message was one headless claude -p call resumed on the same session, with the AskUserQuestion tool disabled so that questions arrive as text.
Run A, turn by turn
| Turn | The person sent | The agent did |
|---|---|---|
| 1 | /openspec-ff-change plus the one-line request | Created the change, read the code and docs/mobile-contract.md, listed six different error shapes, pointed out that the mobile apps need error to stay a string, and asked what was driving the work |
| 2 | The goal: one JSON envelope for every non-2xx response, without breaking mobile v3.x | Proposed four scope items and three envelope shapes, recommended a flat shape with error, code, details and requestId, and asked whether requestId belongs in it |
| 3 | Yes to the shape. requestId is the incoming X-Request-Id or a generated one, and is also sent back as a header | Laid out three ways to build it and recommended one error type with one formatter |
| 4 | "Option 1 works for me." | Wrote brainstorm.md and listed the calls it had made, among them: status codes stay as they are, so an archived project and a validation error both stay 400 |
| 5 | Two corrections: archived project is 409, invalid fields are 422. "The rest is approved." | Wrote the proposal, design, spec (7 requirements, 15 scenarios), 13 tasks and a four-task plan in 2 min 50 s |
| 6 | One correction: details is always an array, on every error | Updated all six artifacts |
| 7 | /openspec-apply-change standardize-api-errors | Worked for 15 min 16 s: worktree, four implementers and four task reviewers, a whole-branch review, a fix round and re-review, verify.md, retrospective.md, archive. Then asked how to finish the branch |
| 8 | "1" (merge locally) | Fast-forward merge, 40 of 40 tests passing, worktree and branch removed |
The agent asked three real questions: why, what shape, and how to build it. It did not ask about status codes or about whether details is optional. It decided those itself.
Three corrections, and where each one was visible
The 409 and 422 corrections were easy to make, because the agent put its choice in the chat under "Calls I made" with a table of every status code. That list is the most useful thing the brainstorming step produced.
The third was not in the chat. The summary at turn 4 listed five calls. The file it had just written contained a sixth:
- `details` (array, optional) — only for validation: `[{ field, message }]`.
Our stand-in approved the design at turn 5 from the chat summary without opening brainstorm.md, and caught the line one turn later while reading spec.md before the apply step. That was our lapse, and we left it in the record. It matters because it is exactly the shape the hidden suite rejects. Check A3 requires every error body to have the same top-level keys, and the three single-prompt vague runs each failed that check and no other.
What the apply step produced
- Eleven subagents: four implementers and four task reviewers on Sonnet 5.5, a whole-branch reviewer on Opus 5.5, then one fix implementer and one re-review.
- Ten commits on the branch: the plan, four tasks, the task checklist, the fix round, verify, retrospective and archive.
- 307 lines added and 17 removed in
src/andtest/, across five files.npm testwent from 4 tests to 40. verify.mdended as "PASS WITH WARNINGS". The warning is real: Node answers a malformed request line or an oversized header itself, before the handler runs, so those responses do not use the envelope. Nobody had considered it during planning.- The whole-branch review found a bug that predates the change. Project and task ids are looked up as keys of plain objects, so
GET /projects/__proto__/tasksreturned 200, andPATCH /tasks/__proto__wrotedoneontoObject.prototypefor the whole process. None of the four task reviews could see it, because no task touched the lookup code.
We replayed the recorded diffs of the six single-prompt Opus runs against the same two requests. Five still return 200 and pollute the prototype. One spec run happens to reject them.
Run B: the person approves everything
The first message from the agent was close to run A's: the same findings and the same question about what was driving the work. The answer was only that the responses should be consistent, so the agent said it would "propose the rest myself". Its proposal differed from run A's in the ways that count:
- The error body is
{ error, code }, withdetailsadded for validation errors only. - Status codes stay as they are: "An archived project stays a 400 rather than becoming a 409".
- Sending
X-Request-Idback is out of scope: "It would help support, but it's a separate feature from consistency."
All three were stated in the chat, and all three were approved. The hidden suite then failed A3, which found two body shapes (code,error and code,details,error), and A6, because the request id never comes back. The mobile contract file in the repo says the apps send that header and that support asks users for it. The agent had read the file and still left the header out, as a scope decision.
The Native execution option
After writing the plan, the agent offered two ways to run it, Subagent-driven or Native, and recommended Native: "There are only three small tasks". That choice was added in Superpowers 6.4.1: the plan handoff offers both and recommends one. The bridge's schema was written against 5.1.0, before it existed, and says it does not support executing-plans, the skill behind Native.
Our approver took the recommendation. The agent invoked executing-plans, implemented all three tasks itself and ran one whole-branch reviewer, which found the same __proto__ bug as in run A. The turn took 5 min 17 s. It then went straight to finishing the branch. The schema's apply sequence, which puts verify, the retrospective and the archive before the merge, did not run. The agent said so: "After merging, the OpenSpec verify and archive steps are still to do." Closing the change took seven more messages: verify, a fix round for two warnings, the retrospective, and the archive. The run's own retrospective records subagent-driven-development as skipped and suggests the schema should count either execution style as valid.
In run A the same handoff did not offer the choice. The agent wrote that "this project's workflow sets the execution method". Same schema, same versions, same request, and a different path. If you want the schema's sequence, say "subagent-driven" when asked, or start the apply step yourself with /openspec-apply-change.
What the two runs say
- The bridge supplies process, not rules. Both runs read the mobile contract and kept
errora string without being told. The rules that are not in the repo (409 and 422,detailsalways present, the request id echoed) were corrected by a person in run A and decided by the agent in run B. - The decisions are written down, in two places. Most are in the chat, under headings like "Calls I made". Some are only in the artifact. Read
brainstorm.mdandspec.mdbefore approving them. A summary of a document is not the document. - An approver who knows nothing gets the vague-prompt result at a much higher price. Run B cost $3.12 to reach a merge that a $0.18 prompt beat by one hidden check.
- If you already know the rules, writing them down is cheaper. The spec prompt scored 8 of 8 in about a minute for about $0.23. Run A needed the same knowledge from the same person, delivered as one answer and three corrections.
- The whole-branch review earns part of its cost. It found a real bug in both runs that the spec did not mention and five of six single-prompt runs kept.
- You also get a record. Both runs left the brainstorm, proposal, design, spec, tasks, plan, verification and retrospective in the repo, and synced the requirements into
openspec/specs/. A single prompt leaves a diff.
When the bridge is worth it
| Situation | What we would do |
|---|---|
| A contract change where nobody has written the rules yet, and someone who knows the product will read the artifacts | Use the bridge. The questions and the "calls I made" lists are where the rules get decided |
| You already have a spec with acceptance criteria | Give the agent the spec. Add Superpowers for the build if you want test-first tasks and reviews. The brainstorm has little left to find |
| Nobody has time to read the artifacts | Do not use it. Approving unread documents costs more and decides nothing |
| A bug fix, a config change, a typo | A normal pull request. The bridge's own README says the same |
| The team needs an audit trail of why a change was made | Use the bridge and commit the archive with the change |
Limits of this test
- Two runs, one fixture, one controller model. Model output varies, and run A and run B already took different paths through the same schema. Treat the numbers as two observations.
- The person in both runs was one of us, answering from a written protocol. A real product owner would volunteer things our informed reviewer was not allowed to say and miss things in other places.
- The answer sheet for run A is the spec used for the single-prompt spec runs, so run A's person held the same information that prompt contains.
- The hidden suite has eight checks. It does not check 409 or 422, so run A's two status-code corrections do not show up in its score.
- Costs are the
total_cost_usdvalues Claude Code reports for each session. The single-prompt runs were recorded on 28 September with an earlier Claude Code release. - We did not test the bridge with the
CLAUDE.mdrouting fragment, with a git remote, or on a harness other than Claude Code 2.1.326.
Download the run pack
agent-run-openspec-superpowers-bridge.zip (103 KB) contains, for each run: every message as sent, a transcript of what the controller session wrote and which tools it called, the archived OpenSpec change with all eight artifacts, the code diff, the hidden-suite and npm test results, and per-turn time and cost. It also has the fixture, the hidden suite, the answer sheet, both protocols and the script that probes the __proto__ ids. Absolute paths in the transcripts are replaced; nothing else is edited.
FAQ
Does superpowers-bridge work with OpenSpec 2.x and Superpowers 7?
In our two runs on OpenSpec 2.1.0 and Superpowers 7.0.2, yes. The schema validated, every skill it names was found, and both runs produced all eight artifacts and an archived change. The setup differs from the README in two places: the workflows are installed as skills named openspec-…-change instead of /opsx: commands, and ff, continue and verify need a custom workflow profile.
What replaces /opsx:ff and /opsx:apply in OpenSpec 2.1?
OpenSpec 2.0 removed the /opsx:* commands because each one already had a matching skill. In a Claude Code install made with openspec init --tools claude, the steps are /openspec-ff-change, /openspec-apply-change, /openspec-verify-change, /openspec-continue-change and /openspec-archive-change. Our install created no /opsx: commands.
How much does a bridge run cost?
On a small Node API with Claude Opus 5.5 as the controller, one full cycle cost $6.28 with subagent-driven execution and $5.18 with Native execution, and took 21 and 16 minutes of agent time. The same change from a single prompt cost about $0.20 and took about a minute.
Can I use Superpowers' Native execution with the bridge?
The schema says it does not support it, and in our run choosing Native skipped the schema's apply sequence, so verify, the retrospective and the archive had to be started by hand after the merge. The code was still written test-first and reviewed once at the end. If you want the schema's order, choose subagent-driven.
Do I need a bridge to use OpenSpec and Superpowers together?
No. A routing rule in AGENTS.md or CLAUDE.md that points Superpowers' design and plan at the OpenSpec change folder also works, and we describe it in the tool comparison. The bridge puts the same rule into the schema, so it does not depend on the agent reading a file.
References
- JiangWay/openspec-schemas: superpowers-bridge (README,
schema.yaml, compatibility section) - Fission-AI/OpenSpec, its 2.0.0 and 2.1.0 release notes, and the @fission-ai/openspec package, version 2.1.0
- Superpowers release notes (Native execution and the two-way plan handoff)
- Superpowers writing-plans SKILL.md and brainstorming SKILL.md
- API error envelope: the recorded single-prompt runs on the same fixture
Run on 2026-11-17 with OpenSpec CLI 2.1.0, obra/superpowers v7.0.2 (commit 22f0b46), superpowers-bridge bundle 1.0.0 (JiangWay/openspec-schemas commit f5d4040, 2026-06-10) and Claude Code 2.1.326. Quotes are from the linked files and from the recorded transcripts.