VERSION: 2.88.0

name: loop description: “Ralph Loop pattern with swarm mode: iterative execution until VERIFIED_DONE with multi-agent coordination. Use when: (1) iterative refinement needed, (2) quality gates must pass, (3) automated validation required. Triggers: /loop, ‘loop until done’, ‘iterate’, ‘keep trying’, ‘fix until passing’.” argument-hint: “<task>” user-invocable: true context: fork agent: general-purpose allowed-tools:

LSP
Task
Read
Edit
Write
Bash
Glob
Grep hooks: PreToolUse:
- path: .claude/hooks/validate-lsp-servers.sh match_tool: LSP

/loop - Ralph Loop Pattern (v2.88)

Execute tasks iteratively with automatic quality validation until VERIFIED_DONE signal.

v2.88 Key Changes (MODEL-AGNOSTIC)

Model-agnostic: Uses model configured in ~/.claude/settings.json or CLI/env vars
No flags required: Iterations use the configured default model
Flexible: Works with GLM-5, Claude, Minimax, or any configured model
Settings-driven: Model selection via ANTHROPIC_DEFAULT_*_MODEL env vars

v2.87 Key Changes (UNIFIED SKILLS MODEL)

Skills/Commands unification: All commands now use SKILL.md format
Single source of truth: Skills live in repo, symlinked globally
Version alignment: All skills updated to v2.87.0
Documentation consolidated: Architecture docs in docs/architecture/

Overview

The Ralph Loop is a continuous execution pattern that iterates through EXECUTE -> VALIDATE -> QUALITY CHECK cycles until the task passes all quality gates or reaches the iteration limit.

+------------------------------------------------------------------+
|                    RALPH LOOP PATTERN                             |
+------------------------------------------------------------------+
|                                                                   |
|   +----------+    +--------------+    +-----------------+         |
|   | EXECUTE  |--->|   VALIDATE   |--->| Quality Passed? |         |
|   |   Task   |    | (hooks/gates)|    +--------+--------+         |
|   +----------+    +--------------+             |                  |
|                                          NO <--+--> YES           |
|                                           |         |             |
|                          +----------------+         |             |
|                          v                          v             |
|                   +------------+          +---------------+       |
|                   |  ITERATE   |          | VERIFIED_DONE |       |
|                   | (max 15/30)|          |   (output)    |       |
|                   +-----+------+          +---------------+       |
|                         |                                         |
|                         +----------> Back to EXECUTE              |
|                                                                   |
+------------------------------------------------------------------+

When to Use

Use /loop when:

Iterative refinement needed - Code requires multiple passes to meet quality standards
Quality gates must pass - TypeScript, ESLint, tests, linting must all pass
Automated validation - Let the loop handle retries automatically
Complex implementations - Multi-file changes that need coordination
Research tasks - Gathering information until complete

DO NOT use for:

Simple one-shot tasks (use direct claude call)
Tasks already in orchestration flow (redundant)
Spec refinement workflows (use /adversarial)

Iteration Limits

Model	Max Iterations	Cost vs Claude	Quality	Use Case
Claude (Sonnet/Opus)	15	100% (baseline)	85-90% SWE-bench	Complex reasoning, high accuracy
GLM-5	30	~10%	80%+ SWE-bench	Standard tasks (2x multiplier)
MiniMax M2.1	30	~8%	74% SWE-bench	Standard tasks (2x multiplier)

Model Selection

Default Mode (Claude)

ralph loop "implement OAuth2 authentication"

Uses Claude Sonnet with 15 iteration limit:

Best for: Complex features, security-critical code, architectural changes
Cost: Standard Claude pricing
Quality: 85%+ SWE-bench accuracy

GLM-5 Mode (–with-glm5 flag)

ralph loop "implement OAuth2 authentication" --with-glm5

Uses GLM-5 with 30 iteration limit:

Best for: Standard features, refactoring, testing, documentation
Cost: ~10% of Claude cost
Quality: 80%+ SWE-bench accuracy

MiniMax Mode (–mmc flag)

ralph loop --mmc "implement OAuth2 authentication"

Uses MiniMax M2.1 with 30 iteration limit:

Best for: Non-critical features, exploratory research
Cost: ~8% of Claude cost
Quality: 74% SWE-bench accuracy

CLI Execution

# Claude mode (15 iterations)
ralph loop "implement user authentication with JWT"

# GLM-5 mode (30 iterations)
ralph loop "refactor database queries" --with-glm5

# MiniMax mode (30 iterations)
ralph loop --mmc "refactor database queries to use TypeORM"

# Complex task with specific requirements
ralph loop "add rate limiting to API endpoints with Redis"

Task Tool Invocation (Swarm Mode)

IMPORTANT: /loop uses swarm mode by default with full multi-agent coordination.

Task:
  subagent_type: "general-purpose"
  model: "sonnet"
  run_in_background: true
  max_iterations: 15
  description: "Loop execution with swarm mode"
  team_name: "loop-execution-team"
  name: "loop-lead"
  mode: "delegate"
  prompt: |
    Execute the following task iteratively until VERIFIED_DONE:

    Task: $ARGUMENTS

    Ralph Loop pattern:
    1. EXECUTE - Implement the task
    2. VALIDATE - Run quality gates (tsc, eslint, tests)
    3. CHECK - Did all gates pass?
       - YES -> VERIFIED_DONE
       - NO -> ITERATE (max 15)

    Output: Final implementation + quality report

Agent Teams Integration (v2.88)

Optimal Scenario: Integrated (Agent Teams + Custom Subagents)

This skill uses the INTEGRATED approach combining Agent Teams coordination with Custom Subagent specialization.

Why Scenario C for This Skill

Iterative execution requires tight coordination between implementation and validation phases
Quality gates (TeammateIdle, TaskCompleted) are essential for VERIFIED_DONE guarantee on each iteration
Specialized ralph-coder agents for implementation, ralph-tester for validation
Shared task list tracks iteration progress and blockers
Multi-phase iteration (EXECUTE -> VALIDATE -> CHECK) benefits from team coordination

Configuration

TeamCreate: Create team “loop-{task-hash}” on loop invocation
TaskCreate: Create iteration tasks for each loop cycle
Spawn: Use ralph-coder for implementation, ralph-tester for validation
Hooks: TeammateIdle + TaskCompleted for quality validation on each iteration
Coordination: Shared task list at ~/.claude/tasks/{team}/

Workflow Pattern

TeamCreate(team_name, description)
  → TaskCreate(iteration_n, "Implement iteration {n}")
  → Task(subagent_type="ralph-coder", team_name) for implementation
  → Task(subagent_type="ralph-tester", team_name) for validation
  → TaskUpdate(status="completed") when iteration passes gates
  → Hooks validate quality before marking complete
  → VERIFIED_DONE when all iterations pass

Team Creation Pattern

When /loop is invoked, it automatically creates a dedicated team for the iteration:

# Automatic team creation
TeamCreate(
  team_name: "loop-{task-hash}",
  description: "Iterative execution: {task}"
)

# Spawn implementation teammate
Task(
  subagent_type: "ralph-coder",
  team_name: "loop-{task-hash}"
)

# Spawn validation teammate
Task(
  subagent_type: "ralph-tester",
  team_name: "loop-{task-hash}"
)

Iteration Execution Flow

Each iteration follows this pattern:

Phase 1: Implementation
- Spawn ralph-coder teammate
- Execute task implementation
- Teammate reports progress via TaskUpdate
Phase 2: Validation
- Spawn ralph-tester teammate
- Run quality gates
- Collect validation results
Phase 3: Hook Verification
- TeammateIdle hook triggers quality checks
- task-completed-quality-gate.sh validates before completion
- Exit 2 from hook = keep working with feedback
- Exit 0 = proceed to next phase
Phase 4: Decision
- All gates pass → VERIFIED_DONE
- Any gate fails → Iterate (max 15/30)

Hook Integration Points

Hook	Trigger	Purpose
`teammate-idle-quality-gate.sh`	TeammateIdle	Quality checks before idle
`task-completed-quality-gate.sh`	TaskCompleted	Final validation before completion
`ralph-subagent-start.sh`	SubagentStart	Load Ralph context into teammates
`glm5-subagent-stop.sh`	SubagentStop	Quality gates when teammate stops

Team Composition

When /loop is invoked, it automatically spawns:

Role	Purpose	Count
Leader	Loop coordinator, iteration management	1
ralph-coder	Implementation specialist	1
ralph-tester	Quality validation specialist	1

Total: 3 agents working in parallel (1 leader + 2 teammates)

Task Coordination

# Leader creates iteration task
TaskCreate(
  subject: "Implement iteration {n}",
  description: "{task requirements}",
  activeForm: "Implementing iteration {n}"
)

# Assign to coder
TaskUpdate(
  taskId: "{id}",
  owner: "ralph-coder",
  status: "in_progress"
)

# Coder completes work
TaskUpdate(
  taskId: "{id}",
  status: "completed"
)

# Leader validates, then marks VERIFIED_DONE or iterates

VERIFIED_DONE Guarantee

The Agent Teams system ensures VERIFIED_DONE through:

TeammateIdle Hook: Validates work quality before any teammate goes idle
TaskCompleted Hook: Final validation gate before task completion
Exit 2 Feedback: Hooks return exit 2 to request fixes with specific feedback
Task Coordination: TaskUpdate system tracks progress and blockers

This creates a quality feedback loop that prevents completion until all standards are met.

Output Location

# Logs saved to ~/.ralph/logs/
ls ~/.ralph/logs/loop-*.log

# View last loop execution
tail -f ~/.ralph/logs/loop-latest.log

Pattern Details

Loop Structure

iteration=0
max_iterations=15  # or 30 for GLM-5/MiniMax

while [[ $iteration -lt $max_iterations ]]; do
    # Step 1: EXECUTE
    implement_task

    # Step 2: VALIDATE
    run_quality_gates  # tsc, eslint, tests, semgrep

    # Step 3: CHECK
    if all_gates_passed; then
        echo "VERIFIED_DONE"
        exit 0
    fi

    # Step 4: ITERATE
    ((iteration++))
    analyze_failures
    apply_fixes
done

# Max iterations reached without VERIFIED_DONE
exit 1

Quality Gates Integration

Each iteration runs quality gates:

TypeScript: tsc --noEmit
ESLint: eslint .
Tests: npm test or pytest
Security: semgrep --config=auto
Custom: Project-specific gates

Stop Hook Integration

The loop integrates with the Stop hook:

# Initialize state
.claude/scripts/ralph-state.sh init "$SESSION_ID" loop "$TASK"

# On VERIFIED_DONE
.claude/scripts/ralph-state.sh complete "$SESSION_ID" loop

# On failure
.claude/scripts/ralph-state.sh fail "$SESSION_ID" loop "$ERROR"

Anti-Patterns

Never use infinite loops (always set max_iterations)
Never skip quality gates (defeats the purpose)
Never use for one-shot tasks (use direct execution)
Never nest loops (causes exponential iterations)

Completion Criteria

VERIFIED_DONE requires ALL:

All quality gates passed
No TypeScript errors
No ESLint errors
Tests passing
Security scan clean (no P0/P1 findings)

Related Skills

/orchestrator - Full orchestration workflow
/gates - Quality validation gates
/adversarial - Spec refinement
/parallel - Parallel subagent execution
/retrospective - Post-task analysis

Action Reporting (v2.93.0)

Esta skill genera reportes automáticos completos para trazabilidad:

Reporte Automático

Cuando esta skill completa, se genera automáticamente:

En la conversación de Claude: Resultados visibles
En el repositorio: docs/actions/loop/{timestamp}.md
Metadatos JSON: .claude/metadata/actions/loop/{timestamp}.json

Contenido del Reporte

Cada reporte incluye:

✅ Summary: Descripción de la tarea ejecutada
✅ Execution Details: Duración, iteraciones, archivos modificados
✅ Results: Errores encontrados, recomendaciones
✅ Next Steps: Próximas acciones sugeridas

Ver Reportes Anteriores

# Listar todos los reportes de esta skill
ls -lt docs/actions/loop/

# Ver el reporte más reciente
cat $(ls -t docs/actions/loop/*.md | head -1)

# Buscar reportes fallidos
grep -l "Status: FAILED" docs/actions/loop/*.md

Generación Manual (Opcional)

source .claude/lib/action-report-lib.sh
start_action_report "loop" "Task description"
# ... ejecución ...
complete_action_report "success" "Summary" "Recommendations"

Referencias del Sistema

Action Reports System - Documentación completa
action-report-lib.sh - Librería helper
action-report-generator.sh - Generador
Unified Architecture v2.88
Skills/Commands Unification
Claude Code Skills Documentation