Ralph Loop

# Ralph Loop Command

**Arguments:** [issue-number|--auto] [--continue] [--stop] [--prd-only] [--dry-run] [--iterations=N (default: 20)] [--force] [--no-policy]

**Description:** PRD-driven autonomous loop using Max subscription. Uses `/clear` + SessionStart hook for fresh context per iteration.

---

## Purpose

Execute PRD user stories autonomously:

```bash
/ralph-loop                     # Start loop from existing PRD
/ralph-loop 123                 # Fetch issue #123, generate PRD, start loop
/ralph-loop --continue          # Resume after /clear (called by hook)
/ralph-loop --stop              # Disable auto-resume, stop loop
/ralph-loop --prd-only          # Use existing PRD without GitHub fetch
/ralph-loop --dry-run           # Generate PRD only, don't start loop

---

How It Works

┌─────────────────────────────────────────────────────┐
│              Ralph Loop Flow (Internal)             │
├─────────────────────────────────────────────────────┤
│ 1. Read .ralph/prd.json                             │
│ 2. Read .ralph/instructions.md (delegation policy)  │
│ 3. Find first story where passes === false          │
│ 4. Delegate to /architect, /conductor, /audit, etc. │
│ 5. Verify completion (TypeScript, tests)            │
│ 6. Update prd.json (passes=true, notes)            │
│ 7. Git commit the changes                           │
│ 8. Run /clear to reset context                      │
│ 9. SessionStart hook → /ralph-loop --continue       │
└─────────────────────────────────────────────────────┘

Key files:

• .ralph/loop-active - Flag to enable auto-resume
• .ralph/prd.json - PRD with user stories
• .ralph/instructions.md - Delegation policy

---

Prerequisites

This command requires:

1. GitHub CLI (gh) - For issue fetching (unless using --prd-only)
2. Project-specific .ralph/ directory - With instructions.md (optional, provides agent policy)

---

Workflow

Step 1: Parse Arguments

ISSUE_NUMBER=""
DRY_RUN="false"
MAX_ITERATIONS="20"
FORCE_OVERWRITE="false"
NO_POLICY="false"
CONTINUE_MODE="false"
STOP_MODE="false"
PRD_ONLY="false"

# Parse arguments
for arg in "$@"; do
  case $arg in
    --continue) CONTINUE_MODE="true" ;;
    --stop) STOP_MODE="true" ;;
    --prd-only) PRD_ONLY="true" ;;
    --dry-run) DRY_RUN="true" ;;
    --iterations=*) MAX_ITERATIONS="${arg#*=}" ;;
    --auto) ISSUE_NUMBER="auto" ;;
    --force) FORCE_OVERWRITE="true" ;;
    --no-policy) NO_POLICY="true" ;;
    [0-9]*) ISSUE_NUMBER="$arg" ;;
  esac
done

# Project paths
PROJECT_ROOT="$(pwd)"
RALPH_DIR="${PROJECT_ROOT}/.ralph"
PRD_FILE="${RALPH_DIR}/prd.json"
PROGRESS_FILE="${RALPH_DIR}/progress.txt"
INSTRUCTIONS_FILE="${RALPH_DIR}/instructions.md"

echo "Ralph Loop - PRD-driven autonomous development"
echo "=============================================="
echo "Project: $PROJECT_ROOT"

# Handle --stop mode immediately
if [[ "$STOP_MODE" == "true" ]]; then
  rm -f "$RALPH_DIR/loop-active"
  echo "Ralph loop stopped. Auto-resume disabled."
  exit 0
fi

Step 2: Handle --continue Mode (Resume from Hook)

if [[ "$CONTINUE_MODE" == "true" ]]; then
  if [[ ! -f "$PRD_FILE" ]]; then
    echo "ERROR: No PRD found at $PRD_FILE"
    exit 1
  fi

  # Skip to execution
  PRD_ONLY="true"
fi

Step 3: Handle --prd-only Mode (Use Existing PRD)

if [[ "$PRD_ONLY" == "true" ]]; then
  if [[ ! -f "$PRD_FILE" ]]; then
    echo "ERROR: No PRD found at $PRD_FILE"
    echo "Generate one first: /ralph-loop [issue-number]"
    exit 1
  fi

  echo "Using existing PRD: $PRD_FILE"
  # Skip GitHub fetch, go to execution
fi

Step 4: Fetch GitHub Issue (if not --prd-only)

if [[ "$PRD_ONLY" != "true" && -n "$ISSUE_NUMBER" ]]; then
  echo ""
  echo "Fetching GitHub issue #$ISSUE_NUMBER..."

  if ! command -v gh &> /dev/null; then
    echo "ERROR: GitHub CLI (gh) not installed"
    exit 1
  fi

  ISSUE_DATA=$(gh issue view "$ISSUE_NUMBER" --json number,title,body,labels 2>/dev/null)
  if [[ -z "$ISSUE_DATA" ]]; then
    echo "ERROR: Issue #$ISSUE_NUMBER not found"
    exit 1
  fi

  ISSUE_TITLE=$(echo "$ISSUE_DATA" | jq -r '.title')
  ISSUE_BODY=$(echo "$ISSUE_DATA" | jq -r '.body')
  echo "Issue: #$ISSUE_NUMBER - $ISSUE_TITLE"

  # Generate PRD from issue (simplified - creates single story)
  mkdir -p "$RALPH_DIR"

  PROJECT_NAME=$(jq -r '.name // empty' package.json 2>/dev/null || basename "$PROJECT_ROOT")

  cat > "$PRD_FILE" << EOF
{
  "name": "$PROJECT_NAME",
  "description": "Implementation for GitHub Issue #$ISSUE_NUMBER: $ISSUE_TITLE",
  "branchName": "feature/issue-$ISSUE_NUMBER",
  "userStories": [
    {
      "id": "US-001",
      "title": "$ISSUE_TITLE",
      "description": "$(echo "$ISSUE_BODY" | jq -Rs .)",
      "acceptanceCriteria": ["Implementation complete", "Tests pass", "Code reviewed"],
      "priority": 1,
      "passes": false,
      "notes": "",
      "executor": "implementation"
    }
  ],
  "metadata": {
    "sourceIssue": $ISSUE_NUMBER,
    "sourceTitle": "$ISSUE_TITLE",
    "generatedAt": "$(date -u +%Y-%m-%dT%H:%M:%SZ)",
    "generatedBy": "ralph-loop"
  }
}
EOF

  echo "PRD generated: $PRD_FILE"
fi

Step 5: Pre-flight Check - Instructions Policy

echo ""
echo "PRE-FLIGHT CHECK: Agent delegation policy..."

if [[ -f "$INSTRUCTIONS_FILE" ]]; then
  echo "Found: $INSTRUCTIONS_FILE"
  echo "Ralph will enforce project-specific agent delegation policies"

  # Validate instructions file has required content
  if grep -q "MUST delegate" "$INSTRUCTIONS_FILE" 2>/dev/null || \
     grep -q "NOT ALLOWED TO IMPLEMENT" "$INSTRUCTIONS_FILE" 2>/dev/null; then
    echo "Policy validated: Agent delegation enforcement present"
  else
    echo "WARNING: instructions.md may not enforce agent delegation"
    echo "Consider adding explicit delegation requirements"
  fi

else
  echo "No project-specific instructions found: $INSTRUCTIONS_FILE"
  echo ""

  if [[ "$NO_POLICY" == "true" ]]; then
    echo "WARNING: Running