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

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/:

fix_plan.md Format

# 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

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

After Each Implementation

1. Run tests (use commands from AGENT.md)
2. If PASS: Mark task - [x] in fix_plan.md
3. If FAIL: Fix the issue, repeat
4. 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:

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

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:

### 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

# 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

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

Common Patterns

Pattern: Feature Implementation

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

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

Pattern: Refactoring

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