beads-superpowers

---

A plugin for Claude Code, Codex, OpenCode, and 7 more AI coding agents that makes your agent write tests before code, debug systematically instead of guessing, and remember what it worked on yesterday. Composable skills enforce the practices; a Dolt-backed issue tracker keeps context across sessions.

Quickstart

The fastest path - Claude Code with native plugin install:

brew install beads                    # 1. Install bd (requires beads v1.1.0+)
# From your shell:
claude plugin marketplace add DollarDill/beads-superpowers
claude plugin install beads-superpowers@beads-superpowers-marketplace
# Or, inside a Claude Code session:
# /plugin marketplace add DollarDill/beads-superpowers
# /plugin install beads-superpowers@beads-superpowers-marketplace
# Then in your project directory:
bd init                               # 2. Bootstrap the Dolt database for this project

Start a new Claude Code session and type "where are we" - the agent will load your bd context and pick up where you left off.

Using a different agent? Jump to install for Codex CLI, OpenCode, Cursor, Gemini CLI, GitHub Copilot CLI, Kimi Code, Antigravity, Factory Droid, or Pi.

The Basic Workflow

1. research-driven-development - When the task needs understanding first: parallel research agents investigate and write a verified knowledge-base document before any design happens.

2. brainstorming - Refines the idea through one-question-at-a-time design dialogue, checks prior decisions in the knowledge store, and ends with a spec you approved - tracked in bd so it survives the session.

3. stress-test - Adversarially interrogates the approved spec branch by branch (offered at every spec review), so flaws surface before planning.

4. writing-plans - Turns the spec into bite-sized tasks with exact files, code, and verification steps. Every task becomes a bd bead.

5. stress-test (again) - The same adversarial pass against the plan itself: task boundaries, parallel-safety, failure modes.

6. subagent-driven-development or executing-plans - Dispatches a fresh subagent per task, each in its own isolated worktree (implementers follow test-driven-development), or executes in batches with human checkpoints.

7. requesting-code-review - Task-level and whole-branch reviews against the plan. Critical findings block progress.

8. verification-before-completion - Nothing is called done without a command that proves it - evidence gates every close.

9. document-release - Audits the project docs against what actually shipped, before the branch merges.

10. finishing-a-development-branch - Presents merge/PR options and lands the plane: close the beads, sync, push.

The agent checks for relevant skills before any task - these are mandatory workflows, not suggestions. And because every task, decision, and lesson lives in bd's Dolt database, the next session starts where this one ended: type "where are we" and the agent picks the thread back up.

What's Inside

Testing

Skill	What it does
test-driven-development	RED-GREEN-REFACTOR loop - Iron Law: no implementation without a failing test

Debugging

Skill	What it does
systematic-debugging	4-phase root-cause analysis before proposing any fix
verification-before-completion	Evidence before claims - nothing is "done" until a command proved it

Design & planning

Skill	What it does
brainstorming	Socratic design session before any code - produces an approved spec
stress-test	Adversarial interrogation of designs and plans, with recommended answers
writing-plans	Bite-sized task plans - every task tracked as a bd bead

Execution

Skill	What it does
subagent-driven-development	Fresh agent per task with spec + quality review; parallel batch mode
executing-plans	Batch plan execution in a single session with checkpoints
dispatching-parallel-agents	Fans out 2+ independent tasks to parallel agents with no shared state
using-git-worktrees	Isolated development branches per feature
requesting-code-review	Dispatches a code-reviewer subagent with structured criteria
receiving-code-review	Verifies review feedback against the code before implementing it - no reflexive agreement
finishing-a-development-branch	Merge/PR flow + land the plane (close beads, sync, push)

Documentation

Skill	What it does
write-documentation	14-rule writing system for human-facing prose - READMEs, guides, release notes
document-release	Post-ship documentation audit - keeps the docs matching what actually shipped

Memory & orientation

Skill	What it does
getting-up-to-speed	Session orientation - loads bd context and produces a current-state summary
memory-curator	Consolidates, deduplicates, and prunes the persistent memory store
session-handoff	Writes a grounded handoff doc so the next session resumes mid-flight work
research-driven-development	Parallel research agents → verified, persistent knowledge base
project-init	Sets up, bootstraps, and recovers the beads/Dolt database behind persistent memory

Full skills reference →

How it works

When you start a task, the agent runs brainstorming to nail down requirements before touching code, then writing-plans to break the work into bd-tracked steps that survive session restarts. During implementation it follows test-driven-development (failing test first, always) and can fan out to parallel subagents via subagent-driven-development - each agent working in its own git worktree. bd stores every task, decision, and note in a local Dolt database, so the agent picks up exactly where it left off next session without relying on chat history.

Underneath all of it is a production-grade standard: the agent treats every task as if real users depend on it, so it won't quietly cut a corner, drop a requirement, or weaken a security control to move faster.

Philosophy

• Design before code - every feature starts as a spec a human approved, not a guess
• TDD is an Iron Law - no implementation without a failing test
• Systematic over ad-hoc - debugging follows a root-cause process, never guess-and-check
• Evidence before claims - "done" requires a command that proves it
• Memory over chat history - tasks, decisions, and lessons persist in bd, not in a scroll buffer

The long form lives in Methodology.

Docs

algocents.com/beads-superpowers - getting started, methodology, skills reference, example workflow, and tips.

• Example Workflow docs - Full walkthrough with diagrams
• Skills Reference - All skills explained
• Methodology - Why this workflow exists

Installation

⚠️ Coexistence warning: Do not install alongside obra/superpowers. Skill names collide - pick one or the other.

Prerequisites

Install bd before the plugin. Its hooks call bd on every session start; without it they fail silently and you lose persistent memory. Use Homebrew (brew install beads) or npm install -g @beads/bd on any platform. Verify with bd version.

Note: Native plugin install installs skills and hooks, but not bd init - run that yourself per project.

Claude Code

claude plugin marketplace add DollarDill/beads-superpowers
claude plugin install beads-superpowers@beads-superpowers-marketplace

Or as slash commands inside a Claude Code session: /plugin marketplace add DollarDill/beads-superpowers then /plugin install beads-superpowers@beads-superpowers-marketplace.

Codex CLI

codex plugin marketplace add DollarDill/beads-superpowers
codex plugin install beads-superpowers@beads-superpowers-marketplace

After installing, enable hooks in ~/.codex/config.toml:

[features]
codex_hooks = true

To get the SessionStart hook under Codex, use the scripted installer (install.sh) rather than the plugin channel - the plugin channel installs the skills but does not wire the hook.

OpenCode

Add to the plugin array in your opencode.json (global or project-level):

{
  "plugin": ["beads-superpowers@git+https://github.com/DollarDill/beads-superpowers.git"]
}

Skills auto-register and the session bootstrap + beads context inject automatically - no other steps. Details, version pinning, migration from pre-0.12 installer copies, and troubleshooting: .opencode/INSTALL.md.

Cursor

/add-plugin beads-superpowers

Run this command inside Cursor Agent. Update via the Marketplace UI.

Gemini CLI

gemini extensions install https://github.com/DollarDill/beads-superpowers

GitHub Copilot CLI

copilot plugin marketplace add DollarDill/beads-superpowers
copilot plugin install beads-superpowers@beads-superpowers-marketplace

Update:

copilot plugin update beads-superpowers

Note: rides the Claude-plugin fallback (skills + session-start via the shared hooks/hooks.json), the same mechanism upstream ships; requires Copilot CLI v1.0.11+ for session-start context injection.

Kimi Code

/plugins install https://github.com/DollarDill/beads-superpowers

Run /new after install to start a fresh session with the plugin active.

Antigravity

agy plugin install https://github.com/DollarDill/beads-superpowers

Note: reuses the Claude plugin manifest - the same mechanism upstream verified.

Factory Droid

droid plugin marketplace add https://github.com/DollarDill/beads-superpowers
droid plugin install beads-superpowers@beads-superpowers-marketplace

Note: reuses the Claude plugin manifest - the same mechanism upstream verified.

Pi

pi install git:github.com/DollarDill/beads-superpowers

npx (any harness)

Installs the skills only - no hooks. Skill activation relies on your harness's native skill discovery.

npx skills add DollarDill/beads-superpowers -g --copy -y

Alternative: scripted install (curl | bash)

curl -fsSL https://raw.githubusercontent.com/DollarDill/beads-superpowers/main/install.sh | bash

The script's role is broader than just copying files. Use it when you need any of:

• Beads/Dolt bootstrap - auto-detects whether bd is installed and guides setup
• Hook registration - writes the SessionStart entry to settings.json (required when using the install-script path)
• yegge.md orchestrator - optional add-on: installed only when you pass --with-yegge. The flag forces the scripted tarball/git install tier (the plugin and npx tiers are skipped for that run), so it can't be combined with a plugin-managed install in one command
• Version pinning - --version X.Y.Z for reproducible CI installs
• CI environments - use --yes --skip-checksum for unattended runs

Supports: --yes (skip prompts), --version X.Y.Z, --with-yegge, --dry-run, --skip-checksum, --uninstall.

Updates: rerun your install command - plugin channels update via their marketplace, npx and the script by rerunning.

Contributing

Contributions are welcome - see CONTRIBUTING.md. PRs target the dev branch (main is the released branch). Ideas and questions live in Discussions.

Built on

• Superpowers by Jesse Vincent - the skill system and development practices
• Beads by Steve Yegge - persistent issue tracking with cross-session memory

Individual skills adapted from:

• Garry Tan - document-release, adapted from garrytan/gstack
• Matt Pocock - stress-test, from skills/grilling; session-handoff, from skills/handoff
• Ivan Neustroev ("Anbeeld") - the writing system behind write-documentation, adapted from WRITING.md (MIT)

License

MIT

Community

• Ideas & questions: GitHub Discussions - the pinned post is the front door
• Bugs: Issues
• Contact: dillon@algocents.com