Ralph Custom

---
description: Execute Ralph orchestration system for autonomous task execution
type: orchestration
---

# Ralph Orchestration Command

**Purpose**: Launch Ralph task agent to autonomously execute complex multi-step goals with continuous iteration until completion.

## ⚠️ Important: Ralph vs Genesis

**Ralph** = Standalone ralph-orchestrator fork at `$RALPH_REPO` (default: `$HOME/projects/ralph-orchestrator`)
- Uses Codex CLI by default (200K context via OpenRouter)
- Separate codebase from your project
- Command: `python -m ralph_orchestrator`

**Genesis** = Your project's orchestration system (different from Ralph!)
- Located at: `$PROJECT_ROOT/genesis/` (or your project's genesis path)
- **Uses Codex CLI by default** (can override with `--claude` flag)
- Command: `python genesis/genesis.py`
- See `/gene` command for Genesis execution

## Ralph Repository Location

**Required**: `$RALPH_REPO` (default: `$HOME/projects/ralph-orchestrator`)

This command will verify the Ralph repo exists before executing. If you want to use a different Ralph installation, specify the repo path as the first argument.

## Usage

```bash
/ralph_custom <goal-file-path> [max-iterations] [ralph-repo-path]

Parameters:

• goal-file-path: Path to markdown goal file defining the autonomous task
• max-iterations: (Optional) Maximum iterations before stopping (default: 20)
• ralph-repo-path: (Optional) Path to Ralph repo (default: $HOME/projects/ralph-orchestrator)

How Ralph Works

Ralph is an autonomous task agent that:

1. Uses Codex CLI by default - larger context windows (200K tokens) via OpenRouter
2. Reads goal files in markdown format with clear success criteria
3. Creates task-specific agents in tmux sessions for parallel work
4. Iterates continuously until goal completion or max iterations reached
5. Self-corrects errors by analyzing failures and adjusting approach
6. Commits progress regularly to track incremental changes
7. Reports completion with evidence of success criteria met

Default Agent: --agent codex (can override with --agent claude, --agent gemini, or --agent auto) Fallback Mode: Use --agent auto to try Codex → Claude → Gemini automatically

Goal File Format

Ralph goal files must follow this structure:

# Goal: [Clear one-sentence goal statement]

## Current Status
[Document starting state]

## Tasks
1. **Task Name**: Clear, actionable task description
2. **Task Name**: Next sequential task

## Success Criteria
✅ Criterion 1 (measurable outcome)
✅ Criterion 2 (verification method)
✅ Criterion 3 (deliverable exists)

## Autonomous Execution
Ralph should:
1. Read this goal file
2. Execute all tasks sequentially
3. Test after each step
4. Document results
5. Commit and push when complete

Best Practices for Ralph Goals

✅ DO: Write Autonomous-Ready Goals

• Clear success criteria: Ralph must know when it's done
• Measurable outcomes: "Tests pass" not "Code works"
• Specific paths: Provide exact file locations and repo paths
• Sequential tasks: Order matters - dependencies first
• Test validation: Include test commands Ralph can run
• Commit protocol: Specify when to commit (after each file, after task, etc.)

❌ DON'T: Create Vague Goals

• "Make it better" - No measurable outcome
• "Fix bugs" - Which bugs? Where?
• "Improve performance" - By how much?
• "Update documentation" - Which files? What content?

Example: Production Deployment Goal

# Goal: Complete Production MCP Server Deployment

## Current Status
✅ Mock server working (15/15 tests passing)
❌ Production server crashes (Firebase initialization error)

## Tasks

### Task 1: Fix Firebase Authentication
**Location**: `/path/to/project/src/config/firebase.ts`

**Issue**: Server crashes with "Service account object must contain 'private_key'"

**Fix**: Implement Application Default Credentials (ADC) support
```typescript
// Add ADC fallback path
else if (process.env.FIREBASE_PROJECT_ID) {
  console.log('🔑 Using Application Default Credentials (ADC)');
  firebaseApp = initializeApp({ projectId: process.env.FIREBASE_PROJECT_ID });
}

Validation:

cd /path/to/project
npm run build
npm start
curl http://localhost:3001/health  # Should return 200 OK

Task 2: Test Production Functionality

After server starts successfully:

1. Test campaign creation:

curl -X POST http://localhost:3001/api/campaigns \
  -H "Content-Type: application/json" \
  -d '{"user_id":"test","title":"Test Campaign","setting":"fantasy"}'

2. Test interaction (use campaign_id from step 1):

curl -X POST http://localhost:3001/api/campaigns/{id}/interaction \
  -H "Content-Type: application/json" \
  -d '{"user_id":"test","user_input":"I explore the dungeon"}'

3. Verify in Firebase Console: Campaign and interaction documents exist

Task 3: Document Production Deployment

Create PRODUCTION_DEPLOYMENT.md with:

• Prerequisites (Node.js, Firebase, credentials)
• Environment variables required
• Deployment steps
• Validation tests
• Known issues

Task 4: Commit and Push

git add -A
git commit -m "feat: add production deployment support with ADC authentication

- Implement Application Default Credentials fallback
- Add production deployment documentation
- Validate with real Firebase/Gemini credentials

Tested with campaign creation and interaction endpoints."
git push origin HEAD:production-deployment-work

Success Criteria

✅ Production server starts without errors (health endpoint responds) ✅ Campaign creation works with real Firebase (document exists in Firestore) ✅ Interaction endpoint works with real Gemini (response generated) ✅ PRODUCTION_DEPLOYMENT.md exists with complete deployment guide ✅ All changes committed and pushed to remote branch ✅ Final validation report created with test results

Autonomous Execution

Ralph should:

1. Read this goal file
2. Execut