codex-ralph 0.1.0

package/README.md

@@ -0,0 +1,25 @@
+# Codex Ralph Loop
+
+Minimal Ralph Loop runner that feeds a sprint requirement into Codex, one item per iteration.
+
+## Quick start
+
+```bash
+npx ralph-loop --sprint=path/to/Sprint_0001.md --max-iterations=1
+```
+
+## Sprint format (Markdown)
+
+Each requirement is a level-2 heading with a checkbox. The loop picks the first unchecked item.
+
+```markdown
+## [ ] Requirement description
+Description: Free-form task details.
+```
+
+## Behavior
+
+- Reads the sprint file, finds the first unchecked item, and passes it to Codex.
+- Derives a parallel notes file alongside the sprint (for example `Sprint_0001.md` -> `SprintNotes_0001.md`) and includes its path in the prompt.
+- Marks items complete only when all steps are satisfied.
+- Uses conventional commits for each completed requirement.

package/agent/prompt.md

@@ -0,0 +1,18 @@
+# Ralph Loop (Codex) Sprint Executor
+
+You are running inside a loop. Each iteration must do **exactly one** sprint requirement from the sprint file provided below, in order.
+
+Process:
+1. Open the sprint file path provided below.
+2. Find the first item that is unchecked.
+3. Implement that requirement fully.
+4. Update the sprint item to checked only when all its steps are satisfied.
+5. Commit your changes with a **conventional commit** message.
+
+If you cannot complete the requirement, leave it unchecked and record the blocker in the Sprint notes file.
+
+After each iteration, update the Sprint notes file with what you did, including details or nuances that will help the next iteration.
+
+When **all** items are checked, output:
+
+<promise>DONE</promise>

package/agent/ralph-loop.sh

@@ -0,0 +1,165 @@
+#!/usr/bin/env bash
+
+set -euo pipefail
+
+SCRIPT_PATH="$(python3 - <<PY
+import os
+print(os.path.realpath("${BASH_SOURCE[0]}"))
+PY
+)"
+ROOT_DIR="$(cd "$(dirname "$SCRIPT_PATH")/.." && pwd)"
+SPRINT_FILE=""
+MAX_ITERATIONS=0
+NOTES_FILE=""
+
+usage() {
+  cat <<USAGE
+Usage: ralph-loop --sprint=PATH [--max-iterations=N]
+
+Options:
+  --sprint=PATH          Path to the sprint markdown file (required).
+  --max-iterations=N     Stop after N iterations (0 = no limit).
+  -h, --help             Show this help.
+USAGE
+}
+
+for arg in "$@"; do
+  case "$arg" in
+    --sprint=*)
+      SPRINT_FILE="${arg#*=}"
+      ;;
+    --max-iterations=*)
+      MAX_ITERATIONS="${arg#*=}"
+      ;;
+    -h|--help)
+      usage
+      exit 0
+      ;;
+    *)
+      echo "Unknown argument: $arg" >&2
+      usage >&2
+      exit 1
+      ;;
+  esac
+ done
+
+if [[ -z "$SPRINT_FILE" ]]; then
+  echo "Sprint file path is required." >&2
+  usage >&2
+  exit 1
+fi
+
+if [[ ! -f "$SPRINT_FILE" ]]; then
+  echo "Sprint file not found: $SPRINT_FILE" >&2
+  exit 1
+fi
+
+if [[ -z "$NOTES_FILE" ]]; then
+  sprint_dir="$(cd "$(dirname "$SPRINT_FILE")" && pwd)"
+  sprint_base="$(basename "$SPRINT_FILE")"
+  notes_base="${sprint_base/Sprint_/SprintNotes_}"
+  if [[ "$notes_base" == "$sprint_base" ]]; then
+    notes_base="${sprint_base%.*}Notes.${sprint_base##*.}"
+  fi
+  NOTES_FILE="$sprint_dir/$notes_base"
+fi
+
+if [[ ! -f "$NOTES_FILE" ]]; then
+  mkdir -p "$(dirname "$NOTES_FILE")"
+  : > "$NOTES_FILE"
+fi
+
+PROMPT_FILE="$ROOT_DIR/agent/prompt.md"
+if [[ ! -f "$PROMPT_FILE" ]]; then
+  echo "Prompt file not found: $PROMPT_FILE" >&2
+  exit 1
+fi
+
+remaining_count() {
+  python3 - <<PY
+from pathlib import Path
+import re
+
+path = Path("$SPRINT_FILE")
+text = path.read_text(encoding="utf-8")
+items = re.findall(r"^## \[( |x|X)\] ", text, flags=re.M)
+print(sum(1 for m in items if m.strip() != "x"))
+PY
+}
+
+next_description() {
+  python3 - <<PY
+from pathlib import Path
+import re
+
+path = Path("$SPRINT_FILE")
+text = path.read_text(encoding="utf-8")
+for match in re.finditer(r"^## \[( |x|X)\] (.+)$", text, flags=re.M):
+    checked = match.group(1)
+    desc = match.group(2).strip()
+    if checked != "x" and checked != "X":
+        print(desc)
+        break
+PY
+}
+
+current_item_block() {
+  python3 - <<PY
+from pathlib import Path
+import re
+
+path = Path("$SPRINT_FILE")
+lines = path.read_text(encoding="utf-8").splitlines()
+start = None
+end = None
+for i, line in enumerate(lines):
+    if re.match(r"^## \[( |x|X)\] ", line):
+        if start is None:
+            checked = line.split("[", 1)[1].split("]", 1)[0].strip()
+            if checked.lower() != "x":
+                start = i
+        elif start is not None:
+            end = i
+            break
+if start is None:
+    print("<no remaining items>")
+else:
+    block = lines[start:end] if end is not None else lines[start:]
+    print("\n".join(block))
+PY
+}
+
+iteration=1
+while true; do
+  remaining="$(remaining_count)"
+  if [[ "$remaining" == "0" ]]; then
+    echo "All sprint requirements complete."
+    echo "<promise>DONE</promise>"
+    exit 0
+  fi
+
+  if [[ "$MAX_ITERATIONS" -gt 0 && "$iteration" -gt "$MAX_ITERATIONS" ]]; then
+    echo "Reached max iterations ($MAX_ITERATIONS) with $remaining remaining." >&2
+    exit 2
+  fi
+
+  desc="$(next_description)"
+  echo "Iteration $iteration - next requirement: $desc"
+
+  prompt_tmp="$(mktemp)"
+  {
+    cat "$PROMPT_FILE"
+    echo ""
+    echo "Sprint file: $SPRINT_FILE"
+    echo "Sprint notes file: $NOTES_FILE"
+    echo ""
+    echo "Current requirement (Markdown):"
+    current_item_block
+  } > "$prompt_tmp"
+
+  codex exec - < "$prompt_tmp"
+
+  rm -f "$prompt_tmp"
+
+  iteration=$((iteration + 1))
+done

package/package.json

@@ -0,0 +1,13 @@
+{
+  "name": "codex-ralph",
+  "version": "0.1.0",
+  "description": "Ralph Loop sprint runner for Codex.",
+  "bin": {
+    "ralph-loop": "agent/ralph-loop.sh"
+  },
+  "scripts": {
+    "ralph-loop": "agent/ralph-loop.sh"
+  },
+  "author": "Igor Sachivka <juicy.igor@gmail.com>",
+  "license": "MIT"
+}