Ralph Wiggum For Codex

Codex-native long-running refinement loop.

This skill is designed to be invoked as a Codex skill ($ralph-wiggum-codex). The loop runner script is an internal execution engine for the skill, not the primary user-facing entrypoint.

When To Use

Use this skill when:

• The task is unlikely to finish in one turn.
• You need repeated implement -> validate -> refine cycles.
• You want schema-based completion signaling with resumable state.
• You need unattended or semi-attended long-running execution with drift resistance.

Do not use this skill when:

• The request is a quick one-shot edit or explanation.
• No meaningful validation loop exists.
• The user wants manual step-by-step control each turn.

Companion Prompt Generator (Recommended Handoff)

When objectives are ambiguous or missing loop configuration, invoke $ralph-prompt-generator first to produce a ready-to-run block for this skill.

Use the companion first when:

• Validation commands are unknown or incomplete.
• Scope/progress paths are unclear.
• Model/reasoning/iteration caps are not specified.
• The task is high risk and you want stronger guardrails before execution.

Companion handoff pattern:

1. Run $ralph-prompt-generator with the raw request.
2. Answer its required question about suggested output sections.
3. Confirm any inferred validations/scopes it proposes (or provide your own).
4. Provide any additional targeted clarifications it requests.
5. Execute the generated block, which should start with:
   • /skills
   • $ralph-wiggum-codex

You can skip the companion when you already have a complete, validated prompt with explicit flags and checks.

Skill-First Operating Contract

When this skill is invoked, execute this flow:

1. Collect or infer:

• cwd
• Objective text
• Validation commands (fastest checks first)
• Progress scopes (--progress-scope) for meaningful edits
• Codex runtime binary/path (--codex-bin) for deterministic runtime selection
• Event stream artifact format (--events-format <tsv|jsonl|both>, default both)
• Whether to persist per-iteration progress artifacts (--progress-artifact)
• Runtime caps (max-iterations, max-stagnant-iterations, timeout settings)
• Completion promise only if compatibility mode is required (deprecated)

2. Prepare loop files under <cwd>/.codex/ralph-loop/:

• objective.md (objective to reload every iteration)
• feedback.md (optional operator steering)

3. Start the loop runner with objective/feedback files and validations.

4. Monitor run artifacts (events.log, run-summary.md, iteration-history.md, validation logs) and report concise progress.

5. If blocked, update feedback.md with corrective guidance and continue (--resume) instead of restarting from scratch.

Execution Command Template

~/.codex/skills/ralph-wiggum-codex/scripts/ralph-loop-codex.sh \
  --cwd /path/to/repo \
  --codex-bin codex \
  --objective-file /path/to/repo/.codex/ralph-loop/objective.md \
  --feedback-file /path/to/repo/.codex/ralph-loop/feedback.md \
  --events-format both \
  --progress-artifact \
  --completion-promise "DONE" \
  --max-iterations 40 \
  --max-stagnant-iterations 6 \
  --progress-scope "src/" \
  --idle-timeout-seconds 900 \
  --hard-timeout-seconds 7200 \
  --timeout-retries 1 \
  --validate-cmd "npm run lint" \
  --validate-cmd "npm run test"

Long-Run Refinement Features

The runner supports long-running autonomy with iterative correction:

• Dynamic objective reload each iteration (--objective-file)
• Live operator feedback ingestion (--feedback-file)
• Auto-generated corrective feedback when codex/validation fails (auto-feedback.md)
• Iteration memory (iteration-history.md) injected into future prompts
• Stagnation detection (--max-stagnant-iterations)
• Scoped no-op prevention (--progress-scope + no_change_justification)
• Default-on watchdog timeouts with controlled retries
• Resumable state and lock-based single-run protection with stale lock recovery

Output Contract

Completion is accepted when all of the following are true:

• codex exec output conforms to .codex/ralph-loop/completion-schema.json
• status is COMPLETE
• Validation commands pass
• Scoped progress gate passes (or includes no_change_justification)
• If compatibility mode is enabled, completion_promise equals --completion-promise

Schema fields:

• status: IN_PROGRESS, BLOCKED, COMPLETE
• evidence: non-empty array of concrete evidence
• next_step: one highest-impact next step
• no_change_justification: required key; non-empty only for justified no-change iterations, else empty string
• completion_promise: required key; compatibility value when configured, else empty string

Core Files

• .codex/ralph-loop/state.env
• .codex/ralph-loop/prompt.txt
• .codex/ralph-loop/events.log
• .codex/ralph-loop/events.jsonl (with --events-format jsonl|both; default both)
• .codex/ralph-loop/completion-schema.json
• .codex/ralph-loop/iteration-history.md
• .codex/ralph-loop/feedback.md
• .codex/ralph-loop/auto-feedback.md
• .codex/ralph-loop/last-message.txt
• .codex/ralph-loop/run-summary.md
• .codex/ralph-loop/progress/ (when --progress-artifact is enabled)
• .codex/ralph-loop/validation/
• .codex/ralph-loop/codex/iteration-<n>-attempt-<m>.jsonl
• .codex/ralph-loop/.lock/meta.env (while active)

events.log remains compatible for existing consumers; JSONL events are additive.

Resume And Stop

Resume:

~/.codex/skills/ralph-wiggum-codex/scripts/ralph-loop-codex.sh \
  --cwd /path/to/repo \
  --resume

Stop safely:

touch /path/to/repo/.codex/ralph-loop/STOP

References

• Harness principles: references/harness-principles.md
• Operational runbook: references/runbook.md
• Reliability vNext: references/reliability-vnext.md