Merging OpenSpec & Superpowers: 7 Integration Pitfalls & the Bridge Skill That Fixes Them

The article demonstrates how to combine two AI programming frameworks — OpenSpec (specification-driven development) and Superpowers (disciplined TDD workflow) — into a unified workflow using a real project: adding JWT authentication to an existing Go microservice with session authentication.

Division of Responsibilities

OpenSpec answers "what to do and why" — produces proposal.md, specs/, design.md, tasks.md; controls requirements and specs; failure mode: building unneeded features; analogy: architectural blueprint.

Superpowers answers "how to do it and by what standard" — produces code, tests, review reports; controls behavior and discipline; failure mode: building needed features incorrectly; analogy: construction code.

Missing either framework leads to distinct failures: only OpenSpec yields correct specs but poor code quality (skipped tests, large commits); only Superpowers yields high-quality code that may not match requirements.

End-to-End Workflow: Adding JWT Auth to a Go Microservice

Step 1: OpenSpec explore — Align Direction

Run /opsx:explore to discuss technical options with the AI before proposing. The author initially skipped this, causing the AI to choose a stateless JWT design without a revocation mechanism, requiring three reworks. The explore phase (5 minutes) surfaced three options: pure JWT, JWT + blocklist, extend existing session. The team chose JWT + Redis blocklist with 30-min access tokens, 7-day refresh tokens, and token rotation.

Step 2: OpenSpec propose — Generate Spec Artifacts

Run /opsx:propose add-jwt-auth to produce four documents:

proposal.md — motivation, scope, and exclusion scope (e.g., "do not modify Web frontend login"). Pitfall: omission of exclusion scope caused the AI to modify unrelated Web login code.

specs/ — incremental requirements in Given/When/Then format (e.g., valid credentials → returns access_token, refresh_token, expires_in; invalid credentials → 401). Pitfall: tasks.md granularity (requirement-level) differs from Superpowers plan granularity (implementation-level TDD steps).

design.md — technical decisions: golang-jwt library, middleware pattern, Redis SET for blocklist with jti as key and TTL = remaining token lifetime, refresh-token rotation.

tasks.md — requirement-level task list (11 tasks from adding dependency to implementing refresh rotation).

Step 3: Human Review of Specs

Manual checklist: proposal scope/exclusions complete? specs cover edge cases (expiry, blocklist, concurrent refresh)? design.md decisions sound? tasks.md missing steps (security/performance tests)? The author found a missing concurrent-refresh scenario — a security vulnerability where an attacker could reuse a refresh token simultaneously — and added a spec for it.

Step 4: The Critical Bridge — Feeding OpenSpec Output to Superpowers

OpenSpec's apply step is replaced by Superpowers' execution flow. The bridge requires:

Load design.md and specs/ as context.

Instruct AI: "Based on OpenSpec tasks.md, use Superpowers writing-plans to break into executable plans."

Superpowers expands each task into TDD steps: write failing test → run → minimal implementation → run → refactor → commit.

Pitfall 4: skipping the context feed lets Superpowers invent its own implementation (e.g., in-memory blocklist instead of Redis). Pitfall 5: OpenSpec's explore and Superpowers' brainstorming duplicate work — solution: skip brainstorming when explore/propose are done, treat proposal.md and design.md as brainstorming output.

Step 5: Superpowers Execution — TDD per Task

Each task runs through: subagent-driven development → internal TDD (test-driven-development) → independent spec-compliance review → independent code-quality review. The author created a custom spec-compliance-check Skill because Superpowers' default review only checks code quality, not spec adherence. The Skill reads main specs, delta specs, verifies every Given/When/Then scenario has implementation, checks design.md decisions, and validates exclusion scope.

Step 6: OpenSpec verify — Spec Compliance Verification

Run /opsx:verify (requires extended profile). It checks three dimensions:

Completeness : Every requirement has implementation (vs Superpowers: reviews code; verify reviews spec)

Correctness : Implementation matches spec intent (vs Superpowers: reviews quality; verify reviews semantics)

Consistency : Implementation matches design.md (vs Superpowers: does not read design.md)

Pitfall 6: treating verify and code review as alternatives. They are complementary: code review = "code written well"; verify = "code does the right thing per spec". Correct order: code-quality review → spec-compliance review → OpenSpec verify.

Step 7: OpenSpec archive — Merge Delta Specs

Run /opsx:archive to merge delta specs into main spec ( openspec/specs/auth/spec.md) and move change folder to archive. This ensures future work sees the updated spec. Pitfall 7: archiving without running full test suite — verify does not run tests. Solution: add Superpowers verification (e.g., go test ./...) before archive.

Step 8: Superpowers Wrap-up

Run finishing-a-development-branch with four options: local merge, push + PR, keep branch, discard. Tests must pass before merge.

Complete 8-Step Combined Workflow

Requirements (OpenSpec-led) : explore (5-10 min) → propose (10-15 min) → human review (5-10 min)

Bridge (human-led) : feed design.md + specs to Superpowers planning (skip OpenSpec apply)

Implementation (Superpowers-led) : TDD per task → dual review (code quality + spec compliance)

Verification (both) : OpenSpec verify + Superpowers verification (run tests) → archive + wrap-up

Core principle: OpenSpec artifacts are Superpowers inputs; Superpowers outputs are OpenSpec verification targets.

Troubleshooting Guide

verify fails → systematic-debugging on that task → re-verify

spec-compliance-check flags non-compliance → decide: fix code or update design.md + re-propose

design.md decision flawed → return to human review → update design.md → re-bridge

tasks.md granularity off → Superpowers planning auto-splits coarse tasks; merge fine tasks in bridge

mid-implementation spec change → pause Superpowers → update design.md (re-propose if major, /opsx:sync if minor) → re-review → re-bridge

parallel changes → separate git worktrees per change; Superpowers parallel agents across worktrees, not within one

Seven Pitfalls Summary

Proposal mismatches needs — Root cause: Skipped explore — Fix: Explore before propose

AI builds extra features — Root cause: Missing exclusion scope — Fix: Write explicit "not doing" list

Task/plan granularity mismatch — Root cause: OpenSpec = what, Superpowers = how — Fix: Bridge layer converts granularity

Implementation diverges from design.md — Root cause: Superpowers lacks spec context — Fix: Feed design.md to brainstorming/planning

Code review misses spec violations — Root cause: Reviewer only sees code quality — Fix: Custom spec-compliance-check Skill

Only verify or only code review — Root cause: Assumed equivalence — Fix: Do both; they check different things

Archive without full test run — Root cause: Verify doesn't run tests — Fix: Add Superpowers verification pre-archive

Automation: openspec-superpowers-bridge Skill

Two custom Skills placed in ~/.claude/skills/ (Claude Code) or .cursor/rules/ (Cursor):

spec-compliance-check — adds spec-adherence review to Superpowers pipeline.

openspec-superpowers-bridge — auto-loads spec context, skips brainstorming, converts scenarios to TDD tests, enforces dual review, runs verify + test before archive.

The bridge Skill directly solves pitfalls 3, 4, 5, 6, 7. Pitfalls 1 and 2 require human action (explore, write exclusions).

When to Use Which Framework

Only OpenSpec : trivial changes (color, typo), clear requirements, self-controlled quality.

Only Superpowers : throwaway scripts, small features with clear scope, no long-term spec needed.

Both : team projects, long-lived codebases, complex features, existing codebases adding features (prevents AI from over-modifying). Decision heuristic: "code lifetime × number of contributors".

Transition path: OpenSpec users add Superpowers' three iron laws (no design → no code; no test → no code; no verification → not done). Superpowers users add OpenSpec explore/propose before complex work.

Empirical Comparison (Author's Experience)

Requirements alignment : OpenSpec Only = proposal+specs confirmed; Superpowers Only = Verbal only; Both = proposal+specs confirmed

AI builds extra features : OpenSpec Only = Exclusion scope controls; Superpowers Only = Occasional (1-2×); Both = Exclusion scope + compliance check (0×)

Test coverage : OpenSpec Only = 0 tests; Superpowers Only = 10 tests; Both = 10 tests

Commit granularity : OpenSpec Only = 1 large commit; Superpowers Only = 8 small commits; Both = 8 small commits

Spec compliance : OpenSpec Only = verify checks; Superpowers Only = Cannot verify; Both = verify + compliance review

Long-term maintenance : OpenSpec Only = Main spec accumulates; Superpowers Only = New chat forgets all; Both = Main spec accumulates + consistent discipline

Rework count : OpenSpec Only = 1-2×; Superpowers Only = 2-3×; Both = 0-1×

Combined value is not additive; it eliminates the two most common failure modes: "right direction, wrong execution" and "right execution, wrong direction".

Three Starting Rules

Explore before propose — don't let AI guess requirements.

Feed design.md to Superpowers — don't let AI guess solution.

Dual review — don't let AI grade its own work.

3-Minute Quickstart

/opsx:explore

— discuss approach /opsx:propose feature-name — generate specs

Human review: proposal, specs, design, tasks

Tell AI: "Read openspec/changes/ specs, use Superpowers writing-plans to plan"

Superpowers TDD per task

Per task: code review → spec-compliance-check → /opsx:verify Run full test suite ( go test ./... etc.) /opsx:archive → Superpowers wrap-up

Step 4 is the linchpin: feed OpenSpec specs to Superpowers; never let Superpowers start empty-handed.