@atlashub/smartstack-cli 1.4.1 → 1.5.1

package/templates/commands/implement.md

@@ -1,663 +1,663 @@
----
-description: Implement a feature from its BA handoff (skip explore phase)
-argument-hint: <FEAT-XXX>
-model: opus
----
-
-# Implement Feature from Handoff
-
-> **Modele:** OPUS (implementation one-shot, zero ambiguite)
-> **Cout estime:** ~$2.00 (one-shot) / ~$5.00-15.00 (avec ralph-loop)
-> **Prerequis:** Handoff valide (4-development-handoff.md)
-
----
-
-## RALPH-LOOP INTEGRATION (OBLIGATOIRE)
-
-```
-╔══════════════════════════════════════════════════════════════════════════════╗
-║  UTILISATION AVEC RALPH-LOOP                                                 ║
-╠══════════════════════════════════════════════════════════════════════════════╣
-║                                                                              ║
-║  /ralph-loop "/implement FEAT-XXX" --completion-promise "COMPLETE"           ║
-║              --max-iterations 25                                             ║
-║                                                                              ║
-║  FICHIERS RALPH (créés automatiquement):                                     ║
-║  ├── prd.json        → Liste des tâches avec statut                          ║
-║  └── progress.txt    → Mémoire persistante entre itérations                  ║
-║                                                                              ║
-║  PROCESSUS PAR ITERATION:                                                    ║
-║  1. Lire prd.json → Trouver prochaine tâche "passes": false                  ║
-║  2. Lire progress.txt → Comprendre le contexte                               ║
-║  3. Implémenter UNE SEULE tâche                                              ║
-║  4. git commit                                                               ║
-║  5. Mettre à jour prd.json → "passes": true                                  ║
-║  6. Ajouter apprentissages à progress.txt                                    ║
-║  7. Si TOUTES tâches "passes": true → <promise>COMPLETE</promise>            ║
-║                                                                              ║
-║  SIGNAL DE FIN: <promise>COMPLETE</promise>                                  ║
-║                                                                              ║
-╚══════════════════════════════════════════════════════════════════════════════╝
-```
-
----
-
-## WORKFLOW RALPH
-
-```
-┌─────────────────────────────────────────────────────────────────────────────┐
-│                           BOUCLE RALPH                                       │
-├─────────────────────────────────────────────────────────────────────────────┤
-│                                                                              │
-│   ITERATION N                                                                │
-│   ┌──────────┐    ┌──────────┐    ┌──────────┐    ┌──────────┐             │
-│   │ 1. LIRE  │───►│ 2. WORK  │───►│ 3. SAVE  │───►│ 4. CHECK │             │
-│   │ prd.json │    │ 1 tâche  │    │ commit   │    │ all done?│             │
-│   │ progress │    │          │    │ prd.json │    │          │             │
-│   └──────────┘    └──────────┘    │ progress │    └────┬─────┘             │
-│                                   └──────────┘         │                    │
-│                                                        ▼                    │
-│                                            ┌─────────────────────┐          │
-│                                            │ NON: Terminer       │          │
-│                                            │ (Ralph relance)     │          │
-│                                            ├─────────────────────┤          │
-│                                            │ OUI: <promise>      │          │
-│                                            │ COMPLETE</promise>  │          │
-│                                            └─────────────────────┘          │
-│                                                                              │
-└─────────────────────────────────────────────────────────────────────────────┘
-```
-
----
-
-## STEP 0: Initialisation Ralph (première itération seulement)
-
-### 0.1 Vérifier si prd.json existe
-
-```bash
-FEATURE_ID=$1  # Paramètre: FEAT-XXX
-
-# Si prd.json n'existe PAS → Première itération, initialiser
-if [ ! -f "prd.json" ]; then
-  echo "Première itération - Initialisation Ralph..."
-  # Continuer vers 0.2
-else
-  echo "Itération suivante - Lecture état..."
-  # Sauter vers STEP 1
-fi
-```
-
-### 0.2 Charger le handoff et créer prd.json
-
-```bash
-# Trouver le dossier feature
-FEATURE_DIR=$(find .business-analyse -type d -name "${FEATURE_ID}*" | head -1)
-HANDOFF_FILE="$FEATURE_DIR/4-development-handoff.md"
-
-if [ ! -f "$HANDOFF_FILE" ]; then
-  echo "ERREUR: Handoff non trouvé"
-  echo "   Lancez d'abord: /business-analyse:6-handoff $FEATURE_ID"
-  exit 1
-fi
-```
-
-**Créer prd.json avec les user stories extraites du handoff:**
-
-```json
-{
-  "feature_id": "FEAT-XXX",
-  "handoff_file": ".business-analyse/FEAT-XXX/4-development-handoff.md",
-  "created_at": "2026-01-16T12:00:00Z",
-  "userStories": [
-    { "id": "1", "title": "Créer Entity Domain", "phase": "backend", "passes": false },
-    { "id": "2", "title": "Créer Configuration EF Core", "phase": "backend", "passes": false },
-    { "id": "3", "title": "Créer Migration EF Core", "phase": "backend", "passes": false },
-    { "id": "4", "title": "Créer Commands/Queries Application", "phase": "backend", "passes": false },
-    { "id": "5", "title": "Créer Validators FluentValidation", "phase": "backend", "passes": false },
-    { "id": "6", "title": "Créer Controller API", "phase": "backend", "passes": false },
-    { "id": "7", "title": "Vérifier Backend Build", "phase": "backend", "passes": false },
-    { "id": "8", "title": "Créer Service API Frontend", "phase": "frontend", "passes": false },
-    { "id": "9", "title": "Créer Pages Frontend", "phase": "frontend", "passes": false },
-    { "id": "10", "title": "Ajouter i18n (4 langues)", "phase": "frontend", "passes": false },
-    { "id": "11", "title": "Ajouter Routes", "phase": "frontend", "passes": false },
-    { "id": "12", "title": "Vérifier Frontend Build", "phase": "frontend", "passes": false },
-    { "id": "13", "title": "Ajouter Notifications (si requis)", "phase": "integrations", "passes": false },
-    { "id": "14", "title": "Ajouter Workflows (si requis)", "phase": "integrations", "passes": false },
-    { "id": "15", "title": "Ajouter Prompts IA (si requis)", "phase": "integrations", "passes": false },
-    { "id": "16", "title": "Tests unitaires", "phase": "tests", "passes": false },
-    { "id": "17", "title": "Tests intégration", "phase": "tests", "passes": false },
-    { "id": "18", "title": "Lint et TypeCheck final", "phase": "quality", "passes": false }
-  ]
-}
-```
-
-### 0.3 Créer progress.txt
-
-```markdown
-# Progress - FEAT-XXX
-
-## Initialisation
-- Feature: {titre du handoff}
-- Date: {timestamp}
-- Handoff: {chemin}
-
-## Contexte du projet
-- Backend: .NET 8, Clean Architecture
-- Frontend: React + TypeScript + Vite
-- Base: SmartStack.app
-
----
-
-```
-
-### 0.4 Premier commit Ralph
-
-```bash
-git add prd.json progress.txt
-git commit -m "chore(ralph): initialize implementation tracking for FEAT-XXX"
-```
-
----
-
-## STEP 1: Lire l'état Ralph (chaque itération)
-
-### 1.1 Lire prd.json
-
-```bash
-# Lire prd.json pour trouver la prochaine tâche
-PRD=$(cat prd.json)
-
-# Identifier la PROCHAINE tâche avec "passes": false
-# → C'est LA tâche à implémenter cette itération
-```
-
-**Analyser prd.json:**
-- Compter les tâches `"passes": true` → Progression
-- Trouver la PREMIÈRE tâche `"passes": false` → Tâche courante
-- Si AUCUNE tâche `"passes": false` → TOUTES TERMINÉES
-
-### 1.2 Lire progress.txt
-
-```bash
-# Lire progress.txt pour comprendre le contexte
-PROGRESS=$(cat progress.txt)
-
-# Extraire les apprentissages des itérations précédentes
-# Comprendre les décisions prises et problèmes résolus
-```
-
-### 1.3 Vérifier git log
-
-```bash
-# Voir les commits récents pour contexte
-git log --oneline -10
-```
-
-### 1.4 Afficher le résumé
-
-```
-================================================================================
-                         RALPH ITERATION - FEAT-XXX
-================================================================================
-
-PROGRESSION: {N}/{TOTAL} tâches terminées
-
-TÂCHE COURANTE: #{id} - {title}
-PHASE: {phase}
-
-CONTEXTE (progress.txt):
-{derniers apprentissages}
-
-================================================================================
-```
-
----
-
-## STEP 2: Implémenter UNE SEULE tâche
-
-> **RÈGLE CRITIQUE:** Ne travailler que sur la tâche identifiée en STEP 1.
-> Ne PAS avancer sur d'autres tâches même si c'est tentant.
-
-### Référence des tâches par phase
-
-**Phase: backend**
-| ID | Tâche | Instructions |
-|----|-------|--------------|
-| 1 | Créer Entity Domain | Voir STEP 3.1 |
-| 2 | Créer Configuration EF Core | Voir STEP 3.2 |
-| 3 | Créer Migration EF Core | `/efcore:migration` |
-| 4 | Créer Commands/Queries Application | Voir STEP 3.3 |
-| 5 | Créer Validators FluentValidation | Voir STEP 3.3 |
-| 6 | Créer Controller API | Voir STEP 3.4 |
-| 7 | Vérifier Backend Build | `dotnet build` |
-
-**Phase: frontend**
-| ID | Tâche | Instructions |
-|----|-------|--------------|
-| 8 | Créer Service API Frontend | Voir STEP 4.1 |
-| 9 | Créer Pages Frontend | Voir STEP 4.2 |
-| 10 | Ajouter i18n (4 langues) | Voir STEP 4.3 |
-| 11 | Ajouter Routes | Voir STEP 4.4 |
-| 12 | Vérifier Frontend Build | `npm run build` |
-
-**Phase: integrations**
-| ID | Tâche | Instructions |
-|----|-------|--------------|
-| 13 | Ajouter Notifications | Voir STEP 5.2 (si requis dans handoff) |
-| 14 | Ajouter Workflows | Voir STEP 5.3 (si requis dans handoff) |
-| 15 | Ajouter Prompts IA | Voir STEP 5.4 (si requis dans handoff) |
-
-**Phase: tests**
-| ID | Tâche | Instructions |
-|----|-------|--------------|
-| 16 | Tests unitaires | `dotnet test --filter "Category=Unit"` |
-| 17 | Tests intégration | `dotnet test --filter "Category=Integration"` |
-
-**Phase: quality**
-| ID | Tâche | Instructions |
-|----|-------|--------------|
-| 18 | Lint et TypeCheck final | `npm run lint && npm run typecheck` |
-
----
-
-## STEP 3: Instructions Backend (tâches 1-7)
-
-### 3.1 Domain Layer
-
-```
-EXPLORER PATTERNS EXISTANTS:
--> src/SmartStack.Domain/Entities/
--> src/SmartStack.Domain/Constants/Permissions.cs
-```
-
-Actions:
-1. Creer l'entite dans Domain/Entities/Business/
-2. Ajouter les constantes de permission
-3. Valider: `dotnet build src/SmartStack.Domain`
-
-### 3.2 Infrastructure Layer
-
-```
-EXPLORER PATTERNS EXISTANTS:
--> src/SmartStack.Infrastructure/Persistence/Configurations/
-```
-
-Actions:
-1. Creer EntityTypeConfiguration
-2. Ajouter HasData pour seed si necessaire
-3. Creer migration: `/efcore:migration`
-4. Valider: `dotnet build src/SmartStack.Infrastructure`
-
-### 3.3 Application Layer
-
-```
-EXPLORER PATTERNS EXISTANTS:
--> src/SmartStack.Application/Features/
-```
-
-Actions:
-1. Creer Commands (Create, Update, Delete)
-2. Creer Queries (GetById, GetList)
-3. Creer DTOs
-4. Creer Validators (FluentValidation)
-5. Valider: `dotnet build src/SmartStack.Application`
-
-### 3.4 API Layer
-
-```
-EXPLORER PATTERNS EXISTANTS:
--> src/SmartStack.Api/Areas/Business/Controllers/
-```
-
-Actions:
-1. Creer Controller dans Areas/Business
-2. Ajouter [RequirePermission] sur chaque action
-3. Documenter avec [ProducesResponseType]
-4. Valider: `dotnet build src/SmartStack.Api`
-
-### 3.5 Check Backend
-
-```bash
-# Build complet
-dotnet build
-
-# Si erreur: corriger et recommencer
-```
-
----
-
-## STEP 4: Implementation Frontend
-
-### 4.1 Service API
-
-```
-EXPLORER PATTERNS EXISTANTS:
--> web/smartstack-web/src/services/api/
-```
-
-Actions:
-1. Creer service avec endpoints
-2. Definir types TypeScript
-3. Valider: `npm run typecheck`
-
-### 4.2 Pages
-
-```
-EXPLORER PATTERNS EXISTANTS:
--> web/smartstack-web/src/pages/business/
--> web/smartstack-web/src/pages/admin/ (pour patterns CRUD)
-```
-
-Actions:
-1. Creer ListPage avec DataTable
-2. Creer DetailPage (si applicable)
-3. Ajouter modals Create/Edit
-4. Implementer filtres et pagination
-5. Ajouter permission checks (usePermission)
-
-### 4.3 i18n
-
-```
-FICHIERS A MODIFIER:
--> web/smartstack-web/src/i18n/locales/fr/{module}.json
--> web/smartstack-web/src/i18n/locales/en/{module}.json
--> web/smartstack-web/src/i18n/locales/it/{module}.json
--> web/smartstack-web/src/i18n/locales/de/{module}.json
-```
-
-Actions:
-1. Ajouter toutes les cles dans les 4 langues
-2. Utiliser useTranslation dans les composants
-
-### 4.4 Routes
-
-```
-FICHIER:
--> web/smartstack-web/src/App.tsx ou routes.tsx
-```
-
-Actions:
-1. Ajouter routes pour les nouvelles pages
-2. Proteger avec RequireAuth si necessaire
-
-### 4.5 Check Frontend
-
-```bash
-cd web/smartstack-web
-npm run lint
-npm run typecheck
-npm run build
-```
-
----
-
-## STEP 5: Integrations SmartStack
-
-> **CRITIQUE:** Lire la Section 9 du handoff pour determiner les integrations requises.
-
-### 5.1 Verifier les integrations requises
-
-```bash
-# Dans le handoff, section 9.4:
-# | Integration | Requis | Skill |
-# |-------------|--------|-------|
-# | Notifications | oui/non | /notification add |
-# | Workflows | oui/non | /workflow create |
-# | IA | oui/non | /ai-prompt create |
-```
-
-### 5.2 Notifications (si requis=oui)
-
-**Skill a executer:** `/notification add`
-
-Actions:
-1. Ajouter le NotificationType dans l'enum
-2. Injecter `INotificationService` dans le service
-3. Ajouter l'appel `SendNotificationAsync` apres les operations CRUD
-4. Creer le hook frontend `use{Module}Notifications.ts`
-
-```csharp
-// Template dans le service
-await _notificationService.SendNotificationAsync(
-    userId: destinataire.Id,
-    type: NotificationType.{Entity}Created,
-    title: _localizer["{module}.notifications.created.title"],
-    message: _localizer["{module}.notifications.created.message", entity.Name],
-    relatedEntityType: nameof({Entity}),
-    relatedEntityId: entity.Id,
-    actionUrl: $"/{module}/{entity.Id}",
-    cancellationToken: ct);
-```
-
-### 5.3 Workflows (si requis=oui)
-
-**Skill a executer:** `/workflow create`
-
-Actions:
-1. Creer le trigger dans WorkflowTriggerConfiguration.cs
-2. Creer le workflow dans WorkflowConfiguration.cs
-3. Ajouter les steps dans WorkflowStepConfiguration.cs
-4. Creer les email templates si necessaire
-5. Ajouter l'appel `TriggerAsync` dans le service
-
-```csharp
-// Template dans le service
-await _workflowService.TriggerAsync(
-    "{entity}.created",
-    new Dictionary<string, object>
-    {
-        ["entityId"] = entity.Id,
-        ["entityName"] = entity.Name,
-        ["userEmail"] = _currentUser.Email
-    },
-    language: _currentUser.Language ?? "fr",
-    cancellationToken: ct);
-```
-
-### 5.4 Assistance IA (si requis=oui)
-
-**Skill a executer:** `/ai-prompt create`
-
-Actions:
-1. Creer le Prompt dans PromptConfiguration.cs
-2. Creer les Blocks dans PromptBlockConfiguration.cs
-3. Creer le OutputSchema si sortie structuree
-4. Ajouter l'appel `CompleteAsync` dans le service
-
-```csharp
-// Template dans le service
-var result = await _aiCompletionService.CompleteAsync<{OutputType}>(
-    "{prompt-code}",
-    new Dictionary<string, object>
-    {
-        ["context"] = context,
-        ["entity"] = entity
-    },
-    cancellationToken: ct);
-```
-
-### 5.5 Migration EF Core (si nouvelles entites)
-
-```bash
-# Si des entites ont ete ajoutees (triggers, workflows, templates)
-/efcore:migration
-```
-
----
-
-## STEP 6: Tests
-
-### 6.1 Tests Unitaires
-
-```bash
-# Backend
-dotnet test --filter "Category=Unit"
-
-# Frontend
-npm run test:unit
-```
-
-### 6.2 Tests Integration
-
-```bash
-# API tests
-dotnet test --filter "Category=Integration"
-```
-
-### 6.3 Collection Postman (optionnel)
-
-```bash
-/controller:postman-templates {module}
-```
-
----
-
-## STEP 7: Persister l'état Ralph (FIN DE CHAQUE ITERATION)
-
-> **OBLIGATOIRE:** Ces actions DOIVENT être faites à CHAQUE itération.
-
-### 7.1 Git commit
-
-```bash
-# Commit du travail de cette itération
-git add -A
-git commit -m "feat({module}): {description courte de la tâche}"
-```
-
-### 7.2 Mettre à jour prd.json
-
-Modifier la tâche courante: `"passes": false` → `"passes": true`
-
-```json
-// AVANT
-{ "id": "3", "title": "Créer Migration EF Core", "phase": "backend", "passes": false }
-
-// APRÈS
-{ "id": "3", "title": "Créer Migration EF Core", "phase": "backend", "passes": true }
-```
-
-### 7.3 Ajouter à progress.txt
-
-Ajouter une entrée à la fin du fichier:
-
-```markdown
-## Itération {DATE} {HEURE}
-- Tâche: #{id} - {title}
-- Fait: {description de ce qui a été implémenté}
-- Fichiers modifiés: {liste des fichiers créés/modifiés}
-- Apprentissages: {ce qui sera utile pour les prochaines itérations}
-- Problèmes: {difficultés rencontrées, le cas échéant}
-```
-
-### 7.4 Commit des fichiers Ralph
-
-```bash
-git add prd.json progress.txt
-git commit -m "chore(ralph): mark task #{id} complete"
-```
-
----
-
-## STEP 8: Vérifier completion et signaler
-
-### 8.1 Compter les tâches restantes
-
-```bash
-# Lire prd.json et compter les "passes": false
-REMAINING=$(grep -c '"passes": false' prd.json)
-```
-
-### 8.2 Si des tâches restent (REMAINING > 0)
-
-```
-================================================================================
-                    ITERATION TERMINEE - FEAT-XXX
-================================================================================
-
-TÂCHE COMPLETEE: #{id} - {title}
-PROGRESSION: {N}/{TOTAL} tâches
-
-PROCHAINE TÂCHE: #{next_id} - {next_title}
-
-================================================================================
-```
-
-**NE PAS afficher `<promise>COMPLETE</promise>`**
-→ Ralph relancera automatiquement une nouvelle itération.
-
-### 8.3 Si TOUTES les tâches sont terminées (REMAINING = 0)
-
-```
-================================================================================
-                    FEATURE IMPLEMENTEE - {FEATURE_ID}
-================================================================================
-
-TOUTES LES TÂCHES TERMINÉES (18/18)
-
-BACKEND:
-  Entity:        src/SmartStack.Domain/Entities/Business/{Entity}.cs
-  Config:        src/SmartStack.Infrastructure/.../Configuration.cs
-  Commands:      src/SmartStack.Application/Features/{Module}/Commands/
-  Queries:       src/SmartStack.Application/Features/{Module}/Queries/
-  Controller:    src/SmartStack.Api/Areas/Business/Controllers/{Module}Controller.cs
-  Migration:     {migration_name}
-
-FRONTEND:
-  Service:       web/smartstack-web/src/services/api/{module}Service.ts
-  Pages:         web/smartstack-web/src/pages/business/{app}/{module}/
-  i18n:          4 langues (fr, en, it, de)
-
-INTEGRATIONS SMARTSTACK:
-  Notifications: {oui/non} - {N} types ajoutes
-  Workflows:     {oui/non} - {N} workflows crees
-  IA Prompts:    {oui/non} - {N} prompts crees
-
-================================================================================
-PROCHAINES ETAPES (manuelles)
-================================================================================
-
-1. Tester manuellement dans le navigateur
-2. Tester les notifications en temps réel (si applicable)
-3. Vérifier les workflows dans l'admin (si applicable)
-4. Générer la documentation:
-   /business-analyse:7-doc-html {FEATURE_ID}
-
-================================================================================
-
-<promise>COMPLETE</promise>
-
-================================================================================
-```
-
----
-
-## Règles Ralph critiques
-
-1. **UNE tâche par itération** - Ne JAMAIS faire plusieurs tâches à la fois
-2. **Toujours commit** - Chaque itération DOIT produire un commit
-3. **Toujours update prd.json** - Marquer la tâche comme terminée
-4. **Toujours enrichir progress.txt** - C'est la mémoire pour les prochaines itérations
-5. **Ne marquer "passes": true que si ça fonctionne** - Si erreur, ne pas marquer comme fait
-
----
-
-## Options (mode sans Ralph)
-
-| Option | Description |
-|--------|-------------|
-| `--no-ralph` | Mode classique sans tracking Ralph |
-| `--phase=1` | Backend seulement |
-| `--phase=2` | Frontend seulement |
-| `--phase=3` | Integrations SmartStack seulement |
-| `--phase=4` | Tests seulement |
-
----
-
-## Fichiers Ralph créés
-
-| Fichier | Description | Gitignore |
-|---------|-------------|-----------|
-| `prd.json` | Liste des tâches avec statut | Non (tracker dans git) |
-| `progress.txt` | Mémoire persistante | Non (tracker dans git) |
-
-Ces fichiers sont commités pour permettre la reprise après interruption.
+---
+description: Implement a feature from its BA handoff (skip explore phase)
+argument-hint: <FEAT-XXX>
+model: opus
+---
+
+# Implement Feature from Handoff
+
+> **Modele:** OPUS (implementation one-shot, zero ambiguite)
+> **Cout estime:** ~$2.00 (one-shot) / ~$5.00-15.00 (avec ralph-loop)
+> **Prerequis:** Handoff valide (4-development-handoff.md)
+
+---
+
+## RALPH-LOOP INTEGRATION (OBLIGATOIRE)
+
+```
+╔══════════════════════════════════════════════════════════════════════════════╗
+║  UTILISATION AVEC RALPH-LOOP                                                 ║
+╠══════════════════════════════════════════════════════════════════════════════╣
+║                                                                              ║
+║  /ralph-loop "/implement FEAT-XXX" --completion-promise "COMPLETE"           ║
+║              --max-iterations 25                                             ║
+║                                                                              ║
+║  FICHIERS RALPH (créés automatiquement):                                     ║
+║  ├── prd.json        → Liste des tâches avec statut                          ║
+║  └── progress.txt    → Mémoire persistante entre itérations                  ║
+║                                                                              ║
+║  PROCESSUS PAR ITERATION:                                                    ║
+║  1. Lire prd.json → Trouver prochaine tâche "passes": false                  ║
+║  2. Lire progress.txt → Comprendre le contexte                               ║
+║  3. Implémenter UNE SEULE tâche                                              ║
+║  4. git commit                                                               ║
+║  5. Mettre à jour prd.json → "passes": true                                  ║
+║  6. Ajouter apprentissages à progress.txt                                    ║
+║  7. Si TOUTES tâches "passes": true → <promise>COMPLETE</promise>            ║
+║                                                                              ║
+║  SIGNAL DE FIN: <promise>COMPLETE</promise>                                  ║
+║                                                                              ║
+╚══════════════════════════════════════════════════════════════════════════════╝
+```
+
+---
+
+## WORKFLOW RALPH
+
+```
+┌─────────────────────────────────────────────────────────────────────────────┐
+│                           BOUCLE RALPH                                       │
+├─────────────────────────────────────────────────────────────────────────────┤
+│                                                                              │
+│   ITERATION N                                                                │
+│   ┌──────────┐    ┌──────────┐    ┌──────────┐    ┌──────────┐             │
+│   │ 1. LIRE  │───►│ 2. WORK  │───►│ 3. SAVE  │───►│ 4. CHECK │             │
+│   │ prd.json │    │ 1 tâche  │    │ commit   │    │ all done?│             │
+│   │ progress │    │          │    │ prd.json │    │          │             │
+│   └──────────┘    └──────────┘    │ progress │    └────┬─────┘             │
+│                                   └──────────┘         │                    │
+│                                                        ▼                    │
+│                                            ┌─────────────────────┐          │
+│                                            │ NON: Terminer       │          │
+│                                            │ (Ralph relance)     │          │
+│                                            ├─────────────────────┤          │
+│                                            │ OUI: <promise>      │          │
+│                                            │ COMPLETE</promise>  │          │
+│                                            └─────────────────────┘          │
+│                                                                              │
+└─────────────────────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## STEP 0: Initialisation Ralph (première itération seulement)
+
+### 0.1 Vérifier si prd.json existe
+
+```bash
+FEATURE_ID=$1  # Paramètre: FEAT-XXX
+
+# Si prd.json n'existe PAS → Première itération, initialiser
+if [ ! -f "prd.json" ]; then
+  echo "Première itération - Initialisation Ralph..."
+  # Continuer vers 0.2
+else
+  echo "Itération suivante - Lecture état..."
+  # Sauter vers STEP 1
+fi
+```
+
+### 0.2 Charger le handoff et créer prd.json
+
+```bash
+# Trouver le dossier feature
+FEATURE_DIR=$(find .business-analyse -type d -name "${FEATURE_ID}*" | head -1)
+HANDOFF_FILE="$FEATURE_DIR/4-development-handoff.md"
+
+if [ ! -f "$HANDOFF_FILE" ]; then
+  echo "ERREUR: Handoff non trouvé"
+  echo "   Lancez d'abord: /business-analyse:6-handoff $FEATURE_ID"
+  exit 1
+fi
+```
+
+**Créer prd.json avec les user stories extraites du handoff:**
+
+```json
+{
+  "feature_id": "FEAT-XXX",
+  "handoff_file": ".business-analyse/FEAT-XXX/4-development-handoff.md",
+  "created_at": "2026-01-16T12:00:00Z",
+  "userStories": [
+    { "id": "1", "title": "Créer Entity Domain", "phase": "backend", "passes": false },
+    { "id": "2", "title": "Créer Configuration EF Core", "phase": "backend", "passes": false },
+    { "id": "3", "title": "Créer Migration EF Core", "phase": "backend", "passes": false },
+    { "id": "4", "title": "Créer Commands/Queries Application", "phase": "backend", "passes": false },
+    { "id": "5", "title": "Créer Validators FluentValidation", "phase": "backend", "passes": false },
+    { "id": "6", "title": "Créer Controller API", "phase": "backend", "passes": false },
+    { "id": "7", "title": "Vérifier Backend Build", "phase": "backend", "passes": false },
+    { "id": "8", "title": "Créer Service API Frontend", "phase": "frontend", "passes": false },
+    { "id": "9", "title": "Créer Pages Frontend", "phase": "frontend", "passes": false },
+    { "id": "10", "title": "Ajouter i18n (4 langues)", "phase": "frontend", "passes": false },
+    { "id": "11", "title": "Ajouter Routes", "phase": "frontend", "passes": false },
+    { "id": "12", "title": "Vérifier Frontend Build", "phase": "frontend", "passes": false },
+    { "id": "13", "title": "Ajouter Notifications (si requis)", "phase": "integrations", "passes": false },
+    { "id": "14", "title": "Ajouter Workflows (si requis)", "phase": "integrations", "passes": false },
+    { "id": "15", "title": "Ajouter Prompts IA (si requis)", "phase": "integrations", "passes": false },
+    { "id": "16", "title": "Tests unitaires", "phase": "tests", "passes": false },
+    { "id": "17", "title": "Tests intégration", "phase": "tests", "passes": false },
+    { "id": "18", "title": "Lint et TypeCheck final", "phase": "quality", "passes": false }
+  ]
+}
+```
+
+### 0.3 Créer progress.txt
+
+```markdown
+# Progress - FEAT-XXX
+
+## Initialisation
+- Feature: {titre du handoff}
+- Date: {timestamp}
+- Handoff: {chemin}
+
+## Contexte du projet
+- Backend: .NET 8, Clean Architecture
+- Frontend: React + TypeScript + Vite
+- Base: SmartStack.app
+
+---
+
+```
+
+### 0.4 Premier commit Ralph
+
+```bash
+git add prd.json progress.txt
+git commit -m "chore(ralph): initialize implementation tracking for FEAT-XXX"
+```
+
+---
+
+## STEP 1: Lire l'état Ralph (chaque itération)
+
+### 1.1 Lire prd.json
+
+```bash
+# Lire prd.json pour trouver la prochaine tâche
+PRD=$(cat prd.json)
+
+# Identifier la PROCHAINE tâche avec "passes": false
+# → C'est LA tâche à implémenter cette itération
+```
+
+**Analyser prd.json:**
+- Compter les tâches `"passes": true` → Progression
+- Trouver la PREMIÈRE tâche `"passes": false` → Tâche courante
+- Si AUCUNE tâche `"passes": false` → TOUTES TERMINÉES
+
+### 1.2 Lire progress.txt
+
+```bash
+# Lire progress.txt pour comprendre le contexte
+PROGRESS=$(cat progress.txt)
+
+# Extraire les apprentissages des itérations précédentes
+# Comprendre les décisions prises et problèmes résolus
+```
+
+### 1.3 Vérifier git log
+
+```bash
+# Voir les commits récents pour contexte
+git log --oneline -10
+```
+
+### 1.4 Afficher le résumé
+
+```
+================================================================================
+                         RALPH ITERATION - FEAT-XXX
+================================================================================
+
+PROGRESSION: {N}/{TOTAL} tâches terminées
+
+TÂCHE COURANTE: #{id} - {title}
+PHASE: {phase}
+
+CONTEXTE (progress.txt):
+{derniers apprentissages}
+
+================================================================================
+```
+
+---
+
+## STEP 2: Implémenter UNE SEULE tâche
+
+> **RÈGLE CRITIQUE:** Ne travailler que sur la tâche identifiée en STEP 1.
+> Ne PAS avancer sur d'autres tâches même si c'est tentant.
+
+### Référence des tâches par phase
+
+**Phase: backend**
+| ID | Tâche | Instructions |
+|----|-------|--------------|
+| 1 | Créer Entity Domain | Voir STEP 3.1 |
+| 2 | Créer Configuration EF Core | Voir STEP 3.2 |
+| 3 | Créer Migration EF Core | `/efcore:migration` |
+| 4 | Créer Commands/Queries Application | Voir STEP 3.3 |
+| 5 | Créer Validators FluentValidation | Voir STEP 3.3 |
+| 6 | Créer Controller API | Voir STEP 3.4 |
+| 7 | Vérifier Backend Build | `dotnet build` |
+
+**Phase: frontend**
+| ID | Tâche | Instructions |
+|----|-------|--------------|
+| 8 | Créer Service API Frontend | Voir STEP 4.1 |
+| 9 | Créer Pages Frontend | Voir STEP 4.2 |
+| 10 | Ajouter i18n (4 langues) | Voir STEP 4.3 |
+| 11 | Ajouter Routes | Voir STEP 4.4 |
+| 12 | Vérifier Frontend Build | `npm run build` |
+
+**Phase: integrations**
+| ID | Tâche | Instructions |
+|----|-------|--------------|
+| 13 | Ajouter Notifications | Voir STEP 5.2 (si requis dans handoff) |
+| 14 | Ajouter Workflows | Voir STEP 5.3 (si requis dans handoff) |
+| 15 | Ajouter Prompts IA | Voir STEP 5.4 (si requis dans handoff) |
+
+**Phase: tests**
+| ID | Tâche | Instructions |
+|----|-------|--------------|
+| 16 | Tests unitaires | `dotnet test --filter "Category=Unit"` |
+| 17 | Tests intégration | `dotnet test --filter "Category=Integration"` |
+
+**Phase: quality**
+| ID | Tâche | Instructions |
+|----|-------|--------------|
+| 18 | Lint et TypeCheck final | `npm run lint && npm run typecheck` |
+
+---
+
+## STEP 3: Instructions Backend (tâches 1-7)
+
+### 3.1 Domain Layer
+
+```
+EXPLORER PATTERNS EXISTANTS:
+-> src/SmartStack.Domain/Entities/
+-> src/SmartStack.Domain/Constants/Permissions.cs
+```
+
+Actions:
+1. Creer l'entite dans Domain/Entities/Business/
+2. Ajouter les constantes de permission
+3. Valider: `dotnet build src/SmartStack.Domain`
+
+### 3.2 Infrastructure Layer
+
+```
+EXPLORER PATTERNS EXISTANTS:
+-> src/SmartStack.Infrastructure/Persistence/Configurations/
+```
+
+Actions:
+1. Creer EntityTypeConfiguration
+2. Ajouter HasData pour seed si necessaire
+3. Creer migration: `/efcore:migration`
+4. Valider: `dotnet build src/SmartStack.Infrastructure`
+
+### 3.3 Application Layer
+
+```
+EXPLORER PATTERNS EXISTANTS:
+-> src/SmartStack.Application/Features/
+```
+
+Actions:
+1. Creer Commands (Create, Update, Delete)
+2. Creer Queries (GetById, GetList)
+3. Creer DTOs
+4. Creer Validators (FluentValidation)
+5. Valider: `dotnet build src/SmartStack.Application`
+
+### 3.4 API Layer
+
+```
+EXPLORER PATTERNS EXISTANTS:
+-> src/SmartStack.Api/Areas/Business/Controllers/
+```
+
+Actions:
+1. Creer Controller dans Areas/Business
+2. Ajouter [RequirePermission] sur chaque action
+3. Documenter avec [ProducesResponseType]
+4. Valider: `dotnet build src/SmartStack.Api`
+
+### 3.5 Check Backend
+
+```bash
+# Build complet
+dotnet build
+
+# Si erreur: corriger et recommencer
+```
+
+---
+
+## STEP 4: Implementation Frontend
+
+### 4.1 Service API
+
+```
+EXPLORER PATTERNS EXISTANTS:
+-> web/smartstack-web/src/services/api/
+```
+
+Actions:
+1. Creer service avec endpoints
+2. Definir types TypeScript
+3. Valider: `npm run typecheck`
+
+### 4.2 Pages
+
+```
+EXPLORER PATTERNS EXISTANTS:
+-> web/smartstack-web/src/pages/business/
+-> web/smartstack-web/src/pages/admin/ (pour patterns CRUD)
+```
+
+Actions:
+1. Creer ListPage avec DataTable
+2. Creer DetailPage (si applicable)
+3. Ajouter modals Create/Edit
+4. Implementer filtres et pagination
+5. Ajouter permission checks (usePermission)
+
+### 4.3 i18n
+
+```
+FICHIERS A MODIFIER:
+-> web/smartstack-web/src/i18n/locales/fr/{module}.json
+-> web/smartstack-web/src/i18n/locales/en/{module}.json
+-> web/smartstack-web/src/i18n/locales/it/{module}.json
+-> web/smartstack-web/src/i18n/locales/de/{module}.json
+```
+
+Actions:
+1. Ajouter toutes les cles dans les 4 langues
+2. Utiliser useTranslation dans les composants
+
+### 4.4 Routes
+
+```
+FICHIER:
+-> web/smartstack-web/src/App.tsx ou routes.tsx
+```
+
+Actions:
+1. Ajouter routes pour les nouvelles pages
+2. Proteger avec RequireAuth si necessaire
+
+### 4.5 Check Frontend
+
+```bash
+cd web/smartstack-web
+npm run lint
+npm run typecheck
+npm run build
+```
+
+---
+
+## STEP 5: Integrations SmartStack
+
+> **CRITIQUE:** Lire la Section 9 du handoff pour determiner les integrations requises.
+
+### 5.1 Verifier les integrations requises
+
+```bash
+# Dans le handoff, section 9.4:
+# | Integration | Requis | Skill |
+# |-------------|--------|-------|
+# | Notifications | oui/non | /notification add |
+# | Workflows | oui/non | /workflow create |
+# | IA | oui/non | /ai-prompt create |
+```
+
+### 5.2 Notifications (si requis=oui)
+
+**Skill a executer:** `/notification add`
+
+Actions:
+1. Ajouter le NotificationType dans l'enum
+2. Injecter `INotificationService` dans le service
+3. Ajouter l'appel `SendNotificationAsync` apres les operations CRUD
+4. Creer le hook frontend `use{Module}Notifications.ts`
+
+```csharp
+// Template dans le service
+await _notificationService.SendNotificationAsync(
+    userId: destinataire.Id,
+    type: NotificationType.{Entity}Created,
+    title: _localizer["{module}.notifications.created.title"],
+    message: _localizer["{module}.notifications.created.message", entity.Name],
+    relatedEntityType: nameof({Entity}),
+    relatedEntityId: entity.Id,
+    actionUrl: $"/{module}/{entity.Id}",
+    cancellationToken: ct);
+```
+
+### 5.3 Workflows (si requis=oui)
+
+**Skill a executer:** `/workflow create`
+
+Actions:
+1. Creer le trigger dans WorkflowTriggerConfiguration.cs
+2. Creer le workflow dans WorkflowConfiguration.cs
+3. Ajouter les steps dans WorkflowStepConfiguration.cs
+4. Creer les email templates si necessaire
+5. Ajouter l'appel `TriggerAsync` dans le service
+
+```csharp
+// Template dans le service
+await _workflowService.TriggerAsync(
+    "{entity}.created",
+    new Dictionary<string, object>
+    {
+        ["entityId"] = entity.Id,
+        ["entityName"] = entity.Name,
+        ["userEmail"] = _currentUser.Email
+    },
+    language: _currentUser.Language ?? "fr",
+    cancellationToken: ct);
+```
+
+### 5.4 Assistance IA (si requis=oui)
+
+**Skill a executer:** `/ai-prompt create`
+
+Actions:
+1. Creer le Prompt dans PromptConfiguration.cs
+2. Creer les Blocks dans PromptBlockConfiguration.cs
+3. Creer le OutputSchema si sortie structuree
+4. Ajouter l'appel `CompleteAsync` dans le service
+
+```csharp
+// Template dans le service
+var result = await _aiCompletionService.CompleteAsync<{OutputType}>(
+    "{prompt-code}",
+    new Dictionary<string, object>
+    {
+        ["context"] = context,
+        ["entity"] = entity
+    },
+    cancellationToken: ct);
+```
+
+### 5.5 Migration EF Core (si nouvelles entites)
+
+```bash
+# Si des entites ont ete ajoutees (triggers, workflows, templates)
+/efcore:migration
+```
+
+---
+
+## STEP 6: Tests
+
+### 6.1 Tests Unitaires
+
+```bash
+# Backend
+dotnet test --filter "Category=Unit"
+
+# Frontend
+npm run test:unit
+```
+
+### 6.2 Tests Integration
+
+```bash
+# API tests
+dotnet test --filter "Category=Integration"
+```
+
+### 6.3 Collection Postman (optionnel)
+
+```bash
+/controller:postman-templates {module}
+```
+
+---
+
+## STEP 7: Persister l'état Ralph (FIN DE CHAQUE ITERATION)
+
+> **OBLIGATOIRE:** Ces actions DOIVENT être faites à CHAQUE itération.
+
+### 7.1 Git commit
+
+```bash
+# Commit du travail de cette itération
+git add -A
+git commit -m "feat({module}): {description courte de la tâche}"
+```
+
+### 7.2 Mettre à jour prd.json
+
+Modifier la tâche courante: `"passes": false` → `"passes": true`
+
+```json
+// AVANT
+{ "id": "3", "title": "Créer Migration EF Core", "phase": "backend", "passes": false }
+
+// APRÈS
+{ "id": "3", "title": "Créer Migration EF Core", "phase": "backend", "passes": true }
+```
+
+### 7.3 Ajouter à progress.txt
+
+Ajouter une entrée à la fin du fichier:
+
+```markdown
+## Itération {DATE} {HEURE}
+- Tâche: #{id} - {title}
+- Fait: {description de ce qui a été implémenté}
+- Fichiers modifiés: {liste des fichiers créés/modifiés}
+- Apprentissages: {ce qui sera utile pour les prochaines itérations}
+- Problèmes: {difficultés rencontrées, le cas échéant}
+```
+
+### 7.4 Commit des fichiers Ralph
+
+```bash
+git add prd.json progress.txt
+git commit -m "chore(ralph): mark task #{id} complete"
+```
+
+---
+
+## STEP 8: Vérifier completion et signaler
+
+### 8.1 Compter les tâches restantes
+
+```bash
+# Lire prd.json et compter les "passes": false
+REMAINING=$(grep -c '"passes": false' prd.json)
+```
+
+### 8.2 Si des tâches restent (REMAINING > 0)
+
+```
+================================================================================
+                    ITERATION TERMINEE - FEAT-XXX
+================================================================================
+
+TÂCHE COMPLETEE: #{id} - {title}
+PROGRESSION: {N}/{TOTAL} tâches
+
+PROCHAINE TÂCHE: #{next_id} - {next_title}
+
+================================================================================
+```
+
+**NE PAS afficher `<promise>COMPLETE</promise>`**
+→ Ralph relancera automatiquement une nouvelle itération.
+
+### 8.3 Si TOUTES les tâches sont terminées (REMAINING = 0)
+
+```
+================================================================================
+                    FEATURE IMPLEMENTEE - {FEATURE_ID}
+================================================================================
+
+TOUTES LES TÂCHES TERMINÉES (18/18)
+
+BACKEND:
+  Entity:        src/SmartStack.Domain/Entities/Business/{Entity}.cs
+  Config:        src/SmartStack.Infrastructure/.../Configuration.cs
+  Commands:      src/SmartStack.Application/Features/{Module}/Commands/
+  Queries:       src/SmartStack.Application/Features/{Module}/Queries/
+  Controller:    src/SmartStack.Api/Areas/Business/Controllers/{Module}Controller.cs
+  Migration:     {migration_name}
+
+FRONTEND:
+  Service:       web/smartstack-web/src/services/api/{module}Service.ts
+  Pages:         web/smartstack-web/src/pages/business/{app}/{module}/
+  i18n:          4 langues (fr, en, it, de)
+
+INTEGRATIONS SMARTSTACK:
+  Notifications: {oui/non} - {N} types ajoutes
+  Workflows:     {oui/non} - {N} workflows crees
+  IA Prompts:    {oui/non} - {N} prompts crees
+
+================================================================================
+PROCHAINES ETAPES (manuelles)
+================================================================================
+
+1. Tester manuellement dans le navigateur
+2. Tester les notifications en temps réel (si applicable)
+3. Vérifier les workflows dans l'admin (si applicable)
+4. Générer la documentation:
+   /business-analyse:7-doc-html {FEATURE_ID}
+
+================================================================================
+
+<promise>COMPLETE</promise>
+
+================================================================================
+```
+
+---
+
+## Règles Ralph critiques
+
+1. **UNE tâche par itération** - Ne JAMAIS faire plusieurs tâches à la fois
+2. **Toujours commit** - Chaque itération DOIT produire un commit
+3. **Toujours update prd.json** - Marquer la tâche comme terminée
+4. **Toujours enrichir progress.txt** - C'est la mémoire pour les prochaines itérations
+5. **Ne marquer "passes": true que si ça fonctionne** - Si erreur, ne pas marquer comme fait
+
+---
+
+## Options (mode sans Ralph)
+
+| Option | Description |
+|--------|-------------|
+| `--no-ralph` | Mode classique sans tracking Ralph |
+| `--phase=1` | Backend seulement |
+| `--phase=2` | Frontend seulement |
+| `--phase=3` | Integrations SmartStack seulement |
+| `--phase=4` | Tests seulement |
+
+---
+
+## Fichiers Ralph créés
+
+| Fichier | Description | Gitignore |
+|---------|-------------|-----------|
+| `prd.json` | Liste des tâches avec statut | Non (tracker dans git) |
+| `progress.txt` | Mémoire persistante | Non (tracker dans git) |
+
+Ces fichiers sont commités pour permettre la reprise après interruption.