Ralph TUI - Créer des Perles (Beads)
Convertit les PRD en perles (épopée + tâches enfants) pour exécution autonome via ralph-tui.
Remarque : Cette compétence est fournie avec le plugin Beads Tracker de ralph-tui. Les futurs plugins de suivi (Linear, GitHub Issues, etc.) incluront leurs propres compétences de création de tâches.
Le Travail
Prendre un PRD (fichier markdown ou texte) et créer des perles dans .beads/beads.jsonl :
- Extraire les Quality Gates de la section "Quality Gates" du PRD
- Créer une perle épopée pour la fonctionnalité
- Créer des perles enfants pour chaque user story (avec les Quality Gates ajoutées)
- Configurer les dépendances entre les perles (schéma → backend → UI)
- Produire un résultat prêt pour
ralph-tui run --tracker beads
Étape 1 : Extraire les Quality Gates
Recherchez la section "Quality Gates" dans le PRD :
## Quality Gates
Ces commandes doivent fonctionner pour chaque user story :
- `pnpm typecheck` - Vérification des types
- `pnpm lint` - Linting
Pour les histoires UI, inclure également :
- Vérifier dans le navigateur avec la compétence dev-browser
Extrayez :
- Gates universels : Commandes qui s'appliquent à TOUTES les histoires (p. ex.,
pnpm typecheck) - Gates UI : Commandes qui s'appliquent uniquement aux histoires UI (p. ex., vérification dans le navigateur)
Si aucune section Quality Gates n'existe : Demandez à l'utilisateur quelles commandes doivent fonctionner, ou utilisez une valeur par défaut raisonnable comme npm run typecheck.
Format de Sortie
Les perles utilisent la commande bd create avec la syntaxe HEREDOC pour gérer en toute sécurité les caractères spéciaux :
# Créer l'épopée (lien vers le PRD source)
bd create --type=epic \
--title="[Nom de la fonctionnalité]" \
--description="$(cat <<'EOF'
[Description de la fonctionnalité du PRD]
EOF
)" \
--external-ref="prd:./tasks/nom-fonctionnalite-prd.md"
# Créer une perle enfant (avec Quality Gates dans les critères d'acceptation)
bd create \
--parent=EPIC_ID \
--title="[Titre de l'histoire]" \
--description="$(cat <<'EOF'
[Description de l'histoire 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, des$variableset des()dans les descriptions.
Taille des Histoires : La Règle #1
Chaque histoire doit pouvoir être réalisée en UNE itération de ralph-tui (~une fenêtre de contexte de l'agent).
ralph-tui lance une nouvelle instance d'agent par itération sans mémoire du travail précédent. Si une histoire est trop grande, l'agent manque de contexte avant de terminer.
Histoires de taille adaptée :
- Ajouter une colonne à une base de données + migration
- Ajouter un composant UI à une page existante
- Mettre à jour une action serveur avec une nouvelle logique
- Ajouter une liste déroulante 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
- "Refactoriser l'API" → Diviser en une histoire par endpoint ou par motif
Règle empirique : Si vous ne pouvez pas décrire le changement en 2-3 phrases, c'est trop grand.
Ordre des Histoires : D'abord les Dépendances
Les histoires s'exécutent dans l'ordre des dépendances. Les histoires précédentes ne doivent pas dépendre des suivantes.
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ésumé qui agrègent les données
Ordre incorrect :
- ❌ Composant UI (dépend d'un schéma qui n'existe pas encore)
- ❌ Changement de schéma
Dépendances avec bd dep add
Utilisez la commande bd dep add pour spécifier quelles perles doivent être terminées en premier :
# Créer d'abord les perles
bd create --parent=epic-123 --title="US-001 : Ajouter le schéma" ...
bd create --parent=epic-123 --title="US-002 : Créer l'API" ...
bd create --parent=epic-123 --title="US-003 : Construire l'UI" ...
# Ajouter ensuite les dépendances (le problème dépend du bloqueur)
bd dep add ralph-tui-002 ralph-tui-001 # US-002 dépend de US-001
bd dep add ralph-tui-003 ralph-tui-002 # US-003 dépend de US-002
Syntaxe : bd dep add <problème> <dépend_de> — le problème dépend de (est bloqué par) dépend_de.
ralph-tui va :
- Afficher les perles bloquées comme "bloquées" jusqu'à ce que les dépendances soient terminées
- Ne jamais sélectionner une perle pour exécution tant que ses dépendances sont ouvertes
- Inclure le contexte de dépendance dans l'invite lorsqu'il travaille sur une perle
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épend du backend)
- Intégration/polissage (dépend de l'UI)
Critères d'Acceptation : Quality Gates + Spécifiques à l'Histoire
La description de chaque perle doit inclure les critères d'acceptation avec :
- Critères spécifiques à l'histoire du PRD (ce que cette histoire 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 une valeur par défaut 'cold'" - "La liste déroulante de filtre a les options : Tout, Froid, Ami"
- "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 → une perle
- Première histoire : Aucune dépendance (crée la fondation)
- Histoires 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 histoires :
status: "open" - Critères d'acceptation : Critères de l'histoire + Quality Gates ajoutées
- Histoires UI : Ajouter également les gates spécifiques à l'UI (vérification dans le navigateur)
Division des Gros PRD
Si un PRD contient de grandes fonctionnalités, divisez-les :
Original :
"Ajouter un suivi de sensibilisation des amis avec différents messages"
Divisé en :
- US-001 : Ajouter le champ investorType à la base de données
- US-002 : Ajouter un bouton bascule de type à la liste des investisseurs UI
- 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 réalisé et vérifié indépendamment.
Exemple
PRD d'entrée :
# PRD : Sensibilisation des Amis
Ajouter la possibilité de marquer les investisseurs comme "amis" pour une sensibilisation chaleureuse.
## Quality Gates
Ces commandes doivent fonctionner pour chaque user story :
- `pnpm typecheck` - Vérification des types
- `pnpm lint` - Linting
Pour les histoires UI, inclure également :
- Vérifier dans le navigateur avec 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' (valeur par défaut 'cold')
- [ ] Générer et exécuter la migration avec succès
### US-002 : Ajouter un 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 Froid | Ami
- [ ] Le basculement 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 :**
- [ ] Liste déroulante de filtre : Tout | Froid | Ami
- [ ] Le filtre persiste dans les paramètres d'URL
Perles de sortie :
# Créer l'épopée (lien vers le PRD source)
bd create --type=epic \
--title="Suivi de Sensibilisation des Amis" \
--description="$(cat <<'EOF'
Sensibilisation chaleureuse pour les retours sur le deck
EOF
)" \
--external-ref="prd:./tasks/amis-sensibilisation-prd.md"
# US-001 : Aucune dépendance (première - crée le schéma)
bd 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' (valeur par défaut 'cold')
- [ ] Générer et exécuter la migration avec succès
- [ ] pnpm typecheck fonctionne
- [ ] pnpm lint fonctionne
EOF
)" \
--priority=1
# US-002 : Histoire UI (obtient également la vérification navigateur)
bd create --parent=ralph-tui-abc \
--title="US-002 : Ajouter un bouton bascule de type aux lignes de la liste des investisseurs" \
--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 Froid | Ami
- [ ] Le basculement affiche une boîte de dialogue de confirmation
- [ ] Sur confirmation : met à jour le type dans la base de données
- [ ] pnpm typecheck fonctionne
- [ ] pnpm lint fonctionne
- [ ] Vérifier dans le navigateur avec la compétence dev-browser
EOF
)" \
--priority=2
# Ajouter la dépendance : US-002 dépend de US-001
bd dep add ralph-tui-002 ralph-tui-001
# US-003 : Histoire UI
bd 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
- [ ] Liste déroulante de filtre : Tout | Froid | Ami
- [ ] Le filtre persiste dans les paramètres d'URL
- [ ] pnpm typecheck fonctionne
- [ ] pnpm lint fonctionne
- [ ] Vérifier dans le navigateur avec la compétence dev-browser
EOF
)" \
--priority=3
# Ajouter la dépendance : US-003 dépend de US-002
bd dep add ralph-tui-003 ralph-tui-002
Emplacement de Sortie
Les perles sont écrites dans : .beads/beads.jsonl
Après la création, exécutez ralph-tui :
# Travailler sur une épopée spécifique
ralph-tui run --tracker beads --epic ralph-tui-abc
# Ou laisser choisir la meilleure tâche automatiquement
ralph-tui run --tracker beads
ralph-tui va :
- Travailler sur les perles de l'épopée spécifiée (ou sélectionner la meilleure tâche disponible)
- Fermer chaque perle une fois terminée
- Fermer l'épopée quand tous les enfants sont terminés
- Afficher
<promise>COMPLETE</promise>lorsque l'épopée est terminée
Liste de Vérification Avant de Créer les Perles
- Extraire les Quality Gates du PRD (ou demander à l'utilisateur si manquant)
- Chaque histoire est réalisable en une itération (assez petite)
- Les histoires sont ordonnées par dépendance (schéma → backend → UI)
- Les Quality Gates sont ajoutées aux critères d'acceptation de chaque perle
- Les histoires UI ont une vérification navigateur (si spécifiée dans les Quality Gates)
- Les critères d'acceptation sont vérifiables (pas vagues)
- Aucune histoire ne dépend d'une histoire ultérieure (uniquement des histoires précédentes)
- Les dépendances sont ajoutées avec
bd dep addaprès la création des perles