Ralph-Style Autonomous Development Skill

When to Use This Skill

Invoke this skill when:

•User says "until done", "keep going until complete", "finish this"
•Task requires multiple iterations (tests passing, all features complete)
•Long-running autonomous development is requested
•User explicitly mentions "Ralph" or "autonomous loop"

Core Concept

Ralph is a bash wrapper for Claude Code that keeps you running until the job is done. This skill teaches you to work in a Ralph-compatible way, even without the external wrapper.

The Ralph Pattern

code

1. Read fix_plan.md → Pick next incomplete task
2. Implement → Run tests
3. Update fix_plan.md → Mark complete or note blockers
4. Repeat until ALL tasks complete
5. Output EXIT_SIGNAL: true when truly done

File Structure

Maintain these files in .ralph/:

File	Purpose
`PROMPT.md`	High-level project goals and rules
`fix_plan.md`	Checkbox task list (current work)
`AGENT.md`	Build/test commands

fix_plan.md Format

markdown

# Current Sprint Tasks

## Priority 1 (Critical)
- [ ] Task description here
- [x] Completed task

## Priority 2 (Important)
- [ ] Another task

## Blockers
- None currently

Working Loop Behavior

Before Each Implementation

•Read fix_plan.md
•Select the first unchecked - [ ] item
•Announce: "Working on: [task name]"

After Each Implementation

•Run tests (use commands from AGENT.md)
•If PASS: Mark task - [x] in fix_plan.md
•If FAIL: Fix the issue, repeat
•Move to next task

Completion Detection

DO NOT output EXIT_SIGNAL: true unless:

•ALL checkboxes in fix_plan.md are [x]
•ALL tests pass
•No remaining work

Output format when truly complete:

code

RALPH_STATUS:
  tasks_complete: true
  tests_passing: true
  EXIT_SIGNAL: true

Circuit Breaker Rules

Stop and ask for help if:

•Same error 3+ times in a row
•No progress for 3+ iterations
•Blocked by external dependency (API key, permission, etc.)

Example Workflow

code

User: "Implement feature X until all tests pass"

Claude Code:
1. Check/create .ralph/fix_plan.md
2. Break feature X into subtasks
3. Loop:
   - Pick first unchecked task
   - Implement
   - Run tests
   - Mark complete if passing
   - Repeat
4. When all done:
   RALPH_STATUS:
     tasks_complete: true
     tests_passing: true
     EXIT_SIGNAL: true

Integration with CLAUDE.md

Add to project's CLAUDE.md:

markdown

### Autonomous Development
- For "until done" tasks, follow `.claude/skills/ralph-autonomous-dev/SKILL.md`
- Always use fix_plan.md to track progress
- Output EXIT_SIGNAL: true only when truly complete

Commands Reference

bash

# Build & Test iOS
cd aniccaios && fastlane test

# Build & Test API
cd apps/api && npm test

# Run E2E Tests
maestro test maestro/ --include-tags smokeTest

Key Principles

•Never exit prematurely - Only EXIT_SIGNAL when ALL work is done
•Track progress explicitly - Update fix_plan.md after each task
•Test after every change - Don't mark complete without passing tests
•Ask for help when stuck - Circuit breaker prevents infinite loops
•Incremental commits - Commit after each completed task

Common Patterns

Pattern: Feature Implementation

code

1. Create fix_plan.md with subtasks
2. Implement each subtask
3. Test after each
4. Commit when task passes
5. Move to next

Pattern: Bug Fix

code

1. Reproduce the bug (write failing test)
2. Fix the code
3. Verify test passes
4. Commit
5. EXIT_SIGNAL: true

Pattern: Refactoring

code

1. Ensure all tests pass (baseline)
2. Make incremental changes
3. Run tests after each change
4. Commit when stable
5. EXIT_SIGNAL: true when complete

References

•Ralph GitHub
•Claude Code Best Practices