https://github.com/dollardill/beads-superpowers
Claude Code plugin merging Superpowers skills with Beads issue tracking. 15 mandatory skills + persistent task memory for AI coding agents.
https://github.com/dollardill/beads-superpowers
ai-agents beads claude-code claude-code-plugin developer-tools issue-tracker superpowers tdd
Last synced: about 2 months ago
JSON representation
Claude Code plugin merging Superpowers skills with Beads issue tracking. 15 mandatory skills + persistent task memory for AI coding agents.
- Host: GitHub
- URL: https://github.com/dollardill/beads-superpowers
- Owner: DollarDill
- License: mit
- Created: 2026-04-06T06:02:42.000Z (2 months ago)
- Default Branch: main
- Last Pushed: 2026-04-19T09:30:29.000Z (about 2 months ago)
- Last Synced: 2026-04-19T11:34:28.891Z (about 2 months ago)
- Topics: ai-agents, beads, claude-code, claude-code-plugin, developer-tools, issue-tracker, superpowers, tdd
- Language: Shell
- Homepage: https://github.com/DollarDill/beads-superpowers#readme
- Size: 556 KB
- Stars: 4
- Watchers: 1
- Forks: 0
- Open Issues: 2
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
- Security: SECURITY.md
- Agents: AGENTS.md
Awesome Lists containing this project
README
Process discipline and persistent memory for AI coding agents.
---
## Try it in 60 seconds
### Option A: Claude Code Marketplace (recommended)
```bash
claude plugin marketplace add DollarDill/beads-superpowers
claude plugin install beads-superpowers@beads-superpowers-marketplace
```
### Option B: npx (via Vercel Skills CLI)
```bash
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)
```bash
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](install.sh) for details.
### Then, in any project
```bash
cd your-project
bd init
```
In Claude Code, run `/skills` to verify — you should see 20 skills available.
If you previously ran bd setup claude
The plugin's SessionStart hook already runs `bd prime`. Remove the duplicate hooks:
```bash
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](https://github.com/obra/superpowers)** by Jesse Vincent — 20 mandatory skills enforcing TDD, brainstorming, systematic debugging, and two-stage code review.
- **[Beads](https://github.com/gastownhall/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
```text
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 --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`](docs/METHODOLOGY.md) for the research basis.
## Skills reference
| Skill | Category | When to use |
|-------|----------|-------------|
| **using-superpowers** | Meta | Every session start — routes to the right skill |
| **brainstorming** | Design | Before any creative work — explores design before code |
| **writing-plans** | Planning | After design approval — creates bite-sized task plans |
| **subagent-driven-development** | Execution | Execute plans with fresh subagent per task + two-stage review |
| **executing-plans** | Execution | Execute plans in a single session with checkpoints |
| **test-driven-development** | Quality | Any feature or bugfix — RED-GREEN-REFACTOR cycle |
| **systematic-debugging** | Quality | Any bug or test failure — 4-phase root cause analysis |
| **verification-before-completion** | Quality | Before any "done" claim — evidence before assertions |
| **requesting-code-review** | Review | After implementation — dispatches code reviewer |
| **receiving-code-review** | Review | When receiving feedback — anti-sycophancy review reception |
| **using-git-worktrees** | Infrastructure | Isolated development branches with safety checks |
| **finishing-a-development-branch** | Infrastructure | Merge/PR decision tree + Land the Plane protocol |
| **dispatching-parallel-agents** | Advanced | 2+ independent tasks without shared state |
| **writing-skills** | Meta | Creating or modifying skills — TDD for process docs |
| **document-release** | Quality | Post-ship documentation audit — syncs docs to match shipped code |
| **project-init** | Infrastructure | Beads/Dolt DB setup, bootstrap, and recovery |
| **stress-test** | Design | Adversarial interrogation of designs/plans with recommended answers |
| **setup** | Infrastructure | Post-npx hook installation — configures SessionStart for skills auto-activation |
| **auditing-upstream-drift** | Meta | Periodic audit for staleness vs upstream superpowers and beads |
| **getting-up-to-speed** | Meta | Start of session or post-compaction — runs bd commands, deep-dives the codebase, produces a structured current-state summary |
### Beads commands used in skills
| Action | Command | Used in |
|--------|---------|---------|
| Create epic | `bd create "Epic: name" -t epic` | subagent-driven-dev, executing-plans |
| Create task | `bd create "Task: name" -t task --parent ` | subagent-driven-dev, executing-plans |
| Claim work | `bd update --claim` | executing-plans |
| Complete work | `bd close --reason "description"` | all execution skills |
| Check remaining | `bd ready --parent ` | subagent-driven-dev, executing-plans |
| Add dependency | `bd dep add ` | subagent-driven-dev, writing-plans |
| Store learning | `bd remember "insight"` | any session |
| Sync to remote | `bd dolt push` | finishing-a-development-branch |
| Session context | `bd prime` | SessionStart hook (automatic) |
## Architecture
```mermaid
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
| Decision | Rationale |
|----------|-----------|
| **Orchestrator-only beads** | Only the main agent manages beads. Subagents focus on implementation — no concurrent bead conflicts. |
| **Plugin subsumes bd hooks** | The plugin's SessionStart hook runs `bd prime` itself. No need for separate `bd setup claude` hooks. |
| **TodoWrite fully replaced** | Every TodoWrite reference is replaced with `bd` commands. Zero active TodoWrite usage. |
| **Land the Plane in finishing skill** | Session close protocol lives in the terminal skill, not a separate skill. Every pipeline path ends here. |
| **Skills are Markdown, not code** | Pure documentation — no build step, no dependencies, works on any platform with a file system. |
## Project structure
```text
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`](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:
```bash
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:
```bash
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](https://github.com/anthropics/claude-code/issues/14061). Use the symlink approach instead.
For the full contributor guide, see [`CONTRIBUTING.md`](CONTRIBUTING.md).
## Attribution
- **Superpowers skills** — [obra/superpowers](https://github.com/obra/superpowers) by Jesse Vincent (MIT License)
- **Beads issue tracker** — [gastownhall/beads](https://github.com/gastownhall/beads) by Steve Yegge (MIT License)
- **beads-superpowers integration** — Dillon Frawley
## License
[MIT](LICENSE)