colmarius/ralph

Ralph Autonomous Agent

Orchestrates autonomous code generation through repeated iterations using fresh agent instances until all tasks are complete.

Execution Contract

Inputs

When invoking ralph, provide:

• Plan file path: Absolute or workspace-relative path to the plan markdown file
• Starting task (optional): Task ID to resume from (e.g., "Task 3")
• Max tasks (optional): Maximum tasks to complete before pausing for review (default: 5)
• Max iterations (optional): Default 20

State Files

Ralph creates a companion progress file alongside the plan:

.agents/plans/in-progress/
├── my-feature.md              # The plan
└── my-feature.progress.md     # Progress log (auto-created)

Task Status Markers

In plan files, tasks use checkbox status with optional annotations:

| Marker | Meaning | |--------|---------| | - [ ] | Not started | | - [x] | Completed | | - [ ] (blocked) | Blocked, needs intervention | | - [ ] (manual-verify) | Requires manual verification |

Stop Conditions

The loop exits when ANY of these occur:

1. All tasks complete: Every task checkbox is [x]
2. Max tasks reached: Completed N tasks this session (default: 5) — pause for user review
3. Blocked encountered: A task is marked (blocked)
4. Max iterations reached: Default 20 iterations
5. Only manual-verify remaining: All incomplete tasks require manual verification
6. Explicit stop: User interrupts

Handoff Payload

When handing off to fresh iteration, include:

Continue ralph execution for: [plan file path]

Current task: [Task ID and title]
Tasks completed this session: [N of max_tasks]
Last progress: [Most recent progress entry summary]
Next action: [Specific next step]

Load the ralph skill and continue execution.

Pause for Review

When max tasks is reached (before all tasks complete):

1. Update progress file: Log "Paused after N tasks for review"
2. Commit all work: Ensure all completed tasks are committed
3. Report to user: List completed tasks and next task to resume from
4. Do NOT handoff: Wait for user to review and continue

Resume command:

Continue ralph from Task X on [plan file path]

Phases

Phase 1: Setup

Before running the loop, ensure the plan has proper structure.

Required task format:

- [ ] **Task N: Short descriptive title**
  - Scope: `path/to/affected/files` or package name
  - Depends on: Task M (or "none")
  - Acceptance:
    - Specific criterion 1
    - Specific criterion 2
  - Notes: Optional implementation hints

Task sizing rule: If you can't describe the task in 2-3 sentences, it's too big. Split it.

Dependency ordering: Schema → Service → API → UI → Tests

Phase 2: Execution Loop

Each iteration follows this workflow:

1. Load context: Read plan file, identify next incomplete task, track tasks completed this session
2. Check dependencies: Ensure all Depends on tasks are complete
3. Implement: Complete the task following its scope and acceptance criteria
4. Verify: Run verification commands (see Verification section)
5. Update progress: Append entry to .progress.md
6. Update plan: Check off completed task [x]
7. Commit: One task = one commit with proper footers
8. Increment counter: tasks_completed++
9. Check stop conditions:
   • If tasks_completed >= max_tasks → pause for review (do NOT handoff)
   • If all tasks complete → exit with success
   • Otherwise → handoff to next iteration

Git discipline:

• One task = one commit
• Never push to main branch
• Include footers: Amp-Thread-ID and Co-authored-by: Amp <[email protected]>
• Commit format: feat: [Task ID] - [Task Title]

Verification Strategy

Run verification commands appropriate for the project. Check AGENTS.md for project-specific commands.

| Situation | Action | |-----------|--------| | Every task | Run typecheck/build command | | After code changes | Run linter | | Logic changes | Run tests | | Pre-commit | Run full CI check |

Examples by language:

# TypeScript/Node
npm run check && npm run lint && npm test

# Rust
cargo check && cargo clippy && cargo test

# Go
go build ./... && go test ./...

# Python
mypy . && ruff check . && pytest

Stuck Detection & Safety

Limits

• Max iterations: 20 per session
• Max retries per task: 2 attempts before marking blocked
• Scope control: Only modify files in declared Scope

Blocking a Task

When a task cannot proceed:

1. Add (blocked) annotation to the task checkbox
2. Add blocker details to progress file
3. Stop the loop and surface to user

Example blocked task:

- [ ] (blocked) **Task 5: Integrate payment API**
  - Scope: `cloud/functions/payments`
  - Depends on: Task 4
  - Acceptance: Payment webhook handler works
  - Notes: Blocked - need API credentials from finance team

Manual Verification Tasks

Tasks marked (manual-verify) require human interaction:

• Don't retry these automatically
• Stop loop when only manual-verify tasks remain
• Surface verification instructions to user

Guardrails

1. Scope control: Only touch files in declared Scope
2. No scope creep: Expanding scope requires explicit plan edit
3. No prod commands: Never run production deployments
4. No secrets: Never commit credentials or API keys
5. Branch safety: Never push to main

Usage

Starting Fresh

Run ralph on .agents/plans/tech-debt/in-progress/my-feature.md

Resuming

Continue ralph from Task 5 on .agents/plans/tech-debt/in-progress/my-feature.md

Checking Status

Show ralph progress for .agents/plans/tech-debt/in-progress/my-feature.md

Integration with Plans

Ralph works with plans in the standard directory structure:

• Plans live in .agents/plans/in-progress/
• Create plans manually following the task format above
• Use ralph to execute plans autonomously