Was macht Ralph TUI - Beads erstellen?
Wandelt PRDs in Beads (Epic + Unteraufgaben) für die autonome Ausführung mit ralph-tui um.
Hinweis: Diese Fähigkeit ist im Beads-Tracker-Plugin von ralph-tui enthalten. Zukünftige Tracker-Plugins (Linear, GitHub Issues usw.) werden eigene Aufgabenerstellungsfähigkeiten mitbringen.
Die Aufgabe
Nimm ein PRD (Markdown-Datei oder Text) und erstelle Beads in .beads/beads.jsonl:
- Extrahiere Qualitätsgates aus dem Abschnitt „Qualitätsgates“ des PRD
- Erstelle ein Epic-Bead für das Feature
- Erstelle untergeordnete Beads für jede User Story (mit angehängten Qualitätsgates)
- Richte Abhängigkeiten zwischen den Beads ein (Schema → Backend → UI)
- Ausgabe bereit für
ralph-tui run --tracker beads
Schritt 1: Qualitätsgates extrahieren
Suche nach dem Abschnitt „Qualitätsgates“ im PRD:
## Qualitätsgates
Diese Befehle müssen für jede User Story bestehen:
- `pnpm typecheck` - Typprüfung
- `pnpm lint` - Linting
Für UI-Stories zusätzlich:
- Überprüfung im Browser mit der dev-browser-Fähigkeit
Extrahiere:
- Universelle Gates: Befehle, die für ALLE Stories gelten (z.B.
pnpm typecheck) - UI-Gates: Befehle, die nur für UI-Stories gelten (z.B. Browser-Überprüfung)
Falls kein Abschnitt „Qualitätsgates“ existiert: Frage den Benutzer, welche Befehle bestehen sollen, oder verwende eine sinnvolle Vorgabe wie npm run typecheck.
Ausgabeformat
Beads verwenden den bd create-Befehl mit HEREDOC-Syntax, um Sonderzeichen sicher zu handhaben:
# Epic erstellen (mit Verweis auf das Quell-PRD)
bd create --type=epic \
--title="[Feature-Name]" \
--description="$(cat <<'EOF'
[Feature-Beschreibung aus dem PRD]
EOF
)" \
--external-ref="prd:./tasks/feature-name-prd.md"
# Untergeordnetes Bead erstellen (mit Qualitätsgates in den Akzeptanzkriterien)
bd create \
--parent=EPIC_ID \
--title="[Story-Titel]" \
--description="$(cat <<'EOF'
[Story-Beschreibung mit Akzeptanzkriterien EINSCHLIESSLICH Qualitätsgates]
EOF
)" \
--priority=[1-4]
KRITISCH: Verwende immer
<<'EOF'(einfach quotiert) für den HEREDOC-Delimiter. Dies verhindert die Shell-Interpretation von Backticks,$variablenund()in Beschreibungen.
Story-Größe: Die #1-Regel
Jede Story muss in EINER ralph-tui-Iteration (~einem Agenten-Kontextfenster) abschließbar sein.
ralph-tui startet pro Iteration eine frische Agenteninstanz ohne Erinnerung an vorherige Arbeit. Wenn eine Story zu groß ist, geht dem Agenten der Kontext aus, bevor er fertig ist.
Richtig dimensionierte Stories:
- Datenbankspalte + Migration hinzufügen
- Ein UI-Element auf einer bestehenden Seite hinzufügen
- Eine Serveraktion mit neuer Logik aktualisieren
- Ein Filter-Dropdown zu einer Liste hinzufügen
Zu groß (diese aufteilen):
- „Das gesamte Dashboard bauen“ → Aufteilen in: Schema, Abfragen, UI-Komponenten, Filter
- „Authentifizierung hinzufügen“ → Aufteilen in: Schema, Middleware, Login-UI, Session-Handling
- „Die API umgestalten“ → Aufteilen in eine Story pro Endpunkt oder Muster
Faustregel: Wenn du die Änderung nicht in 2–3 Sätzen beschreiben kannst, ist sie zu groß.
Story-Reihenfolge: Abhängigkeiten zuerst
Stories werden in der Abhängigkeitsreihenfolge ausgeführt. Frühere Stories dürfen nicht von späteren abhängen.
Korrekte Reihenfolge:
- Schema-/Datenbankänderungen (Migrationen)
- Serveraktionen / Backend-Logik
- UI-Komponenten, die das Backend nutzen
- Dashboard-/Übersichtsansichten, die Daten aggregieren
Falsche Reihenfolge:
- ❌ UI-Komponente (abhängig von Schema, das noch nicht existiert)
- ❌ Schema-Änderung
Abhängigkeiten mit bd dep add
Verwende den Befehl bd dep add, um festzulegen, welche Beads zuerst abgeschlossen sein müssen:
# Zuerst die Beads erstellen
bd create --parent=epic-123 --title="US-001: Schema hinzufügen" ...
bd create --parent=epic-123 --title="US-002: API erstellen" ...
bd create --parent=epic-123 --title="US-003: UI bauen" ...
# Dann Abhängigkeiten hinzufügen (issue depends-on blocker)
bd dep add ralph-tui-002 ralph-tui-001 # US-002 hängt von US-001 ab
bd dep add ralph-tui-003 ralph-tui-002 # US-003 hängt von US-002 ab
Syntax: bd dep add <issue> <depends-on> — das Issue hängt ab von (wird blockiert durch) depends-on.
ralph-tui wird:
- Blockierte Beads als „blocked“ anzeigen, bis Abhängigkeiten abgeschlossen sind
- Nie ein Bead zur Ausführung auswählen, solange seine Abhängigkeiten offen sind
- Den Abhängigkeitskontext in die Eingabeaufforderung einbeziehen, wenn an einem Bead gearbeitet wird
Korrekte Abhängigkeitsreihenfolge:
- Schema-/Datenbankänderungen (keine Abhängigkeiten)
- Backend-Logik (abhängig von Schema)
- UI-Komponenten (abhängig von Backend)
- Integration/Verfeinerung (abhängig von UI)
Akzeptanzkriterien: Qualitätsgates + Story-spezifisch
Jede Bead-Beschreibung sollte Akzeptanzkriterien enthalten mit:
- Story-spezifischen Kriterien aus dem PRD (was diese Story erreicht)
- Qualitätsgates aus dem Abschnitt „Qualitätsgates“ des PRD (am Ende angehängt)
Gute Kriterien (überprüfbar):
- „Spalte
investorTypemit Standardwert 'cold' zur Investorentabelle hinzufügen“ - „Filter-Dropdown hat Optionen: Alle, Kalt, Freund“
- „Klick auf Umschalter zeigt Bestätigungsdialog“
Schlechte Kriterien (vage):
- ❌ „Funktioniert korrekt“
- ❌ „Benutzer kann X einfach tun“
- ❌ „Gute UX“
- ❌ „Behandelt Randfälle“
Konvertierungsregeln
- Extrahiere Qualitätsgates zuerst aus dem PRD
- Jede User Story → ein Bead
- Erste Story: Keine Abhängigkeiten (schafft Grundlage)
- Folge-Stories: Hängen von ihren Vorgängern ab (UI hängt vom Backend ab usw.)
- Priorität: Basierend auf Abhängigkeitsreihenfolge, dann Dokumentenreihenfolge (0=kritisch, 2=mittel, 4=Rückstand)
- Alle Stories:
status: "open" - Akzeptanzkriterien: Story-Kriterien + Qualitätsgates angehängt
- UI-Stories: Zusätzlich UI-spezifische Gates anhängen (Browser-Überprüfung)
Große PRDs aufteilen
Wenn ein PRD große Features enthält, teile sie auf:
Original:
„Freunde-Kontakt-Track mit unterschiedlichen Nachrichten hinzufügen“
Aufgeteilt in:
- US-001: investorType-Feld zur Datenbank hinzufügen
- US-002: Typ-Umschalter zur Investorenlisten-UI hinzufügen
- US-003: Freund-spezifische Phasenfortschrittslogik erstellen
- US-004: Freund-Nachrichtenvorlagen erstellen
- US-005: Aufgabengenerierung für Freunde verdrahten
- US-006: Filter nach Typ hinzufügen
- US-007: Neues Investorenformular aktualisieren
- US-008: Dashboard-Zählungen aktualisieren
Jeder Eintrag ist eine fokussierte Änderung, die unabhängig abgeschlossen und überprüft werden kann.
Beispiel
Eingabe-PRD:
# PRD: Freunde-Kontaktaufnahme
Möglichkeit, Investoren als „Freunde“ für warme Kontaktaufnahme zu markieren.
## Qualitätsgates
Diese Befehle müssen für jede User Story bestehen:
- `pnpm typecheck` - Typprüfung
- `pnpm lint` - Linting
Für UI-Stories zusätzlich:
- Überprüfung im Browser mit der dev-browser-Fähigkeit
## User Stories
### US-001: investorType-Feld zur Investorentabelle hinzufügen
**Beschreibung:** Als Entwickler muss ich Investoren als 'cold' oder 'friend' kategorisieren können.
**Akzeptanzkriterien:**
- [ ] Spalte investorType hinzufügen: 'cold' | 'friend' (Standard 'cold')
- [ ] Migration erstellen und erfolgreich ausführen
### US-002: Typ-Umschalter zu Investorenlisten-Zeilen hinzufügen
**Beschreibung:** Als Ryan möchte ich den Investorentyp direkt aus der Liste umschalten können.
**Akzeptanzkriterien:**
- [ ] Jede Zeile hat einen Cold | Friend-Umschalter
- [ ] Umschalten zeigt Bestätigungsdialog
- [ ] Bei Bestätigung: Typ in Datenbank aktualisieren
### US-003: Investoren nach Typ filtern
**Beschreibung:** Als Ryan möchte ich die Liste filtern, um nur Freunde oder Kalte zu sehen.
**Akzeptanzkriterien:**
- [ ] Filter-Dropdown: Alle | Kalt | Freund
- [ ] Filter bleibt in URL-Parametern erhalten
Ausgabe-Beads:
# Epic erstellen (mit Verweis auf das Quell-PRD)
bd create --type=epic \
--title="Freunde-Kontakt-Track" \
--description="$(cat <<'EOF'
Warme Kontaktaufnahme für Deck-Feedback
EOF
)" \
--external-ref="prd:./tasks/freunde-kontaktaufnahme-prd.md"
# US-001: Keine Abhängigkeiten (erste - erstellt Schema)
bd create --parent=ralph-tui-abc \
--title="US-001: investorType-Feld zur Investorentabelle hinzufügen" \
--description="$(cat <<'EOF'
Als Entwickler muss ich Investoren als 'cold' oder 'friend' kategorisieren können.
## Akzeptanzkriterien
- [ ] Spalte investorType hinzufügen: 'cold' | 'friend' (Standard 'cold')
- [ ] Migration erstellen und erfolgreich ausführen
- [ ] pnpm typecheck besteht
- [ ] pnpm lint besteht
EOF
)" \
--priority=1
# US-002: UI-Story (erhält auch Browser-Überprüfung)
bd create --parent=ralph-tui-abc \
--title="US-002: Typ-Umschalter zu Investorenlisten-Zeilen hinzufügen" \
--description="$(cat <<'EOF'
Als Ryan möchte ich den Investorentyp direkt aus der Liste umschalten können.
## Akzeptanzkriterien
- [ ] Jede Zeile hat einen Cold | Friend-Umschalter
- [ ] Umschalten zeigt Bestätigungsdialog
- [ ] Bei Bestätigung: Typ in Datenbank aktualisieren
- [ ] pnpm typecheck besteht
- [ ] pnpm lint besteht
- [ ] Überprüfung im Browser mit der dev-browser-Fähigkeit
EOF
)" \
--priority=2
# Abhängigkeit hinzufügen: US-002 hängt von US-001 ab
bd dep add ralph-tui-002 ralph-tui-001
# US-003: UI-Story
bd create --parent=ralph-tui-abc \
--title="US-003: Investoren nach Typ filtern" \
--description="$(cat <<'EOF'
Als Ryan möchte ich die Liste filtern, um nur Freunde oder Kalte zu sehen.
## Akzeptanzkriterien
- [ ] Filter-Dropdown: Alle | Kalt | Freund
- [ ] Filter bleibt in URL-Parametern erhalten
- [ ] pnpm typecheck besteht
- [ ] pnpm lint besteht
- [ ] Überprüfung im Browser mit der dev-browser-Fähigkeit
EOF
)" \
--priority=3
# Abhängigkeit hinzufügen: US-003 hängt von US-002 ab
bd dep add ralph-tui-003 ralph-tui-002
Ausgabeort
Beads werden geschrieben nach: .beads/beads.jsonl
Nach der Erstellung ralph-tui ausführen:
# An einem bestimmten Epic arbeiten
ralph-tui run --tracker beads --epic ralph-tui-abc
# Oder die beste Aufgabe automatisch auswählen lassen
ralph-tui run --tracker beads
ralph-tui wird:
- An Beads innerhalb des angegebenen Epics arbeiten (oder die beste verfügbare Aufgabe auswählen)
- Jedes Bead schließen, wenn es abgeschlossen ist
- Das Epic schließen, wenn alle untergeordneten Aufgaben erledigt sind
<promise>COMPLETE</promise>ausgeben, wenn das Epic abgeschlossen ist
Checkliste vor dem Erstellen der Beads
- Qualitätsgates aus dem PRD extrahiert (oder Benutzer gefragt, falls fehlend)
- Jede Story ist in einer Iteration abschließbar (klein genug)
- Stories sind nach Abhängigkeit geordnet (Schema → Backend → UI)
- Qualitätsgates an jedes Bead-Akzeptanzkriterium angehängt
- UI-Stories haben Browser-Überprüfung (falls in Qualitätsgates angegeben)
- Akzeptanzkriterien sind überprüfbar (nicht vage)
- Keine Story hängt von einer späteren Story ab (nur von früheren)
- Abhängigkeiten mit
bd dep addnach dem Erstellen der Beads hinzugefügt