Ralph TUI - Créer des Tâches JSON
Convertit les PRD au format prd.json pour une exécution autonome avec ralph-tui.
Note : Cette compétence est intégrée au plugin de suivi JSON de
ralph-tui. Les futurs plugins de suivi (Linear, GitHub Issues, etc.) intégreront leurs propres compétences de création de tâches.
⚠️ CRITIQUE : La sortie DOIT être un objet JSON PLAT avec
nameetuserStoriesau niveau RACINE. N'enveloppez PAS le contenu dans un objetprdet n'utilisez PAS un tableautasks. Voir la section « Anti-Patterns du Schéma » ci-dessous.
Le Travail
Prenez un PRD (fichier markdown ou texte) et créez un fichier prd.json :
- Extraire les Quality Gates de la section « Quality Gates » du PRD
- Analyser les user stories du PRD
- Ajouter les quality gates aux critères d'acceptation de chaque histoire
- Configurer les dépendances entre les histoires
- Produire une sortie prête pour
ralph-tui run --prd <chemin>
É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 des types
- `pnpm lint` - Analyse du code
Pour les histoires UI, inclure également :
- Vérifier dans le navigateur à l'aide de la compétence dev-browser
Extrayez :
- Gates universels : Commandes qui s'appliquent à TOUTES les histoires (ex.
pnpm typecheck) - Gates UI : Commandes qui s'appliquent uniquement aux histoires UI (ex. vérification navigateur)
S'il n'y a pas de section Quality Gates : Demandez à l'utilisateur quelles commandes doivent réussir, ou utilisez une valeur par défaut raisonnable comme npm run typecheck.
Format de Sortie
Le fichier JSON DOIT être un objet PLAT au niveau racine :
{
"name": "[Nom du projet depuis le PRD ou le répertoire]",
"branchName": "ralph/[nom-fonctionnalité-en-kebab-case]",
"description": "[Description de la fonctionnalité depuis le PRD]",
"userStories": [
{
"id": "US-001",
"title": "[Titre de l'histoire]",
"description": "En tant que [utilisateur], je veux [fonctionnalité] afin de [bénéfice]",
"acceptanceCriteria": [
"Critère 1 du PRD",
"Critère 2 du PRD",
"pnpm typecheck passe",
"pnpm lint passe"
],
"priority": 1,
"passes": false,
"notes": "",
"dependsOn": []
},
{
"id": "US-002",
"title": "[Histoire UI qui dépend de US-001]",
"description": "...",
"acceptanceCriteria": [
"...",
"pnpm typecheck passe",
"pnpm lint passe",
"Vérifier dans le navigateur à l'aide de la compétence dev-browser"
],
"priority": 2,
"passes": false,
"notes": "",
"dependsOn": ["US-001"]
}
]
}
CRITIQUE : Anti-Patterns du Schéma (À NE PAS UTILISER)
Les motifs suivants sont INVALIDES et provoqueront des erreurs de validation :
❌ MAUVAIS : Objet enveloppant
{
"prd": {
"name": "...",
"userStories": [...]
}
}
Ceci encapsule tout dans un objet prd. NE FAITES PAS CELA. Les champs name et userStories doivent être au niveau RACINE.
❌ MAUVAIS : Utiliser « tasks » à la place de « userStories »
{
"name": "...",
"tasks": [...]
}
Le tableau s'appelle "userStories", pas "tasks".
❌ MAUVAIS : Structures imbriquées complexes
{
"metadata": {...},
"overview": {...},
"migration_strategy": {
"phases": [...]
}
}
Même si le PRD décrit des phases/jalons/sprints, vous DEVEZ aplatir le tout dans un seul tableau userStories.
❌ MAUVAIS : Utiliser « status » à la place de « passes »
{
"userStories": [{
"id": "US-001",
"status": "open" // MAUVAIS !
}]
}
Utilisez "passes": false pour les histoires incomplètes, "passes": true pour les terminées.
✅ CORRECT : Structure plate à la racine
{
"name": "Android Kotlin Migration",
"branchName": "ralph/kotlin-migration",
"userStories": [
{"id": "US-001", "title": "Créer l'interface Scraper", "passes": false, "dependsOn": []},
{"id": "US-002", "title": "Implémenter WeebCentralScraper", "passes": false, "dependsOn": ["US-001"]}
]
}
Taille des Histoires : La Règle #1
Chaque histoire doit pouvoir être réalisée en UNE SEULE itération de ralph-tui (environ une fenêtre de contexte d'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 épuise le contexte avant de terminer.
Histoires de taille adaptée :
- 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 filtre déroulant à une liste
Trop grandes (à diviser) :
- « Construire tout le tableau de bord » → 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 point de terminaison ou par motif
Règle générale : Si vous ne pouvez pas décrire le changement en 2-3 phrases, c'est trop grand.
Dépendances avec dependsOn
Utilisez le tableau dependsOn pour spécifier quelles histoires doivent être terminées en premier :
{
"id": "US-002",
"title": "Créer les points de terminaison de l'API",
"dependsOn": ["US-001"], // Ne sera pas sélectionné tant que US-001 n'est pas réussie
...
}
Ralph-tui va :
- Afficher US-002 comme « bloquée » jusqu'à ce que US-001 soit terminée
- Ne jamais sélectionner US-002 pour exécution tant que US-001 est ouverte
- Inclure « Prérequis : US-001 » dans l'invite lorsqu'il travaille sur US-002
Ordre correct des dépendances :
- Modifications du schéma/base de données (aucune dépendance)
- Logique backend (dépend du schéma)
- Composants UI (dépendent du backend)
- Intégration/finitions (dépendent de l'UI)
Critères d'Acceptation : Quality Gates + Spécifiques à l'Histoire
Les critères d'acceptation de chaque histoire doivent inclure :
- Critères spécifiques à l'histoire issus du PRD (ce que cette histoire accomplit)
- Quality gates issus de la section Quality Gates du PRD (ajoutés à la fin)
Bons critères (vérifiables) :
- « Ajouter la colonne
statusà la table tasks avec la valeur par défaut 'open' » - « Le filtre déroulant a les options : Toutes, Ouvertes, Fermées »
- « Cliquer sur supprimer 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 en premier
- Chaque user story → une entrée JSON
- Identifiants (IDs) : Séquentiels (US-001, US-002, etc.)
- Priorité : Basée sur l'ordre des dépendances (1 = la plus élevée)
- dependsOn : Tableau des identifiants d'histoires dont dépend cette histoire
- Toutes les histoires :
passes : falseetnotesvide - branchName : Dérivé du nom de la fonctionnalité, en kebab-case, préfixé par
ralph/ - Critères d'acceptation : Critères de l'histoire + quality gates ajoutés
- Histoires UI : Ajouter également les gates spécifiques à l'UI (vérification navigateur)
Emplacement de Sortie
Par défaut : ./tasks/prd.json (à côté des fichiers markdown du PRD)
Cela permet de garder tous les fichiers liés au PRD ensemble dans le répertoire tasks/.
Ou spécifiez un chemin différent - ralph-tui l'utilisera avec :
ralph-tui run --prd ./chemin/vers/prd.json
Exemple
PRD d'entrée :
# PRD : Système de Priorité des Tâches
Ajouter des niveaux de priorité aux tâches.
## Quality Gates
Ces commandes doivent réussir pour chaque user story :
- `pnpm typecheck` - Vérification des types
- `pnpm lint` - Analyse du code
Pour les histoires UI, inclure également :
- Vérifier dans le navigateur à l'aide de la compétence dev-browser
## User Stories
### US-001 : Ajouter le champ priorité à la base de données
**Description :** En tant que développeur, j'ai besoin de stocker la priorité des tâches.
**Critères d'acceptation :**
- [ ] Ajouter colonne priorité : 1-4 (défaut 2)
- [ ] La migration s'exécute avec succès
### US-002 : Afficher le badge de priorité sur les cartes de tâches
**Description :** En tant qu'utilisateur, je veux voir la priorité d'une tâche d'un coup d'œil.
**Critères d'acceptation :**
- [ ] Le badge affiche P1/P2/P3/P4 avec des couleurs
- [ ] Le badge est visible sans survol
### US-003 : Ajouter un filtre déroulant de priorité
**Description :** En tant qu'utilisateur, je veux filtrer les tâches par priorité.
**Critères d'acceptation :**
- [ ] Filtre déroulant : Toutes, P1, P2, P3, P4
- [ ] Le filtre persiste dans l'URL
Sortie prd.json :
{
"project": "my-app",
"branchName": "ralph/task-priority",
"description": "Ajouter des niveaux de priorité aux tâches",
"userStories": [
{
"id": "US-001",
"title": "Ajouter le champ priorité à la base de données",
"description": "En tant que développeur, j'ai besoin de stocker la priorité des tâches.",
"acceptanceCriteria": [
"Ajouter colonne priorité : 1-4 (défaut 2)",
"La migration s'exécute avec succès",
"pnpm typecheck passe",
"pnpm lint passe"
],
"priority": 1,
"passes": false,
"notes": "",
"dependsOn": []
},
{
"id": "US-002",
"title": "Afficher le badge de priorité sur les cartes de tâches",
"description": "En tant qu'utilisateur, je veux voir la priorité d'une tâche d'un coup d'œil.",
"acceptanceCriteria": [
"Le badge affiche P1/P2/P3/P4 avec des couleurs",
"Le badge est visible sans survol",
"pnpm typecheck passe",
"pnpm lint passe",
"Vérifier dans le navigateur à l'aide de la compétence dev-browser"
],
"priority": 2,
"passes": false,
"notes": "",
"dependsOn": ["US-001"]
},
{
"id": "US-003",
"title": "Ajouter un filtre déroulant de priorité",
"description": "En tant qu'utilisateur, je veux filtrer les tâches par priorité.",
"acceptanceCriteria": [
"Filtre déroulant : Toutes, P1, P2, P3, P4",
"Le filtre persiste dans l'URL",
"pnpm typecheck passe",
"pnpm lint passe",
"Vérifier dans le navigateur à l'aide de la compétence dev-browser"
],
"priority": 3,
"passes": false,
"notes": "",
"dependsOn": ["US-002"]
}
]
}
Exécution avec ralph-tui
Après avoir créé prd.json :
ralph-tui run --prd ./tasks/prd.json
Ralph-tui va :
- Charger les histoires depuis prd.json
- Sélectionner l'histoire avec la priorité la plus élevée dont
passesestfalseet qui n'a pas de dépendances bloquantes - Générer une invite avec les détails de l'histoire + les critères d'acceptation
- Exécuter l'agent pour implémenter l'histoire
- Marquer
passes: trueune fois terminée - Répéter jusqu'à ce que toutes les histoires soient réussies
Liste de Vérification Avant d'Enregistrer
- Quality Gates extraits du PRD (ou demande à l'utilisateur si manquants)
- Chaque histoire réalisable en une seule itération
- Histoires ordonnées par dépendance (schéma → backend → UI)
-
dependsOncorrectement défini pour chaque histoire - Quality gates ajoutés aux critères d'acceptation de chaque histoire
- Les histoires UI ont une vérification navigateur (si spécifié dans les Quality Gates)
- Les critères d'acceptation sont vérifiables (pas vagues)
- Pas de dépendances circulaires