---
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.
