Philosophy

Every rule in this plugin traces back to one goal: a discipline layer that makes agent memory and process actually stick. Left alone, an agent skips straight to code, claims work is done before checking it, and forgets everything the moment the session ends. Superpowers attacked the first half of that problem: process discipline. Beads attacked the second: persistent memory. What follows is why beads-superpowers behaves the way it does once the two are wired together, not what it does day to day (that’s Methodology) and not the evidence behind each call (that’s Research).

Design before code. You’ll notice the agent doesn’t start typing when you describe a feature. It asks about purpose, constraints, and success criteria first, one question at a time, then proposes two or three approaches with trade-offs before writing a line. That’s a hard gate, not a suggestion. No implementation skill runs until a design is presented and approved, even for a change that looks trivial, because unexamined assumptions in a “simple” change are where the wasted work usually hides. A spec caught before code exists is far cheaper to fix than one caught after - what skipping that check costs is documented, not assumed.

Evidence before claims. An agent left to its own judgment will say “tests pass” because it expects them to, not because it ran them, and that gap is exactly what breaks trust once a human notices it. So nothing here may claim “done,” “fixed,” or “passing” without a command that was just run, in this message, with its output attached; a bead can’t close without that evidence attached to it, and one closed without it is treated as worse than one left open. You’ll see command output pasted before any word of celebration. Nobody else verifies that for the agent; someone has to run the check and read the result, which is exactly why unverified completion is a recurring failure class.

One orchestrator, disposable subagents. Workers dispatched to implement a task start with a blank slate: no memory of your conversation, no access to the tracker, just the exact instructions the orchestrator hands them for that one job. Only the orchestrating agent creates, claims, or closes anything in the tracker; a subagent’s output goes back as something the orchestrator reads on its own time, not a live exchange with whichever subagent runs next. Letting every subagent touch shared state or talk to each other directly is where coordination tends to break down first: a dropped handoff, an ignored update, two agents quietly disagreeing about a decision neither one surfaced. See why that failure mode shows up so often in multi-agent systems.

A tracker instead of ephemeral todos. A todo list that a chat window forgets the moment it closes is worse than no todo list at all, since it creates the appearance of tracking without the substance. That’s why every reference to TodoWrite in the skills this plugin inherited got replaced with a bd command: every task, every checklist step inside a multi-step skill, and every durable lesson goes into the tracker instead, as a bead with an ID that survives a session ending mid-task, a dependency graph, and an audit trail of what happened and when. If a session dies with work half-done, the next one finds an in-progress record instead of a blank page.

Skills are Markdown, not code. Following Superpowers’ original design, a skill here is a plain instruction file that any agent reads and follows: the same file works whether the harness is Claude Code, Codex, or something else entirely. bd is the only runtime dependency, and it’s optional: skills work without it, they just lose persistence rather than losing correctness. Keeping skills as prose instead of compiled code is what makes them portable across agents in the first place; a compiled dependency would tie the whole plugin to one runtime.

Absolute rules over hedged guidance. Skills say “NO PRODUCTION CODE WITHOUT A FAILING TEST FIRST,” not “consider writing a test first,” and that’s deliberate, not a style preference. Compliance research on AI agents found a substantial compliance gap between firm, absolute instructions and hedged ones asking for the same thing. Given enough pressure or a late hour, an agent can talk itself out of anything phrased as a suggestion; “MUST” and “NEVER” close that door. Every discipline-enforcing skill also pairs its Iron Law with a table naming the exact rationalizations agents reach for, so the excuse is on the page before the agent ever reaches for it.

Process skills come first. When a request could trigger more than one skill, the ones that shape the approach run before the ones that carry it out. Brainstorming or systematic-debugging goes ahead of whichever implementation skill the task eventually needs, because building on an unexamined approach costs more to unwind later than pausing to choose one up front. “Let’s build X” routes to design before it routes to code; “fix this bug” routes to root-cause analysis before it routes to a patch.

Curated injection, not context dumps. Hundreds of accumulated memories don’t all show up at once when a session opens. The start-of-session hook selects a small, high-salience slice plus a pointer to the rest, under a hard size ceiling, instead of injecting everything the store has ever collected. The size of that saving was measured, not assumed. The reasoning isn’t only cost: a short, ranked slice is easier for an agent to act on than an undifferentiated wall of text, and whatever didn’t make the cut stays one search away rather than disappearing.

Knowledge lives in the tracker. A design rationale or research finding written up once and left in a folder nobody revisits doesn’t help the next session that needs it. So reference material - research findings, design notes, past decisions - goes into the same tracker as the work itself, tagged and searchable by topic instead of scattered across documents that drift out of sync with what actually happened. The full write-up can still live in a document; what the tracker holds is the pointer to it, retrievable the moment a related question comes up rather than only if someone remembers where it’s parked. Memory & Sessions covers how that retrieval actually works.

Production-grade by default. Every project is treated as if it has real users, no matter how small it looks: “it’s just a script” is exactly the rationalization that ships the worst defects. On its own initiative, the agent won’t quietly drop a requirement, take an undisclosed shortcut, or weaken a security control to save time. Instead, a genuine trade-off goes to a human to decide, and a security regression is refused outright, never negotiated. The standing instruction lives in one place and echoes wherever a consequential decision actually happens: brainstorming, review, and the completion check.

The mechanism these add up to (the skill lifecycle, the hook, the bead lifecycle) lives in Methodology. The literature and the measurements behind them are collected in Research.