feat: task/pipeline loops — repeat until exit condition met (Ralph Wiggum pattern)

[dean0x]

Task/Pipeline Loops

Summary

Enable repeating a task or pipeline until an exit condition is met. Inspired by the Ralph Wiggum Loop pattern — feed a spec to an agent, check if done, repeat until success.

Use Cases

• "Keep implementing items from the spec until npm test && npm run build passes"
• "Run code review → fix issues loop until no issues found"
• "Retry flaky deployment pipeline until health check passes (max 3 attempts)"

Proposed Interface

CLI

# Single task loop
beat loop "implement next item from spec.md" \
  --until "npm test && npm run build" \
  --max-iterations 10

# Pipeline loop
beat loop --pipeline \
  --step "implement next spec item" \
  --step "run tests and fix failures" \
  --until "npm test" \
  --max-iterations 5

MCP

await CreateLoop({
  prompt: "implement next item from the spec",
  exitCondition: "npm test && npm run build",
  maxIterations: 10,
  agent: "claude",
});

Key Design Decisions

• Exit condition: Shell command that returns exit code 0 for "done". Evaluated after each iteration.
• Max iterations: Required safety cap to prevent infinite loops.
• Context carry-forward: Each iteration starts fresh (Ralph pattern) vs. continues from checkpoint. Could support both modes.
• Spec injection: How does the spec/plan get fed to each iteration? Via prompt, file reference, or CLAUDE.md?
• Loop + Schedule composition: A scheduled loop ("every night, loop until spec is done") combines both features.

Building Blocks Already in Place

• Task delegation and execution — core
• Checkpoints and continueFrom — v0.4.0
• Pipelines — v0.4.1
• Multi-agent support — v0.5.0

Open Questions

1. Should the exit condition run in the task's working directory?
2. Should loop state (iteration count, last result) be persisted?
3. How to handle partial progress — if iteration 5/10 gets halfway, should iteration 6 continue from checkpoint or start fresh?
4. Should there be a "cooldown" between iterations (prevent hammering rate limits)?

References

• Everything is a Ralph Loop — Geoffrey Huntley
• Ralph Wiggum as a "software engineer"

Version

Target: v0.6.0