ralphi-loop

name	ralphi-loop
description	Executing a single iteration of the ralph autonomous coding loop. Use when ralph invokes the agent to implement the next user story from the PRD.

Ralph Agent — Per-Iteration Instructions

You are an autonomous coding agent working on a software project.

1. Load Configuration

Read .ralphi/config.yaml for project name, language, and framework.

Read the rules section in .ralphi/config.yaml and follow every rule listed.

Read the boundaries.never_touch section in .ralphi/config.yaml. Do NOT modify any file matching those patterns.

2. Your Task

1. Read the PRD at .ralphi/prd.json
2. Read the progress log at .ralphi/progress.txt (check Codebase Patterns section first)
3. Confirm the target story context in PRD (runtime already handles branch checkout/creation from PRD branchName before iteration starts).
4. Pick the highest priority unblocked user story:
   • Prefer status: "open"
   • If no open stories are available, resume status: "in_progress"
5. Implement that single user story
6. Run the REQUIRED Post-Implementation Step-Back Review Protocol (Section 3)
7. Run quality checks (see below)
8. Update AGENTS.md files if you discover reusable patterns (see below)
9. If checks pass, commit ALL changes with message: feat: [Story ID] - [Story Title]
10. Update the PRD for the completed story:

• status: "done"

11. Append your progress to .ralphi/progress.txt

3. REQUIRED Post-Implementation Step-Back Review Protocol

Run this protocol after implementation and before quality checks/commit.

1. Re-ground in source of truth
   • Re-read the target story in .ralphi/prd.json (description + acceptance criteria)
   • Re-read ## Codebase Patterns and the latest iteration entry in .ralphi/progress.txt
2. Run a deterministic code review pass
   • Review every changed file against this checklist:
     • Every change maps to at least one acceptance criterion
     • No unrelated refactors or scope creep were introduced
     • Tests were added/updated where behavior changed
     • .ralphi/config.yaml rules and boundaries are still respected
   • Set Review Outcome to exactly one value: PASS or CHANGES_REQUIRED
   • If CHANGES_REQUIRED, fix issues and run this protocol again
3. Run a PRD trajectory check
   • Classify trajectory with exactly one value:
     • ON_TRACK — Implementation is aligned with PRD intent/scope
     • RISK — Still aligned, but has a known dependency/open risk
     • DRIFT — Current implementation diverges from PRD intent/scope
   • Record a short rationale for RISK or DRIFT
   • If DRIFT, define a corrective plan and do not mark the story complete until corrected

4. Quality Checks

Read the commands section in .ralphi/config.yaml and run each configured command (test, lint, build, typecheck, etc.). You can also run ralphi check which runs all commands in sequence.

Quality checks are also enforced by a pre-commit hook. If you try to commit and checks fail, fix the issues and try again. Do NOT use git commit --no-verify.

5. Progress Report Format

APPEND to .ralphi/progress.txt (never replace, always append):

## [Date/Time] - [Story ID]
Session: [Session URL/ID if available, else N/A]
Review Outcome: [PASS | CHANGES_REQUIRED]
Trajectory: [ON_TRACK | RISK | DRIFT]
Trajectory Notes: [Short rationale; required for RISK/DRIFT, else N/A]
Corrective Plan: [Required if DRIFT, else N/A]
- 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")
---

Include a session reference if your engine provides one. Otherwise write N/A.

6. Consolidate Patterns

If you discover a reusable pattern, add it to the ## Codebase Patterns section at the TOP of .ralphi/progress.txt (create if it doesn't exist). Only add patterns that are general and reusable, not story-specific.

7. Update AGENTS.md Files

Before committing, check if edited files have learnings worth preserving in nearby AGENTS.md files:

• API patterns or conventions specific to that module
• Gotchas or non-obvious requirements
• Dependencies between files
• Testing approaches

8. Quality Requirements

• ALL commits must pass quality checks
• Do NOT commit broken code
• Keep changes focused and minimal
• Follow existing code patterns

Important

• Work on ONE story per iteration
• Commit frequently
• Keep CI green
• Read the Codebase Patterns section in .ralphi/progress.txt before starting
• This phase is prompt/skill-driven only; do not require runtime command/tool changes for this review protocol