{"id":"f7bb6677-087a-400c-8f29-290f7f193f89","shortId":"PFx6ak","kind":"skill","title":"ralph-wiggum-codex","tagline":"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.","description":"# Ralph Wiggum For Codex\n\nCodex-native Ralph loop for long-running autonomous task completion.\n\nThis skill is designed to be invoked as `$ralph-wiggum-codex`. The shell runner is support infrastructure for the skill, not the product story.\n\n## When To Use\n\nUse this skill when:\n- The task is too large or uncertain for a single turn.\n- You want the agent centered on the user request and acceptance criteria, not just test output.\n- You want a mandatory work phase followed by a fresh-context review phase.\n- You need resumable state, explicit blocked handling, and long-run drift control.\n\nDo not use this skill when:\n- The request is a quick one-shot edit or explanation.\n- The user wants manual turn-by-turn control.\n- The task is mostly a prompt rewrite, not execution. Use `$ralph-prompt-generator` first in that case.\n\n## Optional Prompt Generator\n\nWhen the request is underspecified, invoke `$ralph-prompt-generator` first to turn it into a Ralph-ready prompt file.\n\nUse the companion first when:\n- The objective is fuzzy.\n- Acceptance criteria are missing.\n- Source-of-truth artifacts are unclear.\n- You want review checkpoints before starting the long run.\n\nCompanion handoff pattern:\n1. Run `$ralph-prompt-generator` with the raw request.\n2. Review the saved planning artifacts after Steps 1-2.\n3. Review the saved critique after Step 4.\n4. Use the final prompt saved at `docs/prompt-improver-spec/final-prompts/<prompt-name>.md`.\n5. Run the short Ralph-ready invocation snippet it returns at the end.\n\n## Skill-First Operating Contract\n\nWhen this skill is invoked, execute this flow:\n\n1. Collect or infer:\n- `cwd`\n- objective text\n- acceptance criteria\n- optional source-of-truth artifacts\n- optional verification commands\n- progress scopes (`--progress-scope`) for anti-no-op protection\n- runtime caps when the run needs them\n\n2. Materialize repo-backed state under `<cwd>/.codex/ralph-loop/`:\n- `objective.md`\n- `acceptance-criteria.md`\n- `feedback.md`\n- `work-summary.md`\n- `review-feedback.md`\n- `review-result.txt`\n\n3. Start the loop runner in objective-first mode.\n\n4. For each iteration:\n- run a fresh-context work phase\n- run optional verification\n- run a fresh-context review phase\n- continue until the reviewer can honestly ship the task or confirm a real blocker\n\n5. If blocked, capture the blocker in `RALPH-BLOCKED.md`, stop with `task_blocked`, and wait for updated task/feedback files before resuming.\n\n## Execution Command Template\n\n```bash\n~/.codex/skills/ralph-wiggum-codex/scripts/ralph-loop-codex.sh \\\n  --cwd /path/to/repo \\\n  --objective-file /path/to/repo/.codex/ralph-loop/objective.md \\\n  --acceptance-file /path/to/repo/.codex/ralph-loop/acceptance-criteria.md \\\n  --feedback-file /path/to/repo/.codex/ralph-loop/feedback.md \\\n  --max-iterations 40 \\\n  --max-stagnant-iterations 6 \\\n  --progress-scope \"src/\" \\\n  --idle-timeout-seconds 900 \\\n  --hard-timeout-seconds 7200 \\\n  --timeout-retries 1 \\\n  --validate-cmd \"npm run lint\" \\\n  --validate-cmd \"npm run test\"\n```\n\n## Core Loop Behavior\n\nThe runner is a mandatory work/review loop:\n- Work phase: executes against the objective, acceptance criteria, source of truth, and feedback.\n- Optional verification: runs after the work phase when configured.\n- Review phase: re-enters with fresh context and decides `SHIP`, `REVISE`, or `BLOCKED`.\n\nCompletion is objective-first:\n- The task is complete only when the work phase reports `COMPLETE`, the review phase decides `SHIP`, and any configured verification passes.\n- A real blocker stops the loop as `task_blocked`.\n- `--progress-scope` plus `no_change_justification` only prevents fake no-op completion. It is not the product definition of success.\n\n## Work and Review Contracts\n\nWork schema (`work-schema.json`):\n- `status`: `IN_PROGRESS`, `BLOCKED`, `COMPLETE`\n- `assessment`: concise statement of progress against the objective and acceptance criteria\n- `evidence`: non-empty array of concrete evidence\n- `next_step`: one highest-impact next step\n- `blocker_reason` (optional but required when `status=BLOCKED`)\n- `no_change_justification` (optional)\n\nReview schema (`review-schema.json`):\n- `decision`: `SHIP`, `REVISE`, `BLOCKED`\n- `assessment`: concise review judgment\n- `feedback`: actionable review guidance or ship confirmation\n- `evidence`: non-empty array of concrete evidence\n\n## Core Files\n\n- `.codex/ralph-loop/state.env`\n- `.codex/ralph-loop/objective.md`\n- `.codex/ralph-loop/acceptance-criteria.md`\n- `.codex/ralph-loop/feedback.md`\n- `.codex/ralph-loop/work-summary.md`\n- `.codex/ralph-loop/review-feedback.md`\n- `.codex/ralph-loop/review-result.txt`\n- `.codex/ralph-loop/RALPH-BLOCKED.md`\n- `.codex/ralph-loop/.ralph-complete`\n- `.codex/ralph-loop/work-schema.json`\n- `.codex/ralph-loop/review-schema.json`\n- `.codex/ralph-loop/iteration-history.md`\n- `.codex/ralph-loop/auto-feedback.md`\n- `.codex/ralph-loop/run-summary.md`\n- `.codex/ralph-loop/validation/`\n- `.codex/ralph-loop/codex/iteration-<n>-<phase>-attempt-<m>.jsonl`\n\n## Stop Reasons\n\n- `task_complete`\n- `task_blocked`\n- `max_iterations_reached`\n- `max_consecutive_failures_reached`\n- `max_stagnant_iterations_reached`\n- `stop_file_detected`\n\n## Resume And Stop\n\nResume:\n\n```bash\n~/.codex/skills/ralph-wiggum-codex/scripts/ralph-loop-codex.sh \\\n  --cwd /path/to/repo \\\n  --resume\n```\n\nStop safely:\n\n```bash\ntouch /path/to/repo/.codex/ralph-loop/STOP\n```\n\n## References\n\n- Harness principles: `references/harness-principles.md`\n- Operational runbook: `references/runbook.md`\n- Reliability vNext: `references/reliability-vnext.md`","tags":["ralph","wiggum","codex","mattmagg","agent-skills","agentic-workflows","ai-agents","ai-coding-agent","automation","autonomous-agents","autonomous-coding","codex-skill"],"capabilities":["skill","source-mattmagg","skill-ralph-wiggum-codex","topic-agent-skills","topic-agentic-workflows","topic-ai-agents","topic-ai-coding-agent","topic-automation","topic-autonomous-agents","topic-autonomous-coding","topic-codex","topic-codex-skill","topic-developer-tools","topic-iterative-refinement"],"categories":["ralph-wiggum-codex"],"synonyms":[],"warnings":[],"endpointUrl":"https://skills.sh/MattMagg/ralph-wiggum-codex/ralph-wiggum-codex","protocol":"skill","transport":"skills-sh","auth":{"type":"none","details":{"cli":"npx skills add MattMagg/ralph-wiggum-codex","source_repo":"https://github.com/MattMagg/ralph-wiggum-codex","install_from":"skills.sh"}},"qualityScore":"0.454","qualityRationale":"deterministic score 0.45 from registry signals: · indexed on github topic:agent-skills · 8 github stars · SKILL.md body (5,546 chars)","verified":false,"liveness":"unknown","lastLivenessCheck":null,"agentReviews":{"count":0,"score_avg":null,"cost_usd_avg":null,"success_rate":null,"latency_p50_ms":null,"narrative_summary":null,"summary_updated_at":null},"enrichmentModel":"deterministic:skill-github:v1","enrichmentVersion":1,"enrichedAt":"2026-05-18T19:08:55.619Z","embedding":null,"createdAt":"2026-04-23T13:04:19.398Z","updatedAt":"2026-05-18T19:08:55.619Z","lastSeenAt":"2026-05-18T19:08:55.619Z","tsv":"'-2':257 '/.codex/ralph-loop':345 '/.codex/skills/ralph-wiggum-codex/scripts/ralph-loop-codex.sh':421,700 '/path/to/repo':423,702 '/path/to/repo/.codex/ralph-loop/acceptance-criteria.md':431 '/path/to/repo/.codex/ralph-loop/feedback.md':435 '/path/to/repo/.codex/ralph-loop/objective.md':427 '/path/to/repo/.codex/ralph-loop/stop':708 '1':238,256,302,462 '2':248,338 '3':258,352 '4':265,266,362 '40':439 '5':275,397 '6':444 '7200':458 '900':453 'accept':28,105,215,309,429,491,599 'acceptance-criteria.md':347 'acceptance-fil':428 'action':641 'agent':98 'anti':327 'anti-no-op':326 'array':605,651 'artifact':223,253,316 'assess':590,636 'attempt':673 'autonom':49 'back':342 'bash':420,699,706 'behavior':477 'block':34,130,399,408,520,555,588,624,635,680 'blocker':396,402,549,617 'cap':332 'captur':400 'case':181 'center':99 'chang':561,626 'checkpoint':229 'cmd':465,471 'code':8 'codex':4,39,41,63 'codex-n':40 'codex/ralph-loop/.ralph-complete':665 'codex/ralph-loop/acceptance-criteria.md':659 'codex/ralph-loop/auto-feedback.md':669 'codex/ralph-loop/codex/iteration-':672 'codex/ralph-loop/feedback.md':660 'codex/ralph-loop/iteration-history.md':668 'codex/ralph-loop/objective.md':658 'codex/ralph-loop/ralph-blocked.md':664 'codex/ralph-loop/review-feedback.md':662 'codex/ralph-loop/review-result.txt':663 'codex/ralph-loop/review-schema.json':667 'codex/ralph-loop/run-summary.md':670 'codex/ralph-loop/state.env':657 'codex/ralph-loop/validation':671 'codex/ralph-loop/work-schema.json':666 'codex/ralph-loop/work-summary.md':661 'collect':303 'command':319,418 'companion':208,235 'complet':51,521,529,536,569,589,678 'concis':591,637 'concret':607,653 'configur':506,544 'confirm':393,646 'consecut':685 'context':22,122,370,380,514 'continu':383 'contract':293,581 'control':137,163 'core':475,655 'criteria':29,106,216,310,492,600 'critiqu':262 'cwd':306,422,701 'decid':516,540 'decis':632 'definit':575 'design':55 'detect':694 'docs/prompt-improver-spec/final-prompts':273 'drift':136 'edit':152 'empti':604,650 'end':288 'enter':511 'evid':601,608,647,654 'execut':172,299,417,487 'explan':154 'explicit':27,129 'failur':686 'fake':565 'feedback':433,497,640 'feedback-fil':432 'feedback.md':348 'file':205,414,426,430,434,656,693 'final':269 'first':14,178,195,209,291,360,525 'flow':301 'follow':117 'fresh':21,121,369,379,513 'fresh-context':20,120,368,378 'fuzzi':214 'generat':177,184,194,243 'guidanc':643 'handl':35,131 'handoff':236 'har':710 'hard':455 'hard-timeout-second':454 'highest':613 'highest-impact':612 'honest':388 'idl':450 'idle-timeout-second':449 'impact':614 'infer':305 'infrastructur':69 'invoc':282 'invok':58,190,298 'iter':365,438,443,682,690 'jsonl':674 'judgment':639 'justif':562,627 'larg':88 'lint':468 'long':16,47,134,233 'long-run':15,46,133 'loop':18,44,355,476,484,552 'mandatori':114,482 'manual':158 'materi':339 'max':437,441,681,684,688 'max-iter':436 'max-stagnant-iter':440 'md':274 'miss':218 'mode':361 'most':167 'nativ':42 'need':10,126,336 'next':609,615 'no-op':566 'non':603,649 'non-empti':602,648 'npm':466,472 'object':13,212,307,359,425,490,524,597 'objective-fil':424 'objective-first':12,358,523 'objective.md':346 'one':150,611 'one-shot':149 'op':329,568 'oper':292,713 'option':182,311,317,374,498,619,628 'output':110 'pass':546 'pattern':237 'phase':26,116,124,372,382,486,504,508,534,539 'plan':252 'plus':559 'prevent':564 'principl':711 'product':75,574 'progress':320,323,446,557,587,594 'progress-scop':322,445,556 'prompt':169,176,183,193,204,242,270 'protect':330 'quick':148 'ralph':2,36,43,61,175,192,202,241,280 'ralph-blocked.md':404 'ralph-prompt-gener':174,191,240 'ralph-readi':201,279 'ralph-wiggum-codex':1,60 'raw':246 're':510 're-ent':509 'reach':683,687,691 'readi':203,281 'real':33,395,548 'reason':618,676 'refer':709 'references/harness-principles.md':712 'references/reliability-vnext.md':718 'references/runbook.md':715 'reliabl':716 'repo':341 'repo-back':340 'report':535 'request':103,145,187,247 'requir':621 'resum':30,127,416,695,698,703 'retri':461 'return':285 'review':25,123,228,249,259,381,386,507,538,580,629,638,642 'review-feedback.md':350 'review-result.txt':351 'review-schema.json':631 'revis':518,634 'rewrit':170 'run':17,48,135,234,239,276,335,366,373,376,467,473,500 'runbook':714 'runner':66,356,479 'runtim':331 'safe':705 'save':251,261,271 'schema':583,630 'scope':321,324,447,558 'second':452,457 'shell':65 'ship':389,517,541,633,645 'short':278 'shot':151 'singl':93 'skill':53,72,82,142,290,296 'skill-first':289 'skill-ralph-wiggum-codex' 'snippet':283 'sourc':220,313,493 'source-mattmagg' 'source-of-truth':219,312 'src':448 'stagnant':442,689 'start':231,353 'state':31,128,343 'statement':592 'status':585,623 'step':255,264,610,616 'stop':405,550,675,692,697,704 'stori':76 'success':577 'support':68 'task':9,50,85,165,391,407,527,554,677,679 'task/feedback':413 'templat':419 'test':109,474 'text':308 'timeout':451,456,460 'timeout-retri':459 'topic-agent-skills' 'topic-agentic-workflows' 'topic-ai-agents' 'topic-ai-coding-agent' 'topic-automation' 'topic-autonomous-agents' 'topic-autonomous-coding' 'topic-codex' 'topic-codex-skill' 'topic-developer-tools' 'topic-iterative-refinement' 'touch':707 'truth':222,315,495 'turn':94,160,162,197 'turn-by-turn':159 'uncertain':90 'unclear':225 'underspecifi':189 'updat':412 'use':5,79,80,140,173,206,267 'user':102,156 'valid':464,470 'validate-cmd':463,469 'verif':318,375,499,545 'vnext':717 'wait':410 'want':96,112,157,227 'wiggum':3,37,62 'work':23,115,371,485,503,533,578,582 'work-schema.json':584 'work-summary.md':349 'work/review':483","prices":[{"id":"9fe2de50-1c32-4c6e-84c4-010c7eeb7d0e","listingId":"f7bb6677-087a-400c-8f29-290f7f193f89","amountUsd":"0","unit":"free","nativeCurrency":null,"nativeAmount":null,"chain":null,"payTo":null,"paymentMethod":"skill-free","isPrimary":true,"details":{"org":"MattMagg","category":"ralph-wiggum-codex","install_from":"skills.sh"},"createdAt":"2026-04-23T13:04:19.398Z"}],"sources":[{"listingId":"f7bb6677-087a-400c-8f29-290f7f193f89","source":"github","sourceId":"MattMagg/ralph-wiggum-codex/ralph-wiggum-codex","sourceUrl":"https://github.com/MattMagg/ralph-wiggum-codex/tree/main/skills/ralph-wiggum-codex","isPrimary":false,"firstSeenAt":"2026-04-23T13:04:19.398Z","lastSeenAt":"2026-05-18T19:08:55.619Z"}],"details":{"listingId":"f7bb6677-087a-400c-8f29-290f7f193f89","quickStartSnippet":null,"exampleRequest":null,"exampleResponse":null,"schema":null,"openapiUrl":null,"agentsTxtUrl":null,"citations":[],"useCases":[],"bestFor":[],"notFor":[],"kindDetails":{"org":"MattMagg","slug":"ralph-wiggum-codex","github":{"repo":"MattMagg/ralph-wiggum-codex","stars":8,"topics":["agent-skills","agentic-workflows","ai-agents","ai-coding-agent","automation","autonomous-agents","autonomous-coding","codex","codex-skill","developer-tools","iterative-refinement"],"license":"mit","html_url":"https://github.com/MattMagg/ralph-wiggum-codex","pushed_at":"2026-03-06T05:14:04Z","description":"Installable Codex skill for long-running autonomous coding refinement loops with validation and resumable state","skill_md_sha":"827549f6b4927dbd52adf84d60ada7a8e26e2258","skill_md_path":"skills/ralph-wiggum-codex/SKILL.md","default_branch":"main","skill_tree_url":"https://github.com/MattMagg/ralph-wiggum-codex/tree/main/skills/ralph-wiggum-codex"},"layout":"multi","source":"github","category":"ralph-wiggum-codex","frontmatter":{"name":"ralph-wiggum-codex","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."},"skills_sh_url":"https://skills.sh/MattMagg/ralph-wiggum-codex/ralph-wiggum-codex"},"updatedAt":"2026-05-18T19:08:55.619Z"}}