ralph-wiggum

name	ralph-wiggum
description	Long-running iterative development loops with pacing control and verifiable progress. Use when tasks require multiple iterations, many discrete steps, or periodic reflection with clear checkpoints; avoid for simple one-shot tasks or quick fixes.

Ralph Wiggum For Codex

This is an alias skill for the Codex-adapted Ralph workflow. Prefer the same behavior and tool selection described in skills/ralph/SKILL.md.

Available tools:

• ralph_start
• ralph_done
• ralph_status
• ralph_resume
• ralph_stop
• ralph_list
• ralph_cancel
• ralph_archive

When Codex exposes those tools through its host MCP layer, the actual callable names may be host-qualified forms such as mcp__ralph-loop-tools__ralph_start and mcp__ralph-loop-tools__ralph_done rather than bare ralph_start / ralph_done names.

Use this skill when the user explicitly references "Ralph Wiggum", "ralph-wiggum", or asks for Pi-style multi-iteration looping behavior inside Codex.

Task contract and limitations match the main ralph skill:

• Start with a full Markdown task file
• Keep Goals, Checklist, Verification, and Notes
• Continue iterations with ralph_done
• Updating the task file alone does not hand off the iteration; the handoff happens only when ralph_done (or a successful tmux auto-follow built on it) actually advances the loop
• Do not bypass the Ralph control surface with direct internal helper calls such as advance_loop(...); that can advance iteration state without the supported ralph_done handoff semantics or prompt-trigger refresh
• If the host shows the Ralph plugin/skill but does not actually expose callable Ralph tools in the session under either the bare ralph_* names or the host-qualified names such as mcp__ralph-loop-tools__ralph_start, treat that as a host-side MCP exposure failure and report it instead of reading or mutating .tmp/ralph-loop-tools/ state directly
• Before concluding the host is healthy but tools are missing, run scripts/install_codex_plugin.py --check; if it reports stale plugin install/cache state, refresh with scripts/install_codex_plugin.py and restart or reload Codex
• Explicit loop names do not bypass active-loop ownership. If a loop is still active in another Codex session, mutating operations such as ralph_done, ralph_stop, forced restart of that same active loop, or ralph_cancel must fail instead of letting one session change another session's active loop
• Completion is inferred from checklist completion or <promise>COMPLETE</promise> inside the task file
• Pi-like automatic compact-then-follow-up requires tmux; if TMUX is not set, tell the user it is unavailable and do not offer a non-tmux fallback
• Compact is triggered through Codex TUI /compact via tmux, not through a host API
• The tmux follow-up waits for Codex idle state before injecting input and uses Codex rollout-log busy-state checks modeled on Codoxear
• The tmux worker first waits for the triggering turn to reach task_complete/turn_complete/turn_aborted, which avoids Stop-hook timing races with still-running turns
• The tmux worker previews the next prompt, pastes it into tmux, and only then commits the next Ralph iteration; delivery failures leave the loop on the prior iteration and surface the error in ralph_status
• ralph_status can now surface pending continuation and the latest auto-follow failure reason when tmux follow-up does not continue
• Hook-driven session scope comes from the hook event session_id first, and otherwise implicit current-loop resolution uses CODEX_THREAD_ID / CODEX_WEB_RESUME_SESSION_ID instead of one shared global pointer
• If a Ralph process has no session id at all, it should not implicitly adopt another session's owned loop
• The supported no-source deployment refreshes plugin discovery/cache with scripts/install_codex_plugin.py and installs lifecycle hooks through /vePFS-Mindverse/user/intern/ccss/.codex/hooks.json, generated by scripts/install_workspace_hooks.py
• The Stop hook schedules the follow-up worker in the background so compact waits do not block the hook
• The hook launcher resolves ralph_hook.py from the plugin source directory instead of assuming the current project cwd matches the plugin repo
• Hook guidance is injected only for Ralph-generated next-iteration prompts, not for arbitrary prompts that merely mention Ralph