Using OpenSpec with Superpowers
Overview
OpenSpec owns what (spec-driven change lifecycle + openspec CLI). Superpowers owns how (TDD, plan execution, verification). Scale Superpowers usage to task size: small changes get inline discipline, only large/complex changes load the full skill chain. This profile disables OpenSpec's apply workflow, so implementation comes from Superpowers.
Prerequisites — check and FIX before starting
Run these checks in order. Fix what you can automatically; only stop to ask when a step needs the user's choice (tool picker) or a manual restart.
| Check | Verify with | Fix (do it yourself whenever possible) |
|---|---|---|
| openspec CLI | openspec --version in terminal |
Run npm install -g @fission-ai/openspec, re-verify with openspec --version |
| Project initialized | openspec/config.yaml exists, and the tool has its openspec skills (e.g. openspec-propose, openspec-explore) |
Run openspec init and select the tool (add --tools <id> to skip the picker). For the expanded workflow set (new/continue/ff/verify/bulk-archive/onboard), run openspec config profile, then openspec init again with the same tool |
| superpowers loaded | superpowers:test-driven-development is an available skill in this runtime |
Refer to the superpowers:using-superpowers skill's platform references (e.g. references/codex-tools.md on ~/.agents/skills/) for this runtime's skills directory; install if absent |
Do not proceed past a failed check until it either passes or the user has explicitly chosen to skip it. After automatic installs, tell the user to restart the AI assistant (skills/config load at startup) and re-run this skill.
Choose by Task Size — first step, always
| Size | Trigger (any qualifies) | Superpowers usage |
|---|---|---|
| Small | ≤1 file changed, ≤~50 lines net, no API/schema change, no shared-module impact, single concern | No skill loading, no subagents. Inline TDD + verify |
| Large | 2+ files, >~50 lines, API/spec/schema change, cross-module impact, or work parallelizable across independent tasks | Load mapped skills below |
When triggers are borderline or mixed (one small fix in a large change), classify by the largest sub-task. When genuinely in the middle, default to Small — under-engineering beats over-engineering for token cost.
Do not load subagent / parallel-agents / code-review skills for Small tasks. That overhead defeats the purpose.
How to Trigger
- Say any of: "用 openspec + superpowers 做 [X]", "用 using-openspec-superpowers", "先从 spec 提案开始做 [X]" — the description keywords match and the skill loads automatically.
- Or invoke it explicitly via
/skill:using-openspec-superpowers(or the runtime's named-skill command). - The skill runs its own prerequisites check first, so an unconfigured project is auto-diagnosed instead of failing mid-flow.
Example (Small task)
> User: "用 using-openspec-superpowers 给登录表单加个密码可见性切换"
- Prereqs pass automatically (openspec + superpowers already configured).
/opsx:propose(this runtime's form) creates the change; user approves artifacts.- Sized Small (1 file, a few lines) → inline TDD: failing test → toggle logic → test passes.
openspec status --change "login-password-visibility" --jsonconfirms done; test passes.openspec archive; optional finishing check, confirmed with user.
Expected: ~1 small spec change + one code cycle, no subagents, no skill-chain loading.
Phase Mapping (Large tasks: load the skill. Small tasks: apply the discipline inline, skip loading)
| OpenSpec phase | OpenSpec artifact/command | Superpowers skill (Large only) |
|---|---|---|
| Explore idea | openspec-explore |
superpowers:brainstorming |
| Propose change | openspec-propose (proposal/specs/design/tasks.md) |
superpowers:brainstorming before drafting |
| Implement tasks (apply disabled) | tasks.md from openspec new change = plan |
superpowers:executing-plans reads tasks.md + superpowers:test-driven-development per task |
| Fix bugs during impl | — | superpowers:systematic-debugging |
| Review code | — | superpowers:requesting-code-review → superpowers:receiving-code-review |
| Verify & sync | openspec-verify-change (openspec status ... --json) + openspec-sync-specs (openspec validate --specs) |
superpowers:verification-before-completion |
| Archive | openspec-archive-change (openspec archive) |
superpowers:finishing-a-development-branch |
Workflow
- Check prerequisites (table above): verify openspec CLI, project init, superpowers. Install what is missing; remind the user to restart the AI assistant afterward. Only continue when all three pass.
- Propose: run the openspec propose workflow for this runtime (
/opsx-proposein opencode,/opsx:proposein Claude Code, or the openspec-propose skill). Get user approval on the planning artifacts before any code.applyis disabled — do not expect anopenspec-apply-changeskill. - Size the task (see table). Small → proceed inline. Large → load the mapped skills.
- Small task, inline: implement directly with TDD (RED-GREEN-REFACTOR, one cycle per change). Run the relevant verification. Mark task
doneonly when its test passes. Do not drift outside the approved spec; if forced to, runopenspec-update-changefirst. - Large task: open
tasks.md,superpowers:executing-plansreads it, per-tasksuperpowers:test-driven-development. Bugs →superpowers:systematic-debugging. Review →requesting-code-reviewthenreceiving-code-review. Final gate →superpowers:verification-before-completion. - Verify & sync:
openspec status --change "<name>" --json→openspec validate --specs→ fold delta specs intospecs/. - Archive:
openspec archive, thensuperpowers:finishing-a-development-branch. For Small tasks the finishing review is optional — confirm with the user.
Guardrails
- Never write code for a change whose planning artifacts are not approved.
- Never mark a task done without its test passing.
- Never spawn subagents / parallel agents for Small tasks.
- Divergent from the approved spec?
openspec-update-changefirst, then re-implement; do not silently expand scope.
Common Mistakes
- Skipping the prerequisites check → running the workflow on a project without openspec/superpowers and hitting
command not foundmid-flow. - Assuming
npm install -gis enough without runningopenspec initper project (it configures the tool-specific skills). - Loading the full skill chain for a one-line fix (token waste).
- Dispatching subagents for a change one person could do inline.
- Skipping per-task TDD → untested change reaching review.
- Calling the change "done" before verification gates → merged unverified work.
- Editing code where OpenSpec says planning-only (propose/update phases do not edit code).
FAQ
Q: Do I need both openspec and superpowers? Yes — this skill wires the two. See Prerequisites; missing pieces are installed automatically or you are told exactly how.
Q: What if apply isn't available? This profile disables OpenSpec's apply, so implementation runs through Superpowers (executing-plans + TDD). That is by design — do not look for an openspec-apply-change skill.
Q: Small vs Large, how do I decide? See the task-size table (file count, line count, API/schema impact). Borderline → default Small.
Q: Can I use it in a fresh project with no openspec yet? Yes — the prerequisites check runs openspec init for you, then the workflow proceeds.
Q: Why does the finish step sometimes ask "confirm with the user" for Small tasks? Small changes skip the full review chain to save tokens; the user opts in to a finish review rather than getting it by default.
