ralph-loop

SKILL: Ralph Loop

Purpose: Autonomous completion loop - iterate until all tests pass, coverage met, type-check clean Target: Coder, Tester, Validator teammates ⚠️ Teammates Only: This skill is for coder/tester teammates in Agent Teams. Team Lead spawns teammates who execute this loop autonomously.

---

Quick Start

When to Use This Skill

• After first code change (Entry point)
• Tests failing or coverage low
• Type-check errors present
• Lint violations found

Quick Reference

# Ralph Loop: Autonomous iteration
iteration=0
max_iterations=7
early_escalation=false

# Check for --early flag or architecture-related failure
if [[ "$*" == *"--early"* ]] || is_architecture_failure; then
  max_iterations=2
  early_escalation=true
fi

while [ $iteration -lt $max_iterations ]; do
  echo "Iteration $((iteration + 1))/$max_iterations"

  # Run verification
  if run_all_checks; then
    echo "✓ All quality gates passed"
    break
  fi

  # Fix failures
  fix_failures

  # Update state
  update_state "$SC" "in_progress" $((iteration + 1))
  ((iteration++))
done

# Complete or escalate
if [ $iteration -eq $max_iterations ]; then
  # Message Team Lead for GPT Architect escalation
  echo "Max iterations reached. Messaging Team Lead for GPT Architect escalation..."
else
  echo "<CODER_COMPLETE>"  # All checks pass
fi

---

Core Concepts

Entry Point

Trigger: Immediately after first code change

Detection:

• Coder teammate makes first edit/write
• Tests run and fail
• Ralph Loop begins automatically
• TeammateIdle hook prevents premature idle on quality check failure

Quality Gates

All must pass before completion:

1. Tests: npm test - All tests pass
2. Coverage: ≥80% overall, ≥90% core modules
3. Type-check: npm run type-check or tsc --noEmit
4. Lint: npm run lint - Zero violations
5. TODOs: All SC TODOs must be [x] before <CODER_COMPLETE>
   • PLAN_PATH from execute-plan prompt OR auto-detect in .pilot/plan/in_progress/
   • grep -q "^- \[ \]" "$PLAN_PATH" must return false (no unchecked items)
6. TaskCompleted Hook: Automatically verifies gates 1-5 when teammate marks task done