using-superbeads

Using Superbeads

Overview

Superbeads wires the superpowers brainstorm→plan→execute workflow into beads, making beads the single source of truth. This skill is the canonical definition of the override contract and field mapping, referenced by the three wrapper skills (superbeads:brainstorming, superbeads:writing-plans, superbeads:executing-plans) and the /superbeads-materialize command.

Prefer superbeads:* skills

When any of these superpowers skills would apply, invoke the superbeads equivalent instead:

Instead of...	Use...
superpowers:brainstorming	superbeads:brainstorming
superpowers:writing-plans	superbeads:writing-plans
superpowers:executing-plans	superbeads:executing-plans

If no superbeads wrapper exists for a skill, fall back to the superpowers original unchanged.

Override contract

Each wrapper skill invokes the underlying superpowers skill for its full dialogue and discipline, then intercepts three specific behaviors:

1. persist-to-file → persist-to-beads — wherever superpowers would write a spec or plan markdown, invoke /superbeads-materialize instead to land the content in beads.
2. "user reviews the written spec/plan" gate → "user reviews the beads epic/tasks" — wherever superpowers would ask the user to review a file, direct the user to bd show <id> to review the beads record.
3. inter-skill handoff → superbeads: equivalent* — wherever superpowers hands off to the next superpowers skill (e.g., brainstorming → writing-plans), hand off to the corresponding superbeads wrapper instead.

This override is legal under superpowers' own instruction-priority model (user/project instructions > skills), so no superpowers file is edited.

Source-of-truth rule

Beads is the sole durable home for spec and plan content. Never commit anything under docs/superpowers/.

Field mapping

When materializing superpowers content into beads, map fields as follows.

Spec → Epic fields

Spec content	Beads field
Purpose / problem statement	--description
Architecture / key decisions	--design
Success criteria	--acceptance
Open questions / notes	--notes

Plan → child tasks (under the epic)

Each item below creates a task object; it does not set a field on the epic.

Plan content	Beads action
Each plan "Task N"	bd create --type=task --parent <epic-id>
Task goal / intent	task --description
Task acceptance criteria	task --acceptance
Task bite-sized steps	task --design (full code/tests/commands)
Task dependencies	bd dep add edges / graph edges

All materialization is done exclusively by /superbeads-materialize.

Scratch safety-net

If a wrapped superpowers skill writes a scratch file despite the override, /superbeads-materialize ingests its content into beads and deletes it.