OpenSpec vs Superpowers: My Spec-Driven Workflow

The first time I pointed OpenSpec and Superpowers at the same feature, I ended up with two spec documents for one checkbox. Superpowers’ brainstorming skill fired on its own and wrote a design doc into docs/superpowers/specs/; I ran /opsx:propose anyway and got a second spec in openspec/changes/<id>/proposal.md. Within the hour the two files disagreed with each other, and both looked authoritative. The same unrouted setup bit me again later: /opsx:apply cheerfully wrote an entire implementation with zero tests, and I didn’t notice until code review.

These days the same class of feature runs clean. One /opsx:propose, a failing test before every line of implementation, and an /opsx:archive at the end that freezes the reasoning for whoever reopens the feature in three weeks. Nothing about either tool changed. The entire difference is a routing block in CLAUDE.md, about a dozen lines long — and this post is the field report on getting from the first state to the second: the spec-driven development workflow that actually works, commands included.

One thing to clear up front, because search traffic tells me most people arrive here typing “openspec vs superpowers” and expecting a winner. After months of running both on real projects, I’m convinced the versus framing is a trap. These tools don’t compete for the same job any more than a blueprint competes with a site foreman. One decides what gets built and preserves why; the other decides how well it gets built and refuses to let the agent cut corners. Asking which is “better” is like asking whether a compiler or a linter is better — they live at different layers of the same pipeline.

I wrote the full triple-stack breakdown of Claude Code, OpenSpec and Superpowers earlier this year; it answered “what are these tools, and is running all three overkill.” This piece is the sequel: it assumes you have both installed and walks you to the working loop — where they collide, how to wire them, and when each one is worth reaching for.

What OpenSpec and Superpowers Each Actually Own

You can’t route two tools until you know what job each one holds, and the mistake every “vs” post repeats is comparing them feature-by-feature as if they were rival editors. They’re not on the same row of the table — they’re on different rows.

The numbers alone hint at how differently they’re positioned. As of mid-2026, Superpowers sits at roughly 249,000 GitHub stars, and — the part most comparisons miss — it’s no longer a Claude-only plugin. It now installs into Codex, Cursor, Antigravity, Copilot CLI, Kimi, OpenCode and more. It stopped being a plugin and became a methodology. OpenSpec sits at roughly 59,000 stars, deliberately narrower, focused on one thing: keeping implementation intent out of ephemeral chat history and inside versioned files.

OpenSpec owns the artifact layer. Its output is a set of files: proposal.md (including the critical Out-of-Scope section), a specs/ directory of GIVEN/WHEN/THEN behavior, design.md for the reasoning behind choices, and tasks.md as the checklist. Its unique power isn’t that it writes these files — Superpowers writes design docs too — it’s the Delta/Archive model. Every change lives in its own versioned folder and gets archived on completion, so three iterations later you can still reconstruct why version 1 chose bcrypt and version 2 switched to argon2. That history is the thing nothing else in this stack preserves.

Superpowers owns the behavior layer. It doesn’t hand you a template to fill in. It opens a conversation — “What are you really trying to do? Who’s the user? What are the constraints?” — and teases the spec out of that dialogue. Then it enforces execution: true red/green TDD, subagent-driven development where independent agents work through each task with a two-stage review, and the notorious rule that any implementation written before its test gets deleted, not warned about. Its value is discipline, not documentation.

flowchart TB
    subgraph WHAT["OpenSpec · owns WHAT + WHY"]
        direction LR
        P["proposal.md
+ Out-of-Scope"] --- SP["specs/
GIVEN/WHEN/THEN"]
        SP --- DL["Delta / Archive
versioned per change"]
    end
    subgraph HOW["Superpowers · owns HOW WELL"]
        direction LR
        CV["Conversation-first
teases spec out"] --- TDD["TDD: deletes code
written before test"]
        TDD --- SA["Subagent-driven
two-stage review"]
    end
    WHAT -->|"hands the spec down"| HOW
    HOW -->|"execution feedback"| WHAT
    style WHAT fill:#018472,color:#fff
    style HOW fill:#2b6cb0,color:#fff
    style P fill:#015f54,color:#fff
    style SP fill:#015f54,color:#fff
    style DL fill:#015f54,color:#fff
    style CV fill:#1e4e8c,color:#fff
    style TDD fill:#1e4e8c,color:#fff
    style SA fill:#1e4e8c,color:#fff

Here’s the reframe that makes everything downstream click: OpenSpec is document-first, Superpowers is conversation-first. That single difference explains almost every situational trade-off. When your requirements are already crisp, document-first is faster — you just write them down. When your requirements are fuzzy, conversation-first is faster, because the dialogue does the discovery work that a blank template can’t. So the real question was never “which tool is better” but “how settled are my requirements right now?”

Wiring OpenSpec and Superpowers So They Don’t Fight

Back to the collision from the opening, because this is the part almost every tutorial skips and it’s exactly where people get burned. OpenSpec and Superpowers do not auto-chain. Neither tool detects the other. Install both with zero configuration and the next time you describe a feature, Superpowers’ brainstorming skill fires automatically and you still want to run /opsx:propose — so you get a docs/superpowers/specs/ design doc and an openspec/changes/<id>/proposal.md for the same feature, drifting out of sync within the hour. What makes it maddening is that both files look authoritative.

The fix is convention, enforced in CLAUDE.md. You pick one planning system by writing it down, because nothing else will pick it for you. Here’s the routing block I paste into every project that runs both — copy it, adjust the paths, and the collision disappears:

## Spec-driven routing (OpenSpec + Superpowers)

- For any NEW feature, ALWAYS start with `/opsx:propose`.
  Do NOT run Superpowers `brainstorming` or `writing-plans` —
  OpenSpec owns the planning phase in this repo.
- When running `/opsx:apply`, ALWAYS follow TDD:
  write a failing test first, then implementation. Delete any
  implementation written before its test.
- During apply, run the code-review skill before every commit,
  and open an isolated git worktree for the change.
- `/opsx:archive` is ALWAYS the last action of a completed change.
  Never leave a change un-archived — the next session will
  re-read the stale spec and re-implement finished work.

That block does three things the tools won’t do on their own.

First, it routes planning to OpenSpec, so Superpowers’ brainstorming stops competing for the same job.

Second, it manually switches on Superpowers’ execution skills during apply — because TDD, code review, and worktree isolation do not activate automatically inside /opsx:apply. They fire only if CLAUDE.md tells them to. That’s the exact gap behind my zero-test implementation: OpenSpec plans; it does not discipline execution.

Third, it makes archiving non-negotiable, which prevents the single most common OpenSpec bug: forgetting to archive, then watching the next session re-read the stale spec and re-implement work that’s already done.

If you only remember one sentence from this article, make it this: the tools give you the parts, CLAUDE.md is the assembly instructions, and without it the parts actively interfere with each other. For the deeper mechanics of how these skills load and trigger, my Claude Code skills guide and the Superpowers deep dive cover the underlying model.

The Working Loop: One Feature, Two Iterations

With the routing in place, here’s the rhythm the combination settles into. I’ll walk it on a concrete example — a “remember me” login option whose session length gets revised two weeks later — because a feature that gets revised is exactly where the two-tool loop shines and where a single tool quietly loses information. Every command below is copy-pasteable.

Iteration one starts with /opsx:propose Add remember-me checkbox with 30-day sessions. OpenSpec generates the four artifacts. Open proposal.md and check Out-of-Scope first — you’re confirming the agent didn’t silently add “remember this device” fingerprinting you never asked for. Because planning already happened here, Superpowers’ brainstorming must not fire again; that’s the routing block doing its job. Then run /opsx:apply, and — only because your CLAUDE.md says so — Superpowers’ TDD takes over: each task writes a failing test first, implements, self-reviews, commits. Finish with /opsx:archive, which merges the spec delta and freezes iteration one’s reasoning.

Two weeks later the requirement changes to 7-day sessions with a refresh token. Run /opsx:propose again — it creates a new change folder, not an edit of the old one. The archived first iteration still exists. When your reviewer asks “wait, why did we ever pick 30 days?”, the answer is one git log away in the archived delta. Superpowers alone can’t do this: its second brainstorming session overwrites the first design doc, and the original reasoning is gone. That’s the entire argument for the combination, made concrete.

sequenceDiagram
    participant You
    participant OS as OpenSpec
    participant SP as Superpowers
    participant CC as Claude Code
    Note over You,CC: Iteration 1 — 30-day sessions
    You->>OS: /opsx:propose remember-me, 30d
    OS-->>You: proposal / specs / design / tasks
    You->>OS: review Out-of-Scope ✓
    You->>SP: /opsx:apply (TDD wired in CLAUDE.md)
    SP->>CC: RED → GREEN → review → commit
    CC-->>You: tasks done
    You->>OS: /opsx:archive (freeze reasoning)
    Note over You,CC: Iteration 2 — 7-day + refresh, 2 weeks later
    You->>OS: /opsx:propose 7d + refresh token
    OS-->>You: NEW change folder (v1 archive intact)
    You->>SP: /opsx:apply
    SP->>CC: RED → GREEN → review → commit
    Note over You,OS: "Why 30 days originally?"
→ answer lives in v1 archive

When OpenSpec, When Superpowers, When Both

The loop above is the both case, but most features don’t earn it. I resisted writing a decision rule for a long time because “it depends” felt more honest — except “it depends” is useless at 2pm with a feature in front of you and a need to start. So here’s the rule I actually follow, reduced to the two variables that matter: how settled are the requirements, and how many times will this feature be touched?

Fuzzy requirements plus a one-shot build: Superpowers alone. Its conversation-first brainstorming is literally designed for the case where you can’t write the spec yet, and its TDD keeps a throwaway from becoming a liability. This is my default for probably 70% of daily work. Don’t reach for OpenSpec here — writing a document-first spec for requirements you haven’t thought through yet is the single most common way to waste an hour and produce a spec you immediately rewrite.

Settled requirements plus a single clean unit: OpenSpec alone is genuinely faster than talking it out. You already know what you want; /opsx:propose turns it into structured artifacts in one pass, and you skip the Socratic questioning. But — and this is the honest edge case the “vs” posts skip — you lose Superpowers’ execution discipline. So OpenSpec-alone only makes sense if you’re comfortable reviewing the code yourself, or if you add the TDD rules to CLAUDE.md manually.

The combination earns its overhead in exactly one quadrant: a feature that will be iterated more than once, by more than one person, over more than one session. That’s where OpenSpec’s Delta/Archive stops being theoretical — the “why is the session TTL 30 days?” moment from the walkthrough above. Superpowers alone would have overwritten that reasoning on the next brainstorm.

flowchart TD
    Start["Feature in front of you"] --> Q1{"Requirements
settled?"}
    Q1 -->|"No, still fuzzy"| SP["Superpowers alone
conversation teases out spec
+ TDD execution"]
    Q1 -->|"Yes, crisp"| Q2{"Iterated more than
once, by more
than one person?"}
    Q2 -->|"No, one-shot"| OS["OpenSpec alone
propose in one pass
add TDD rule manually"]
    Q2 -->|"Yes, long-lived"| Both["Both, routed
OpenSpec plans + archives
Superpowers executes"]
    SP --> Ship1["Ship"]
    OS --> Ship2["Ship"]
    Both --> Ship3["Ship + audit trail"]
    style Start fill:#1a202c,color:#fff
    style SP fill:#2b6cb0,color:#fff
    style OS fill:#018472,color:#fff
    style Both fill:#c05621,color:#fff
    style Ship1 fill:#4a5568,color:#fff
    style Ship2 fill:#4a5568,color:#fff
    style Ship3 fill:#4a5568,color:#fff

Five Pitfalls I Hit Running This for Real

The mother article listed generic pitfalls; these are the specific ones that bit me while running the combined workflow, which is a different and sharper set.

Treating “openspec vs superpowers” as either/or. I spent my first week trying to decide which one to standardize on, when the answer was “both, at different layers.” If you find yourself arguing which tool wins, you’ve misdiagnosed the layers. Reread the layer map.

Over-speccing fuzzy requirements. OpenSpec’s document-first model punishes you when requirements aren’t settled. I once ran /opsx:propose on a half-formed idea, got a confident four-file spec, and rewrote all four files twice. Superpowers’ conversation would have surfaced the ambiguity before committing anything to disk. Match the tool to how settled the requirement is.

Assuming /opsx:apply enforces TDD. It doesn’t — this is the zero-test story from the opening. The first time I ran the combined loop without the CLAUDE.md routing block, apply happily wrote implementation with zero tests, and I only noticed at code review. OpenSpec plans; it does not discipline execution. That’s Superpowers’ job, and only if you wire it in.

Subagent token blowup on large task lists. Superpowers’ subagent-driven development rebuilds context per agent, which is fantastic for isolation and expensive for a 40-task change. On big features I now split into multiple OpenSpec changes rather than one giant tasks.md, so each subagent run stays cheap. The Hacker News crowd is right that token cost is the real trade-off here.

Believing specs fix agent laziness. The sharpest critique in the Hacker News SDD thread was that the bottleneck is “agent adherence and laziness,” not spec quality. A perfect spec does not guarantee the agent follows it. This is precisely why Superpowers’ hard rules — delete pre-test code, two-stage review — matter more than OpenSpec’s document polish. Specs constrain; they do not compel.

My 2026 Verdict

If you take one decision framework away: default to Superpowers, promote to the combination when a feature crosses the “iterated by more than one person, over more than one session” line. Superpowers is the tool that improves any project — its conversation-first planning and TDD enforcement add value at every scale, and in 2026 it works across nearly every coding agent, not just Claude Code. That breadth alone makes it the safer default bet. OpenSpec is the specialist you add when decision traceability becomes a real, felt bottleneck — usually the moment a teammate asks “why did we build it this way?” and nobody can answer.

Don’t run the full combination on everything; that’s the over-engineering trap the mother article warned about, and it’s still true. A 30-minute script does not need a Delta/Archive audit trail. But when you do combine them, the CLAUDE.md routing block is not optional garnish — it’s the thing that turns two tools that ignore each other into one coherent loop. Get the routing right and you get the best of both layers: OpenSpec remembers why, Superpowers guarantees how well, and Claude Code does the typing. For the broader Claude Code workflow this all sits inside, my complete Claude Code guide is the map.

Related Reading:

• Claude Code + OpenSpec + Superpowers: Triple Stack or Overkill?
• Superpowers Deep Dive: The Skills Framework That Turns Claude Code into a Senior Engineer
• Claude Code Skills Guide: How Agent Skills Actually Work
• Claude Code Complete Guide: From Beginner to Expert