Grundlegende Konzepte

Workspace

Ein Workspace ist ein Projektverzeichnis, das einen .beads/-Ordner enthaelt. Das Datenbank-Backend kann SQLite (veraltet) oder Dolt sein. Jeder Workspace verwaltet seinen eigenen Satz an Issues, unabhaengig von anderen Projekten.

Beadbox erkennt Workspaces aus der Registry unter ~/.beadbox/registry.json, einem Cookie, das deinen letzten aktiven Workspace verfolgt, und durch Scannen des aktuellen Arbeitsverzeichnisses nach .beads/-Ordnern. Wechsle zwischen Workspaces mit dem Selektor in der Kopfzeile.

Im eingebetteten Modus bleiben alle Daten lokal, ohne Abhaengigkeit von Konten oder der Cloud. Ein Workspace kann sich optional mit einem entfernten Dolt-Server fuer Mehrbenutzerzugriff verbinden, was Push- und Pull-Synchronisation ermoeglicht.

Bead

Ein Bead ist die grundlegende Arbeitseinheit: ein Issue, eine Aufgabe oder ein Ticket. Jeder Bead hat:

• Eine eindeutige ID (z. B. bb-a3f2), zugewiesen vom bd CLI, bestehend aus einem Workspace-Praefix und einem base32-kodierten Suffix
• Einen Titel und eine optionale Beschreibung (Markdown wird unterstützt)
• Status: open, in_progress, blocked, deferred, ready_for_qa, qa_passed, ready_to_ship oder closed
• Priorität: P0 (kritisch) bis P4 (Backlog)
• Typ: task, bug, feature, epic, chore oder decision (Kerntypen). Benutzerdefinierte Typen wie molecule und gate koennen pro Workspace konfiguriert werden.
• Einen optionalen Zuständigen

Erstelle Beads mit bd create und sieh sie dir mit bd show an. In Beadbox klickst du auf einen beliebigen Bead im Baum, um seinen Detailbereich zu öffnen.

Epic

Ein Epic ist ein Bead mit Untereinträgen. Er bündelt zusammengehörige Arbeit und verfolgt den Gesamtfortschritt. In der Baumansicht zeigen Epics einen Fortschrittsbalken, der auf der Anzahl geschlossener Untereinträge basiert.

Erstelle einen Untereintrag mit --parent:

bd create --title="Subtask" --type=task --parent=EPIC-ID

Epics können verschachtelt werden. Ein Untereintrag eines Epics kann selbst ein Epic mit eigenen Untereinträgen sein. Die Baumansicht stellt diese Hierarchie mit Auf-/Zuklapp-Steuerelementen dar.

Abhängigkeit

Ein Bead kann andere Beads blockieren. Wenn Bead A Bead B blockiert, kann B nicht fortgesetzt werden, bis A geschlossen ist. Abhängigkeiten erscheinen als Blocker-Badges in der Baumansicht und als Abhängigkeitsliste im Detailbereich.

Setze eine Abhaengigkeit mit bd dep:

bd dep BEAD-A --blocks BEAD-B

Beadbox zeichnet den Abhängigkeitsgraphen, damit du auf einen Blick siehst, welche Beads den Fortschritt blockieren.

Kommentar

Jeder Bead hat einen Kommentar-Thread. Kommentare sind die Art, wie Agents und Menschen über einen Bead kommunizieren: Pläne vor der Implementierung posten, Fertigstellung melden, Blocker markieren und QA-Verifizierungsschritte bereitstellen.

Füge einen Kommentar über das CLI hinzu:

bd comments add BEAD-ID --author agent-name "PLAN: ..."
bd comments add BEAD-ID --author agent-name "DONE: ..."

In Beadbox werden Kommentare als Markdown im Detailbereich gerendert, chronologisch sortiert.

Status-Lebenszyklus

Jeder Bead durchläuft diesen Lebenszyklus:

Jeder Status hat ein eigenes Farb-Badge in Beadbox. Die Filterleiste lässt dich Beads nach Status ein- oder ausblenden. Das Aktivitäts-Dashboard gruppiert Beads nach Pipeline-Stufe anhand dieser Status.