Prompt Engineering & Templates

Relevant source files

The following files were used as context for generating this wiki page:

• templates/AGENT.md
• templates/PROMPT.md
• templates/fix_plan.md
• create_files.sh
• ralph_import.sh
• tests/helpers/fixtures.bash
• CLAUDE.md

The prompt engineering and template system is the core mechanism for directing the autonomous AI agent, "Ralph". These markdown files define the project's goals, constraints, tasks, and quality standards. They act as the primary interface between the human user and the AI, translating high-level requirements into actionable instructions and providing a structured way for the AI to report its status.

The system is built around a set of key template files that are created for each new project. These files guide the AI's behavior, manage its workflow, and establish the criteria for project completion.

Sources: create_files.sh:426-431, README.md:200-209

Core Template Files

Three main template files form the foundation of a Ralph-managed project. They are initialized by the setup.sh script, which copies them from the templates/ directory.

Sources: create_files.sh:434-438

File	Purpose
PROMPT.md	The main instruction set for the AI agent in each loop. It defines context, objectives, and critical reporting rules.
@fix_plan.md	A prioritized task list (TODO list) that the agent follows to guide its work.
@AGENT.md	Contains project-specific build/run instructions and defines mandatory quality standards for testing and version control.

This diagram shows how the core templates interact to guide the AI agent.

PROMPT.md: The Agent's Core Instructions

This is the most critical file, as its content is passed to the Claude Code AI in every iteration of the ralph_loop.sh. It establishes the agent's persona, objectives, and operational rules.

Sources: create_files.sh:28-29, create_files.sh:455-458

Key Sections

• Context: Sets the persona for the AI: "You are Ralph, an autonomous AI development agent...".
• Current Objectives: A high-level list of goals, such as studying specs, reviewing the fix plan, and implementing tasks.
• Key Principles: Core behavioral rules like "ONE task per loop" and "Search the codebase before assuming...".
• Testing Guidelines: Critical rules for testing, emphasizing implementation over excessive testing and focusing on new functionality.
• Execution Guidelines: Instructions for the development cycle: search, implement, test, document.
• Completion Awareness: Defines how the agent should behave when it believes the project is complete, preventing "busy work".
• File Structure: A brief overview of the project's directory layout.
• Current Task: The final instruction, directing the agent to consult @fix_plan.md.

Sources: templates/PROMPT.md:1-55

Status Reporting (RALPH_STATUS)

A crucial component of PROMPT.md is the mandatory status reporting block. The agent must include this block at the end of its output. The ralph_loop.sh script parses this block to understand the outcome of the loop and decide on the next action (e.g., continue, exit).

The format is strictly defined:

---RALPH_STATUS---
STATUS: IN_PROGRESS | COMPLETE | BLOCKED
TASKS_COMPLETED_THIS_LOOP: <number>
FILES_MODIFIED: <number>
TESTS_STATUS: PASSING | FAILING | NOT_RUN
WORK_TYPE: IMPLEMENTATION | TESTING | DOCUMENTATION | REFACTORING
EXIT_SIGNAL: false | true
RECOMMENDATION: <one line summary of what to do next>
---END_RALPH_STATUS---

Sources: templates/PROMPT.md:58-70

The EXIT_SIGNAL: true flag is the primary mechanism for the agent to signal that it has completed the project, which triggers a graceful shutdown of the development loop.

The following table details each field in the status block:

Field	Description	Possible Values
STATUS	The overall status of the project from the agent's perspective.	IN_PROGRESS, COMPLETE, BLOCKED
TASKS_COMPLETED_THIS_LOOP	Number of tasks from @fix_plan.md completed in the current loop.	Integer
FILES_MODIFIED	Number of files created or changed.	Integer
TESTS_STATUS	The outcome of any tests that were run.	PASSING, FAILING, NOT_RUN
WORK_TYPE	The primary category of work performed.	IMPLEMENTATION, TESTING, DOCUMENTATION, REFACTORING
EXIT_SIGNAL	A boolean flag to signal project completion.	true, false
RECOMMENDATION	A brief, human-readable suggestion for the next step.	String

Sources: templates/PROMPT.md:58-97

This sequence diagram illustrates the interaction based on the status report.

@fix_plan.md: Prioritized Task Management

This file functions as a simple, markdown-based task manager. The AI agent reads this file to determine its next priority and updates it by marking tasks as complete.

The structure is organized by priority:

• ## High Priority
• ## Medium Priority
• ## Low Priority
• ## Completed

Tasks are represented as checklist items, e.g., - [ ] Define core data structures. The agent is expected to change [ ] to [x] upon completion.

Sources: templates/fix_plan.md:1-23

@AGENT.md: Build Instructions & Quality Standards

This file serves two purposes:

1. Build/Run Instructions: It provides the AI with the necessary commands to set up, build, test, and run the project. This includes commands like npm install, pytest, and cargo build.
2. Quality Standards: It defines a strict, non-negotiable set of quality gates that all new features must meet before being considered complete. This turns the agent into a quality-conscious developer.

The quality standards include:

• Testing Requirements: Minimum code coverage (e.g., 85%), 100% test pass rate, and required test types (unit, integration).
• Git Workflow: Mandates the use of conventional commits, feature branches, and pushing changes to a remote repository.
• Documentation Requirements: Ensures that code comments and implementation documents (AGENT.md, README.md) are kept synchronized with the codebase.

A Feature Completion Checklist is provided to enforce these standards systematically.

Sources: templates/AGENT.md:1-119

PRD Conversion Prompt

The ralph_import.sh script contains a specialized, sophisticated prompt template designed to convert a user-provided Product Requirements Document (PRD) into the standard set of Ralph template files. This automates the project setup process.

The conversion prompt instructs the AI to:

1. Analyze the input PRD to extract goals, features, and technical constraints.
2. Generate PROMPT.md: Transform the PRD into development instructions for the agent.
3. Generate @fix_plan.md: Convert requirements into a prioritized task list.
4. Generate specs/requirements.md: Create a detailed technical specification document.

Sources: ralph_import.sh:282-376

This flowchart shows the PRD conversion process.

Summary

The template and prompt engineering system is the "brain" of the Ralph agent. PROMPT.md acts as its core programming, defining its behavior and communication protocol. @fix_plan.md serves as its short-term memory and task list, while @AGENT.md functions as its conscience, enforcing quality and best practices. The ralph_import.sh prompt further extends this capability by allowing the system to bootstrap itself from high-level human-written documents, making Ralph a powerful tool for autonomous software development.

Sources: README.md:124-133, CLAUDE.md:133-139