Ralph - Recursive Task Execution

Autonomous task execution that works with any agent harness (amp, opencode, claude, etc.).

How It Works

• You provide a prompt - e.g., "Implement the next task from prd.json and ensure all QA checks pass"

• Agent executes ONE task - Implements, tests, commits

• Agent creates new session - Starts fresh with summary of what was done + the same prompt

• Repeat until done - Continues until all tasks are complete

Two Phases

Phase Purpose Trigger

Setup Configure task source (prd.json or task_list) "set up ralph", "configure ralph"

Loop Execute tasks recursively until done "run ralph", "start the loop"

Supported Task Sources

1. PRD Markdown File (Recommended)

A markdown PRD file generated by the prd skill, located at /tasks/prd-[feature-name].md :

PRD: Task Priority System

User Stories

US-001: Add priority field to database

Description: As a developer, I need to store task priority...

Acceptance Criteria:

• Add priority column to tasks table
• Generate and run migration
• Typecheck passes

US-002: Display priority indicator

Description: As a user, I want to see task priority...

Acceptance Criteria:

• Show colored priority badge
• Typecheck passes

Ralph automatically extracts user stories (US-001, US-002, etc.) and converts them to tasks with sequential dependencies (US-002 depends on US-001, etc.).

2. PRD JSON File

A prd.json file containing tasks with explicit dependencies:

{ "feature": "User Authentication", "tasks": [ { "id": "auth-1", "title": "Add user table migration", "description": "Create migration for users table", "dependencies": [], "status": "open" } ] }

3. task_list (amp-compatible)

Tasks stored in amp's task_list system with parent/subtask relationships.

Quick Start

Setup Phase

User: set up ralph

Assistant: What task source?

1. PRD JSON file (path/to/prd.json)
2. task_list (existing amp tasks)

[User selects and provides details]

Assistant: [Creates ralph.json config file] ✅ Ralph configured! Run "ralph" to start execution.

Execution Phase

User: run ralph

Agent:

1. Reads ralph.json config
2. Finds next ready task
3. Implements it
4. Updates prd.json or task_list status
5. Commits changes
6. Generates session summary
7. Creates new session with summary + original prompt
8. New session continues the loop...

Configuration File (ralph.json)

{ "version": "1.0", "taskSource": { "type": "prd-json", "path": "tasks/prd.json" }, "prompt": "Implement the next ready task from the PRD. Ensure typecheck passes, tests pass, and changes are committed.", "harness": { "type": "generic", "newSessionCommand": "/new" }, "qualityChecks": { "typecheck": "npm run typecheck", "test": "npm run test", "lint": "npm run lint" }, "progressFile": "scripts/ralph/progress.json" }

Harness Types

• generic

• Uses /new command to create fresh sessions (opencode, claude, etc.)

• amp

• Uses amp's built-in handoff mechanism

• custom

• Define your own session creation logic

Session Handoff Protocol

When a task is complete, the agent must:

1. Update Progress

// scripts/ralph/progress.json { "currentSession": { "startedAt": "2026-01-31T10:00:00Z", "completedTask": { "id": "auth-1", "title": "Add user table migration", "filesChanged": ["migrations/001_users.sql"] }, "learnings": [ "Use knex for migrations in this codebase", "Password hashing uses bcrypt with 10 rounds" ] }, "completedTasks": ["auth-1"], "remainingTasks": ["auth-2", "auth-3"], "blockedTasks": [], "patterns": { "database": "Use knex migrations in migrations/ folder", "api": "Express routes go in routes/ folder" } }

2. Commit Changes

git add . git commit -m "feat: Add user table migration"

3. Create New Session

For generic harness (opencode, claude, etc.):

/new [SESSION_CONTEXT]

=== RALPH SESSION CONTEXT === Original Prompt: Implement the next ready task from the PRD. Ensure typecheck passes, tests pass, and changes are committed.

Previous Session Summary:

• Completed: auth-1 (Add user table migration)
• Files changed: migrations/001_users.sql
• Learnings: Use knex for migrations; bcrypt with 10 rounds for passwords
• Next ready task: auth-2 (Create login API endpoint)

Progress: 1/3 tasks complete

INSTRUCTIONS:

1. Read ralph.json config
2. Read scripts/ralph/progress.json for context
3. Execute the next ready task
4. Run quality checks (typecheck, tests, lint)
5. Update progress.json and prd.json
6. Commit changes
7. Create new session with updated context using: /new [updated context]
8. Continue until all tasks complete

Use the ralph skill when ready to continue.

Execution Loop Details

Step 1: Load Configuration

Read ralph.json to determine:

• Task source (prd.json or task_list)

• Quality check commands

• Harness type

• Progress file location

Step 2: Find Next Task

For PRD JSON:

• Read prd.json

• Filter tasks where status: "open" and all dependencies are in completedTasks

• Pick first ready task

For task_list:

• Query tasks with ready: true, status: "open"

• Filter to descendants of parent task

• Pick first ready leaf task

Step 3: Execute Task

Implement the task following the description. Always:

• Run quality checks after implementation

• Fix issues until all checks pass

• Update task status to "completed"

Step 4: Update Progress

Append to progress file:

• What was implemented

• Files changed

• Learnings for future sessions

• Updated task counts

Step 5: Handoff

Create new session with:

• Original prompt

• Summary of completed work

• Context from progress file

• Instructions to continue the loop

Step 6: Termination

When no more ready tasks exist:

• Verify all tasks are completed

• Archive progress file

• Clear ralph.json or mark as complete

• Report: "✅ All tasks complete!"

Quality Requirements

Every task MUST pass:

• Typecheck (if configured)

• Tests (if configured)

• Lint (if configured)

• Changes committed

Do NOT proceed to next task until all checks pass.

Key Files

File Purpose

ralph.json

Configuration (task source, prompt, harness)

scripts/ralph/progress.json

Session-to-session memory

scripts/ralph/archive/

Completed run archives

prd.json or task_list Task definitions

Examples

Example 1: PRD JSON with Generic Harness

User creates prd.json

cat > tasks/auth-prd.json << 'EOF' { "feature": "Authentication", "tasks": [ {"id": "1", "title": "Add users table", "dependencies": [], "status": "open"}, {"id": "2", "title": "Create login endpoint", "dependencies": ["1"], "status": "open"} ] } EOF

Configure ralph

cat > ralph.json << 'EOF' { "taskSource": {"type": "prd-json", "path": "tasks/auth-prd.json"}, "prompt": "Implement the next authentication task. Typecheck and tests must pass.", "harness": {"type": "generic", "newSessionCommand": "/new"} } EOF

Run

ralph

Example 2: task_list with amp Harness

Configure ralph for amp

cat > ralph.json << 'EOF' { "taskSource": {"type": "task-list", "parentTaskId": "task-abc123"}, "prompt": "Implement the next ready task. All quality checks must pass.", "harness": {"type": "amp"} } EOF

Run

ralph

References

• Setup Workflow - Detailed configuration

• Execution Loop - Full loop implementation

• Task Format - Writing task descriptions