ralph-loop
The ralph-loop skill operates Ralph orchestration loops by running, monitoring, and recovering loop executions through CLI commands. Use it when managing ralph run operations, inspecting loop state and diagnostics, resuming suspended loops, merging completed worktree results, or debugging unexpected behavior in Ralph's task orchestration system.
git clone --depth 1 https://github.com/mikeyobrien/ralph-orchestrator /tmp/ralph-loop && cp -r /tmp/ralph-loop/skills/ralph-loop ~/.claude/skills/ralph-loopSKILL.md
# Ralph Loop Use this skill to operate Ralph loops from the outside. ## Use This Skill For - Starting or continuing a Ralph run with the right `-c` and `-H` inputs - Inspecting loop state, worktrees, logs, history, and diffs - Resuming a hook-suspended loop - Merging or discarding completed worktree loops - Debugging unexpected loop behavior with current diagnostics files ## Workflow 1. Start with `ralph loops list` or `ralph loops list --json` to establish the current state. 2. If the user wants execution, run `ralph run ...` with the right core config and hats source. 3. If the loop is stuck or suspicious, inspect `logs`, `history`, and `diff` before changing state. 4. If the loop is suspended, read `.ralph/suspend-state.json` and use `ralph loops resume <id>`. 5. If a loop is queued or in `needs-review`, inspect the diff first, then use `merge`, `process`, `retry`, or `discard` as appropriate. 6. Use diagnostics when you need detailed evidence about hats, events, tool calls, parse errors, or performance. ## Guardrails - Prefer the CLI over direct edits to `.ralph` state files. - Treat tasks and memories as the canonical runtime systems; do not center scratchpad as the primary state model. - Inspect diffs before merging. - Only remove lock or queue artifacts when the underlying process is confirmed dead. - Manual edits under `.ralph/` are last-resort recovery steps and should be called out explicitly when used. ## Read These References When Needed - For command recipes and operator flows: `references/commands.md` - For diagnostics files and suspend-state details: `references/diagnostics.md`
Guides implementation of code tasks using test-driven development in an Explore, Plan, Code, Commit workflow. Acts as a Technical Implementation Partner and TDD Coach — following existing patterns, avoiding over-engineering, and producing idiomatic, modern code.
Generates structured .code-task.md files from descriptions or PDD implementation plans. Auto-detects input type, creates properly formatted tasks with Given-When-Then acceptance criteria.
Use when testing Ralph's hat collection presets, validating preset configurations, or auditing the preset library for bugs and UX issues.
Lists all code tasks in the repository with their status, dates, and metadata. Useful for getting an overview of pending work or finding specific tasks.
Transforms a rough idea into a detailed design document with implementation plan. Follows Prompt-Driven Development — iterative requirements clarification, research, design, and planning.
Browser automation via Playwriter (remorses) using persistent Chrome sessions and the full Playwright Page API.
Use when creating animated demos (GIFs) for pull requests or documentation. Covers terminal recording with asciinema and conversion to GIF/SVG for GitHub embedding.
Introspect, explain, and improve Ralph Orchestrator using its published llms.txt doc map. Use this skill whenever the user asks questions about Ralph's behavior, wants to understand how a Ralph internal works (event loop, hats, memories, tasks, backends, presets), debug an unfamiliar failure mode, or propose a code change to the ralph-orchestrator repo. The skill teaches the agent to discover authoritative answers from the live docs via llms.txt before guessing, and to scope improvements through the published architecture rather than the local checkout alone.