Ralph Loop

A structured workflow for using GitHub Copilot and PowerShell to build features through iterative development based on a ralph loop with a Product Requirements Document (PRD) and execution plan.

Overview

The Ralph Loop is a methodology that combines:

1. A PRD.md - Product Requirements Document that defines what to build
2. A plan.json - Structured execution plan with tasks for Copilot to complete
3. A PROMPT.md - Prompt to tell Copilot what to do at the start of each iteration
4. An activity.txt - File to log the actions, progress and blockers of each iteration
5. A ralph.ps1 - PowerShell loop for automated iteration through the plan tasks

Usage

Step 1: Create the PRD

Use GitHub Copilot to generate a PRD based on your feature requirements.

Example prompt:

Create a PRD.md file for the following feature:

[Describe your feature here]

The PRD should include:
- Overview and objectives
- User stories
- Functional requirements
- Non-functional requirements
- Acceptance criteria
- Out of scope items

Step 2: Create the Plan

After the PRD is created, have Copilot generate a structured plan based on the json template below.

Example prompt:

Based on the PRD.md, create `plan.json` with your requirements:

json
[
  {
    "category": "functional",
    "description": "User can send a message and see it in the conversation",
    "steps": ["Open chat", "Type message", "Click Send", "Verify it appears"],
    "passes": false
  }
]

| Field         | Description                                |
|---------------|--------------------------------------------|
| `category`    | `"functional"`, `"ui"`, or custom          |
| `description` | One-line summary                           |
| `steps`       | How to verify it works                     |
| `passes`      | `false` → `true` when complete             |

Step 3: Create the PROMPT.md

PROMPT.md will be used by Copilot at the start of each loop. It should be agnostic of the current state or goals remaining for the project. Update the template below with information specific to your project.

PROMPT.md template

This is a {one sentence description of project}

First read activity.txt to see what was recently accomplished.

Open plan.json and choose the single highest priority task where passes is false.

Work on exactly ONE task: implement the change.

If you run into permission issues, please record the details to activity.txt

If you run into an error and are unable to implement the change, update activity.txt with what the error was, and how you tried to fix it.

After implementing, do the following:
1. {Add any tests or checks here specific to your project}

Do not git init, do not change remotes, do not push.

ONLY WORK ON A SINGLE TASK. ONLY WORK WITHIN THIS REPO

When all tasks have "passes" set to true, output <promise>COMPLETE</promise>

Step 4: Run the Loop

Execute the ralph loop PowerShell script to iterate through the plan:

PowerShell command:

.\ralph.ps1 -Prompt PROMPT.md -Prd PRD.md -Iterations 20 -AllowProfile dev

Workflow Tips

• Provide a test or way for Copilot to check its work
• Review output of first iteration to ensure it has appropriate permissions

Files

File	Purpose
PRD.md	Product Requirements Document
plan.json	Structured task execution plan
activity.txt	Log of Copilot actions and progress
PROMPT.md	Copilot's prompt at the start of each iteration