A beads-integrated fork of Superpowers by Jesse Vincent
Superpowers-BD is a multi-agent-tool plugin for Claude Code, Codex, and OpenCode. It extends the original Superpowers workflow with beads by Steve Yegge - a git-backed issue tracker that enables persistent task management, dependency tracking, and wave-based parallel execution across coding sessions.
The shared skills define workflow intent: design before coding, plan with dependencies, implement in verified waves, and preserve work across sessions. Each supported agent tool gets a native execution layer for skills, progress tracking, delegation, command entry points, verification, and hooks where that platform supports them.
| Shared intent | Claude Code implementation | Codex implementation |
|---|---|---|
| Track progress | TaskCreate, TaskUpdate, TaskList, TaskGet |
update_plan |
| Delegate work | Task with background execution when appropriate |
spawn_agent, then wait_agent when blocked on results |
| Ask questions | AskUserQuestion |
Direct user question, or structured question tool when available |
| Verify completion | Skill plus verification commands and captured evidence |
$skill plus verification commands and captured evidence |
Superpowers-BD aims for outcome parity, not identical implementation. Shared skills and beads semantics stay common; each platform uses its own native plugin, agent, hook, and progress surfaces.
| Capability | Claude Code | Codex | Current limitation |
|---|---|---|---|
| Skills | Bundled through .claude-plugin/plugin.json; invoked with the Skill tool and namespaced slash-command handoffs where applicable |
Bundled through .codex-plugin/plugin.json; invoked as native $skill entries such as $brainstorming, $plan2beads, and $subagent-driven-development |
Codex UI metadata currently exists for the high-traffic workflow skills; other skills still load from SKILL.md without per-skill UI polish |
| Agents | agents/code-reviewer.md and agents/epic-verifier.md use Claude Code agent frontmatter and Claude-specific effort settings |
.codex/agents/*.toml defines project-local agents; plugins/superpowers-bd/agents/*.md bundles installed-plugin Codex agents that inherit the active Codex model |
Codex implementation workers still use the default worker; specialist Codex agents cover review, aggregation, and verification |
| Hooks | hooks/hooks.json wires SessionStart, SessionEnd, TaskCompleted, and PostToolUse behavior for Claude Code |
.codex/hooks.json wires project-local hooks; plugins/superpowers-bd/hooks.json bundles installed-plugin SessionStart and PostToolUse hooks |
Claude Code keeps the link-plugin-components.sh workaround until plugin-loaded frontmatter hooks are proven reliable. Codex plugin hooks are bundled in the local marketplace wrapper rather than declared as a root manifest field |
| Review workflow | /superpowers-bd:cr and review skills dispatch Claude Code reviewers, with optional cross-model Codex advisory review when available |
$ad-hoc-code-review uses Codex-native reviewer agents and the shared review standards |
In a native Codex session, Codex is the orchestrator; it does not run a separate Codex advisory review of itself |
| SDD | subagent-driven-development dispatches Claude Code background Task workers and reviewers in dependency-aware waves |
$subagent-driven-development uses spawn_agent, wait_agent, Codex checkpoint fields, and Codex reviewer/verifier agents |
Both paths rely on cooperative file ownership prompts and beads state; hook-based hard file locking is not the primary conflict-control layer |
| Tests | tests/claude-code/ validates Claude Code sessions and skill behavior |
tests/codex/run-tests.sh validates Codex manifests, native agents, hooks, workflow semantics, fallback CLI, and wrapper integrity |
End-to-end interactive behavior still depends on the active agent tool and its installed feature set |
| Fallbacks | Claude Code uses the plugin marketplace path | Codex can use .codex/superpowers-bd-codex as a manual bootstrap fallback when native plugin install is unavailable |
The fallback CLI is maintained for skill discovery/loading only; native Codex plugin install is the preferred path |
| Feature | Superpowers | Superpowers-BD |
|---|---|---|
| Task tracking | In-memory TodoWrite | Persistent beads issues |
| Dependencies | None | bd dep add with blocking |
| Parallel execution | Basic subagents | Wave orchestration with conflict detection |
| Session persistence | Lost on context clear | Survives compaction, resumable |
| Epic verification | Self-review | Dedicated epic-verifier agent |
| Plan conversion | Manual | plan2beads command |
Required: beads - git-backed issue tracker
# Install beads (choose one)
brew install beads
npm install -g @beads/bd
go install github.com/steveyegge/beads/cmd/bd@latestWithout beads, the core workflow (plan2beads, executing-plans, subagent-driven-development) will not function.
These tools enhance linting and complexity checks but are not required — hooks gracefully degrade without them.
| Tool | Purpose | Install |
|---|---|---|
| shellcheck | Shell script linting | brew install shellcheck |
| lizard | Cyclomatic complexity checking | pip install lizard |
| cognitive-complexity-ts | Cognitive complexity for TS/TSX | npm install -g cognitive-complexity-ts |
Beads tracks WHAT work to do (features/epics, 1-4 hours). Each agent tool's native progress surface tracks HOW progress is made within those items (quality gates, 5-30 min).
12 skills enforce quality gates with native progress dependencies:
systematic-debugging- 4 phase tasks enforce "NO FIXES BEFORE ROOT CAUSE"rule-of-five-code/rule-of-five-plans/rule-of-five-tests- 5 sequential pass tasks with dependencies (variant-aware)test-driven-development- RED/GREEN/REFACTOR per featurewriting-plans- 7 tasks (draft + checklist + rule-of-five-plans)
Skipping phases is visible in the active platform's progress surface. Claude Code uses TaskList; Codex uses update_plan ordering.
5-pass review required for any artifact >50 lines, with artifact-specific variants:
Code (rule-of-five-code): Draft, Correctness, Clarity, Edge Cases, Excellence
Plans (rule-of-five-plans): Draft, Feasibility, Completeness, Risk, Optimality
Tests (rule-of-five-tests): Draft, Coverage, Independence, Speed, Maintainability
Integrated into writing-plans, executing-plans, writing-skills, and implementer prompts.
Key Decisions - Plans require 3-5 architectural decisions with rationale. Copied to epic description so implementers understand WHY, not just WHAT.
Task Context Sections - Optional but recommended:
Purpose:- Why this task existsNot In Scope:- Prevents overbuildingGotchas:- Known quirks from planning
Cross-Wave Summaries - After each wave, orchestrator posts summary comment to epic with conventions established and notes for future waves.
Problem: Verification was documented but skippable. Implementers rubber-stamped their own work.
Solution: Dedicated epic-verifier agent runs AFTER all implementation tasks close:
- Engineering checklist: YAGNI, drift, test coverage, regressions, docs, security
- Variant-aware rule-of-five on files with >50 lines changed
- Produces PASS/FAIL verdict with file:line evidence
- Does NOT fix issues - reports them for implementers to fix
7 explicit states with defined transitions:
INIT → LOADING → DISPATCH → MONITOR → REVIEW → CLOSE → COMPLETE
Background Execution - run_in_background: true enables true parallelism:
- Dispatch multiple implementations simultaneously
- Await completion notifications, Read output files for verdicts
- Immediately dispatch reviews as implementations finish
Budget Tier Selection - Model matrix based on subscription:
| Role | max-20x | max-5x | pro/api |
|---|---|---|---|
| Orchestrator | opus | opus | sonnet |
| Implementer | opus | sonnet | haiku |
| Reviewer | opus | sonnet | sonnet |
Failure Recovery - Documented patterns for timeout, FAIL verdict, file conflicts, context exceeded.
Use beads for personal issue tracking without committing to repo:
curl -fsSL https://raw.githubusercontent.com/schlenks/superpowers-bd/main/scripts/setup-beads-local.sh | bashInitializes beads in stealth mode (.beads/ in .git/info/exclude) and adds worktree auto-exclude to shell config.
It starts from the moment you fire up your coding agent. As soon as it sees that you're building something, it doesn't just jump into trying to write code. Instead, it steps back and asks you what you're really trying to do.
Once it's teased a spec out of the conversation, it shows it to you in chunks short enough to actually read and digest.
After you've signed off on the design, your agent puts together an implementation plan that's clear enough for an enthusiastic junior engineer with poor taste, no judgement, no project context, and an aversion to testing to follow. It emphasizes true red/green TDD, YAGNI (You Aren't Gonna Need It), and DRY.
Next up, once you say "go", it converts the plan to a beads epic with tracked dependencies, then launches subagent-driven-development - an orchestrator dispatches implementers in parallel waves, reviews their work with dedicated spec and code reviewers, and continues forward. Work persists across sessions. Agent tools can work autonomously for hours without deviating from the plan.
When implementation completes, a dedicated epic-verifier agent runs systematic verification (YAGNI, drift, tests, security, rule-of-five) before the branch is finished.
If Superpowers has helped you, consider sponsoring Jesse Vincent's opensource work - he created the original system this fork builds upon.
Note: Installation differs by platform. Claude Code and Codex have plugin marketplace flows. OpenCode uses a local plugin symlink.
In Claude Code, register the marketplace first:
/plugin marketplace add schlenks/superpowers-bdThen install the plugin from this marketplace:
/plugin install superpowers-bd@schlenks/superpowers-bdCheck that commands appear:
/help# Should see:
# /superpowers-bd:brainstorm - Interactive design refinement
# /superpowers-bd:write-plan - Create implementation plan
# /superpowers-bd:execute-plan - Execute plan in batches
Preferred native plugin install:
codex plugin marketplace add schlenks/superpowers-bd@mainThen install or enable superpowers-bd from Codex and restart Codex so bundled skills load.
Codex model routing defaults to the broadly available profile:
[superpowers_bd]
codex_model_profile = "standard"Use standard for gpt-5.3-codex. If your Codex plan has access to gpt-5.5, set codex_model_profile = "premium" in your project .codex/config.toml and set Codex itself to gpt-5.5. Plugin-bundled Codex agents do not pin a model, so they inherit the active Codex model.
Detailed docs: docs/README.codex.md
Tell OpenCode:
Fetch and follow instructions from https://raw.githubusercontent.com/schlenks/superpowers-bd/refs/heads/main/.opencode/INSTALL.md
Detailed docs: docs/README.opencode.md
-
brainstorming - Activates before writing code. Refines rough ideas through questions, explores alternatives, presents design in sections for validation. Saves design document.
-
using-git-worktrees - Activates after design approval. Creates isolated workspace on new branch, runs project setup, verifies clean test baseline.
-
writing-plans - Activates with approved design. Breaks work into bite-sized tasks (2-5 minutes each). Every task has exact file paths,
Depends on:sections, complete code, verification steps. -
plan2beads - Converts markdown plan to beads epic with tracked dependencies. Creates parent epic and child tasks with proper blocking relationships.
-
subagent-driven-development - Orchestrator dispatches implementers in parallel waves based on dependency graph. Each wave:
- Checks file conflicts between ready tasks
- Dispatches implementations (optionally in background for true parallelism)
- Runs spec review + code review (can be parallel)
- Closes completed tasks, unlocking next wave
-
test-driven-development - Activates during implementation. Enforces RED-GREEN-REFACTOR: write failing test, watch it fail, write minimal code, watch it pass, commit.
-
epic-verifier - Activates when all implementation tasks close. Dedicated verification agent runs engineering checklist (YAGNI, drift, tests, docs, security) and variant-aware rule-of-five on significant files. Produces PASS/FAIL verdict with evidence.
-
finishing-a-development-branch - Activates after verification passes. Presents options (merge/PR/keep/discard), cleans up worktree.
The agent checks for relevant skills before any task. Mandatory workflows, not suggestions.
Testing
- test-driven-development - RED-GREEN-REFACTOR cycle (includes testing anti-patterns reference)
Debugging
- systematic-debugging - 4-phase root cause process (includes root-cause-tracing, defense-in-depth, condition-based-waiting techniques)
- verification-before-completion - Ensure it's actually fixed
Collaboration
- brainstorming - Socratic design refinement
- writing-plans - Detailed implementation plans with dependency tracking
- executing-plans - Batch execution with checkpoints (beads-aware)
- dispatching-parallel-agents - Concurrent subagent workflows
- requesting-code-review - Pre-review checklist
- receiving-code-review - Responding to feedback
- using-git-worktrees - Parallel development branches
- finishing-a-development-branch - Merge/PR decision workflow
- subagent-driven-development - Wave-based orchestration with state machine, background execution, budget tier selection, and failure recovery
Verification
- epic-verifier - Dedicated agent for epic completion verification (YAGNI, drift, tests, docs, security, variant-aware rule-of-five)
- rule-of-five-code - 5-pass review for code (Draft, Correctness, Clarity, Edge Cases, Excellence)
- rule-of-five-plans - 5-pass review for plans/design docs (Draft, Feasibility, Completeness, Risk, Optimality)
- rule-of-five-tests - 5-pass review for tests (Draft, Coverage, Independence, Speed, Maintainability)
Beads Integration
- beads - Git-backed issue tracking skill
- plan2beads - Convert markdown plans to beads epics with dependencies
Meta
- writing-skills - Create new skills following best practices (includes testing methodology)
- using-superpowers - Introduction to the skills system
Superpowers-BD is designed to be forked and customized. Supported platforms use local > marketplace priority when their skill loader supports local overrides:
- Local skills in the platform-specific local skill directory take precedence
- Marketplace skills are used as fallbacks
This means you can:
- Fork this repository to your organization
- Add custom skills or modify existing ones
- Install your fork as a plugin
- Your customizations override marketplace defaults
When invoking skills, the active agent tool checks for local versions first when its skill loader supports local priority:
| If you want... | Try first (local) | Fall back to (plugin) |
|---|---|---|
| brainstorming | brainstorming |
superpowers-bd:brainstorming |
| writing-plans | writing-plans |
superpowers-bd:writing-plans |
| executing-plans | executing-plans |
superpowers-bd:executing-plans |
- Test-Driven Development - Write tests first, always
- Systematic over ad-hoc - Process over guessing
- Complexity reduction - Simplicity as primary goal
- Evidence over claims - Verify before declaring success
Read more: Superpowers for Claude Code
Skills live directly in this repository. To contribute:
- Fork the repository
- Create a branch for your skill
- Follow the
writing-skillsskill for creating and testing new skills - Submit a PR
See skills/writing-skills/SKILL.md for the complete guide.
In Claude Code, skills update when you update the plugin:
/plugin update superpowers-bdFor Codex updates, see docs/README.codex.md. For OpenCode updates, see docs/README.opencode.md.
MIT License - see LICENSE file for details
- This fork: https://github.com/schlenks/superpowers-bd/issues
- Upstream Superpowers: https://github.com/obra/superpowers
- Beads: https://github.com/steveyegge/beads