git:20260304.41c0aa3 to git:20260306.6aec60a

18 added, 21 removed. Audit A to A.

---

name: ralph-wiggum-codex

- description: Use when a coding task needs multi-iteration autonomous refinement with explicit completion criteria, validation commands, resumable loop state, and long-running progress control.

+ description: Use when a coding task needs repeated implement-validate-fix cycles with clear stop conditions and resumable state.

---

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

+ ## Optional Prompt Generator

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

+ When the objective or guardrails are genuinely unclear, invoke `$ralph-prompt-generator` first to run the staged prompt-improver workflow 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.

+ - The task is high risk and you want critique, revision, and review checkpoints before execution.

+ - You want the prompt saved as a reusable file in the repo.

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`

+ 2. Review the saved planning artifacts after Steps 1-2.

+ 3. Review the saved critique after Step 4.

+ 4. Use the final prompt saved at `docs/prompt-improver-spec/final-prompts/<prompt-name>.md`.

+ 5. Run the short Ralph-ready invocation snippet it returns at the end.

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

+ Skip the companion when the task is already clear enough to run directly.

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

+ - Only pin `codex-bin`, `model`, `profile`, or compatibility fields when the user or environment actually needs them

+ Default posture:

+ - Prefer the simplest workable invocation.

+ - Infer missing validations/scopes from repo context when practical.

+ - Do not force the companion generator or advanced flags when the task is already clear.

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

```bash

~/.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

+ - `no_change_justification` (optional): include only for justified no-change iterations

+ - `completion_promise` (optional): include only when compatibility mode is enabled

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

```bash

~/.codex/skills/ralph-wiggum-codex/scripts/ralph-loop-codex.sh \

--cwd /path/to/repo \

--resume

```

Stop safely:

```bash

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`