Ralph is an autonomous AI agent loop designed to iteratively complete items defined in a Product Requirements Document (PRD). It operates by repeatedly spawning fresh Amp instances, each with a clean context, until all PRD tasks are marked as complete. Memory between iterations is persisted through Git history, an append-only progress.txt file for accumulated learnings, and a prd.json file that tracks the status of user stories.

Core Methodology and Technical Details:

The system functions as an iterative control loop, where each cycle attempts to advance the project state towards completion of a defined task.

1. Initialization and PRD Conversion: The process begins with a markdown-based PRD. A dedicated "PRD skill" is used to generate this detailed requirements document. Subsequently, a "Ralph skill" converts this markdown PRD into a structured prd.json file. This JSON file serves as the agent's task list, containing individual user stories, each with a passes boolean status and a branchName for feature branch creation.

2. Iterative Execution Loop: The ralph.sh script orchestrates the main loop. In each iteration:
   • Context Initialization: A new Amp instance is spawned, ensuring a pristine execution environment without residual context from prior attempts.
   • State Input: The Amp instance's behavior is guided by prompt.md (general instructions), the current codebase state (from Git history), prd.json (to identify the next task), and progress.txt (to leverage past learnings). Crucially, Amp also automatically reads AGENTS.md files, which are dynamically updated with patterns, gotchas, and context discovered by the agent in previous iterations, serving as a form of long-term, evolvable memory for the LLM.
   • Story Selection: Ralph prioritizes the highest-priority user story in prd.json where passes: false.
   • Task Execution: The Amp instance attempts to implement this single story. This requires stories to be "right-sized" – small enough to be completed within a single LLM context window (e.g., adding a database column, updating a UI component). Large tasks are explicitly discouraged as they lead to context overflow and poor code generation.
   • Quality Checks and Feedback: After implementation, automated quality checks are executed. These include:
     • Type checking to catch type errors.
     • Running unit/integration tests to verify behavior.
     • Ensuring the Continuous Integration (CI) pipeline remains green.
     • For UI-specific stories, acceptance criteria must include "Verify in browser using dev-browser skill." This triggers an automated browser verification step, allowing Ralph to navigate, interact with the UI, and confirm visual or functional changes. This forms a critical feedback loop, providing real-world observation of UI correctness.
   • State Update and Memory Persistence:
     • If all checks pass, the changes are committed to Git, and the corresponding story in prd.json is updated to passes: true.
     • Learnings from the iteration, regardless of success, are appended to progress.txt. This provides an accumulating log of insights and debugging information.
     • AGENTS.md files are updated with new knowledge, effectively refining the agent's "understanding" of the codebase and project conventions for subsequent iterations. This iterative knowledge augmentation is crucial for the agent's adaptability and efficiency.

3. Termination Condition: The loop continues until all stories in prd.json have passes: true, at which point Ralph outputs $<promise>COMPLETE</promise>$ and exits.

Key Components:

• ralph.sh: The main bash script controlling the autonomous loop.
• prompt.md: Instructions provided to each Amp instance to guide its behavior.
• prd.json: The machine-readable task list containing user stories and their completion status.
• progress.txt: An append-only log of learnings and outcomes from each iteration.
• skills/prd/: An Amp skill for generating initial PRDs.
• skills/ralph/: An Amp skill for converting markdown PRDs into the prd.json format.
• AGENTS.md: Files where the agent records discovered patterns, gotchas, and useful context for future iterations and human developers.

Ralph's effectiveness hinges on its ability to manage state across distinct LLM invocations through external persistence mechanisms (Git, prd.json, progress.txt, and AGENTS.md), coupled with robust, automated feedback loops to validate its generated code.