Methodology

Design philosophy, research basis, and rationale behind merging Superpowers skills with Beads issue tracking into a single Claude Code plugin.

The Problem

AI coding agents in 2025–2026 face two fundamental problems that, until now, have been solved by two separate systems.

Problem 1: No Process Discipline

Without explicit workflow enforcement, AI agents consistently:

• Skip to coding before understanding the problem
• Write implementation before tests
• Claim work is "done" without running verification
• Accept review feedback without questioning it (sycophancy)
• Attempt fix after fix without investigating root causes
• Rationalise skipping every process step with plausible-sounding excuses

Superpowers (by Jesse Vincent) solved this with 14 composable skills that use bright-line rules, anti-rationalization tables, and pressure-tested enforcement language. Compliance doubled from 33% to 72% when using absolute rules over hedged guidance (Meincke et al. 2025).

Problem 2: No Persistent Memory

When an AI coding session ends:

• Todo lists created with TodoWrite vanish entirely
• Task dependencies are forgotten
• Work-in-progress has no audit trail
• The next session starts completely blind
• Learned conventions and preferences are lost

Beads (by Steve Yegge) solved this with a Dolt-backed issue tracker that provides:

• Hash-based IDs that work without central coordination
• Cell-level merge for conflict-free multi-agent operation
• bd prime context injection at every session start
• bd remember for persistent cross-session learnings
• Full audit trail via the events table

The Gap

Superpowers had process discipline but ephemeral tracking (TodoWrite). Beads had persistent tracking but no process discipline (just raw issue CRUD). Neither was complete alone.

beads-superpowers bridges the gap: every process step in every skill now creates, updates, or closes a persistent bead. The agent doesn't just follow the right process — it leaves a permanent record of having done so.

The Solution

beads-superpowers is a Claude Code plugin that merges two upstream systems, each addressing one of the two failure modes.

Superpowers — Process Discipline

Superpowers provides 21 composable skills enforcing TDD, brainstorming before code, systematic debugging, two-stage code review, and verification before completion. Skills are not suggestions. They use bright-line rules, Iron Laws, and anti-rationalization tables. The bootstrap skill (using-superpowers) routes to the correct skill automatically based on the task type.

Beads — Persistent Memory

Beads is a Dolt-backed issue tracker built for AI agents. Every task is a bead — a persistent record with a hash-based ID that survives session boundaries. bd prime injects current task state, remaining work, and learned memories at every session start. The agent never starts blind.

The Integration

By replacing every TodoWrite call in every Superpowers skill with the equivalent bd command, the two systems become one. Following process discipline now automatically populates persistent memory. The agent cannot do one without the other.

The Integration

Every reference to TodoWrite across all 14 original Superpowers skills was replaced with beads (bd) commands.

The replacement was done at both granularity levels that TodoWrite operated at in Superpowers:

• Task level — tracking plan tasks in execution skills
• Checklist level — tracking internal steps within a skill's own checklist

Both were replaced. Even the brainstorming 9-step checklist and the writing-skills 20-step checklist now create beads. This means every process step, at every level, is persistent and auditable.

If only task-level tracking is persistent but checklist-level tracking is ephemeral, agents learn that "some tracking is optional." The bright-line rule is: all tracking uses beads, no exceptions.

Orchestrator-Only Design

The three subagent prompt files (implementer, spec-reviewer, code-quality-reviewer) are deliberately not beads-aware. This is the orchestrator-only design decision:

• The orchestrating agent creates, claims, and closes beads
• Subagents focus purely on implementation and review
• This prevents concurrent bead write conflicts
• It keeps subagent prompts focused and simple

The pattern: orchestrator creates bead → dispatches subagent → subagent implements → orchestrator closes bead.

What Was Added Beyond the Replacement

• Beads Issue Tracking section in using-superpowers — every session starts with beads awareness
• Land the Plane protocol in finishing-a-development-branch — every session ends with bd dolt push + git push
• Beads Completion section in verification-before-completion — bd close without evidence is lying
• Epic/child bead pattern in execution skills — plans become epic beads with task children
• Dependency tracking in execution skills — bd dep add for task dependencies
• Context forwarding in brainstorming — brainstorming beads link to plan epics via discovered-from

What Was Preserved

The integration was designed to be additive. The following content from the original 14 Superpowers skills was kept completely intact:

• All 14 original Superpowers skills and their complete content
• Every anti-rationalization table, Iron Law, and Red Flags section
• The progressive skill chain (brainstorming → plans → execution → finishing)
• The two-stage review pattern (spec compliance then code quality)
• All subagent prompt templates (implementer, spec-reviewer, code-quality-reviewer) — unchanged
• Platform reference files for Gemini, Copilot CLI, and Codex

Note: beads-superpowers has since grown to 21 skills. Six additional skills were created specifically for this project: auditing-upstream-drift, document-release, getting-up-to-speed, project-init, setup, and stress-test.

Agent Memory Types

Beads provides all seven types of memory that AI agents need. By integrating beads into every skill, all seven memory types are populated as a natural byproduct of following the workflow.

Research Basis

The skill enforcement language is grounded in two research streams.

Cialdini (2021) — Influence Principles Applied to AI

From Influence: The Psychology of Persuasion (New and Expanded Edition), three principles inform how skills are written:

• Authority — Iron Laws and bright-line rules ("NO PRODUCTION CODE WITHOUT A FAILING TEST FIRST")
• Consistency — Once an agent starts following a skill, consistency pressure maintains compliance
• Scarcity — "You cannot rationalize your way out of this" removes alternatives

Meincke et al. (2025) — AI Agent Compliance

Research on AI agent compliance with explicit vs hedged instructions found:

• Compliance doubled from 33% to 72% when using absolute rules over hedged guidance
• Pre-emptive rationalization counters outperform reactive correction
• Specific examples of non-compliance are more effective than generic warnings

This is why every discipline-enforcing skill includes an Iron Law (absolute, memorable, no exceptions), a Red Flags table (anticipated rationalizations with pre-loaded counter-arguments), and bright-line rules (MUST/NEVER/NO EXCEPTIONS instead of "consider"/"prefer"/"try to").

Claude Search Optimization (CSO)

A critical finding from the writing-skills meta-skill:

When a skill's description field summarizes the workflow, Claude may follow the description instead of reading the full skill content. A description saying "code review between tasks" caused Claude to do ONE review, even though the skill clearly showed TWO reviews.

As a result, every skill's YAML frontmatter description field is a trigger condition ("when to use this"), not a workflow summary ("what this does"). This ensures the full skill content is always read.

End-to-End Workflow

The following is what happens when an agent receives a feature request with beads-superpowers active.

Step 1 — Session Start

The SessionStart hook fires automatically. It loads the using-superpowers skill (providing beads-aware routing) and runs bd prime (injecting beads context and persistent memories from previous sessions).

Step 2 — Brainstorming

The agent checks whether brainstorming applies (yes for any creative work). The brainstorming skill activates:

• bd create "Brainstorming: auth system" -t task
• Creates child beads for each checklist step
• Explores project context, asks clarifying questions
• Proposes 2–3 approaches with trade-offs
• Presents design, gets user approval
• Writes design spec, commits to git
• Terminal state: invokes writing-plans

Step 3 — Writing Plans

The writing-plans skill creates an implementation plan with bite-sized tasks (2–5 minutes each). Each task has exact file paths, code snippets, and verification steps. The plan is saved to docs/ and handed off to subagent-driven-development.

Step 4 — Subagent-Driven Development

The orchestrating agent creates an epic bead and task beads with dependencies:

bd create "Epic: Auth System" -t epic
bd create "Task 1-5" -t task --parent <epic-id>
bd dep add <child> <depends-on>

For each task:

• bd update <task-id> --claim
• Dispatch implementer subagent (with full task text)
• Implementer implements using TDD (RED-GREEN-REFACTOR)
• Dispatch spec reviewer subagent → pass/fail loop
• Dispatch code quality reviewer subagent → pass/fail loop
• bd close <task-id> --reason "Completed: spec + quality passed"

After all tasks, a final code reviewer is dispatched and finishing-a-development-branch is invoked.

Step 5 — Finishing the Branch

The finishing-a-development-branch skill runs six steps:

1. Verify all tests pass (hard gate)
2. Determine base branch
3. Present 4 options (merge / PR / keep / discard)
4. Execute chosen option
5. Cleanup worktree
6. Land the Plane

Step 6 — Land the Plane

bd close <epic-id> --reason "All tasks complete"
bd dolt push
git pull --rebase && git push
git status

Step 7 — Next Session

bd prime injects completed beads, remaining work, and memories. The next session starts exactly where the last one left off.

Every step is tracked. Every decision is auditable. Every session starts where the last one left off.