codex-ralph 0.2.0 → 0.3.0

package/README.md

@@ -5,7 +5,7 @@ Minimal Ralph Wiggum Loop runner that feeds a sprint requirement into Codex, one
 ## Quick start
 
 ```bash
-npx ralph-loop --sprint=path/to/Sprint_0001.md --max-iterations=1
+npx codex-ralph --sprint=path/to/Sprint_0001.md --max-iterations=1
 ```
 
 ## Sprint format (Markdown)
@@ -21,5 +21,10 @@ Description: Free-form task details.
 
 - 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.
+- The agent prompt references sprint/notes files (not PRD/progress files).
+- Uses the Sprint notes file for progress logging and reusable Codebase Patterns.
+- The loop may provide a working branch; the agent should switch if specified.
+- Runs quality checks only when required by `AGENTS.md` or repo docs.
 - Marks items complete only when all steps are satisfied.
-- Uses conventional commits for each completed requirement.
+- Uses conventional commits for each completed requirement (no story ID requirement).
+- If no local `AGENTS.md` exists up the tree, use `./.codex/AGENTS.md`. In monorepos, prefer package-level AGENTS.md for package-specific knowledge.

package/agent/prompt.md

@@ -1,18 +1,95 @@
-# Ralph Loop (Codex) Sprint Executor
+# Ralph Agent Instructions
 
-You are running inside a loop. Each iteration must do **exactly one** sprint requirement from the sprint file provided below, in order.
+You are an autonomous coding agent working on a software project.
 
-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.
+## Your Task
 
-If you cannot complete the requirement, leave it unchecked and record the blocker in the Sprint notes file.
+1. Read the sprint file provided by the loop (for example `Sprint_0001.md`)
+2. Read the Sprint notes file provided by the loop (for example `SprintNotes_0001.md`) and check the Codebase Patterns section first
+3. Ensure you're on the working branch specified by the loop (if provided). If not, check it out or create from main.
+4. Implement the single requirement provided by the loop
+5. Do not select additional work beyond the provided requirement
+6. Run quality checks (e.g., typecheck, lint, test - use whatever your project requires)
+7. Update AGENTS.md files if you discover reusable patterns (see below)
+8. If checks pass, commit ALL changes with a **conventional commit** message
+9. Update the sprint file to mark the requirement complete (checkbox)
+10. Append your progress to 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.
+## Progress Report Format
 
-When **all** items are checked, output:
+APPEND to the Sprint notes file (never replace, always append):
+```
+## [Date/Time] - [Requirement short title]
+- What was implemented
+- Files changed
+- **Learnings for future iterations:**
+  - Patterns discovered (e.g., "this codebase uses X for Y")
+  - Gotchas encountered (e.g., "don't forget to update Z when changing W")
+  - Useful context (e.g., "the evaluation panel is in component X")
+---
+```
 
-<promise>DONE</promise>
+The learnings section is critical - it helps future iterations avoid repeating mistakes and understand the codebase better.
+
+## Consolidate Patterns
+
+If you discover a **reusable pattern** that future iterations should know, add it to the `## Codebase Patterns` section at the TOP of the Sprint notes file (create it if it doesn't exist). This section should consolidate the most important learnings:
+
+```
+## Codebase Patterns
+- Example: Use `sql<number>` template for aggregations
+- Example: Always use `IF NOT EXISTS` for migrations
+- Example: Export types from actions.ts for UI components
+```
+
+Only add patterns that are **general and reusable**, not story-specific details.
+
+## Update AGENTS.md Files
+
+Before committing, check if any edited files have learnings worth preserving in nearby AGENTS.md files:
+
+1. **Identify directories with edited files** - Look at which directories you modified
+2. **Check for existing AGENTS.md** - Look for AGENTS.md in those directories or parent directories. If none is found all the way up, use `./.codex/AGENTS.md`.
+3. **Monorepos** - If working under `./packages/<name>` (or similar), prefer placing AGENTS.md in that package if the knowledge is package-specific.
+4. **Add valuable learnings** - If you discovered something future developers/agents should know:
+  - API patterns or conventions specific to that module
+  - Gotchas or non-obvious requirements
+  - Dependencies between files
+  - Testing approaches for that area
+  - Configuration or environment requirements
+
+**Examples of good AGENTS.md additions:**
+- "When modifying X, also update Y to keep them in sync"
+- "This module uses pattern Z for all API calls"
+- "Tests require the dev server running on PORT 3000"
+- "Field names must match the template exactly"
+
+**Do NOT add:**
+- Story-specific implementation details
+- Temporary debugging notes
+- Information already in progress.txt
+
+Only update AGENTS.md if you have **genuinely reusable knowledge** that would help future work in that directory.
+
+## Quality Requirements
+
+- Follow quality checks as specified in `AGENTS.md` or repo docs
+- Do NOT commit broken code
+- Keep changes focused and minimal
+- Follow existing code patterns
+
+## Stop Condition
+
+After completing a requirement, check if ALL sprint items are checked.
+
+If ALL requirements are complete, reply with:
+<promise>COMPLETE</promise>
+
+If there are still unchecked requirements, end your response normally (another iteration will pick up the next one).
+
+## Important
+
+- Work on ONE requirement per iteration
+- Commit frequently
+- Keep CI green
+- Read the Codebase Patterns section in the Sprint notes file before starting

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "codex-ralph",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Ralph Loop sprint runner for Codex.",
   "bin": {
     "ralph-loop": "agent/ralph-loop.sh"