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