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

Delegation flow

Ralph Loop (Orchestrator) 00 Init / 01 Load 03 Commit PRD 04 Check / 05 Report /apex -d PRD state APEX (Executor) Analysis + Planning Code Generation Generated Code Entities Services Controllers Tests Frontend Pages Loop until complete

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