beads-superpowers

Process discipline and persistent memory for AI coding agents.

Try it in 60 seconds

Option A: Claude Code Marketplace (recommended)

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

Option B: npx (via Vercel Skills CLI)

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

After installing, tell Claude: "Run the setup skill" — this configures the SessionStart hook that makes skills activate automatically.

Option C: curl (one command, no dependencies)

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

Installs 20 skills to ~/.claude/skills/ and configures the SessionStart hook automatically. Supports --yes (CI mode), --version X.Y.Z, --dry-run, and --uninstall. See install.sh for details.

Then, in any project

cd your-project
bd init

In Claude Code, run /skills to verify — you should see 20 skills available.

The plugin's SessionStart hook already runs bd prime. Remove the duplicate hooks:

bd setup claude --remove

Why it exists

AI coding agents have two recurring failure modes:

1. No process discipline. They skip tests, rush to code, and claim work is done without verification.
2. No persistent memory. Todo lists vanish when a session ends. The next session starts blind.

beads-superpowers merges two upstream systems to solve both at once:

• Superpowers by Jesse Vincent — 20 mandatory skills enforcing TDD, brainstorming, systematic debugging, and two-stage code review.
• Beads by Steve Yegge — a Dolt-backed issue tracker that survives across sessions, agents, and projects.

The result: skills that don't just tell agents how to work — they give agents a persistent ledger to track what they're working on.

How it works

Session Start
  │
  ▼
SessionStart hook fires automatically
  ├── Injects using-superpowers skill (skill routing + beads awareness)
  └── Runs bd prime (beads CLI context + persistent memories)
  │
  ▼
Agent receives task from user
  │
  ▼
Skill system activates
  ├── brainstorming → design spec → user approval
  ├── writing-plans → implementation plan → beads created for each task
  ├── subagent-driven-development → execute tasks → two-stage review
  │     └── Per task: bd create → bd update --claim → implement → bd close
  └── finishing-a-development-branch → merge/PR → Land the Plane
  │
  ▼
Land the Plane (mandatory session close)
  ├── bd close <completed-beads> --reason "description"
  ├── bd dolt push (sync beads to Dolt remote)
  ├── git push (sync code to remote)
  └── git status (verify clean state)

The using-superpowers skill (loaded at every session start) enforces:

IF A SKILL APPLIES TO YOUR TASK, YOU DO NOT HAVE A CHOICE. YOU MUST USE IT.

Skills are not suggestions. They use bright-line rules, anti-rationalization tables, and empirically-tested enforcement language. See docs/METHODOLOGY.md for the research basis.

Skills reference

Beads commands used in skills

Architecture

flowchart TB
    User[User prompt] --> Orchestrator
    subgraph Orchestrator [Main Agent — orchestrator-only beads]
        SP[using-superpowers skill]
        BD[bd prime — beads context]
        SP --> Routing{Route to skill}
        BD --> Routing
    end
    Routing -->|design| Brainstorm[brainstorming]
    Routing -->|plan| WP[writing-plans]
    Routing -->|execute| SDD[subagent-driven-development]
    Routing -->|debug| Debug[systematic-debugging]
    SDD --> Sub1[Subagent 1: Task A]
    SDD --> Sub2[Subagent 2: Task B]
    Sub1 -->|results| Review[Two-stage review]
    Sub2 -->|results| Review
    Review --> Close[bd close + bd dolt push]
    Close --> Land[Land the Plane: git push]

The orchestrator is the only agent that touches beads. Subagents focus on implementation and have no concurrent bead-conflict surface. The two-stage review catches both spec deviation (first-stage spec reviewer) and code-quality issues (second-stage code reviewer) before any task is marked complete.

Design decisions

Project structure

beads-superpowers/
├── .claude-plugin/         Plugin manifests (auto-discovered by Claude Code)
├── .github/                CI workflow, Dependabot, issue/PR templates
├── assets/                 README banner SVG
├── hooks/                  SessionStart hook (bash + Windows polyglot wrapper)
├── skills/                 20 beads-native skills
├── agents/                 code-reviewer agent
├── commands/               Deprecated slash commands (will be removed in a future version)
├── docs/                   METHODOLOGY, SETUP-GUIDE, testing, upstream-reference
├── tests/                  Test infrastructure (5 suites)
├── scripts/                bump-version.sh
├── CHANGELOG.md
├── CLAUDE.md               Plugin development instructions
├── AGENTS.md               Agent instructions
├── CONTRIBUTING.md         How to contribute
├── SECURITY.md             Vulnerability reporting policy
├── LICENSE                 MIT
└── README.md               This file

For a deeper directory listing, see docs/SETUP-GUIDE.md.

Development

When you edit skills in this repo, the installed plugin cache goes stale. The simplest fix is a one-time symlink:

rm -rf ~/.claude/plugins/cache/beads-superpowers-marketplace/beads-superpowers/0.4.1
ln -s ~/workplace/beads-superpowers \
  ~/.claude/plugins/cache/beads-superpowers-marketplace/beads-superpowers/0.4.1

Verify sync:

diff -rq skills/ ~/.claude/plugins/cache/beads-superpowers-marketplace/beads-superpowers/0.4.1/skills/

claude plugin update exists but has a cache invalidation bug. Use the symlink approach instead.

For the full contributor guide, see CONTRIBUTING.md.

Attribution

• Superpowers skills — obra/superpowers by Jesse Vincent (MIT License)
• Beads issue tracker — gastownhall/beads by Steve Yegge (MIT License)
• beads-superpowers integration — Dillon Frawley

License

MIT