Skip to content
/
Tier A A4 Markdown scaffold

SuperBeads Universal Framework (Wiggum Flavour)

superbeads-wiggum · EliaAlberti/superbeads-universal-framework · ★ 31 · last commit 2026-03-26

Bring Beads task tracking, atomic git commits, session memory, and domain-specific verification to Claude Code via a universal CLI-installed scaffold.

Best whenUniversal patterns belong in Core; domain-specific patterns belong in Packs — every Core feature must work for code, research, design, writing, AND PM.
Skip ifRunning bare bv (interactive TUI), Claiming done without verify.sh passing
vs seeds
agent-os: Beads task integration (b…
Primitive shape 6 total
Commands 6
00

Summary

SuperBeads Universal Framework (Wiggum Flavour) — Summary

SuperBeads Universal Framework (EliaAlberti/superbeads-universal-framework) is a Claude Code methodology framework that integrates Steve Yegge's Beads task tracking with a universal Core Engine (session memory, atomic git commits, observable verification) plus five optional domain Packs (iOS, Python, Web, Design, PM). It is installed via a shell script that copies files to ~/.superbeads/ and adds a superbeads CLI to PATH. The "Wiggum Flavour" branding refers to the subtitle shown in the README — the author's named variant of the Universal Framework. The framework initializes a project with CLAUDE.md (session memory), .beads/ (task database), .superbeads/ (sprint tracking + agent definitions), and verify.sh (domain-specific verification script). A built-in TUI (using the separately installed bv) shows Board, Kanban, Dependency Graph, and Insights dashboards.

Differs from seeds: closest to agent-os (CLAUDE.md as primary artifact, markdown-scaffold philosophy) but adds Beads task integration, a superbeads CLI binary, domain packs, and the bv TUI. Unlike agent-os which ships 5 slash-commands, SuperBeads ships 6 slash-commands (/resume, /preserve, /compress, /wrapup, /status, /task) plus a standalone CLI.

01

Overview

SuperBeads Universal Framework — Origin and Philosophy

Origin

Author: Elia Alberti (GitHub: EliaAlberti). 31 stars. Version 2.0.0 (as of March 2026). Shell-based installer. Created 2026.

Philosophy: Universal Patterns for Any Task

From core/ARCHITECTURE.md:

"The Core Engine embodies a single principle: Universal patterns that work for any task."

The universality test:

  • Does this work for code? ✓
  • Does this work for research? ✓
  • Does this work for design? ✓
  • Does this work for writing? ✓
  • Does this work for PM? ✓
  • If any answer is "no", it belongs in a Pack, not Core.

Core Pillars

Session Memory: CLAUDE.md persists project context across sessions. /resume reloads it, /preserve archives it when it exceeds 280 lines.

Atomic Git Commits: One commit per task, format: ✓ task-007: Password validation. Clean, traceable history with easy rollback.

Observable Verification: Every task has a verifiable completion signal (build passes, tests green, file exists). verify.sh runs domain-specific checks.

Task Discipline: Tasks are atomic, time-boxed, single-responsibility. Beads integration provides dependency tracking and graph analysis.

"Wiggum Flavour" Branding

The framework's README subtitle reads: "with Wiggum Flavour" — a named variant that bundles the Beads integration (bd + bv), the TUI board views, and the domain pack system. The "Wiggum" name appears to be a personal branding choice by the author (no further explanation in the repo).

02

Architecture

SuperBeads Universal Framework — Architecture

Distribution

Clone + shell installer:

git clone https://github.com/EliaAlberti/superbeads-universal-framework.git
./core/scripts/install-superbeads.sh

Copies core files to ~/.superbeads/, adds superbeads CLI to PATH.

Required Runtime

  • Claude Code CLI
  • Git
  • Beads CLI (bd) — installed automatically by superbeads init
  • Beads Viewer TUI (bv) — installed automatically by superbeads init
  • Domain-specific tools per pack (Xcode for iOS, Node for Web, etc.)

Directory Tree (post-init)

your-project/
├── CLAUDE.md                  # Project memory (persists across sessions)
├── .beads/                    # Task tracking database (bd)
│   └── issues.jsonl
├── .superbeads/               # Sprint tracking and settings
│   ├── sprint/
│   └── agents/                # (after pack install)
├── verify.sh                  # Root verification script
└── scripts/                   # (after pack install)
    └── verify.sh              # Domain-specific verification

Repository Structure

superbeads-universal-framework/
├── core/
│   ├── ARCHITECTURE.md
│   ├── README.md
│   ├── docs/                  # Universal documentation
│   │   ├── UNIVERSAL-AGENTS.md
│   │   ├── TASK-DISCIPLINE.md
│   │   ├── VERIFICATION-FRAMEWORK.md
│   │   ├── SESSION-PROTOCOLS.md
│   │   ├── SPRINT-TRACKING.md
│   │   ├── SUPERVISOR-MODEL.md
│   │   ├── BEADS-INTEGRATION.md
│   │   └── USING-CORE-ALONE.md
│   ├── templates/             # CLAUDE.md, agent, skill, task, verify, sprint templates
│   └── scripts/
│       ├── superbeads          # Main CLI (shell)
│       ├── install-superbeads.sh
│       └── verify.sh          # Verification runner
├── packs/
│   ├── ios/
│   ├── python/
│   ├── web/
│   ├── design/
│   └── pm/
├── GUIDE.md
├── VISION.md
└── research/

Target AI Tools

Claude Code (primary). No MCP, no hooks configuration — purely markdown + CLI scaffolding.

03

Components

SuperBeads Universal Framework — Components

CLI (superbeads)

Command Purpose
superbeads init Initialize project (creates CLAUDE.md, .beads/, .superbeads/, verify.sh; installs bd + bv)
superbeads pack install <name> Install domain pack (ios/python/web/design/pm)
superbeads status Show project status
superbeads --version Show version

Claude Code Slash Commands (via CLAUDE.md)

Command Purpose
/resume Load project context + recent session logs; supports topic search
/preserve Save progress; auto-archives when CLAUDE.md > 280 lines
/compress Save searchable session logs before /compact
/wrapup End-of-session save, archive, cleanup
/status Show superbeads status overview
/task Task management operations

Templates (core/templates/)

Template Purpose
Agent template Universal agent role definition
Skill template Skill definition scaffold
Task schema Atomic task format
Verify template Verification script scaffold
Sprint template Sprint planning format
Settings schema Project settings
CLAUDE.md template Session memory scaffold

Domain Packs (packs/)

Pack Domain
ios Xcode, Swift, iOS-specific verification
python Python toolchain, pytest, type-checking
web Node.js, test frameworks
design Design asset workflows
pm Project management workflows

Beads Viewer TUI (bv) — Installed by Framework

Mode Purpose
Board view Visual task board
Kanban view Workflow columns
Dependency graph Task relationships visualization
Insights dashboard Project health metrics
05

Prompts

SuperBeads Universal Framework — Prompts

The framework ships template files rather than raw prompt files. The actual prompt content lives in CLAUDE.md (generated from core/templates/CLAUDE.md) and core documentation files injected at session start.

Prompt 1: Universal Agents Documentation (core/docs/UNIVERSAL-AGENTS.md)

Technique: Role definition as behavioral contract. Defines what an "agent" is in this context and what behaviors are universal vs pack-specific.

Not publicly readable without cloning, but architecture doc describes it as:

"Universal agent role definition — defines patterns that work for code, research, design, writing, PM"

Prompt 2: Task Discipline (core/docs/TASK-DISCIPLINE.md)

Technique: Constraint specification for task sizing. The architecture doc describes:

"Task sizing and structure — atomic, time-boxed, single-responsibility"

Prompt 3: Session Protocols (core/docs/SESSION-PROTOCOLS.md)

Technique: Procedural workflow spec with session state machine.

From README, the session protocol excerpt:

/resume loads context + recent session logs, supports topic search /preserve saves progress, auto-archives when CLAUDE.md exceeds 280 lines /compress saves searchable session logs before /compact No more re-explaining your project every time

Prompt 4: Verification Framework (core/docs/VERIFICATION-FRAMEWORK.md)

Technique: Observable completion contract.

From README:

"Every task has a verifiable completion signal" "Build passes, tests green, file exists, checklist done"

Note: The framework's actual SKILL.md content for its slash commands was not fetchable via raw URL (shell-based installer, not individual skill files in the standard .claude/ structure).

09

Uniqueness

SuperBeads Universal Framework — Uniqueness and Positioning

Differs from Seeds

Closest to agent-os (CLAUDE.md as primary session memory, scaffold-plus-CLI philosophy, Claude Code primary tool) but with four additions:

  1. Beads integration: agent-os has no task tracking. SuperBeads integrates Beads (bd + bv) for atomic task management with dependency graphs.
  2. superbeads CLI binary: agent-os ships 5 slash-commands that write markdown. SuperBeads ships a dedicated shell CLI plus 6 Claude Code slash-commands.
  3. Domain packs: 5 domain-specific extension packs (iOS, Python, Web, Design, PM) with domain-specific verification scripts. agent-os has no domain specialization.
  4. Verification gate: verify.sh must pass before commits. agent-os has no automated verification.

Also related to spec-driver (24 skills, session memory pattern) but SuperBeads uses explicit CLI + CLAUDE.md rather than autonomous skill activation.

Positioning

SuperBeads targets individual developers or small teams who want lightweight Beads task tracking, session memory, and atomic git discipline without the operational complexity of Gas Town. The "Universal" claim means it works for non-coding tasks (research, design, PM) — making it broader than most coding-specific frameworks.

Observable Failure Modes

  1. Shell installer fragility: The install script copies to ~/.superbeads/ — updates require re-cloning and re-running the installer.
  2. Beads dependency: Like Gas Town, requires the separate bd/bv CLIs from Steve Yegge's repo.
  3. 280-line CLAUDE.md limit: If the project is complex and the agent writes extensively to CLAUDE.md without running /preserve, context can get unwieldy before archival triggers.
  4. Pack coupling: Domain packs assume specific toolchains (Xcode, Node) — projects with mixed stacks may need custom pack.

Cross-References

  • Gas Town — more operationally complete Beads-based multi-agent system; SuperBeads is the single-agent lighter alternative
  • beads-ui — can be used alongside SuperBeads for visual board view
  • beads (steveyegge/beads) — underlying task tracking substrate
04

Workflow

SuperBeads Universal Framework — Workflow

Phases

Phase Trigger Artifact
1. Init superbeads init CLAUDE.md, .beads/, .superbeads/, verify.sh
2. Pack install (optional) superbeads pack install <name> Domain-specific scripts and agents in .superbeads/
3. Session start Claude Code opens project /resume loads CLAUDE.md + context
4. Task planning bd create "..." or natural language Bead in .beads/issues.jsonl
5. Task execution Claude Code works through tasks Code changes + git commits
6. Verification After each task verify.sh runs; must pass
7. Git commit After verification passes One commit per task: ✓ task-007: description
8. Session end /wrapup or /preserve Session log archived; CLAUDE.md updated

Approval Gates

Gate Type Mechanism
Verification Automated verify.sh must pass before commit
CLAUDE.md archival Threshold-based /preserve auto-triggers when >280 lines

Session Memory Lifecycle

New session → /resume → CLAUDE.md loaded into context
Work → git commits (one per task)
End session → /wrapup → session log saved
CLAUDE.md > 280 lines → /preserve → CLAUDE.md auto-archived → fresh CLAUDE.md
Pre-compact → /compress → searchable session log saved
06

Memory Context

SuperBeads Universal Framework — Memory and Context

State Storage

CLAUDE.md (session memory)

  • Location: CLAUDE.md in project root
  • Content: Project context, preferences, active tasks, session summaries
  • Persistence: project-scoped (git-tracked)
  • Lifecycle: loaded at session start via /resume; archived when >280 lines via /preserve

.beads/ (task state)

  • File: .beads/issues.jsonl (Beads JSONL format)
  • Content: Tasks/beads with status, dependencies, metadata
  • Persistence: project-scoped (git-tracked)
  • Managed by: bd CLI

.superbeads/ (sprint state)

  • Content: sprint plans, agent definitions (after pack install), settings
  • Persistence: project-scoped

Session Logs (archive)

  • Created by /compress (before /compact) and /wrapup (end of session)
  • Stored in .superbeads/ or project-local archive directory
  • Searchable via /resume <topic>

Context Compaction Handling

/compress explicitly saves session logs before Claude Code's /compact command. This is the pre-compact escape hatch to prevent context loss.

Cross-Session Handoff

/resume <topic> at session start re-injects CLAUDE.md + searches recent session logs for the specified topic. Provides continuity without re-explaining project state.

07

Orchestration

SuperBeads Universal Framework — Orchestration

No multi-agent orchestration. SuperBeads is a single-agent methodology framework.

  • Multi-agent: no
  • Orchestration pattern: sequential (one agent, one task at a time)
  • Isolation: none (in-place edits)
  • Execution mode: interactive-loop (human drives session; agent executes tasks)
  • Consensus: none
  • Multi-model: no

The core/docs/SUPERVISOR-MODEL.md document describes human oversight patterns — not multi-agent coordination. The "agents" in .superbeads/agents/ (after pack install) are agent persona definitions for Claude Code, not independent processes.

08

Ui Cli Surface

SuperBeads Universal Framework — UI and CLI Surface

CLI Binary

superbeads — shell script installed to PATH from ~/.superbeads/bin/

Key commands: init, pack install <name>, status, --version

Not a thin wrapper over claude/codex — it is its own shell script orchestrating initialization and pack installation.

Local TUI (via bv — installed automatically)

bv is the Beads Viewer TUI, installed by superbeads init. It provides:

  • Board view: task status board
  • Kanban view: workflow columns
  • Dependency graph: task relationship visualization
  • Insights dashboard: project health metrics

NOTE: bv (bare) launches interactive TUI — NOT safe for agent use. Agents must use --robot-* flags.

Screenshots

From README (docs/screenshots/):

  1. Session Start — /resume loads project context
  2. Project Status — superbeads status overview
  3. AI Recommendation — smart task prioritization
  4. Task Details — full task information
  5. Session End — /wrapup saves progress
  6. SuperBeads Board — interactive task viewer
  7. SuperBeads Kanban Board — visual workflow columns
  8. SuperBeads Dependency Graph — task relationships
  9. SuperBeads Insight Dashboard — project health metrics

No Local Web Dashboard

No web server. No browser UI. The bv TUI is terminal-only.

No MCP Servers

No MCP integration.

Related frameworks

same archetype · same primary tool · same memory type

BMAD-METHOD ★ 48k
A4 Markdown scaffold

Provides a full agile delivery lifecycle with named expert-persona AI collaborators that elicit the human's best thinking rather…

Agent OS ★ 4.6k
A4 Markdown scaffold

Extracts implicit codebase conventions into token-efficient markdown standards files and injects them selectively into AI agent…

Claude Conductor ★ 367
A4 Markdown scaffold

Gives Claude Code a persistent, cross-linked, auto-analyzed documentation system so it retains codebase context across sessions.

Spec-Driver (Greenfield Spec-Driven Development) ★ 25
A4 Markdown scaffold

Prevents spec rot in AI-assisted development by making implementation changes flow back into evergreen, authoritative specs via…

Anthropic Knowledge Work Plugins ★ 16k
A4 Markdown scaffold

Role-specialized plugin bundles with live MCP connectors that turn Claude into a domain expert for enterprise knowledge workers.

Codex Integration for Claude Code (skill-codex) ★ 1.3k
A4 Markdown scaffold

Single Claude Code skill that handles Codex CLI invocation correctly (stdin blocking, thinking token suppression, session resume)…