superpowers

BDD Superpowers

简体中文

BDD Superpowers is a fork of Superpowers. It keeps the original skills-first development workflow and adds a behavior/control harness to the design, planning, and review path.

The base workflow is still Superpowers: brainstorm the design, write a spec, write an implementation plan, implement with TDD, review, and verify. The difference is that non-trivial behavior work also gets Behavior Evaluation in the spec and Behavior Coverage in the plan.

In practical terms: TDD still checks local implementation correctness. Behavior Evaluation and Behavior Coverage check whether the whole flow is still doing what the user wanted, even when the code has become too large or too opaque for a human to inspect line by line.

This is not the official Superpowers distribution. Official marketplaces may install upstream Superpowers. To use this fork, install from https://github.com/zhexulong/bdd-superpowers.git.

Quickstart

Give your agent BDD Superpowers: Codex CLI, OpenCode, Claude Code, Cursor, Gemini CLI, GitHub Copilot CLI, Kimi Code, Antigravity, Factory Droid, Pi.

The internal skill namespace remains superpowers:* for compatibility with existing agents and configs.

How It Works

It starts the same way Superpowers does. When you ask your coding agent to build something, it should not jump directly into code. It uses the brainstorming skill to understand what you are trying to do, explore alternatives, and turn the conversation into a reviewable design.

BDD Superpowers extends that path with a bounded behavior grill. The agent pressure-tests concrete examples, behavior boundaries, reject signals, invariants, and correction paths without turning the session into hours of exhaustive questioning. It should answer from code, docs, and existing conventions when it can, and ask the user only when the answer would change the design route.

Once the design is written, the spec can include Behavior Evaluation. This section is not another implementation plan. It names what behavior must be observable, what result is expected, what signal means the system drifted, what invariant must hold across the flow, and where to correct if the evidence fails.

After design approval, writing-plans still produces a Superpowers-style implementation plan with concrete tasks, file paths, tests, interfaces, and verification. When the spec contains Behavior Evaluation, the plan also includes Behavior Coverage: a short horizontal mapping from scenarios and invariants to implementation tasks and evidence. Technical-only tasks remain valid; the goal is not to force fake BDD onto every local slice.

Review checks more than local test pass/fail. BDD Superpowers adds architecture ownership checks to document review and a shorter version to code review. The reviewer looks for cases where local implementation is correct but the behavior pipeline is wrong, and for cases where convenience glue, caches, wrappers, fallback paths, debug artifacts, or eval artifacts have quietly become product contract or runtime authority.

This matters because many agent mistakes are not bad code in isolation. They are wrong ownership: a temporary support mechanism starts deciding routing, truth, method, answer shape, read order, or policy. The reviewer asks what higher-level behavior a mechanism now controls, whether that ownership belongs there, and whether it should be thinned, moved behind a private/eval-only boundary, relocated to an explicit contract/spec layer, or removed.

What Differs From Upstream Superpowers

• Bounded behavior grill in brainstorming - targeted behavior pressure-testing before the design is finalized, without asking dozens of low-value questions up front.
• Behavior Evaluation in specs - concrete examples, expected results, failure signals, invariants, observable evidence, and correction paths for non-trivial behavior changes.
• Behavior Coverage in plans - connects behavior scenarios to implementation tasks and verification evidence, while allowing unrelated implementation work to stay technical-only.
• Design document review - checks missing behavior evidence, ambiguous failure signals, weak invariants, unclear correction paths, hidden ownership, accidental architecture, and support mechanisms becoming product contract.
• Plan document review - rejects fake per-task behavior coverage, checks whether horizontal scenarios are carried through the plan, and blocks support/eval/debug machinery becoming product contract.
• Code review reinforcement - checks flow-level drift and hidden ownership: local tests passing while the intended behavior or pipeline is not preserved, or implementation glue taking over truth, method, routing, or policy ownership.

Installation