Spec Kit writes WHAT. Superpowers enforces HOW. This bridge only carries the handoff.

speckit-superpowers-bridge

中文版：README.zh-CN.md

speckit-superpowers-bridge is the handoff layer between Spec Kit design artifacts and Superpowers implementation discipline. Spec Kit stays the source of truth for design (constitution → spec → plan → tasks). Superpowers executes implementation with TDD, verification, and review, invoked explicitly at named lifecycle phases. Codex and Claude Code share the same repo-local protocol.

No daemon. No service. No database. No second workflow engine. No custom discipline beyond native Superpowers.

The design intent is documented in the Spec Kit vs Superpowers comparison article — this extension is the minimal wiring that lets the two tools cooperate.

---

At a glance

Install the current stable release:

specify extension add speckit-superpowers-bridge \
  --from https://github.com/lihan3238/speckit-superpowers-bridge/releases/latest/download/speckit-superpowers-bridge.zip

Why speckit-superpowers-bridge

Spec Kit is excellent at producing durable design artifacts (constitution, spec, plan, tasks, checklists, analysis), but its bundled speckit.implement is a one-shot LLM run with no TDD, no subagent fan-out, no structured review.

Superpowers is excellent at execution discipline (TDD, systematic debugging, subagent-driven development, verification, code review, finishing a development branch), but it natively expects to drive design through its own brainstorming and writing-plans skills, not from a Spec Kit tasks.md.

The bridge is the thinnest possible glue that lets the two cooperate without either side colonizing the other’s role: a single superpowers-handoff.json state file, five hardcoded guard rules, six small scripts per shell flavor, and one orchestrator skill that invokes native Superpowers in order against the Spec Kit tasks.md. No runtime matrix, no audit loop, no implementation validation pass, no command-parity subsystem, no custom DSL — just the smallest contract that makes the cycle work.

Quick Start

specify init my-project --integration claude   # or --integration codex
cd my-project
specify extension add speckit-superpowers-bridge \
  --from https://github.com/lihan3238/speckit-superpowers-bridge/releases/latest/download/speckit-superpowers-bridge.zip

What this does, in 7 steps:

1. specify init bootstraps a Spec Kit project with your chosen agent integration.
2. specify extension add ... /releases/latest/download/... installs the bridge from the stable-alias URL (always resolves to the latest released bridge — never goes stale on subsequent releases).
3. Spec Kit registers the bridge’s 3 commands and 5 hooks in .specify/extensions.yml.
4. Bridge writes its boundary guard at .specify/extensions/speckit-superpowers-bridge/scripts/.
5. Drive a feature: /speckit-specify → /speckit-clarify → /speckit-plan → /speckit-tasks.
6. The after_tasks hook fires automatically — bridge writes .specify/superpowers-handoff.json with status executing.
7. /speckit-superpowers-bridge (Claude Code) or $speckit-superpowers-bridge (Codex) maps canonical tasks.md into a disposable Task N adapter for native superpowers:executing-plans, then invokes verification + code review + branch finishing. Handoff transitions to complete.

[!TIP] Have only a vague idea? Run superpowers:brainstorming before /speckit-specify. The bridge guard allows it in the pre-spec window — the resulting design doc at docs/superpowers/specs/--design.md can be referenced in your /speckit-specify description so the LLM picks it up as context. See feature 010-prespec-brainstorming for the documented lifecycle decision.

1.x Readiness and Support

v1.0.0 is a stable protocol release: no new workflow engine, no daemon, no service, no database, and no replacement for native Spec Kit or Superpowers behavior. The release adds stricter package/readiness checks and evidence for the supported platforms and agents.

v1.0.1 is a documentation and development-checkout cleanup patch on the same protocol surface.

v1.0.2 is a discoverability and launch-asset patch: README hero image, social cards, marketplace wording, and small contributor-doc fixes; runtime bridge behavior is unchanged.

v1.0.3 is a Spec Kit 0.10.x compatibility-alignment patch: re-verified on Spec Kit CLI 0.10.2, declares the new category/effect manifest fields, and refreshes bootstrap docs for 0.10.0’s opt-in git extension; runtime bridge behavior is unchanged.

v1.1.0 is a Superpowers 6.0.0 compatibility-alignment release: the verified-against-Superpowers baseline moves 5.1.0 → 6.0.0 (a major upstream bump) with zero bridge runtime change. Superpowers 6.0.0’s breaking changes are all internal to upstream skills (the subagent-driven-development reviewer-prompt consolidation, worktrees relocating to project .worktrees/, vendor-neutral prose, three new harnesses) and transparent to the thin bridge, which invokes Superpowers by skill name only. See specs/016-superpowers-6-0-0-alignment/research.md for the grep-backed impact analysis.

v1.2.0 makes the bridge a true plug-and-play drop-in for speckit.implement: it dispatches the same before_implement / after_implement extension hooks, emits Spec Kit’s mandatory EXECUTE_COMMAND: directive, actually invokes and waits for each mandatory hook, and runs post-hooks before the handoff becomes complete. It also fixes Issue #13 by replacing GNU-only missing-path canonicalization in the bash handoff writer, so standard macOS installations need no GNU coreutils. No command, registered hook, state file, schema, or guard rule was added. See specs/018-release-0-16-4-hardening/spec.md.

Spec Kit 1.0.12 and Superpowers 6.4.2 are the current audited development baselines. The bridge adopts the latest tracked git and agent-context sources, current command placeholders, Spec Kit’s malformed-registry reporting, and a disposable task adapter for Superpowers’ Task N heading contract. The runtime floor remains >=0.8.10; the bridge still owns no parallel hook runner, planner, or state machine. Superpowers 6.4.2 keeps all invoked skill names, while its heading-based executor is fed from the canonical Spec Kit tasks.md through disposable execution scaffolding. v1.3.0 aligns the bridge with Spec Kit 1.0.12 and Superpowers 6.4.2. It reports malformed extension registries using the current parser-error contract and adapts Spec Kit checkbox tasks to the Task N headings required by Superpowers 6.4.2 using stable disposable files outside the native Superpowers workspace. The canonical tasks.md remains the only requirements and completion source; the three-command, five-hook, handoff v1, guard, actor, stable-alias, and >=0.8.10 runtime contracts are unchanged. See specs/019-update-latest-upstreams/spec.md.

Run the lightweight readiness check after install:

bash .specify/extensions/speckit-superpowers-bridge/scripts/bash/bridge-status.sh --readiness --actor codex
bash .specify/extensions/speckit-superpowers-bridge/scripts/bash/bridge-status.sh --readiness --json --actor codex

.\.specify\extensions\speckit-superpowers-bridge\scripts\powershell\bridge-status.ps1 -Readiness -Actor claude
.\.specify\extensions\speckit-superpowers-bridge\scripts\powershell\bridge-status.ps1 -Readiness -Json -Actor claude

The readiness report is read-only. It checks script flavor, required tools, command namespace, package files, current bridge state, verified agent metadata, and the next recommended action.

Demo: user flow

Positioning

How the bridge differs from doing nothing, doing only one side, or using a peer hybrid:

The bridge’s brand is compatible with upstream growth + extremely lightweight. Every release is graded against the constitution’s Principle VI Native-First gate: does upstream already do this? Is upstream the right place to fix this? If either answer is “yes”, the bridge does NOT add the feature.

---

---

Contributing and License

MIT — see LICENSE.

This extension was developed using AI coding assistants (Claude Code for design + planning; Codex for implementation passes; Claude Code for the v0.3.0 trim and the v0.6.0 polish) per the AI-disclosure requirement in Spec Kit CONTRIBUTING.md. Every artifact passes human review before commit. Smoke tests under tests/ (bash flavor as of 009) exercise the handoff schema, the 5 hardcoded guard rules, the bridge-state output, the before/after-implement hook dispatch, and cross-agent skill parity.

Issues and discussion: