[codex] add Ralph Codex adaptation docs

AGENTS.md

@@ -1,47 +1,92 @@
-# Ralph Agent Instructions
+# Ralph Codex Workbench
 
-## Overview
+This repo is the upstream Ralph source plus a local Codex adaptation workbench.
 
-Ralph is an autonomous AI agent loop that runs AI coding tools (Amp or Claude Code) repeatedly until all PRD items are complete. Each iteration is a fresh instance with clean context.
+Use it for two things:
 
-## Commands
+- understanding the original Ralph behavior from `CLAUDE.md`, `ralph.sh`,
+  `skills/prd/SKILL.md`, and `skills/ralph/SKILL.md`
+- building and validating the Codex-native adaptation without losing fidelity to the
+  original one-story loop
 
-```bash
-# Run the flowchart dev server
-cd flowchart && npm run dev
+## Read order
 
-# Build the flowchart
-cd flowchart && npm run build
+1. Read `README.md`.
+2. Read:
+   - `CLAUDE.md`
+   - `skills/prd/SKILL.md`
+   - `skills/ralph/SKILL.md`
+   - `ralph.sh`
+   - `prd.json.example`
+3. Read:
+   - `docs/product/README.md`
+   - `docs/product/01_prd.md`
+   - `docs/product/02_hld.md`
+   - `docs/product/03_lld.md`
+4. For current adaptation state and handoff context, read:
+   - `docs/issues/0000-discovery-journal.md`
+   - `docs/issues/0001-upstream-behavior-audit.md`
 
-# Run Ralph with Amp (default)
-./ralph.sh [max_iterations]
+## Local Codex skills
 
-# Run Ralph with Claude Code
-./ralph.sh --tool claude [max_iterations]
-```
+Use the installed local Codex skills instead of re-deriving the workflow from scratch
+every time:
 
-## Key Files
+- `ralph-prd`
+- `ralph-loop`
 
-- `ralph.sh` - The bash loop that spawns fresh AI instances (supports `--tool amp` or `--tool claude`)
-- `prompt.md` - Instructions given to each AMP instance
--  `CLAUDE.md` - Instructions given to each Claude Code instance
-- `prd.json.example` - Example PRD format
-- `flowchart/` - Interactive React Flow diagram explaining how Ralph works
+These are the Codex-native equivalents of:
 
-## Flowchart
+- upstream `skills/prd/SKILL.md`
+- upstream `CLAUDE.md` plus `skills/ralph/SKILL.md`
 
-The `flowchart/` directory contains an interactive visualization built with React Flow. It's designed for presentations - click through to reveal each step with animations.
+## Core behavior to preserve
 
-To run locally:
-```bash
-cd flowchart
-npm install
-npm run dev
-```
+- one story per iteration
+- `prd.json` is the task ledger
+- `progress.txt` is append-only memory
+- reusable patterns belong at the top of `progress.txt`
+- nearby `AGENTS.md` files should capture genuinely reusable local knowledge
+- commit only after checks pass
+- output `COMPLETE` only when all stories pass
 
-## Patterns
+## Doc routing
 
-- Each iteration spawns a fresh AI instance (Amp or Claude Code) with clean context
-- Memory persists via git history, `progress.txt`, and `prd.json`
-- Stories should be small enough to complete in one context window
-- Always update AGENTS.md with discovered patterns for future iterations
+- `docs/product/`
+  - Codex adaptation specs
+- `docs/issues/`
+  - behavior mismatches, discoveries, and the UTC handoff journal
+- `docs/tests/`
+  - validation procedures and adaptation checks
+- `docs/tasks/`
+  - bounded adaptation work items
+- `docs/tasks/done/`
+  - completed work records
+- `docs/gaps/`
+  - unresolved runtime or product gaps, especially the future standalone Codex runner
+
+## Handoff discipline
+
+After each meaningful work loop, append a UTC entry to:
+
+- `docs/issues/0000-discovery-journal.md`
+
+Minimum fields:
+
+- `utc_timestamp`
+- `focus`
+- `what_was_done`
+- `files_or_areas_touched`
+- `what_changed_in_understanding`
+- `next_step`
+
+## Important constraints
+
+- Keep the upstream file contract unchanged in the first pass:
+  - `prd.json`
+  - `progress.txt`
+  - `tasks/prd-<feature>.md`
+- The Codex adaptation should stay faithful to Ralph, not become a generic autonomous
+  agent framework.
+- There is no confirmed local `codex` CLI/runtime contract here yet, so the standalone
+  loop runner remains a documented future gap rather than an implemented shell loop.

docs/gaps/0001-codex-runner-gap.md

@@ -0,0 +1,25 @@
+# Codex Runner Gap
+
+## Missing piece
+
+Ralph’s upstream `ralph.sh` repeatedly spawns `amp` or `claude` non-interactively.
+
+There is no confirmed local `codex` CLI/runtime contract available in this environment
+to replace that behavior 1:1 yet.
+
+## What is already solved
+
+- Codex-native PRD generation skill
+- Codex-native one-story loop skill
+- repo-local Codex workbench documentation
+
+## What remains for future work
+
+- define the invocation contract for a standalone Codex runner
+- decide how the runner executes repeated isolated iterations
+- preserve:
+  - max-iteration limit
+  - branch discipline
+  - progress logging
+  - story completion updates
+  - `COMPLETE` stop condition

docs/gaps/README.md

@@ -0,0 +1,13 @@
+# Gaps
+
+Use this folder for:
+
+- missing runtime pieces
+- unresolved product or workflow questions
+- future work that should not be silently improvised
+
+When a gap is resolved, move the result into:
+
+- `docs/product/`
+- `docs/issues/`
+- or `docs/tasks/done/`

docs/issues/0000-discovery-journal.md

@@ -0,0 +1,53 @@
+# Ralph Codex Adaptation Journal
+
+## 2026-04-08T11:04:42Z
+
+### Focus
+
+Clone the upstream Ralph repo and turn it into a documented Codex adaptation workbench
+with local skills and an explicit future-runner gap.
+
+### What was done
+
+- cloned `snarktank/ralph` into `/home/shetautnetjerheru/ralph`
+- inspected upstream:
+  - `README.md`
+  - `CLAUDE.md`
+  - `skills/prd/SKILL.md`
+  - `skills/ralph/SKILL.md`
+  - `ralph.sh`
+  - `prd.json.example`
+- created local Codex skills:
+  - `~/.codex/skills/ralph-prd/SKILL.md`
+  - `~/.codex/skills/ralph-loop/SKILL.md`
+- turned the cloned repo into a Codex workbench with:
+  - root `AGENTS.md`
+  - `docs/product/`
+  - `docs/issues/`
+  - `docs/tests/`
+  - `docs/tasks/`
+  - `docs/gaps/`
+
+### Files or areas touched
+
+- `AGENTS.md`
+- `docs/product/*`
+- `docs/issues/*`
+- `docs/tests/*`
+- `docs/tasks/*`
+- `docs/gaps/*`
+- `~/.codex/skills/ralph-prd/SKILL.md`
+- `~/.codex/skills/ralph-loop/SKILL.md`
+
+### What changed in understanding
+
+The key translation boundary is now clear:
+
+- Codex can preserve Ralph’s one-story workflow as a skill/workbench model today
+- the standalone autonomous runner is a separate runtime problem because there is no
+  local `codex` CLI/runtime contract available here yet
+
+### Next step
+
+Validate the local Codex skills against the upstream files line by line and record any
+behavior drift in `docs/issues/0001-upstream-behavior-audit.md`.

docs/issues/0001-upstream-behavior-audit.md

@@ -0,0 +1,24 @@
+# Upstream Behavior Audit
+
+This note tracks how the Codex adaptation maps to upstream Ralph behavior.
+
+## Preserved directly
+
+- one story per iteration
+- `prd.json` as the execution ledger
+- `progress.txt` as append-only memory
+- codebase-pattern consolidation at the top of `progress.txt`
+- nearby `AGENTS.md` updates for reusable local knowledge
+- stop with `COMPLETE` only when all stories pass
+
+## Adapted for Codex
+
+- upstream `CLAUDE.md` is translated into the `ralph-loop` skill rather than used as a
+  raw prompt file
+- upstream PRD generation is translated into the `ralph-prd` skill
+- the standalone shell runner is documented as a future gap rather than implemented
+
+## Current known gap
+
+- no local non-interactive `codex` runtime contract exists here, so `ralph.sh` cannot
+  be replaced 1:1 yet

docs/issues/README.md

@@ -0,0 +1,12 @@
+# Issues and Journal
+
+Use this folder for:
+
+- upstream-to-Codex behavior mismatches
+- adaptation discoveries
+- workflow caveats
+- the UTC handoff journal
+
+Canonical handoff log:
+
+- `0000-discovery-journal.md`

docs/product/01_prd.md

@@ -0,0 +1,46 @@
+# Ralph Codex Adaptation PRD
+
+## Product
+
+Create a Codex-native adaptation of Ralph that preserves the one-story autonomous loop
+discipline and the original file contract.
+
+## Purpose
+
+The adaptation should:
+
+- preserve Ralph’s one-story-per-iteration model
+- preserve `prd.json` as the execution ledger
+- preserve `progress.txt` as append-only memory
+- preserve nearby `AGENTS.md` updates as reusable repo knowledge
+- let Codex users run the Ralph workflow without depending on Claude-specific prompts
+
+## Users
+
+- Codex users running Ralph-style iterative development
+- repo owners who want a PRD-to-loop workflow in Codex
+- future implementers of a standalone Codex runner
+
+## Required capabilities
+
+- PRD generation into `tasks/prd-<feature>.md`
+- PRD-to-`prd.json` conversion
+- one-story loop discipline against `prd.json`
+- progress and pattern logging in `progress.txt`
+- nearby `AGENTS.md` learning capture
+- branch/check/commit discipline
+
+## Non-goals for this pass
+
+- replacing Ralph’s file contract
+- inventing a different task ledger
+- implementing a standalone Codex CLI runner before a runtime contract exists
+- turning Ralph into a generic autonomous framework
+
+## Success criteria
+
+- local Codex skills exist for PRD generation and the one-story loop
+- the cloned Ralph repo documents the Codex adaptation clearly
+- every major behavior from the upstream Claude/Amp workflow is either:
+  - implemented as a local Codex skill/workflow
+  - or recorded as an explicit future runner gap

docs/product/02_hld.md

@@ -0,0 +1,62 @@
+# Ralph Codex Adaptation HLD
+
+## System role
+
+The Codex adaptation is a workflow translation layer over Ralph’s existing model.
+
+It keeps Ralph’s core state surfaces:
+
+- `tasks/prd-<feature>.md`
+- `prd.json`
+- `progress.txt`
+- nearby `AGENTS.md`
+
+## Main subsystems
+
+### PRD authoring
+
+- local skill: `ralph-prd`
+- generates markdown PRDs in `tasks/`
+
+### Execution loop
+
+- local skill: `ralph-loop`
+- reads `prd.json`
+- chooses one pending story
+- implements only that story
+- runs checks
+- updates progress and story state
+
+### Progress memory
+
+- `progress.txt` remains append-only
+- `Codebase Patterns` stays near the top and accumulates reusable knowledge
+
+### Local knowledge capture
+
+- nearby `AGENTS.md` files capture durable local conventions and gotchas
+
+### Future standalone runner
+
+- a later runtime wrapper can drive repeated Codex iterations
+- it should orchestrate `ralph-loop`, not redefine the workflow
+
+## Data flow
+
+1. create markdown PRD
+2. convert PRD into `prd.json`
+3. start one iteration
+4. read `prd.json` and `progress.txt`
+5. select highest-priority incomplete story
+6. implement exactly one story
+7. run checks
+8. if passing, commit and mark story complete
+9. append progress
+10. repeat until `COMPLETE`
+
+## Invariants
+
+- one story at a time
+- no completion on failed checks
+- file contract remains unchanged
+- reusable knowledge goes into `progress.txt` and nearby `AGENTS.md`