Ralph Run

---
description: Executer Claude en boucle continue jusqu'a completion de la tache (Ralph Wiggum v2.0)
argument-hint: <description-tache> [--auto-detect|--init|--interactive]
---

# Ralph Run - Boucle Continue d'Agent IA v2.0

Execute Claude en boucle continue jusqu'a ce que la tache soit terminee ou que les criteres Definition of Done (DoD) soient satisfaits.

## Arguments

**$ARGUMENTS**

- `<description-tache>`: La tache a accomplir par Claude
- `--auto-detect`: Detection automatique du type de projet et configuration DoD
- `--init`: Generer la configuration sans executer
- `--interactive`: Assistant de configuration interactif

## Nouvelles fonctionnalites v2.0

| Fonctionnalite | Description |
|----------------|-------------|
| **Integration Hooks** | Integration bidirectionnelle avec Claude Code 2.1.23+ |
| **Auto-Detection** | Detection automatique du type de projet (Symfony, Flutter, React, etc.) |
| **Dashboard** | Affichage temps reel avec barre de progression |
| **Export Metriques** | Metriques au format JSON et Prometheus |
| **Circuit Breaker Adaptatif** | 5 profils avec apprentissage historique |
| **Moniteur de Sante** | Detection blocage, spirale d'erreurs, gonflement contexte |
| **Templates DoD** | Templates preconfigures pour 8 technologies |

## Processus

### 1. Initialisation de session

1. **Verifier prerequis**:
   - Verifier disponibilite de Claude
   - Chercher configuration `ralph.yml`
   - Initialiser repertoire session (`.ralph/`)

2. **Detection automatique** (si `--auto-detect`):
   - Detecter type de projet (Symfony, Flutter, React, Python, .NET, Go, Rust)
   - Charger template DoD approprie
   - Configurer commandes test et lint

3. **Charger configuration**:
   - Lire `ralph.yml` ou `.claude/ralph.yml`
   - Definir iterations max, timeouts, criteres DoD
   - Initialiser hooks si actives

### 2. Boucle principale avec Dashboard

╔═══════════════════════════════════════════════════════════════╗ ║ RALPH WIGGUM - Session: ralph-xxx PHASE: GREEN ║ ╠═══════════════════════════════════════════════════════════════╣ ║ ITERATION 8/25 ECOULE: 12:34 ║ ║ PROGRES ████████████████░░░░░░░░░░░░░░░░░░░░░░░░░░░░ 32% ║ ║ ║ ║ Circuit Breaker: ░░ (0/4) Contexte: ████████░░ 78% ║ ╚═══════════════════════════════════════════════════════════════╝

### 3. Validation Definition of Done

Le systeme DoD valide la completion via plusieurs criteres:

| Validateur | Description |
|------------|-------------|
| `command` | Executer commande shell (tests, lint, build) |
| `output_contains` | Verifier pattern dans sortie Claude |
| `file_changed` | Verifier modification fichiers |
| `hook` | Executer hook Claude existant |
| `human` | Validation humaine interactive |

### 3bis. Integration `/goal` (Claude Code 2.1.139+) — Alternative native aux DoD

Depuis Claude Code v2.1.139, la commande native `/goal` offre une alternative aux DoD validators manuels. Au lieu de definir des criteres via `ralph.yml` et de les valider apres chaque iteration, vous pouvez exprimer le critere de completion directement comme un objectif Claude Code, et la session s'arrete automatiquement quand l'objectif est atteint.

**Quand utiliser `/goal` plutot que les DoD validators ?**

| Critere | DoD validator | `/goal` natif |
|---------|---------------|---------------|
| Test command verifiable | `command: pytest` | `/goal "tous les tests passent"` |
| Pattern textuel attendu | `output_contains: "✓"` | `/goal "le build affiche 0 erreur"` |
| Modification de fichier | `file_changed: src/auth.py` | `/goal "src/auth.py implements login"` |
| Hook Claude | `hook: custom-validator.sh` | Garder DoD validator (plus expressif) |
| Validation humaine | `human` | Garder DoD validator (interactif) |

> **⚠️ `/goal` est une commande IN-SESSION, pas un flag CLI.** On la tape dans le prompt d'une session Claude Code interactive (ou via `claude -p '/goal "..."'` en mode headless). Il n'existe **pas** d'argument `ralph.sh --goal`. Un Stop hook (exit code 2) bloque l'arret tant que l'objectif n'est pas atteint et s'auto-efface une fois la condition remplie.

**Pattern recommande :**

```text
# Dans une session Claude Code interactive — taper directement :
/goal all tests pass and code coverage >= 80%

# Equivalent headless (non-interactif) :
claude -p '/goal "all tests pass and code coverage >= 80%"'

Pour les criteres complexes (hooks, validation humaine), garder les DoD validators de ralph.yml : /goal (verification semantique) et DoD validators (criteres deterministes) sont complementaires, pas exclusifs.

Avantages de /goal :

• Verification semantique par Claude (pas juste pattern matching)
• Pas de configuration ralph.yml necessaire pour les cas simples
• Integration native avec le circuit breaker (le /goal non atteint est traite comme un signal d'arret)
• Compatible avec --auto-detect (Ralph genere automatiquement un /goal adapte au type de projet)

Migration depuis DoD purs :

# Avant (ralph.yml) : 12 lignes
dod:
  validators:
    - type: command
      cmd: "pytest tests/"
      success: "passed"
    - type: file_changed
      path: "src/auth.py"
    - type: output_contains
      pattern: "Coverage: 8[0-9]%|9[0-9]%"

# Apres (commande simple)
ralph.sh --goal "tests pass, src/auth.py implements login, coverage >= 80%"

4. Circuit Breaker Adaptatif (v2.0)

Selection automatique du profil selon mots-cles:

Profil	Mots-cles	Sans Modif	Erreurs	Max Iter
quick_fix	fix, bug, typo	2	3	10
small_feature	add, implement	3	4	15
medium_feature	feature, create	4	6	25
large_feature	refactor, migrate	5	8	50
exploration	explore, investigate	10	15	100

5. Integration Hooks (Claude Code 2.1.23+)

SessionStart → session-restore.sh