your-project/
├── docs/ai/ralph/
│   ├── PROMPT.md      # Ralph's iteration instructions
│   ├── fix_plan.md    # Task list and priorities
│   ├── AGENTS.md      # Build/test instructions + learnings
│   └── status.json    # Iteration tracking
├── CLAUDE.md          # Symlink → docs/ai/ralph/AGENTS.md
└── .gitignore         # Updated to exclude docs/ai/ralph/

Ralph started. Beginning autonomous iteration loop...

=========================================
Starting iteration 1
=========================================
Iteration 1: Implemented user authentication
- Files changed: src/auth.ts, tests/auth.test.ts
- Tests: PASS (all 12 tests passing)
- Next: Add password reset flow

=========================================
Starting iteration 2
=========================================
Iteration 2: Implemented password reset flow
- Files changed: src/reset.ts, tests/reset.test.ts
- Tests: PASS (all 15 tests passing)
- Next: RALPH_COMPLETE

RALPH_COMPLETE signal detected. All tasks complete!

Ralph completed successfully!
- Total iterations: 2
- Status: complete
- All tasks in fix_plan.md have been completed.

User: /ralph:iterate

Iteration 3 complete.

Summary from ralph-worker:
- Implemented database migration system
- Files changed: src/migrations/, tests/migrations.test.ts
- Tests: PASS (all 18 tests passing)
- Next: Add user roles and permissions

To continue:
- Run /ralph:iterate again for the next iteration
- Run /ralph:start to begin autonomous looping

User: /ralph:stop

Ralph has been signaled to stop.

- The current iteration (if running) will finish naturally
- No new iterations will be spawned
- Status updated to 'stopped'

You can resume later with /ralph:start or run a single iteration with /ralph:iterate.

User: /ralph:reset

⚠️  WARNING: This will discard ALL uncommitted changes and untracked files.
This cannot be undone. Are you sure you want to proceed? (yes/no)

User: yes

✅ Repository reset complete
- All uncommitted changes discarded
- All untracked files removed
- Repository at: abc1234
- Status updated to: reset

/ralph:init

**Optionally edit `docs/ai/ralph/PROMPT.md`:**
Add project-specific instructions, adjust workflow, customize behavior.

### 3. Start Autonomous Development

Ralph will now work through your task list autonomously, committing progress after each task.

### 4. Monitor and Control

**Check progress:**
- Each iteration summary is displayed in chat
- View `docs/ai/ralph/fix_plan.md` to see completed tasks
- View `docs/ai/ralph/AGENTS.md` to see learnings accumulated

**Intervene if needed:**
- `/ralph:stop` - Stop gracefully
- `/ralph:iterate` - Step through one iteration manually
- `/ralph:reset` - Hard reset if stuck

**Resume:**
- `/ralph:start` - Resume autonomous loop

## Agents

Ralph uses two agents with different roles:

### ralph-worker (Sonnet 4.5)

**Role:** Executes one task per iteration with fresh context

**Configuration:**
- Model: Claude Sonnet 4.5
- Tools: Bash, Read, Edit, Write, Grep, Glob, Task
- bypassPermissions: true (autonomous operation)

**Behavior:**
- Starts each iteration with zero memory
- Reads context files: PROMPT.md, fix_plan.md, AGENTS.md, status.json
- Follows 9-step process: choose task → search → implement → test → document → update tracking → commit → tag → signal completion
- Returns concise summary to main session

**9-Step Process:**
1. Choose highest priority task from fix_plan.md
2. Search codebase with Glob/Grep to understand patterns
3. Implement solution (no placeholders, complete code only)
4. Test using commands from AGENTS.md
5. Document learnings in AGENTS.md
6. Update fix_plan.md (move task to Completed)
7. Commit with conventional commit message
8. Tag clean checkpoints (incremental versioning: 0.0.1, 0.0.2, ...)
9. Signal completion (RALPH_COMPLETE) or continue to next task

### ralph-oracle (Opus 4.5 + Extended Thinking)

**Role:** Provides deep reasoning for complex decisions

**Configuration:**
- Model: Claude Opus 4.5
- Tools: Read, Grep, Glob (read-only)
- extendedThinking: true (ultrathink mode)

**Behavior:**
- Spawned by ralph-worker only when needed
- Read-only access (cannot modify files)
- Uses extended thinking for deep analysis
- Returns structured recommendations

**When consulted:**
- Architecture decisions (which pattern to use)
- Priority conflicts (which task first)
- Debugging complex failures (root cause analysis)
- Validation before major refactoring

**Recommendation format:**

**Decision-making principles:**
1. Simplicity over complexity
2. Consistency with existing patterns
3. Completeness (no placeholders)
4. Eventual consistency (multiple simple iterations)
5. Fail forward (easy recovery)

## Safety Mechanisms

Ralph is designed with multiple safety layers:

### 1. Fresh Context Per Iteration
- Each iteration starts with zero memory
- Prevents context drift and hallucination accumulation
- Forces explicit knowledge capture in files
- Ensures reproducibility

### 2. bypassPermissions Mode
- ralph-worker runs with autonomous permissions
- No prompts for file operations or git commands
- Enables true autonomous operation
- Controlled environment (can be stopped with /ralph:stop)

### 3. User Checkpoints
- Prompts user every 10 iterations for continuation
- Prevents runaway loops
- Gives user regular control points
- Can decline to stop loop

### 4. Graceful Stop Signal
- `/ralph:stop` uses signal file (.ralph_stop)
- Current iteration finishes normally
- Clean shutdown, no abrupt termination
- Can resume with `/ralph:start`

### 5. One Task Per Iteration
- Single focus prevents scope creep
- Clear boundaries for each iteration
- Easy to review changes (one task = one commit)
- Reduces complexity

### 6. Automatic Commits
- Every completed task gets committed
- Provides rollback points
- Git history shows clear progress
- Can reset with `/ralph:reset` if needed

### 7. Oracle Consultation
- Complex decisions get Opus 4.5 + extended thinking
- Prevents worker from guessing on critical choices
- Read-only oracle cannot make changes
- Recommendations are explicit and traceable

### 8. Completion Signals
- RALPH_COMPLETE when all tasks done
- RALPH_BLOCKED when cannot proceed
- Clear exit conditions prevent infinite loops
- User knows when intervention needed

## Templates

Ralph uses 3 templates copied to your project during initialization:

### PROMPT.md - Iteration Instructions

Contains the 9-step process and core principles. Ralph reads this at the start of each iteration.

**Key sections:**
- Core Principles (fresh context, one task, eventual consistency)
- Context Loading (which files to read)
- Oracle Consultation (when and how to spawn oracle)
- 9-Step Iteration Process (detailed workflow)
- Return Format (how to summarize iteration)
- Failure Handling (what to do when stuck)

**Customization:**
Add project-specific instructions, adjust priorities, modify workflow.

### fix_plan.md - Task Tracking

The task list that drives Ralph's work. Tasks ordered by priority (top = highest).

**Sections:**
- **Tasks:** Pending work in priority order (markdown checkboxes)
- **Completed:** Finished tasks with timestamps
- **Blocked/Issues:** Tasks that cannot proceed with blocker descriptions

**Signals:**
- `RALPH_COMPLETE` at top = all tasks done
- `RALPH_BLOCKED: [reason]` = cannot proceed, needs user intervention

**Usage:**
Ralph moves tasks between sections after each iteration. You can edit this file anytime to add/remove/reprioritize tasks.

### AGENTS.md - Build/Test Instructions

Contains build commands, test commands, and accumulated learnings.

**Sections:**
- **How to Build:** Commands to build the project (npm install, make build, etc.)
- **How to Test:** Commands to run tests (npm test, pytest, etc.)
- **Learnings:** Discoveries from iterations (patterns, gotchas, useful context)

**Special note:**
This file is symlinked as `CLAUDE.md` in your project root, so Claude Code automatically reads it when starting any conversation in the project.

**Updates:**
Ralph appends learnings after each iteration. Build/test commands can be updated as needed.

## Troubleshooting

### Ralph won't start

**Error: "PROMPT.md not found"**
- Run `/ralph:init` first to initialize the project

**Error: "fix_plan.md is empty"**
- Add at least one task to the Tasks section in `docs/ai/ralph/fix_plan.md`

### Ralph is stuck or looping

**Same error repeated:**
1. Run `/ralph:stop` to stop the loop
2. Check `docs/ai/ralph/AGENTS.md` learnings for clues
3. Fix the issue manually or update fix_plan.md to skip the problematic task
4. Run `/ralph:reset` if the codebase is in a bad state
5. Resume with `/ralph:start` or single-step with `/ralph:iterate`

**Not making progress:**
- Check fix_plan.md for RALPH_BLOCKED signal
- Review the blocker description
- Resolve the blocker or adjust task priorities
- Resume with `/ralph:start`

### Tests keep failing

**Build/test commands wrong:**
1. Edit `docs/ai/ralph/AGENTS.md`
2. Update the "How to Build" and "How to Test" sections with correct commands
3. Ralph will read the updated commands on next iteration

**Environment issues:**
- Ralph runs in the same environment as Claude Code
- Check that dependencies are installed
- Verify git config (user.name, user.email) is set
- Ensure database/services are running if needed

### Commits have wrong author

**Git config not set:**
```bash
git config user.name "Your Name"
git config user.email "[email protected]"

Co-Authored-By: Ralph Wiggum <ralph@claude-code>