┌───────────────────── Spec Kit phase ─────────────────────┐
  user ─► /speckit-constitution ─► /speckit-specify ─► /speckit-clarify ─►
          /speckit-plan ─► /speckit-tasks
                                                       │
                                                       │ after_tasks hook
                                                       ▼
                          ┌──────── speckit-superpowers-bridge ─────────┐
                          │  handoff (writes superpowers-handoff.json)  │
                          │  guard (5 hardcoded boundary rules)         │
                          │  execute (orchestrates native skills)       │
                          └──────────────────┬──────────────────────────┘
                                             │
                  ┌────────── Superpowers phase (explicit invocations) ───────┐
                  ▼                                                            ▼
       superpowers:executing-plans                   superpowers:verification-before-completion
       superpowers:test-driven-development           superpowers:requesting-code-review
       superpowers:systematic-debugging              superpowers:finishing-a-development-branch
                                             │
                                             │ handoff transitions logged
                                             ▼
                                   .specify/bridge-events.jsonl

Spec Kit must be installed first. The extension is listed in the official Spec Kit community catalog for discovery and review.

Official listing: docs/community/extensions.md (accepted via issue #2581 and PR #2586).

The community catalog is discovery-only by default, so the normal install command uses the stable latest-release ZIP.

Pure Codex

specify init my-project --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

No Claude Code dependency. The bridge runs entirely through Codex's $speckit-* invocation surface.

Pure Claude Code

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

No Codex dependency. The bridge runs through Claude Code's /speckit-* slash commands.

Both (cross-agent handoff)

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

Both .agents/skills/ (Codex) and .claude/skills/ (Claude Code) receive the bridge skill peer files. You can design in one agent and implement in another by simply switching tabs.

Local development usage (for working on this bridge repo itself):

This source checkout already contains the bridge extension at .specify/extensions/speckit-superpowers-bridge/, and .specify/extensions.yml registers that local source as the installed extension. Use the normal $speckit-* / /speckit-* commands from this repo; do not install the published ZIP into the same checkout unless you intentionally want to replace the local extension tree with release contents.

If a fresh specify init --here ... --force regenerated local install state and the bridge needs to be re-registered, install from a temporary copy outside the target extension directory:

tmp="$(mktemp -d)"
cp -a ./.specify/extensions/speckit-superpowers-bridge "$tmp"/
specify extension add --dev "$tmp/speckit-superpowers-bridge"

Do not pass ./.specify/extensions/speckit-superpowers-bridge directly as the --dev source from this source checkout. Spec Kit installs to that same target path, so source and destination would be identical.

PowerShell equivalent:

$tmp = New-Item -ItemType Directory -Path ([System.IO.Path]::Combine([System.IO.Path]::GetTempPath(), [System.Guid]::NewGuid().ToString()))
Copy-Item .\.specify\extensions\speckit-superpowers-bridge $tmp.FullName -Recurse
specify extension add --dev (Join-Path $tmp.FullName "speckit-superpowers-bridge")

Use the published ZIP only in a separate consumer project or in the sibling release-verification sandbox ../test_specify_superpower.

Version-pinned install (for reproducible installs of a specific release):

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

Windows users need PowerShell 5.1+ (preinstalled on supported Windows releases). Linux and macOS users run the same extension ZIP through the bash flavor and need:

• bash >= 4.0
• jq >= 1.6

Install examples:

sudo apt install bash jq      # Ubuntu / Debian
brew install bash jq          # macOS
sudo dnf install bash jq      # Fedora

Contributors who run the repository smoke tests on any OS use the WSL bash suite (bash tests/run-all.sh, post-009 cleanup). End users do not need PowerShell Core (pwsh) for normal bridge execution.

1. /speckit-constitution            (one time per project)
2. /speckit-specify "add OAuth2 sign-in"
3. /speckit-clarify                 (the bridge asks 2–5 targeted Qs)
4. /speckit-plan                    (writes plan.md + research.md + data-model.md + contracts/)
5. /speckit-tasks                   (writes tasks.md)
                       │
                       │ after_tasks hook fires → handoff JSON written; status=executing
                       ▼
6. /speckit-superpowers-bridge      (Claude Code)  or  $speckit-superpowers-bridge  (Codex)
       │
       │ bridge SKILL.md loads; native Superpowers skills run in order:
       │   • superpowers:executing-plans drives the per-task loop
       │   • superpowers:test-driven-development per code-modifying task
       │   • superpowers:verification-before-completion at phase boundary
       │   • superpowers:requesting-code-review then :finishing-a-development-branch at end
       ▼
7. handoff → complete; next /speckit-specify auto-archives the previous one

Not every change needs the full Spec Kit → bridge → Superpowers workflow. You decide the route:

The bridge no longer recommends this routing automatically (the previous recommend-route command was removed in 0.3.0). You make the call. The guard still enforces boundary rules either way — it does not block direct Superpowers use when there is no active Spec Kit handoff.

Fresh marketplace installs generate $speckit-superpowers-bridge / /speckit-superpowers-bridge from the execute command alias. The canonical fallback remains $speckit-speckit-superpowers-bridge-execute / /speckit-speckit-superpowers-bridge-execute. Handoff and guard intentionally keep their canonical long names because they are advanced/internal commands.

If you see .agents/skills/speckit-speckit-superpowers-bridge-* or .claude/skills/speckit-speckit-superpowers-bridge-*, that is normal: Spec Kit generated those skills from extension commands. The source repository also contains short local bridge skill mirrors under .agents/skills/speckit-superpowers-bridge/ and .claude/skills/speckit-superpowers-bridge/; do not expect those development mirrors to be copied directly from the extension ZIP.

The 6 meta-commands that existed in v0.2.x (audit, validate, parity, recommend-route, submission-checklist, cleanup-audit) were removed in 0.3.0. They duplicated discipline that native Superpowers already provides, or codified custom features beyond the thin-bridge scope. See CHANGELOG.md.

The bridge reads two layers of configuration in priority order: explicit script arguments > environment variables.

Actor resolution: when a bridge script needs to know which agent invoked it (-Actor), it resolves in this order:

1. Explicit -Actor <codex|claude|unknown> argument.
2. SPECKIT_BRIDGE_ACTOR environment variable.
3. Literal "unknown".

Per-agent bridge SKILL.md files hardcode -Actor / --actor to their own agent — so in normal dialog use, you never need to set the env var. The chain matters for CI or manual script invocation.

See AGENTS.md for the master cross-agent protocol; CLAUDE.md for Claude-specific supplements.

[!WARNING] WSL users: do NOT set git config --global http.proxy. Use the per-call env-var pattern from AGENTS.md (https_proxy=http://10.77.0.11:10808 git push ...). A global proxy config bakes the address into git config and breaks on every machine where that proxy is unreachable. The bridge's release runbook and smoke suite assume the env-var-per-call pattern.

This release (v1.2.0) is verified against:

• Spec Kit 0.16.4 for repository bootstrap, Linux bash verification, and the v1.2.0 release sandbox; runtime floor remains >=0.8.10
• Superpowers 6.3.0
• Codex CLI 0.147.0
• Claude Code 2.1.233

Verified metadata is captured in .specify/extensions/speckit-superpowers-bridge/verified-versions.json — a project-owned additive schema refreshed when a bridge release or upstream compatibility baseline changes. v1.2.0 records bridge, upstream tool, platform, and real-agent rows; missing or blocked rows are not advertised as verified.

When upstream tools ship a new release that breaks the bridge, we either patch the bridge scripts or pin the documented compatible versions in CHANGELOG.md.

Spec Kit 0.9.x moved coding-agent context updates into the bundled agent-context extension. The bridge runtime does not depend on that extension, so requires.speckit_version stays at >=0.8.10; this repository tracks the current 0.16.4 agent-context and git sources only to keep its own Spec Kit project bootstrap current.

[!NOTE] From v0.6.0 onward, the marketplace download_url is decoupled from the version. It permanently points at https://github.com/lihan3238/speckit-superpowers-bridge/releases/latest/download/speckit-superpowers-bridge.zip and resolves via GitHub's /releases/latest/ alias. Future bridge releases never edit download_url; only version is bumped in marketplace/catalog-entry.json. This removes a recurring per-release edit class and a drift surface — one of the smallest possible Principle-VI wins.

Adapted with attribution from the Spec Kit vs Superpowers comparison article (truongpx396, dev.to).

• Spec Kit owns WHAT. Constitution, spec, clarify, plan, tasks, checklists, analysis. These are durable design artifacts under .specify/ and specs/.
• Superpowers owns HOW. TDD, debugging, executing-plans, requesting-code-review, verification-before-completion, finishing-a-development-branch. These are implementation discipline skills invoked at lifecycle phases.
• The bridge orchestrates native skills and does not provide custom discipline. It contributes only: generated extension command skills, six small scripts in PowerShell and bash flavors (update-handoff, guard-command, auto-archive-handoff, bridge-state, bridge-status, common-actor-resolution), and 5 hardcoded boundary rules. No runtime matrix, no audit loop, no implementation validation pass, no command-parity subsystem.