ralph-loop

# Ralph Loop

## Overview
This skill guides **OpenClaw agents** to execute Ralph Loop workflows using the `exec` and `process` tools. The agent orchestrates AI coding agent sessions following the Ralph playbook flow:

1) **Define Requirements** → JTBD → Focus Topics → `specs/*.md`
2) **PLANNING Loop** → Create/update `IMPLEMENTATION_PLAN.md` (do not implement)
3) **BUILDING Loop** → Implement tasks, run tests (backpressure), update plan, commit

The loop persists context via `PROMPT.md` + `AGENTS.md` (loaded each iteration) and the plan/specs on disk.

## How This Skill Works

This skill generates instructions for **OpenClaw agents** to execute Ralph Loops using the `exec` and `process` tools.

- The agent calls `exec` tool with the coding agent command
- Uses `pty: true` to provide TTY for interactive CLIs
- Uses `background: true` for monitoring capabilities
- Uses `process` tool to monitor progress and detect completion

**Important**: Users don't run these scripts directly - the OpenClaw agent executes them using its tool capabilities.

---

## TTY Requirements

Some coding agents **require a real terminal (TTY)** to work properly, or they will hang:

**Interactive CLIs (need TTY)**:
- OpenCode, Codex, Claude Code, Pi, Goose

**Non-interactive CLIs (file-based)**:
- aider, custom scripts

**Solution**: Use **exec + process mode** for interactive CLIs, simple loops for file-based tools.

---

## Agent Tool Usage Patterns

### Interactive CLIs (Recommended Pattern)

For OpenCode, Codex, Claude Code, Pi, and Goose - these require TTY support:

**When I (the agent) receive a Ralph Loop request, I will:**

1. **Use exec tool** to launch the coding agent:
   ```
   exec tool with parameters:
   - command: "opencode run --model <MODEL> \"$(cat PROMPT.md)\""
   - workdir: <project_path>
   - background: true
   - pty: true
   - yieldMs: 60000
   - timeout: 3600
   ```

2. **Capture session ID** from exec tool response

3. **Use process tool** to monitor:
   ```
   proce...

# Ralph Loop

## Acknowledgments

This skill is inspired by and improves upon:

1. **Ralph Loop** by @jordyvandomselaar  
   https://github.com/openclaw/skills/blob/main/skills/jordyvandomselaar/ralph-loop/SKILL.md

2. **Coding Agent** by @steipete  
   https://github.com/openclaw/skills/blob/main/skills/steipete/coding-agent/SKILL.md

## Key Improvement

**Solved the hanging issue** with coding agents in ralph-loop: The original pure background bash mode couldn't provide TTY for interactive CLIs (OpenCode, Codex, Claude Code), causing processes to hang.

**Solution**: Uses OpenClaw's **exec + process mode** to provide a real TTY environment with background monitoring and real-time log access.

---

## Introduction

Ralph Loop is a skill that guides **OpenClaw agents** to execute Ralph Wiggum playbook workflows using the `exec` and `process` tools. The agent orchestrates AI coding agent sessions, dividing software development into two phases:

1. **PLANNING**: Analyze requirements, create implementation plan, no code writing
2. **BUILDING**: Implement features according to plan, run tests, commit code

## How This Works

**For OpenClaw Agents**: This skill teaches you how to use the `exec` and `process` tools to orchestrate Ralph Loops.

**For Users**: You ask your OpenClaw agent to "create a Ralph Loop" and it will:
- Use its `exec` tool to launch coding agents (OpenCode, Codex, etc.)
- Use its `process` tool to monitor progress
- Check completion conditions by reading files
- Report progress back to you

**You don't run scripts directly** - your OpenClaw agent handles everything using its tool capabilities.

## Core Features

### ✅ Agent Tool Integration
- Uses OpenClaw's `exec` tool for launching coding agents
- Uses OpenClaw's `process` tool for monitoring and control
- Proper TTY support via `pty: true` parameter

### ✅ Interactive CLI Support
- Provides real terminal environment for OpenCode, Codex, Claude Code, Goose
- Solves hanging issues that occur witho...