🌉 OpenSpec × Superpowers Bridge

Spec-driven development for Claude Code — with TDD & code-review gates baked in. ✨

Turn a rough idea into shipped, reviewed code — one hard-gated phase at a time.

🚀 The four-phase flow

🧭  /opsx:explore <topic>   →  discuss  →  requirements.md (DRAFT → REVIEWED)
📝  /opsx:propose <topic>   →  proposal + specs + design + tasks
🛠️  /opsx:apply   <topic>   →  TDD execution + code-review gates
📦  /opsx:archive <topic>   →  archive + capability spec + CLAUDE.md

🚧 Each phase is a hard boundary. No skipping ahead — the discipline is the point.

📋 Prerequisites

| | Prerequisite | Install | |---|---|---| | 🟢 | Node.js 20.19+ | nodejs.org | | ⚡ | superpowers — skills infrastructure | claude --plugin-url https://github.com/obra/superpowers | | 📐 | OpenSpec CLI — schema + workflow engine | npm install -g @fission-ai/openspec@latest |

⚡ Install

In your project root (the directory that contains .claude/):

npx @sbswang2002/superspec init --tools claude

This will:

• ✅ check for the OpenSpec CLI and the superpowers plugin (and tell you how to install either if missing);
• 📐 promote the superpowers-driven schema into your project's openspec/schemas/ dir;
• 🔌 install the opsx slash commands into .claude/commands/opsx;
• 🗂️ run openspec init --tools none and create openspec/config.yaml from the template (never overwriting an existing config).

Verify: openspec schemas should list superpowers-driven with (project). 🎉

🔧 Required: tune openspec/config.yaml for your project

The installer writes openspec/config.yaml from a generic template. Before your first change, edit it to match your project — otherwise the generated artifacts and verification gates run on empty placeholders:

• 🧪 project.test_commands — your test command(s), e.g. ["pytest", "npm test"]. Used by the apply phase's eval + verification gates.
• 🌐 project.e2e_command — optional e2e command.
• 🔍 project.custom_verification_checks — any extra grep/lint checks for final verification.
• 📖 context — describe your tech stack, directory layout, and conventions. Injected into every artifact-generation prompt.
• 📏 rules — optional per-artifact generation rules.

See What goes in config.yaml below for the full reference.

Then kick off your first change:

/opsx:explore my-first-feature

⬆️ Upgrading

Re-run the installer to re-promote the latest schema and refresh commands:

npx @sbswang2002/superspec@latest init --tools claude

📒 What goes in config.yaml

| Key | Purpose | Example | |---|---|---| | project.test_commands | List of test commands | ["pytest", "npm test"] | | project.e2e_command | E2E test command (optional) | "npm run e2e" | | project.custom_verification_checks | Project-specific checks in final verification | ["grep -rn 'secret' src/"] | | context | Project description for Claude | Natural language | | rules | Per-artifact generation rules | See config-template.yaml |

📚 Detailed workflow reference

See docs/workflow.md for:

• 🎯 When to use OpenSpec (and when not to)
• 🔄 Phase-by-phase breakdown with inputs, outputs, and anti-patterns
• 🗂️ Project file layout
• ⚠️ Known gotchas
• 🔁 Quarterly upstream sync routine

❓ Does this conflict with official OpenSpec commands?

Nope. Official OpenSpec uses the openspec-* prefix. This plugin uses opsx:*. Zero collision. 🤝