Ralph Loop (Agent Mode)

Ralph Loop

Overview

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.

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):

Non-interactive CLIs (file-based):

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  \"$(cat PROMPT.md)\""
   - workdir: 
   - background: true
   - pty: true
   - yieldMs: 60000
   - timeout: 3600
   

2. Capture session ID from exec tool response

3. Use process tool to monitor:

   process tool with:
   - action: "poll"
   - sessionId: 
   
   process tool with:
   - action: "log"
   - sessionId: 
   - offset: -30  (for recent output)
   

4. Check completion by reading IMPLEMENTATION_PLAN.md for sentinel text

5. Clean up with process kill if needed:

   process tool with:
   - action: "kill"
   - sessionId: 
   

Benefits: TTY support, real-time logs, timeout handling, parallel sessions, workdir isolation

Agent Workflow

1) Gather Inputs

Required:

Optional:

Auto-detect:

2) Requirements → Specs (Optional)

If requirements are unclear:

3) PROMPT.md + AGENTS.md

PROMPT.md references:

AGENTS.md includes:

4) Prompt Templates

PLANNING Prompt (no implementation):

You are running a Ralph PLANNING loop for this goal: .
Read specs/* and the current codebase. Only update IMPLEMENTATION_PLAN.md.
Rules:
Do not implement
Do not commit
Create a prioritized task list
Write down questions if unclear
Completion:
When plan is ready, add: STATUS: PLANNING_COMPLETE

BUILDING Prompt:

You are running a Ralph BUILDING loop for this goal: .
Context: specs/*, IMPLEMENTATION_PLAN.md, AGENTS.md
Tasks:
1) Pick the most important task
2) Investigate code
3) Implement
4) Run backpressure commands from AGENTS.md
5) Update IMPLEMENTATION_PLAN.md
6) Update AGENTS.md with learnings
7) Commit with clear message
Completion:
When all done, add: STATUS: COMPLETE

5) CLI Command Reference

The agent constructs command strings using these patterns:

| CLI | Command String Pattern | |-----|----------------------| | OpenCode | opencode run --model "$(cat PROMPT.md)" | | Codex | codex exec "$(cat PROMPT.md)" (requires git) | | Claude Code | claude "$(cat PROMPT.md)" | | Pi | pi --provider --model -p "$(cat PROMPT.md)" | | Goose | goose run "$(cat PROMPT.md)" |

Common flags:

Detailed Agent Tool Usage Examples

Example 1: OpenCode Ralph Loop

Agent executes this sequence:

Step 1: Launch OpenCode with exec tool
{
  command: "opencode run --model github-copilot/claude-opus-4.5 \"$(cat PROMPT.md)\"",
  workdir: "/path/to/project",
  background: true,
  pty: true,
  timeout: 3600,
  yieldMs: 60000
}
Step 2: Capture session ID from response
sessionId: "abc123"
Step 3: Monitor with process tool every 10-30 seconds
{
  action: "poll",
  sessionId: "abc123"
}
Step 4: Check recent logs
{
  action: "log",
  sessionId: "abc123",
  offset: -30
}
Step 5: Read IMPLEMENTATION_PLAN.md to check for completion
Look for: "STATUS: COMPLETE" or "STATUS: PLANNING_COMPLETE"
Step 6: If complete or timeout, cleanup
{
  action: "kill",
  sessionId: "abc123"
}

Example 2: Codex with Full Auto

Agent tool calls:

exec tool:
{
  command: "codex exec --full-auto --model anthropic/claude-opus-4 \"$(cat PROMPT.md)\"",
  workdir: "/path/to/project",
  background: true,
  pty: true,
  timeout: 3600
}
Then monitor with process tool as above

Completion Detection

Use flexible regex to match variations:

grep -Eq "STATUS:?\s*(PLANNING_)?COMPLETE" IMPLEMENTATION_PLAN.md

Matches:

Safety & Safeguards

Auto-Approval Flags (Risky!)

Escape Hatches

Best Practices

Troubleshooting

| Problem | Solution | |---------|----------| | OpenCode hangs | Ensure agent uses exec tool with pty: true | | Session won't start | Check CLI path, git repo, command syntax | | Completion not detected | Verify sentinel format in IMPLEMENTATION_PLAN.md | | Process timeout | Agent should increase timeout parameter or simplify tasks | | Parallel conflicts | Agent should use git worktrees for isolation | | Can't see progress | Agent should use process tool with action: "log" |

License

MIT

Credits

This skill builds upon work by:

Key improvement: Uses OpenClaw's exec tool with pty: true to provide TTY for interactive CLIs, solving the hanging issue that occurs with simple background bash execution.

1. Start small: Test with 1-2 iterations first 2. Workdir isolation: Prevent reading unrelated files 3. Set timeouts: Default 1h may not fit all tasks 4. Monitor actively: Check logs, don't terminate prematurely 5. Requirements first: Clear specs before building 6. Backpressure early: Add tests from the start