Ralph TUI - Beads erstellen (beads-rust)
Wandelt PRDs in Beads (Epic + untergeordnete Aufgaben) für die autonome Ausführung mit ralph-tui und beads-rust (br CLI) um.
Hinweis: Dieses Skill verwendet den
br-Befehl von beads-rust. Falls stattdessen das originale beads (bd) installiert ist, verwende das Skillralph-tui-create-beads.
Die Aufgabe
Nimm ein PRD (Markdown-Datei oder Text) und erstelle mit br-Befehlen Beads:
- Extrahiere Qualitätsgates aus dem Abschnitt "Qualitätsgates" des PRDs
- Erstelle ein Epic-Bead für die Funktion
- 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-rust
Schritt 1: Qualitätsgates extrahieren
Suche im PRD nach dem Abschnitt "Qualitätsgates":
## Qualitätsgates
Diese Befehle müssen für jede User Story erfolgreich sein:
- `pnpm typecheck` - Typprüfung
- `pnpm lint` - Linting
Für UI-Stories zusätzlich:
- Im Browser mit dem dev-browser-Skill überprüfen
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 erfolgreich sein sollen, oder verwende eine sinnvolle Voreinstellung wie npm run typecheck.
Ausgabeformat
Beads verwenden den Befehl br create mit HEREDOC-Syntax zur sicheren Handhabung von Sonderzeichen:
# Epic erstellen (Link zurück zum Quell-PRD)
br create --type=epic \
--title="[Funktionsname]" \
--description="$(cat <<'EOF'
[Funktionsbeschreibung aus dem PRD]
EOF
)" \
--external-ref="prd:./tasks/funktionsname-prd.md"
# Untergeordnetes Bead erstellen (mit Qualitätsgates in den Abnahmekriterien)
br create \
--parent=EPIC_ID \
--title="[Story-Titel]" \
--description="$(cat <<'EOF'
[Story-Beschreibung mit Abnahmekriterien INKLUSIVE Qualitätsgates]
EOF
)" \
--priority=[1-4]
KRITISCH: Verwende immer
<<'EOF'(einfach angeführt) für das HEREDOC-Trennzeichen. Dies verhindert die Shell-Interpretation von Backticks,$variablenund()in Beschreibungen.
Story-Größe: Die #1-Regel
Jede Story muss in EINER ralph-tui-iteration abschließbar sein (~ein Agenten-Kontextfenster).
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 sie fertig ist.
Richtig dimensionierte Stories:
- Eine Datenbankspalte + Migration hinzufügen
- Eine UI-Komponente zu einer bestehenden Seite hinzufügen
- Eine Server-Aktion 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, Sitzungsverwaltung
- "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 Reihenfolge ihrer Abhängigkeiten ausgeführt. Frühere Stories dürfen nicht von späteren abhängen.
Korrekte Reihenfolge:
- Schema-/Datenbankänderungen (Migrationen)
- Server-Aktionen / Backend-Logik
- UI-Komponenten, die das Backend nutzen
- Dashboard-/Übersichtsansichten, die Daten aggregieren
Falsche Reihenfolge:
- ❌ UI-Komponente (hängt von Schema ab, das noch nicht existiert)
- ❌ Schema-Änderung
Abhängigkeiten mit br dep add
Verwende den Befehl br dep add, um festzulegen, welche Beads zuerst abgeschlossen sein müssen:
# Beads zuerst erstellen
br create --parent=epic-123 --title="US-001: Schema hinzufügen" ...
br create --parent=epic-123 --title="US-002: API erstellen" ...
br create --parent=epic-123 --title="US-003: UI bauen" ...
# Dann Abhängigkeiten hinzufügen (issue hängt ab von blocker)
br dep add ralph-tui-002 ralph-tui-001 # US-002 hängt von US-001 ab
br dep add ralph-tui-003 ralph-tui-002 # US-003 hängt von US-002 ab
Syntax: br dep add <issue> <hängt-ab-von> — das issue hängt ab von (wird blockiert durch) hängt-ab-von.
ralph-tui wird:
- Blockierte Beads als "blockiert" anzeigen, bis die Abhängigkeiten abgeschlossen sind
- Niemals ein Bead zur Ausführung auswählen, während seine Abhängigkeiten offen sind
- Den Abhängigkeitskontext in den Prompt einbeziehen, wenn an einem Bead gearbeitet wird
Korrekte Abhängigkeitsreihenfolge:
- Schema-/Datenbankänderungen (keine Abhängigkeiten)
- Backend-Logik (hängt von Schema ab)
- UI-Komponenten (hängen vom Backend ab)
- Integration/Feinschliff (hängt von UI ab)
Abnahmekriterien: Qualitätsgates + Story-spezifisch
Die Beschreibung jedes Beads sollte Abnahmekriterien enthalten mit:
- Story-spezifischen Kriterien aus dem PRD (was diese Story erreicht)
- Qualitätsgates aus dem Abschnitt "Qualitätsgates" des PRDs (am Ende angehängt)
Gute Kriterien (überprüfbar):
- "Spalte
investorTypezur Investor-Tabelle mit Standardwert 'cold' hinzufügen" - "Filter-Dropdown hat Optionen: Alle, Cold, Friend"
- "Klicken des Umschalters zeigt Bestätigungsdialog"
Schlechte Kriterien (vage):
- ❌ "Funktioniert korrekt"
- ❌ "Benutzer kann X einfach tun"
- ❌ "Gute Benutzererfahrung"
- ❌ "Behandelt Randfälle"
Umwandlungsregeln
- Extrahiere Qualitätsgates zuerst aus dem PRD
- Jede User Story → ein Bead
- Erste Story: Keine Abhängigkeiten (schafft Grundlage)
- Nachfolgende 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" - Abnahmekriterien: Story-Kriterien + Qualitätsgates angehängt
- UI-Stories: Auch UI-spezifische Gates anhängen (Browser-Überprüfung)
Aufteilen großer PRDs
Wenn ein PRD große Funktionen hat, teile sie auf:
Original:
"Freunde-Akquise-Kampagne mit verschiedenen Nachrichten hinzufügen"
Aufgeteilt in:
- US-001: Feld investorType zur Datenbank hinzufügen
- US-002: Typ-Umschalter zur Investor-Listen-UI hinzufügen
- US-003: Freundesspezifische Phasenfortschrittslogik erstellen
- US-004: Freundesnachrichtenvorlagen erstellen
- US-005: Aufgabengenerierung für Freunde verdrahten
- US-006: Filter nach Typ hinzufügen
- US-007: Neues-Investor-Formular aktualisieren
- US-008: Dashboard-Zählungen aktualisieren
Jede Änderung ist ein fokussierter Schritt, der unabhängig abgeschlossen und überprüft werden kann.
Beispiel
Eingabe-PRD:
# PRD: Freunde-Akquise
Füge die Möglichkeit hinzu, Investoren als "Freunde" für die warme Akquise zu markieren.
## Qualitätsgates
Diese Befehle müssen für jede User Story erfolgreich sein:
- `pnpm typecheck` - Typprüfung
- `pnpm lint` - Linting
Für UI-Stories zusätzlich:
- Im Browser mit dem dev-browser-Skill überprüfen
## User Stories
### US-001: Feld investorType zur Investor-Tabelle hinzufügen
**Beschreibung:** Als Entwickler muss ich Investoren als 'cold' oder 'friend' kategorisieren können.
**Abnahmekriterien:**
- [ ] Spalte investorType hinzufügen: 'cold' | 'friend' (Standard 'cold')
- [ ] Migration generieren und erfolgreich ausführen
### US-002: Typ-Umschalter zu Investor-Listenzeilen hinzufügen
**Beschreibung:** Als Ryan möchte ich den Investorentyp direkt aus der Liste umschalten können.
**Abnahmekriterien:**
- [ ] Jede Zeile hat einen Cold | Friend-Umschalter
- [ ] Umschalten zeigt Bestätigungsdialog
- [ ] Bei Bestätigung: Typ in der Datenbank aktualisieren
### US-003: Investoren nach Typ filtern
**Beschreibung:** Als Ryan möchte ich die Liste filtern, um nur Freunde oder Kalte zu sehen.
**Abnahmekriterien:**
- [ ] Filter-Dropdown: Alle | Cold | Friend
- [ ] Filter bleibt in URL-Parametern erhalten
Ausgabe-Beads:
# Epic erstellen (Link zurück zum Quell-PRD)
br create --type=epic \
--title="Freunde-Akquise-Kampagne" \
--description="$(cat <<'EOF'
Warme Akquise für Deck-Feedback
EOF
)" \
--external-ref="prd:./tasks/freunde-akquise-prd.md"
# US-001: Keine Abhängigkeiten (erste - erstellt Schema)
br create --parent=ralph-tui-abc \
--title="US-001: Feld investorType zur Investor-Tabelle hinzufügen" \
--description="$(cat <<'EOF'
Als Entwickler muss ich Investoren als 'cold' oder 'friend' kategorisieren können.
## Abnahmekriterien
- [ ] Spalte investorType hinzufügen: 'cold' | 'friend' (Standard 'cold')
- [ ] Migration generieren und erfolgreich ausführen
- [ ] pnpm typecheck ist erfolgreich
- [ ] pnpm lint ist erfolgreich
EOF
)" \
--priority=1
# US-002: UI-Story (bekommt auch Browser-Überprüfung)
br create --parent=ralph-tui-abc \
--title="US-002: Typ-Umschalter zu Investor-Listenzeilen hinzufügen" \
--description="$(cat <<'EOF'
Als Ryan möchte ich den Investorentyp direkt aus der Liste umschalten können.
## Abnahmekriterien
- [ ] Jede Zeile hat einen Cold | Friend-Umschalter
- [ ] Umschalten zeigt Bestätigungsdialog
- [ ] Bei Bestätigung: Typ in der Datenbank aktualisieren
- [ ] pnpm typecheck ist erfolgreich
- [ ] pnpm lint ist erfolgreich
- [ ] Im Browser mit dem dev-browser-Skill überprüfen
EOF
)" \
--priority=2
# Abhängigkeit hinzufügen: US-002 hängt von US-001 ab
br dep add ralph-tui-002 ralph-tui-001
# US-003: UI-Story
br 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.
## Abnahmekriterien
- [ ] Filter-Dropdown: Alle | Cold | Friend
- [ ] Filter bleibt in URL-Parametern erhalten
- [ ] pnpm typecheck ist erfolgreich
- [ ] pnpm lint ist erfolgreich
- [ ] Im Browser mit dem dev-browser-Skill überprüfen
EOF
)" \
--priority=3
# Abhängigkeit hinzufügen: US-003 hängt von US-002 ab
br dep add ralph-tui-003 ralph-tui-002
Änderungen synchronisieren
Nach dem Erstellen der Beads synchronisieren, um nach JSONL zu exportieren (für Git-Versionierung):
br sync --flush-only
Dies exportiert die SQLite-Datenbank nach .beads/issues.jsonl für die Versionsverwaltung.
Ausgabeort
Beads werden gespeichert in: Verzeichnis .beads/ (SQLite-DB + JSONL-Export)
Nach der Erstellung ralph-tui ausführen:
# An einem bestimmten Epic arbeiten
ralph-tui run --tracker beads-rust --epic ralph-tui-abc
# Oder die beste Aufgabe automatisch auswählen lassen
ralph-tui run --tracker beads-rust
ralph-tui wird:
- An Beads innerhalb des angegebenen Epics arbeiten (oder die beste verfügbare Aufgabe auswählen)
- Jedes Bead bei Fertigstellung schließen
- Das Epic schließen, wenn alle untergeordneten Aufgaben erledigt sind
<promise>COMPLETE</promise>ausgeben, wenn das Epic fertig ist
Checkliste vor dem Erstellen von Beads
- Qualitätsgates aus 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 die Abnahmekriterien jedes Beads angehängt
- UI-Stories haben Browser-Überprüfung (falls in Qualitätsgates angegeben)
- Abnahmekriterien sind überprüfbar (nicht vage)
- Keine Story hängt von einer späteren Story ab (nur von früheren)
- Abhängigkeiten mit
br dep addnach dem Erstellen der Beads hinzugefügt -
br sync --flush-onlyausgeführt, um für Git-Versionierung zu exportieren
Unterschiede zu beads (Go-Version)
| Befehl | beads (bd) | beads-rust (br) |
|---|---|---|
| Erstellen | bd create | br create |
| Abhängigkeiten | bd dep add | br dep add |
| Synchronisieren | bd sync | br sync --flush-only |
| Schließen | bd close | br close |
| Speicher | .beads/beads.jsonl | .beads/*.db + JSONL-Export |