Clone the repository

<p align="center">
  <img src="https://img.shields.io/badge/Claude%20Code-Optimized-5A67D8?style=for-the-badge&logo=data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHZpZXdCb3g9IjAgMCAyNCAyNCI+PHBhdGggZmlsbD0id2hpdGUiIGQ9Ik0xMiAyQzYuNDggMiAyIDYuNDggMiAxMnM0LjQ4IDEwIDEwIDEwIDEwLTQuNDggMTAtMTBTMTcuNTIgMiAxMiAyem0wIDE4Yy00LjQxIDAtOC0zLjU5LTgtOHMzLjU5LTggOC04IDggMy41OSA4IDgtMy41OSA4LTggOHoiLz48L3N2Zz4=&logoColor=white" alt="Claude Code Optimized" />
  <img src="https://img.shields.io/badge/Version-1.1.0-green?style=for-the-badge" alt="Version 1.1.0" />
  <img src="https://img.shields.io/badge/Packs-5%20Available-blue?style=for-the-badge" alt="5 Packs Available" />
  <img src="https://img.shields.io/badge/License-MIT-yellow?style=for-the-badge" alt="MIT License" />
</p>

<h1 align="center">SuperBeads Universal Framework</h1>
<h3 align="center"><em>with Wiggum Flavour</em></h3>

<p align="center">
  <strong>A systematic methodology for Claude Code that transforms AI collaboration into structured, verifiable productivity.</strong>
</p>

<p align="center">
  <a href="#screenshots">Screenshots</a> •
  <a href="#installation">Installation</a> •
  <a href="#key-features">Features</a> •
  <a href="#quick-start">Quick Start</a> •
  <a href="#how-it-works">How It Works</a> •
  <a href="#domain-packs">Packs</a> •
  <a href="#faq">FAQ</a> •
  <a href="#credits">Credits</a>
</p>

---

## Screenshots

### Claude Code Integration

<table>
  <tr>
    <td align="center"><strong>Session Start</strong><br/><img src="docs/screenshots/1.Session_Start.png" width="400"/><br/><em>/resume loads project context</em></td>
    <td align="center"><strong>Project Status</strong><br/><img src="docs/screenshots/2.Project_Status.png" width="400"/><br/><em>superbeads status overview</em></td>
  </tr>
  <tr>
    <td align="center"><strong>AI Recommendation</strong><br/><img src="docs/screenshots/3.AI_recommendation.png" width="400"/><br/><em>Smart task prioritization</em></td>
    <td align="center"><strong>Task Details</strong><br/><img src="docs/screenshots/4.Task_Details.png" width="400"/><br/><em>Full task information</em></td>
  </tr>
  <tr>
    <td align="center" colspan="2"><strong>Session End</strong><br/><img src="docs/screenshots/5.Session_End.png" width="400"/><br/><em>/wrapup saves progress</em></td>
  </tr>
</table>

### Visual Task Board (TUI)

<table>
  <tr>
    <td align="center"><strong>Task Board</strong><br/><img src="docs/screenshots/6.SuperBeads_Board.png" width="400"/><br/><em>Interactive task viewer</em></td>
    <td align="center"><strong>Kanban View</strong><br/><img src="docs/screenshots/7.SuperBeads_Kanban_Board.png" width="400"/><br/><em>Visual workflow columns</em></td>
  </tr>
  <tr>
    <td align="center"><strong>Dependency Graph</strong><br/><img src="docs/screenshots/8.SuperBeads_Dependency_Graph.png" width="400"/><br/><em>Task relationships</em></td>
    <td align="center"><strong>Insights Dashboard</strong><br/><img src="docs/screenshots/9.SuperBeads_Insight_Dashboard.png" width="400"/><br/><em>Project health metrics</em></td>
  </tr>
</table>

---

## Installation

### Prerequisites

- Claude Code CLI
- Git (recommended for version control)
- Domain-specific tools as needed (Xcode, Node, Python, etc.)

### Step 1: Install the Framework

```bash
# Clone the repository
git clone https://github.com/EliaAlberti/superbeads-universal-framework.git
cd superbeads-universal-framework

# Run the installer (adds CLI to PATH automatically)
./core/scripts/install-superbeads.sh

# Restart your shell or run:
source ~/.zshrc  # or ~/.bashrc

# Verify installation
superbeads --version
```

The installer:
- Copies core files to `~/.superbeads/`
- Adds `superbeads` CLI to your PATH
- Works across all terminal sessions

### Step 2: Initialize Your Project

```bash
cd your-project

# Initialize (also installs task tracking tools)
superbeads init

# Optionally add a domain pack
superbeads pack install python  # Or: ios, web, design, pm
```

**Installed automatically during `superbeads init`:**
- Task tracking CLI (bd) - for task management
- Task board viewer (bv) - for visual project management TUI

### What Gets Created

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

### Mid-Project Adoption

SuperBeads is designed for mid-project adoption. The initialization is non-destructive-it only adds files and never modifies your existing code.

```bash
cd existing-project
superbeads init  # Safe to run anytime
```

---

## Key Features

### Session Memory
- **CLAUDE.md** persists project context across sessions
- `/resume` loads context 

... (truncated)