## Introduction

Ralph Loop est un orchestrateur pur qui pilote le processus de developpement iteratif depuis des specifications (PRDs) jusqu'a la livraison du code.

Ralph Loop is a pure orchestrator that drives iterative development from specifications (PRDs) to code delivery.

🔄

##### Architecture de delegation

##### Delegation Architecture

Ralph Load ne genere JAMAIS du code. Il:

Ralph Loop NEVER generates code. It:

- Lit les PRDs depuis le handoff Business Analyse
- Reads PRDs from Business Analyse handoff
- Resout les dependances et ordonne les modules
- Resolves dependencies and module ordering
- Delegue TOUT generation de code a `/apex -d`
- Delegates ALL code generation to `/apex -d`
- Suit la progression, valide les resultats, genere des rapports
- Tracks progress, validates results, generates reports

💠

##### Execution garantie

##### Execution Guarantee

Ralph Loop execute TOUTES les taches du debut a la fin sans interaction utilisateur. Il s'arrete seulement quand: toutes les taches sont completes, le max d'iterations est atteint, une impasse, ou Ctrl+C.

Ralph Loop executes ALL tasks from start to finish with no user interaction. It stops only when: all tasks complete, max iterations reached, dead-end, or Ctrl+C.

## Architecture Architecture

#### 6 Etapes

#### 6 Steps

Etape | Step | Description | Description
--- | --- | --- | ---
00 - Init | 00 - Init | Parse args (-m N, -c TEXT, -v, -r), verifie MCP, setup .ralph/, detecte multi-module | Parse args (-m N, -c TEXT, -v, -r), verify MCP, setup .ralph/, detect multi-module
01 - Task Loading | 01 - Task Loading | Charge/cree les taches depuis prd.json (format v3 unifie avec pre-calcul des taches) | Load/create tasks from prd.json (unified v3 format with pre-computed tasks)
02 - Execute | 02 - Execute | Delegue le module a `/apex -d .ralph/prd.json` (mode delegation) | Delegate module to `/apex -d .ralph/prd.json` (delegate mode)
03 - Commit | 03 - Commit | Valide changements, commit git, update prd.json/progress.txt | Validate changes, git commit, update prd.json/progress.txt
04 - Check | 04 - Check | Verifie completion, entre en COMPACT LOOP (voir compact-loop.md) | Check completion, enter COMPACT LOOP (see compact-loop.md)
05 - Report | 05 - Report | Genere rapports finaux dans .ralph/reports/ | Generate final reports in .ralph/reports/

#### Delegation flow

#### Compact Loop (etape 04)

#### Compact Loop (step 04)

Quand une boucle principale se termine, Ralph entre en Compact Loop pour finaliser les taches restantes:

When a main loop finishes, Ralph enters Compact Loop to finalize remaining tasks:

1. Identifie les taches eligibles (dependances satisfaites)
2. Find eligible tasks (dependencies satisfied)
3. Regroupe par categorie (max 5 par batch)
4. Batch by category (max 5 per batch)
5. Delegue a `/apex -d`
6. Delegate to `/apex -d`
7. Teste et valide
8. Test and validate
9. Commit le PRD
10. Commit PRD
11. Boucle jusqu'a completion
12. Loop until completion

## Commandes Commands

`/ralph-loop [description]` Principal Main

Demarre une nouvelle boucle Ralph avec une description de feature.

Start a new Ralph loop with a feature description.

    /ralph-loop implement user authentication
    /ralph-loop -c "COMPLETE" -m 20 refactor cache
    /ralph-loop -v add payment processing

#### Flags

Flag | Flag | Description | Description
--- | --- | --- | ---
`-m N` | `-m N` | Max iterations avant arret (defaut: 50) | Max iterations before stop (default: 50)
`-c TEXT` | `-c TEXT` | Completion promise text (optionnel) | Completion promise text (optional)
`-v` | `-v` | Logging verbose | Verbose logging
`-r` | `-r` | Resume session precedente | Resume previous session

`/ralph-loop -r` Resume

Resume la derniere session Ralph en cours.

Resume the last Ralph session in progress.

    /ralph-loop -r
    /ralph-loop -r -v
    /ralph-loop -r -m 10

`/ralph-loop:cancel-ralph` Cancel

Annule la boucle Ralph active.

Cancel the active Ralph loop.

    /ralph-loop:cancel-ralph

## Workflow Workflow

#### Cas 1: Module unique

#### Case 1: Single Module

L'agent principal execute la Compact Loop directement (pas de sub-agents).

Main agent runs Compact Loop directly (no sub-agents).

1. Init + Load tasks
2. Init + Load tasks
3. Loop: delegue a /apex -d → valide → commit → prochain batch
4. Loop: delegate to /apex -d → validate → commit → next batch
5. Report final
6. Final report

#### Cas 2: Modules multiples

#### Case 2: Multi-Module

Utilise Agent Teams pour parallelisation (2+ modules depuis BA handoff).

Uses Agent Teams for parallelization (2+ modules from BA handoff).

- Team Lead cree une team (TeamCreate)
- Team Lead creates team (TeamCreate)
- Layer 0: modules fondation (spawned first)
- Layer 0: Foundation modules (spawned first)
- Layer 1+: modules dependant de couches precedentes (spawned en parallel)
- Layer 1+: Modules depending on previous layers (spawned in parallel)
- Verification cross-module → report final → TeamDelete
- Cross-module verification → final report → TeamDelete

#### Flux complet recommande

#### Recommended complete flow

    # 1. Effectuer Business Analyse (interactive)
    /business-analyse MyFeature

    # 2. Attendre handoff - verifie que .ralph/prd.json est genere

    # 3. Lancer Ralph Loop pour implementation
    /ralph-loop -r

    # 4. Ou directement avec description
    /ralph-loop -m 50 implement MyFeature

## File Structure

Ralph cree et gere la structure .ralph/:

Ralph creates and manages .ralph/ structure:

    .ralph/
    ├── prd.json                    # Active task list (unified v3 format)
    ├── progress.txt                # Persistent memory / state
    ├── modules-queue.json          # Multi-module tracking
    ├── prd-{module}.json           # Per-module PRDs
    ├── logs/
    │   ├── ralph-2026-02-16.log
    │   └── apex-2026-02-16.log
    └── reports/
        ├── {feature}.md            # Final markdown report
        └── {feature}.json          # Structured report data

💻

##### prd.json format (v3)

Format unifie avec metadata, liste de taches pre-calculees, dependances, statuts.

Unified format with metadata, pre-computed task list, dependencies, statuses.

## Quand utiliser When to use

✅

##### Recommande pour

##### Recommended for

- Implementation de features apres Business Analyse (recommended flow)
- Implementing features after Business Analyse (recommended flow)
- Modules avec specifications completes en PRD
- Modules with complete specifications in PRD
- Projets multi-modules avec dependances claires
- Multi-module projects with clear dependencies
- Workflows iteratifs avec tests automatiques
- Iterative workflows with automated tests

⚠

##### Non recommande pour

##### Not recommended for

- Taches sans PRD predefini (utiliser /apex ou /business-analyse d'abord)
- Tasks without predefined PRD (use /apex or /business-analyse first)
- Operations one-shot simples
- Simple one-shot operations
- Decisions de design necessitant jugement humain
- Design decisions requiring human judgment

#### Integration avec la pile SmartStack

#### Integration with SmartStack Stack

Flux | Flow | Outils | Tools
--- | --- | --- | ---
Specification | Specification | `/business-analyse` | `/business-analyse`
Implementation | Implementation | `/ralph-loop` → `/apex -d` | `/ralph-loop` → `/apex -d`
Validation | Validation | `/validate-feature` | `/validate-feature`
Release | Release | `/gitflow:10-start release` | `/gitflow:10-start release`