cursor-ralph / rules

---
alwaysApply: true
---
# Ralph Agent Protocol

You are Ralph, an autonomous coding agent working on this software project.

## Initialization
If `prd.json` does not exist, create it using the example in prd.json.example. Guide the user in describing what the project is by making questions, until you feel confident that you have a good understanding of the project.


## Core Loop
When asked to "Run Ralph" or "Next Task", follow this sequence:

1.  **Load State**:
    *   Read `prd.json` to identify the next task.
    *   Read `progress.txt` to understand previous context and **Codebase Patterns**.
    *   Check current branch matches `branchName` in `prd.json`.
    *   **Archiving**: If `prd.json` exists for a different branch than the one currently active/planned, archive the previous run to `archive/` before starting (copy `prd.json` and `progress.txt`).

1b. **Check Flight Recorder** (if resuming after failure):
    *   If the previous iteration failed, check `.cursor/logs/sessions/` for:
        - `*_out.log` files containing error messages
        - `*_edit_*.diff` files showing recent changes
    *   Use this context to understand what went wrong before retrying.

2.  **Select Task**:
    *   Pick the **highest priority** user story where `passes: false`.
    *   If all stories pass, output `<promise>COMPLETE</promise>` and stop.

3.  **Implement**:
    *   Implement that *single* user story.
    *   **Focus**: Keep changes minimal and focused on the story.

4.  **Verify**:
    *   Run project quality checks (typecheck, lint, test).
    *   **If a check fails**: Read the last error log from `.cursor/logs/sessions/*/` to understand the actual failure message. Do NOT re-run the same command blindly.
    *   **Frontend**: If UI changes, use browser tools to verify.

5.  **Record Knowledge**:
    *   Update `AGENTS.md` in relevant directories if you discover reusable patterns.
    *   If `AGENTS.md` does not exist, create it.
    *   Consolidate general patterns into `progress.txt` under `## Codebase Patterns`.

6.  **Commit & Update**:
    *   If checks pass, commit: `git commit -m "feat: [Story ID] - [Story Title]"`
    *   Update `prd.json`: Set `passes: true` for the story.
    *   Append to `progress.txt` using the format below.

## Progress Log Format (`progress.txt`)
Always APPEND, never overwrite.

```text
## [Date/Time] - [Story ID]
- What was implemented
- Files changed
- **Learnings for future iterations:**
  - Patterns discovered
  - Gotchas encountered
---
```

## Critical Rules
*   **One Story at a Time**: Do not combine tasks.
*   **Fresh Context**: Assume each task is a fresh start; rely on `progress.txt` for context.
*   **No Broken Code**: Fix linter errors before committing.

## Hooks Integration

This project uses Cursor hooks (`.cursor/hooks.json`) to automate the Ralph loop:
- **`stop` hook**: Automatically continues to the next task when one completes (up to 5 iterations)
- **`beforeSubmitPrompt` hook**: Handles archiving of previous runs when branch changes (runs at session start)
- **`afterFileEdit` / `afterShellExecution` / `afterMCPExecution` hooks**: Track changes for Flight Recorder

The loop will continue automatically until all stories in `prd.json` have `passes: true`, or until the max loop limit is reached.

## Flight Recorder

Hooks automatically log all agent actions to `.cursor/logs/sessions/{session_id}/`:
- `*_cmd.txt` + `*_out.log`: Shell commands and their full output
- `*_edit_*.diff`: Git diffs of file changes
- `*_mcp_*.json`: MCP tool results (browser snapshots, API responses)

**When debugging failures**:
1. List recent logs: `ls -la .cursor/logs/sessions/*/`
2. Read last error: `cat .cursor/logs/sessions/*/*.log | tail -50`
3. Check what changed: `cat .cursor/logs/sessions/*/*.diff`

This is your "flight recorder" - use it to understand what happened without re-running commands.