git:20260306.6aec60a to git:20260306.1c6b68d

74 added, 64 removed. Audit A to A.

---

name: ralph-wiggum-codex

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

+ description: Use when a coding task needs an objective-first long-running loop with fresh-context work and review phases, explicit acceptance criteria, resumable state, and real blocked handling.

---

# Ralph Wiggum For Codex

- Codex-native long-running refinement loop.

+ Codex-native Ralph loop for long-running autonomous task completion.

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

+ This skill is designed to be invoked as `$ralph-wiggum-codex`. The shell runner is support infrastructure for the skill, not the product story.

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

+ - The task is too large or uncertain for a single turn.

+ - You want the agent centered on the user request and acceptance criteria, not just test output.

+ - You want a mandatory work phase followed by a fresh-context review phase.

+ - You need resumable state, explicit blocked handling, and long-run drift control.

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.

+ - The user wants manual turn-by-turn control.

+ - The task is mostly a prompt rewrite, not execution. Use `$ralph-prompt-generator` first in that case.

## Optional Prompt Generator

- When the objective or guardrails are genuinely unclear, invoke `$ralph-prompt-generator` first to run the staged prompt-improver workflow for this skill.

+ When the request is underspecified, invoke `$ralph-prompt-generator` first to turn it into a Ralph-ready prompt file.

Use the companion first when:

- - Validation commands are unknown or incomplete.

- - Scope/progress paths are unclear.

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

+ - The objective is fuzzy.

+ - Acceptance criteria are missing.

+ - Source-of-truth artifacts are unclear.

+ - You want review checkpoints before starting the long run.

Companion handoff pattern:

1. Run `$ralph-prompt-generator` with the raw request.

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.

- 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

- - Runtime caps (`max-iterations`, `max-stagnant-iterations`, timeout settings)

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

+ - objective text

+ - acceptance criteria

+ - optional source-of-truth artifacts

+ - optional verification commands

+ - progress scopes (`--progress-scope`) for anti-no-op protection

+ - runtime caps when the run needs them

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

- - `objective.md` (objective to reload every iteration)

- - `feedback.md` (optional operator steering)

+ 2. Materialize repo-backed state under `<cwd>/.codex/ralph-loop/`:

+ - `objective.md`

+ - `acceptance-criteria.md`

+ - `feedback.md`

+ - `work-summary.md`

+ - `review-feedback.md`

+ - `review-result.txt`

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

+ 3. Start the loop runner in objective-first mode.

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

+ 4. For each iteration:

+ - run a fresh-context work phase

+ - run optional verification

+ - run a fresh-context review phase

+ - continue until the reviewer can honestly ship the task or confirm a real blocker

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

+ 5. If blocked, capture the blocker in `RALPH-BLOCKED.md`, stop with `task_blocked`, and wait for updated task/feedback files before resuming.

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

+ --acceptance-file /path/to/repo/.codex/ralph-loop/acceptance-criteria.md \

--feedback-file /path/to/repo/.codex/ralph-loop/feedback.md \

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

+ ## Core Loop Behavior

- 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

+ The runner is a mandatory work/review loop:

+ - Work phase: executes against the objective, acceptance criteria, source of truth, and feedback.

+ - Optional verification: runs after the work phase when configured.

+ - Review phase: re-enters with fresh context and decides `SHIP`, `REVISE`, or `BLOCKED`.

- ## Output Contract

+ Completion is objective-first:

+ - The task is complete only when the work phase reports `COMPLETE`, the review phase decides `SHIP`, and any configured verification passes.

+ - A real blocker stops the loop as `task_blocked`.

+ - `--progress-scope` plus `no_change_justification` only prevents fake no-op completion. It is not the product definition of success.

- 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`

+ ## Work and Review Contracts

- Schema fields:

+ Work schema (`work-schema.json`):

- `status`: `IN_PROGRESS`, `BLOCKED`, `COMPLETE`

+ - `assessment`: concise statement of progress against the objective and acceptance criteria

- `evidence`: non-empty array of concrete evidence

- `next_step`: one highest-impact next step

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

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

+ - `blocker_reason` (optional but required when `status=BLOCKED`)

+ - `no_change_justification` (optional)

+ Review schema (`review-schema.json`):

+ - `decision`: `SHIP`, `REVISE`, `BLOCKED`

+ - `assessment`: concise review judgment

+ - `feedback`: actionable review guidance or ship confirmation

+ - `evidence`: non-empty array of concrete evidence

## 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/objective.md`

+ - `.codex/ralph-loop/acceptance-criteria.md`

- `.codex/ralph-loop/feedback.md`

+ - `.codex/ralph-loop/work-summary.md`

+ - `.codex/ralph-loop/review-feedback.md`

+ - `.codex/ralph-loop/review-result.txt`

+ - `.codex/ralph-loop/RALPH-BLOCKED.md`

+ - `.codex/ralph-loop/.ralph-complete`

+ - `.codex/ralph-loop/work-schema.json`

+ - `.codex/ralph-loop/review-schema.json`

+ - `.codex/ralph-loop/iteration-history.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)

+ - `.codex/ralph-loop/codex/iteration-<n>-<phase>-attempt-<m>.jsonl`

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

+ ## Stop Reasons

+ - `task_complete`

+ - `task_blocked`

+ - `max_iterations_reached`

+ - `max_consecutive_failures_reached`

+ - `max_stagnant_iterations_reached`

+ - `stop_file_detected`

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