ralph-x

name	ralph-x
description	Build and run an AI development loop — collects pipeline, iterations, checklist, skills via conversation, then generates and executes a staged claude -p loop
argument-hint	[PROMPT]
allowed-tools	["Read","Write","Bash","Glob","Grep"]

Ralph-X: AI Development Loop Generator

Respond in the same language the user uses. Korean → Korean. English → English.

세션 시작 시 자동 마이그레이션

스킬이 호출되면 가장 먼저 아래 코드를 실행한다 (사용자 확인 없이 자동):

python3 -c "
import os, shutil
old = '.claude/ralph-x-runs'
new = 'ralph-x-runs'
if os.path.isdir(old):
    os.makedirs(new, exist_ok=True)
    for item in os.listdir(old):
        src = os.path.join(old, item)
        dst = os.path.join(new, item)
        if not os.path.exists(dst):
            shutil.move(src, dst)
    if not os.listdir(old):
        os.rmdir(old)
    print('migrated')
"

출력이 migrated이면: ".claude/ralph-x-runs/을 ralph-x-runs/로 자동 이동했습니다." 한 줄 안내. 파일이 없으면 조용히 넘어간다.

What You Do

You help the user build a multi-step claude -p loop. Collect requirements via conversation, generate a bash script, then auto-run it in background.

Flow

Step 1: Task (if not provided as argument)

Ask: "What task should I work on? / 어떤 작업을 할까요?"

Step 1-B: Execution Mode

Ask: "실행 방식을 선택하세요 / Choose execution mode:

1. claude-p 루프 — 백그라운드 스크립트 실행 (기본값)
2. in-session — 현재 대화에서 직접 실행"

기본값: 1 (claude-p)

Step 2: Pipeline

First, check if ralph-x-runs/presets.json exists and has entries.

Show the pipeline menu. If presets exist, append them after a separator:

어떻게 진행할까요? / How do you want to proceed?

1. 🚀 Quick — 바로 실행 (single step)
2. 📋 Standard — 분석 → 개발 → 검증
3. 🔬 Thorough — 분석 → 설계 → 개발 → 리뷰 → 테스트
4. 🎯 Custom — 직접 스텝 조합
─────────────────────────
5. kaggle-churn
   ① 분석 — "경쟁 솔루션 상위 10개 분석" (/browse)
   ② 개발 — "LightGBM baseline 구현"
   ③ 검증 — "CV 점수 확인 후 submission 생성" (/test)
6. web-scraper
   ① 분석 — "타겟 사이트 구조 파악"
   ② 개발 — "셀레니움으로 크롤러 구현" (/browse)

Preset display format: For each preset, show steps numbered with circled digits (①②③...). Each step line: ① {step name} — "{task_template or step description, truncated ~30 chars}" (/skill-name)

• Only show (/skill-name) if the step has a non-null skill
• Truncate prompt/description to ~30 chars with … if longer

If user selects a preset (5, 6, ...): load preset config, skip to Step 2-B (claude-p 모드일 때만) with preset's model as default, then Step 3 with preset's max_iterations as default, then Step 4 with preset's checklist pre-filled. Confirm and run.

If no presets exist, show only options 1-4.

If Custom: collect steps one by one ("Step 1?", "Step 2?", ... until "done"/"끝") Each step becomes a SEPARATE claude -p call. Ask if there's a skill to use per step (e.g., /browse, /review, /test, or skip)

Step 2-B: Model (claude-p 모드일 때만 / skip if in-session)

Ask: "어떤 모델로 돌릴까요? (기본: sonnet) / Which model? (default: sonnet)"

Options:

• sonnet (default)
• opus
• haiku
• or full model name (e.g., claude-sonnet-4-6)

Step 3: Iterations

Ask: "최대 몇 회 반복? (기본 10) / Max iterations? (default 10)"

Step 4: Completion Checklist

Ask: "완료 조건을 하나씩 알려주세요 (끝나면 '끝') / Add completion conditions one by one (say 'done' when finished)"

Collect items until done. This becomes a checklist in the prompt.

Step 5: Confirm & Generate

Show summary:

Task: ...
Model: sonnet
Pipeline: Step1 → Step2 → Step3
Iterations: 20
실행 방식: 현재 세션  (또는 claude-p 루프)
Checklist:
 - [ ] condition 1
 - [ ] condition 2
Skills: /browse (Step1), /test (Step3)

Ask to confirm. Then proceed to Step 5-B.

Step 5-B: Run Directory Setup

After user confirms, before generating the script:

1. Generate RUN_ID from task name:

   • Slugify: lowercase, spaces/special chars → hyphens, max 20 chars
   • If using a preset, use the preset name as RUN_ID
   • Examples: "유튜브 아이디어 검증" → youtube-idea-verify, "Kaggle trial" → kaggle-trial

2. Set RUN_DIR: ralph-x-runs/{RUN_ID}

3. Check for collision: If RUN_DIR already exists, append suffix: -2, -3, etc.

   RUN_ID="<slug>"
   RUN_DIR="ralph-x-runs/$RUN_ID"
   if [ -d "$RUN_DIR" ]; then
     i=2
     while [ -d "ralph-x-runs/${RUN_ID}-${i}" ]; do i=$((i+1)); done
     RUN_ID="${RUN_ID}-${i}"
     RUN_DIR="ralph-x-runs/$RUN_ID"
   fi
   

4. Check for running processes in this project:

   ps aux | grep "ralph-x-runs" | grep "$(pwd)" | grep -v grep
   

   If found, warn the user:

   ⚠️ 이 프로젝트에서 이미 Ralph-X 루프가 실행 중입니다.
   1. 기존 루프 중단하고 새로 시작
   2. 기존 루프 유지하고 새 런 추가 (병렬)
   3. 취소
   

5. .gitignore에 ralph-x-runs/ 자동 추가 (없으면 생성):

   if ! grep -qxF 'ralph-x-runs/' .gitignore 2>/dev/null; then
     echo 'ralph-x-runs/' >> .gitignore
   fi
   

6. Create the directory: mkdir -p "$RUN_DIR"

Step 6: Generate Script

Write prompts to temp files (one per step), then call claude -p "$(cat file)" for each. Each step uses a UNIQUE heredoc delimiter (S1EOF, S2EOF, S3EOF, ...).

CRITICAL: NEVER use --max-turns. Each step runs until it finishes on its own.

Create {RUN_DIR}/run.sh (NOT .claude/ralph-x-run.sh):

#!/bin/bash
# Ralph-X Auto-generated Loop
# Task: <task>
# Pipeline: <step names>
# Max iterations: <N>
# RUN_ID: <run_id>

set -euo pipefail

RUN_DIR="ralph-x-runs/<run_id>"
MODEL="<model>"
LOG_FILE="$RUN_DIR/log.md"
CHECKLIST_FILE="$RUN_DIR/checklist.md"

# Initialize log (only if not exists)
if [ ! -f "$LOG_FILE" ]; then
  cat > "$LOG_FILE" << 'LOGEOF'
# Ralph-X Work Log
Task: <task>
Started: <timestamp>
LOGEOF
fi

# Initialize checklist (only if not exists)
if [ ! -f "$CHECKLIST_FILE" ]; then
  cat > "$CHECKLIST_FILE" << 'CHECKEOF'
# Completion Checklist
- [ ] condition 1
- [ ] condition 2
CHECKEOF
fi

MAX_ITER=<N>

# Write step prompts to RUN_DIR (not /tmp — OS cleans /tmp on long runs)
PROMPT_DIR="$RUN_DIR/prompts"
mkdir -p "$PROMPT_DIR"

cat > "$PROMPT_DIR/step1.txt" << 'S1EOF'
You are in a Ralph-X loop.
Task: <task>
Current step: <step 1 description>
<skill instruction if any, e.g. "Use /browse skill to crawl ...">

- Read {RUN_DIR}/log.md for previous work
- Work autonomously. Do NOT ask questions.
- Append your summary to {RUN_DIR}/log.md when done.
S1EOF

cat > "$PROMPT_DIR/step2.txt" << 'S2EOF'
You are in a Ralph-X loop.
Task: <task>
Current step: <step 2 description>

- Read {RUN_DIR}/log.md for previous work
- Work autonomously. Do NOT ask questions.
- Append your summary to {RUN_DIR}/log.md when done.
S2EOF

cat > "$PROMPT_DIR/step3.txt" << 'S3EOF'
You are in a Ralph-X loop.
Task: <task>
Current step: <step 3 description>

- Read {RUN_DIR}/log.md for previous work
- Read {RUN_DIR}/checklist.md for remaining conditions
- Work autonomously. Do NOT ask questions.
- Append your summary to {RUN_DIR}/log.md when done.
- If a checklist item is done, mark it [x] in {RUN_DIR}/checklist.md
S3EOF

# Main loop
for i in $(seq 1 $MAX_ITER); do
  echo "━━━ Ralph-X iteration $i/$MAX_ITER ━━━"

  # Check if all checklist items are done
  if [ -f "$CHECKLIST_FILE" ] && ! grep -q '^\- \[ \]' "$CHECKLIST_FILE" 2>/dev/null; then
    echo "✅ All checklist items complete!"
    break
  fi

  # Step 1: <step 1 name>
  claude -p --model "$MODEL" "$(cat "$PROMPT_DIR/step1.txt")"

  # Step 2: <step 2 name>
  claude -p --model "$MODEL" "$(cat "$PROMPT_DIR/step2.txt")"

  # Step 3: <step 3 name>
  claude -p --model "$MODEL" "$(cat "$PROMPT_DIR/step3.txt")"

  echo "━━━ Iteration $i complete ━━━"
done

# Cleanup (prompts are inside RUN_DIR, keep for debugging; remove if not needed)
# rm -rf "$PROMPT_DIR"

echo "🏁 Ralph-X finished after $i iterations"

For conditional steps (e.g., "every 3 iterations"), wrap in an if:

  # Step 4: submit every 3 iterations
  if [ $((i % 3)) -eq 0 ]; then
    claude -p --model "$MODEL" "$(cat "$PROMPT_DIR/step4.txt")"
  fi

Step 7: Execute

Branch on execution mode chosen in Step 1-B.

Step 7-A: claude-p 루프 (기본)

1. Auto-save preset to ralph-x-runs/presets.json (no confirmation)
2. Auto-run in background: Use Bash tool with run_in_background: true to run bash {RUN_DIR}/run.sh
3. Report: "실행 시작했습니다. 스크립트: {RUN_DIR}/run.sh"

Do NOT ask "실행할까요?" — just run it.

Step 7-B: 현재 세션 실행 (in-session)

1. session_id 즉시 캡처 (Bash):

   SESSION_ID=$(ls -lt ~/.claude/worklogs/.collecting/*.jsonl 2>/dev/null \
     | awk 'NR==1{print $NF}' | xargs basename | sed 's/\.jsonl//')
   [ -z "$SESSION_ID" ] && SESSION_ID=$(ls -t ~/.claude/session-env/ 2>/dev/null | head -1)
   echo "$SESSION_ID"
   

2. mkdir -p {RUN_DIR}

3. Write tool로 {RUN_DIR}/session-state.json 생성:

   {
     "active": true,
     "session_id": "<SESSION_ID>",
     "run_id": "<RUN_ID>",
     "run_dir": "ralph-x-runs/<RUN_ID>",
     "checklist_file": "ralph-x-runs/<RUN_ID>/checklist.md",
     "current_iteration": 0,
     "max_iterations": <N>
   }
   

4. Write tool로 {RUN_DIR}/checklist.md 생성 (수집한 완료 조건들):

   - [ ] condition 1
   - [ ] condition 2
   

5. Write tool로 {RUN_DIR}/log.md 생성 (초기화):

   # Ralph-X Work Log
   Task: <task>
   Mode: in-session
   

6. 루프 실행 (current_iteration < max_iterations AND checklist 미완인 동안):

   • "━━━ Iteration {i}/{MAX} ━━━" 출력
   • pipeline 각 step 내용을 현재 대화에서 직접 수행 (claude -p 호출 금지)
     • {RUN_DIR}/log.md 읽어 이전 컨텍스트 파악
     • 작업 수행 후 결과를 {RUN_DIR}/log.md에 append
   • {RUN_DIR}/checklist.md 갱신 (완료 항목 [ ] → [x])
   • Bash로 session-state.json current_iteration 업데이트:

     python3 -c "
     import json; s=json.load(open('{RUN_DIR}/session-state.json'))
     s['current_iteration']={i}
     json.dump(s,open('{RUN_DIR}/session-state.json','w'))
     "
     

   • checklist 전부 [x] 시 break

7. 완료 처리:

   • Bash로 session-state.json active=false 업데이트:

     python3 -c "
     import json; s=json.load(open('{RUN_DIR}/session-state.json'))
     s['active']=False
     json.dump(s,open('{RUN_DIR}/session-state.json','w'))
     "
     

   • "✅ Ralph 루프 완료 ({N}회 반복)" 출력

중요: in-session 모드에서는 stop hook(ralph-x-gate.sh)이 session-state.json을 감시한다. checklist 미완 + iter < max 상태에서 대화 종료 시도 시 자동으로 차단된다.

Preset System

After generating, ALWAYS auto-save to ralph-x-runs/presets.json:

{
  "preset-name": {
    "model": "sonnet",
    "task_template": "...",
    "steps": [
      {"name": "...", "skill": "/browse or null"},
      {"name": "...", "skill": null},
      {"name": "...", "skill": null, "every_n": 3}
    ],
    "max_iterations": 20,
    "checklist": ["condition 1", "condition 2"]
  }
}

On next /ralph-x invocation, check for presets. If presets exist, append them to the Step 2 pipeline menu after a separator line (─────). Number them continuously (5, 6, 7, ...). Each preset shows its steps with detail:

5. preset-name
   ① step-name — "prompt excerpt ~30chars" (/skill-name)
   ② step-name — "prompt excerpt ~30chars"

• Show skill in parentheses after prompt excerpt, only if skill is not null
• Truncate task_template to ~30 chars for the prompt excerpt. If step has a dedicated description in steps[].name, use that as the step name.
• If user selects a preset number, skip to Step 2-B (claude-p 모드일 때만) with preset's model as default, then Step 3 with preset's max_iterations as default, then Step 4 with preset's checklist pre-filled. Confirm and run.

Rules

claude-p 모드 (Step 7-A)

• Do NOT start working on the task. You ONLY build the script and run it.
• Each step = one claude -p call. NEVER combine multiple steps into one call.
• NEVER use --max-turns on any claude -p call.
• Use UNIQUE heredoc delimiters per step (S1EOF, S2EOF, S3EOF, ...). NEVER reuse delimiters.
• Write prompts to temp files first, then claude -p "$(cat file)". Do NOT inline heredocs inside the for loop.
• Keep step prompts SHORT and SINGLE-PURPOSE.
• Always include log file read/write instructions in each step prompt (use {RUN_DIR}/log.md).
• Always include checklist check in each step prompt (use {RUN_DIR}/checklist.md).
• Step output files go in RUN_DIR: {RUN_DIR}/stage1.md, {RUN_DIR}/stage2.md, etc.
• Auto-save preset after generation. Do NOT ask.
• Auto-run in background after generation. Do NOT ask.

in-session 모드 (Step 7-B)

• session_id를 캡처한 즉시 session-state.json에 기록한다. 나중으로 미루지 않는다.
• 루프 중 claude -p 호출 금지. 현재 대화 컨텍스트에서 직접 수행한다.
• 매 iteration 후 반드시 session-state.json의 current_iteration을 업데이트한다. (stop hook이 이 값으로 차단 여부 판단)
• checklist 항목 완료 시 즉시 [ ] → [x] 로 갱신한다.
• 루프 완료 후 반드시 active=false 처리한다. (미처리 시 stop hook이 계속 차단)

in-session 모드 — 절대 멈추지 않는다 (필수 규칙)

ralph-x in-session 루프는 종료 조건 도달 전까지 절대 멈추지 않는다.

종료 조건은 단 두 가지 (둘 다 충족 필요 X — 둘 중 하나라도):

1. session-state.json의 current_iteration >= max_iterations
2. checklist.md의 모든 항목 [x]

그 외 어떤 상황에서도 루프를 멈추지 않는다. 결과가 fail이든, 가설이 막혀 보이든, 사용자가 질문/comment를 보내든 — 무조건 같은 응답 안에서 다음 iter를 Write/Bash로 즉시 진행한다.

금지 행동:

• "어떻게 갈지 정해주면", "어떤 방향으로?", "계속 진행할까요?", "이거 의미 있나" 등 사용자 컨펌 요청
• 결과 보고 후 응답 종료 (사용자 답 기다리기)
• fail N개 누적 후 "남은 X개 같은 패턴 반복 무의미" 자체 판단으로 멈춤
• "방향 전환 필요", "더 시도해도 무의미할 것" 같은 메타 판단으로 정지
• 같은 응답에서 결과 보고만 하고 다음 iter 코드 안 쓰는 행위

필수 행동:

• 결과 짧게 보고 → 같은 응답 안에서 다음 iter Write/Bash 즉시 실행
• 가설 막히면 시도 안 한 영역 자체 발굴 (사용자 안 묻고): 다른 자산군, 다른 timeframe, 다른 confirm 인자, 매크로 이벤트, 페어 통계차익, ML 분류 등
• 수정 필요하면 자체 판단으로 수정
• 결과 짜내기 (의미 있는 발견 자체 판단 후 log.md/checklist.md에 기록)

why: 사용자가 명시적으로 박은 룰 — "갯수+체크리스트 다 채울 때까지 사용자 컨펌 절대 받지 말고 니 알아서 판단·수정·결과 내라". 이 룰을 어기고 멈추면 사용자가 매번 짜증내고 같은 지적 반복. stop hook 인프라(ralph-x-gate.sh)는 LLM이 멈출 때 "계속 진행" 메시지를 띄우지만, LLM 자체가 "fail 누적 → 의미 없음 → 사용자 컨펌" 패턴으로 자체 정지하면 hook으로 못 막는다. 따라서 LLM 룰 강제.