Thanks to visit codestin.com
Credit goes to github.com

Skip to content

superpowers-bridge

Directory actions

More options

Directory actions

More options

Latest commit

 

History

History

superpowers-bridge

README.md

Superpowers Bridge

Bridges selected installed obra/superpowers quality-control skills into the Spec Kit workflow and adds a small set of bridge-native review utilities.

This extension combines:

  • Hook-based guardrails for core Spec Kit commands (tasks, implement), and
  • Standalone operational commands for debugging, review response, and branch completion.

It does not replace the Spec Kit main flow. The main flow remains:

/speckit.specify -> /speckit.clarify -> /speckit.plan -> /speckit.tasks -> /speckit.analyze | /speckit.checklist -> /speckit.implement

Bridge Model

  [ Spec Kit Main Flow ]                         [ Bridge Enhancements ]

 ┌───────────────────┐
 │ /speckit specify  │ ─────> Spec Kit owns specification creation
 └─────────┬─────────┘
           │
 ┌─────────▼─────────┐
 │ /speckit clarify  │ ─────> Spec Kit owns clarification and spec updates
 └─────────┬─────────┘
           │
 ┌─────────▼─────────┐
 │ /speckit plan     │ ─────> Spec Kit owns technical planning
 └─────────┬─────────┘
           │
 ┌─────────▼─────────┐
 │ /speckit tasks    │ ─────> 1. Execute Core Tasks Logic
 └─────────┬─────────┘        2. 🔍 review (Optional: Coverage + TDD-readiness)
           │                  (after_tasks)
           │
 ┌─────────▼─────────┐       (before_implement)
 │ /speckit implement│ ─────> 1. 🔴 tdd (Mandatory: RED-GREEN-REFACTOR Enforcer)
 └─────────┬─────────┘        2. Execute Core Implement Logic
           │                  3. ✅ verify (Mandatory: Evidence-Based Completion Gate)
           │                  (after_implement)
           ▼
  [ Standalone Utilities ]
   ├─ /speckit.superb.check   ──> 🩺 Skill installation and hook readiness diagnostics
   ├─ /speckit.superb.debug   ──> 🐛 Systematic root-cause investigation
   ├─ /speckit.superb.critique──> 📝 Bridge-native spec-aligned code review
   ├─ /speckit.superb.respond ──> 💬 Rigorous review feedback implementation
   └─ /speckit.superb.finish  ──> 🏁 Branch completion & merge strategy

Features

  • Local skill discovery and readiness diagnostics (check)
  • Mandatory TDD gate before implementation (tdd)
  • Task/spec coverage and TDD-readiness check (review)
  • Mandatory evidence-based completion gate (verify)
  • Bridge-native spec-aligned reviewer role (critique)
  • Root-cause debugging escalation (debug)
  • Structured branch completion options (finish)
  • Technical response workflow for review feedback (respond)

What This Bridge Does Not Do

The bridge intentionally does not take over these responsibilities from Spec Kit:

  • Specification generation and branch creation
  • Clarification and spec mutation
  • Technical planning
  • Task generation
  • Implementation orchestration

The following superpowers workflow skills are therefore not bridged as formal commands or hooks:

  • brainstorming
  • writing-plans
  • subagent-driven-development
  • executing-plans
  • using-git-worktrees
  • requesting-code-review

Design Notes

The V2 redesign rationale is documented in V2-DESIGN-NOTES.md, including:

  • why the bridge no longer tries to embed the full Superpowers workflow
  • which Superpowers skills are intentionally excluded
  • how Spec Kit ownership boundaries were used to shape the bridge
  • why the bridge now depends on locally installed skills instead of remote fallbacks

Installation

Install from ZIP (Recommended)

Install directly from the release asset:

specify extension add superpowers-bridge --from https://github.com/RbBtSn0w/spec-kit-extensions/releases/download/superpowers-bridge-v1.3.0/superpowers-bridge.zip

Install from GitHub Repository (Development)

Clone the collection repository and install the extension folder locally:

git clone https://github.com/RbBtSn0w/spec-kit-extensions.git
cd spec-kit-extensions
specify extension add --dev ./superpowers-bridge

Install Superpowers Skills

This bridge expects the relevant superpowers skills to already be installed in one of these locations:

  1. ./.agents/skills/
  2. ~/.agents/skills/

Workspace skills take precedence over global skills.

Run the diagnostics command after installation:

/speckit.superb.check

Commands

Command Type Purpose
/speckit.superb.check Standalone Verify installed skill availability and hook readiness
/speckit.superb.tdd Hookable Enforce RED-GREEN-REFACTOR before code changes
/speckit.superb.review Hookable Check tasks.md coverage and TDD-readiness
/speckit.superb.verify Hookable Block completion claims without fresh evidence
/speckit.superb.critique Standalone Bridge-native spec-aligned code review
/speckit.superb.debug Standalone Systematic root-cause debugging
/speckit.superb.finish Standalone Post-verify branch completion workflow
/speckit.superb.respond Standalone Process and implement review feedback rigorously

When To Use Each Command

This table is the practical entry point for users. It shows when each command should be used, whether it is automatic or manual, and what problem it solves.

Command Automatic? Best Time To Use Solves
/speckit.superb.check Manual Right after installing the extension or when bridge behavior looks wrong Confirms which superpowers skills were found, where they were found, and which hooks or standalone commands are ready
/speckit.superb.review Optional hook after tasks After tasks.md is generated, before implementation starts Checks whether tasks.md really covers spec.md and whether the task set is precise enough for strict TDD
/speckit.superb.tdd Mandatory hook before implement Immediately before implementation begins Enforces RED-GREEN-REFACTOR and blocks speculative production code before a failing test
/speckit.superb.verify Mandatory hook after implement Immediately after implementation claims are made Requires fresh evidence before any completion claim and verifies spec coverage against passing tests
/speckit.superb.critique Manual After a major task, after implementation, or before opening a PR Reviews the code diff against spec.md, plan.md, and tasks.md to catch implementation drift
/speckit.superb.debug Manual When TDD is stuck, repeated fixes failed, or behavior is still unexplained Switches from trial-and-error to root-cause debugging
/speckit.superb.respond Manual After receiving critique output, PR comments, or external review feedback Processes review items rigorously before implementing or rejecting them
/speckit.superb.finish Manual After verification passes and the work is ready to integrate Handles merge / PR / keep / discard decisions in a structured way

Typical Usage Order

For most users, the extension should feel like this:

  1. Install the extension and run /speckit.superb.check.
  2. Run the normal Spec Kit flow through specify, clarify, plan, and tasks.
  3. Let /speckit.superb.review run after tasks if you want a task coverage and TDD-readiness gate.
  4. Start /speckit.implement; /speckit.superb.tdd runs before implementation and /speckit.superb.verify runs after it.
  5. If implementation gets stuck, run /speckit.superb.debug.
  6. If you want an implementation review, run /speckit.superb.critique.
  7. If review feedback arrives, run /speckit.superb.respond.
  8. Once the work is verified and ready to integrate, run /speckit.superb.finish.

Status Synchronization

The bridge also maintains a lightweight lifecycle marker in the active spec.md file:

**Status**: <State>

This status model is intentionally limited to states that the bridge can actually observe with the current hook surface.

Bridge-Owned States

State Written By Meaning
Tasked after_tasks via /speckit.superb.review tasks.md exists and the feature has entered task-driven implementation preparation
Implementing before_implement via /speckit.superb.tdd implementation has formally entered execution
Verified /speckit.superb.verify implementation passed the verification gate and requirement evidence checks
In Review /speckit.superb.finish after successful PR creation work has been handed off into external review/merge flow
Abandoned /speckit.superb.finish after successful discard work was explicitly discarded

Why There Is No Completed

The bridge does not currently write Completed.

Reason:

  • the common integration path is GitHub PR creation and later merge
  • that final merge event happens outside the current bridge hook surface
  • writing Completed during PR creation would be inaccurate

So the highest accurate PR-based state in the current design is:

  • In Review

Status Write Rules

  • The bridge resolves the active feature path using the same Spec Kit feature resolution mechanism as follow-up commands.
  • It prefers FEATURE_SPEC when available, otherwise FEATURE_DIR/spec.md.
  • It never guesses the feature path from the branch name manually.
  • Status updates are executed through the bundled helper scripts:
    • scripts/bash/sync-spec-status.sh
    • scripts/powershell/sync-spec-status.ps1
  • If the status line is missing, the helper inserts it once near the top of the document: below the first H1 heading when present (after a blank line), otherwise at file start.
  • If the status line exists, the helper updates it in place.
  • The helper normalizes duplicate **Status**: lines into one canonical line.
  • The bridge does not silently overwrite Abandoned.

Hook Integration

This extension registers the following hooks:

  • after_tasks → review (optional)
  • before_implement → tdd (mandatory)
  • after_implement → verify (mandatory)

Configuration

superb-config.template.yml documents the intended bridge configuration shape for discovery order, required skill sets, and standalone command toggles. The current command prompts still use the documented defaults directly; the template is not yet enforced as a live runtime config file. It does not define remote fallbacks or bundled skill content.

Requirements

  • Spec Kit: >=0.4.3
  • Installed superpowers-compatible skills in ./.agents/skills/ or ~/.agents/skills/
  • Optional: the superpowers tool, if you use it to install or manage those skills; the bridge itself relies on the installed skill content being present

Responsibility Boundaries

Responsibility Owner
Create and update spec.md Spec Kit
Clarify unresolved spec decisions Spec Kit
Build plan.md and tasks.md Spec Kit
Analyze artifact consistency Spec Kit
Generate requirements-quality checklists Spec Kit
Enforce TDD discipline during implementation Superpowers Bridge
Enforce verification before completion Superpowers Bridge
Review task coverage and TDD-readiness Superpowers Bridge
Review implementation against spec/plan/tasks Superpowers Bridge
Synchronize bridge-owned lifecycle states in spec.md Superpowers Bridge

Stage Boundaries

The bridge is designed to complement, not replace, the Spec Kit commands that already own specification quality and artifact consistency.

clarify vs Bridge Commands

Command Owner Primary Artifact Solves
/speckit.clarify Spec Kit spec.md Resolves underspecified or ambiguous product requirements and writes the answers back into the spec
/speckit.superb.review Superpowers Bridge tasks.md against spec.md / plan.md Checks whether the generated task plan actually covers the spec and is specific enough for a strict TDD gate
/speckit.superb.critique Superpowers Bridge code diff against spec.md / plan.md / tasks.md Reviews implementation output against declared requirements and implementation intent

checklist vs analyze vs Bridge Commands

Command Owner Primary Focus Solves
/speckit.checklist Spec Kit Requirements-writing quality Tests whether requirements are complete, clear, consistent, measurable, and ready for implementation
/speckit.analyze Spec Kit Cross-artifact consistency Detects contradictions, ambiguity, duplication, and missing links across spec.md, plan.md, and tasks.md
/speckit.superb.review Superpowers Bridge Coverage + TDD readiness Determines whether tasks.md is implementation-ready and can support before_implement TDD enforcement
/speckit.superb.tdd Superpowers Bridge Implementation discipline Enforces RED-GREEN-REFACTOR once implementation begins
/speckit.superb.verify Superpowers Bridge Completion evidence Blocks completion claims unless full verification evidence exists
/speckit.superb.finish Superpowers Bridge Integration handoff state Moves the feature into In Review after PR creation or Abandoned after successful discard

Responsibility Map

 /speckit.superb.check
     |
     +--> validates local superpowers skills and hook readiness

 /speckit.specify -> /speckit.clarify -> /speckit.checklist
        |                 |                  |
        |                 |                  +--> checks requirement-writing quality
        |                 |
        |                 +--> resolves ambiguous or missing product decisions
        |
        +--> creates the feature spec

 /speckit.plan -> /speckit.tasks -> /speckit.analyze
        |                |                 |
        |                |                 +--> checks cross-artifact consistency
        |                |
        |                +--> /speckit.superb.review
        |                     checks task coverage and TDD readiness
        |                     writes `**Status**: Tasked`
        |
        +--> creates technical plan and implementation structure

 /speckit.implement
        |
        +--> /speckit.superb.tdd
        |     enforces test-first implementation before work starts
        |     writes `**Status**: Implementing`
        |
        +--> implementation execution
        |
        +--> /speckit.superb.verify
              enforces evidence before completion claims
              writes `**Status**: Verified`

 Standalone support around implementation:
 - /speckit.superb.debug
   use when implementation is blocked or repeated fixes failed
 - /speckit.superb.critique
   use to review the implementation against spec, plan, and tasks
 - /speckit.superb.respond
   use after critique output or external review feedback
 - /speckit.superb.finish
   use after verification succeeds and the branch is ready to integrate
   writes `**Status**: In Review` after successful PR creation
   writes `**Status**: Abandoned` after successful discard

Practical Division Of Labor

  • Use /speckit.clarify when the spec still has unresolved product or behavior questions.
  • Use /speckit.checklist when you want to test the quality of the written requirements themselves.
  • Use /speckit.analyze when you want a broad consistency check across spec.md, plan.md, and tasks.md.
  • Use /speckit.superb.review when you specifically want to know whether tasks.md is complete enough and precise enough for strict TDD-driven implementation.
  • Use /speckit.superb.tdd and /speckit.superb.verify only around implementation, not during specification or planning.
  • Use /speckit.superb.critique when the code itself, not just the planning artifacts, needs to be reviewed against the declared requirements.
  • Use /speckit.superb.debug when you need root-cause investigation rather than another quick fix.
  • Use /speckit.superb.respond after review comments arrive and you need a disciplined way to accept, reject, or clarify them.
  • Use /speckit.superb.finish only after verification is complete and you are deciding how to integrate or preserve the branch.
  • Read In Review as the current highest accurate PR-based lifecycle state; this bridge does not currently track final GitHub merge completion.

License

MIT — see LICENSE.

Changelog

See CHANGELOG.md.