Ralph TUI - Créer des Beads (beads-rust)
Convertit les PRD en beads (epic + tâches enfants) pour une exécution autonome avec ralph-tui en utilisant beads-rust (CLI br).
Remarque : Cette compétence utilise la commande
brde beads-rust. Si vous avez installé la version originale de beads (bd), utilisez plutôt la compétenceralph-tui-create-beads.
Le Travail
Prenez un PRD (fichier markdown ou texte) et créez des beads à l'aide des commandes br :
- Extraire les Quality Gates de la section "Quality Gates" du PRD
- Créer un bead epic pour la fonctionnalité
- Créer des beads enfants pour chaque user story (avec les quality gates ajoutées)
- Configurer les dépendances entre les beads (schéma → backend → UI)
- Produire une sortie prête pour
ralph-tui run --tracker beads-rust
Étape 1 : Extraire les Quality Gates
Cherchez la section "Quality Gates" dans le PRD :
## Quality Gates
Ces commandes doivent réussir pour chaque user story :
- `pnpm typecheck` - Vérification de typage
- `pnpm lint` - Analyse statique
Pour les stories UI, incluez également :
- Vérifier dans le navigateur en utilisant la compétence dev-browser
Extrayez :
- Gates universels : Commandes qui s'appliquent à TOUTES les stories (ex.
pnpm typecheck) - Gates UI : Commandes qui s'appliquent uniquement aux stories UI (ex. vérification navigateur)
Si aucune section Quality Gates n'existe : Demandez à l'utilisateur quelles commandes doivent réussir, ou utilisez une valeur par défaut raisonnable comme npm run typecheck.
Format de Sortie
Les beads utilisent la commande br create avec la syntaxe HEREDOC pour gérer en toute sécurité les caractères spéciaux :
# Créer un epic (lien vers le PRD source)
br create --type=epic \
--title="[Nom de la fonctionnalité]" \
--description="$(cat <<'EOF'
[Description de la fonctionnalité depuis le PRD]
EOF
)" \
--external-ref="prd:./tasks/feature-name-prd.md"
# Créer un bead enfant (avec quality gates dans les critères d'acceptation)
br create \
--parent=EPIC_ID \
--title="[Titre de la story]" \
--description="$(cat <<'EOF'
[Description de la story avec critères d'acceptation INCLUANT les quality gates]
EOF
)" \
--priority=[1-4]
CRITIQUE : Utilisez toujours
<<'EOF'(avec guillemets simples) pour le délimiteur HEREDOC. Cela empêche l'interprétation par le shell des backticks,$variableset()dans les descriptions.
Taille des Stories : La Règle n°1
Chaque story doit pouvoir être terminée en UNE itération de ralph-tui (~une fenêtre de contexte de l'agent).
ralph-tui crée une nouvelle instance d'agent par itération, sans mémoire des travaux précédents. Si une story est trop grande, l'agent épuise son contexte avant de terminer.
Stories de bonne taille :
- Ajouter une colonne de base de données + migration
- Ajouter un composant UI à une page existante
- Mettre à jour une action serveur avec une nouvelle logique
- Ajouter un menu déroulant de filtre à une liste
Trop grandes (à diviser) :
- "Construire le tableau de bord complet" → Diviser en : schéma, requêtes, composants UI, filtres
- "Ajouter l'authentification" → Diviser en : schéma, middleware, UI de connexion, gestion des sessions
- "Refactorer l'API" → Diviser en une story par point d'accès ou motif
Règle empirique : Si vous ne pouvez pas décrire le changement en 2-3 phrases, c'est trop grand.
Ordre des Stories : D'abord les Dépendances
Les stories s'exécutent dans l'ordre des dépendances. Les stories antérieures ne doivent pas dépendre de stories ultérieures.
Ordre correct :
- Changements de schéma/base de données (migrations)
- Actions serveur / logique backend
- Composants UI qui utilisent le backend
- Vues de tableau de bord/récapitulatives qui agrègent les données
Ordre incorrect :
- ❌ Composant UI (dépend du schéma qui n'existe pas encore)
- ❌ Changement de schéma
Dépendances avec br dep add
Utilisez la commande br dep add pour spécifier quels beads doivent se terminer en premier :
# Créer d'abord les beads
br create --parent=epic-123 --title="US-001 : Ajouter le schéma" ...
br create --parent=epic-123 --title="US-002 : Créer l'API" ...
br create --parent=epic-123 --title="US-003 : Construire l'UI" ...
# Puis ajouter les dépendances (issue dépend-de bloqueur)
br dep add ralph-tui-002 ralph-tui-001 # US-002 dépend de US-001
br dep add ralph-tui-003 ralph-tui-002 # US-003 dépend de US-002
Syntaxe : br dep add <issue> <dépend-de> — l'issue dépend de (est bloquée par) dépend-de.
ralph-tui va :
- Afficher les beads bloqués comme "bloqués" jusqu'à ce que les dépendances soient terminées
- Ne jamais sélectionner un bead pour exécution tant que ses dépendances sont ouvertes
- Inclure le contexte de dépendance dans l'invite lorsqu'il travaille sur un bead
Ordre correct des dépendances :
- Changements de schéma/base de données (aucune dépendance)
- Logique backend (dépend du schéma)
- Composants UI (dépendent du backend)
- Intégration/polissage (dépend de l'UI)
Critères d'Acceptation : Quality Gates + Spécifiques à la Story
La description de chaque bead doit inclure les critères d'acceptation avec :
- Critères spécifiques à la story du PRD (ce que cette story accomplit)
- Quality gates de la section "Quality Gates" du PRD (ajoutés à la fin)
Bons critères (vérifiables) :
- "Ajouter la colonne
investorTypeà la table investor avec la valeur par défaut 'cold'" - "Le menu déroulant de filtre propose les options : Tous, Cold, Friend"
- "Cliquer sur le bouton bascule affiche une boîte de dialogue de confirmation"
Mauvais critères (vagues) :
- ❌ "Fonctionne correctement"
- ❌ "L'utilisateur peut faire X facilement"
- ❌ "Bonne UX"
- ❌ "Gère les cas limites"
Règles de Conversion
- Extraire les Quality Gates du PRD d'abord
- Chaque user story → un bead
- Première story : Aucune dépendance (crée la fondation)
- Stories suivantes : Dépendent de leurs prédécesseurs (UI dépend du backend, etc.)
- Priorité : Basée sur l'ordre des dépendances, puis l'ordre du document (0=critique, 2=moyen, 4=backlog)
- Toutes les stories :
status: "open" - Critères d'acceptation : Critères de la story + quality gates ajoutés
- Stories UI : Ajoutent également les gates spécifiques à l'UI (vérification navigateur)
Division des Gros PRD
Si un PRD contient de grandes fonctionnalités, divisez-les :
Original :
"Ajouter un volet de prospection des amis avec différents messages"
Divisé en :
- US-001 : Ajouter le champ investorType à la base de données
- US-002 : Ajouter le bouton bascule de type à la liste des investisseurs
- US-003 : Créer la logique de progression de phase spécifique aux amis
- US-004 : Créer les modèles de messages pour les amis
- US-005 : Câbler la génération de tâches pour les amis
- US-006 : Ajouter un filtre par type
- US-007 : Mettre à jour le formulaire de nouvel investisseur
- US-008 : Mettre à jour les compteurs du tableau de bord
Chacun est un changement ciblé qui peut être complété et vérifié indépendamment.
Exemple
PRD d'entrée :
# PRD : Prospection des amis
Ajouter la possibilité de marquer les investisseurs comme "amis" pour une prospection chaleureuse.
## Quality Gates
Ces commandes doivent réussir pour chaque user story :
- `pnpm typecheck` - Vérification de typage
- `pnpm lint` - Analyse statique
Pour les stories UI, incluez également :
- Vérifier dans le navigateur en utilisant la compétence dev-browser
## User Stories
### US-001 : Ajouter le champ investorType à la table investor
**Description :** En tant que développeur, j'ai besoin de catégoriser les investisseurs comme 'cold' ou 'friend'.
**Critères d'acceptation :**
- [ ] Ajouter la colonne investorType : 'cold' | 'friend' (par défaut 'cold')
- [ ] Générer et exécuter la migration avec succès
### US-002 : Ajouter le bouton bascule de type aux lignes de la liste des investisseurs
**Description :** En tant que Ryan, je veux basculer le type d'investisseur directement depuis la liste.
**Critères d'acceptation :**
- [ ] Chaque ligne a un bouton bascule Cold | Friend
- [ ] Le changement affiche une boîte de dialogue de confirmation
- [ ] Sur confirmation : met à jour le type dans la base de données
### US-003 : Filtrer les investisseurs par type
**Description :** En tant que Ryan, je veux filtrer la liste pour voir uniquement les amis ou les froids.
**Critères d'acceptation :**
- [ ] Menu déroulant de filtre : Tous | Cold | Friend
- [ ] Le filtre persiste dans les paramètres d'URL
Beads de sortie :
# Créer l'epic (lien vers le PRD source)
br create --type=epic \
--title="Volet de prospection des amis" \
--description="$(cat <<'EOF'
Prospection chaleureuse pour les retours sur deck
EOF
)" \
--external-ref="prd:./tasks/friends-outreach-prd.md"
# US-001 : Aucune dépendance (première - crée le schéma)
br create --parent=ralph-tui-abc \
--title="US-001 : Ajouter le champ investorType à la table investor" \
--description="$(cat <<'EOF'
En tant que développeur, j'ai besoin de catégoriser les investisseurs comme 'cold' ou 'friend'.
## Critères d'acceptation
- [ ] Ajouter la colonne investorType : 'cold' | 'friend' (par défaut 'cold')
- [ ] Générer et exécuter la migration avec succès
- [ ] pnpm typecheck réussit
- [ ] pnpm lint réussit
EOF
)" \
--priority=1
# US-002 : Story UI (reçoit également la vérification navigateur)
br create --parent=ralph-tui-abc \
--title="US-002 : Ajouter le bouton bascule de type aux lignes de la liste" \
--description="$(cat <<'EOF'
En tant que Ryan, je veux basculer le type d'investisseur directement depuis la liste.
## Critères d'acceptation
- [ ] Chaque ligne a un bouton bascule Cold | Friend
- [ ] Le changement affiche une boîte de dialogue de confirmation
- [ ] Sur confirmation : met à jour le type dans la base de données
- [ ] pnpm typecheck réussit
- [ ] pnpm lint réussit
- [ ] Vérifier dans le navigateur en utilisant la compétence dev-browser
EOF
)" \
--priority=2
# Ajouter la dépendance : US-002 dépend de US-001
br dep add ralph-tui-002 ralph-tui-001
# US-003 : Story UI
br create --parent=ralph-tui-abc \
--title="US-003 : Filtrer les investisseurs par type" \
--description="$(cat <<'EOF'
En tant que Ryan, je veux filtrer la liste pour voir uniquement les amis ou les froids.
## Critères d'acceptation
- [ ] Menu déroulant de filtre : Tous | Cold | Friend
- [ ] Le filtre persiste dans les paramètres d'URL
- [ ] pnpm typecheck réussit
- [ ] pnpm lint réussit
- [ ] Vérifier dans le navigateur en utilisant la compétence dev-browser
EOF
)" \
--priority=3
# Ajouter la dépendance : US-003 dépend de US-002
br dep add ralph-tui-003 ralph-tui-002
Synchronisation des Changements
Après avoir créé les beads, synchronisez pour exporter au format JSONL (pour le suivi git) :
br sync --flush-only
Ceci exporte la base de données SQLite vers .beads/issues.jsonl pour le contrôle de version.
Emplacement de Sortie
Les beads sont stockés dans le répertoire : .beads/ (base de données SQLite + export JSONL)
Après la création, exécutez ralph-tui :
# Travailler sur un epic spécifique
ralph-tui run --tracker beads-rust --epic ralph-tui-abc
# Ou le laisser choisir automatiquement la meilleure tâche
ralph-tui run --tracker beads-rust
ralph-tui va :
- Travailler sur les beads dans l'epic spécifié (ou sélectionner la meilleure tâche disponible)
- Fermer chaque bead une fois terminé
- Fermer l'epic lorsque tous les enfants sont terminés
- Afficher
<promise>COMPLETE</promise>lorsque l'epic est terminé
Liste de Vérification Avant de Créer les Beads
- Quality Gates extraits du PRD (ou demandé à l'utilisateur si manquant)
- Chaque story peut être terminée en une itération (assez petite)
- Les stories sont ordonnées par dépendance (schéma → backend → UI)
- Quality gates ajoutés aux critères d'acceptation de chaque bead
- Les stories UI ont une vérification navigateur (si spécifié dans les Quality Gates)
- Les critères d'acceptation sont vérifiables (pas vagues)
- Aucune story ne dépend d'une story ultérieure (uniquement des stories antérieures)
- Dépendances ajoutées avec
br dep addaprès la création des beads -
br sync --flush-onlyexécuté pour exporter pour le suivi git
Différences avec beads (version Go)
| Commande | beads (bd) | beads-rust (br) |
|---|---|---|
| Créer | bd create | br create |
| Dépendances | bd dep add | br dep add |
| Synchroniser | bd sync | br sync --flush-only |
| Fermer | bd close | br close |
| Stockage | .beads/beads.jsonl | .beads/*.db + export JSONL |