vibe-fabric 0.3.3 → 0.4.0

package/dist/core/repo/templates/claude-scripts.js

@@ -15,191 +15,652 @@ Ralph Runner - Autonomous multi-session executor for vibe-fabric.
 
 This script manages autonomous execution loops for implementing plans
 or creating plans from scopes. It handles:
-- Session state persistence
-- Progress tracking
-- Error recovery
-- Notification hooks
+- One task per Claude session to prevent context exhaustion
+- Session state persistence with atomic writes
+- Progress tracking and resume capability
+- Error recovery with retry logic
+- Blocker detection (PLAN_BLOCKED marker)
 
 Usage:
     uv run ralph-runner.py --mode execute --plan PLAN-ID --loop
     uv run ralph-runner.py --mode plan --scope SCOPE-ID --loop
     uv run ralph-runner.py --status
     uv run ralph-runner.py --cancel
+    uv run ralph-runner.py --resume --loop
 """
 
 import argparse
 import json
 import os
+import re
+import shutil
+import subprocess
 import sys
+import time
 from datetime import datetime
 from pathlib import Path
-from typing import Optional
+from typing import Optional, Literal
 
 try:
     from pydantic import BaseModel
     from rich.console import Console
     from rich.panel import Panel
+    from rich.progress import Progress, SpinnerColumn, TextColumn
+    from rich.table import Table
 except ImportError:
     print("Dependencies not available. Run with: uv run ralph-runner.py")
     sys.exit(1)
 
 console = Console()
 
-# State file location
+# Configuration
 STATE_FILE = Path(".claude/ralph-state.json")
+PROMPT_FILE = Path(".claude/ralph-prompt.local.md")
+CLAUDE_CACHE_DIR = Path.home() / ".claude" / "cache" / "conversations"
+SESSION_TIMEOUT = 1800  # 30 minutes
+INTER_SESSION_DELAY = 3  # seconds between sessions
+MAX_RETRIES = 1  # retry failed tasks once
+
+
+class TaskState(BaseModel):
+    """State for a single task in the plan."""
+    id: int
+    status: Literal["pending", "in_progress", "completed", "blocked"]
+    started_at: Optional[str] = None
+    completed_at: Optional[str] = None
+    error: Optional[str] = None
+    retries: int = 0
 
 
 class RalphState(BaseModel):
     """Persistent state for Ralph sessions."""
-    active: bool = False
-    mode: str = "execute"  # execute or plan
-    target_id: str = ""  # PLAN-ID or SCOPE-ID
-    session_number: int = 0
-    started_at: Optional[str] = None
+    mode: Literal["execute", "plan"]
+    plan_id: Optional[str] = None
+    plan_path: Optional[str] = None
+    scope_id: Optional[str] = None
+    scope_path: Optional[str] = None
+    started_at: str
+    phase: Literal[
+        "research_pending", "executing", "cleanup_pending", "complete",
+        "extraction_pending", "planning", "validation_pending"
+    ]
+    current_task: int = 0
+    total_tasks: int = 0
+    research_complete: bool = False
+    tasks: list[TaskState] = []
     last_session_at: Optional[str] = None
     sessions_completed: int = 0
-    status: str = "idle"  # idle, running, paused, completed, failed
+    modules: list[str] = []  # For plan mode: identified modules
 
 
-def load_state() -> RalphState:
+def load_state() -> Optional[RalphState]:
     """Load state from file."""
     if STATE_FILE.exists():
         try:
-            data = json.loads(STATE_FILE.read_text())
-            return RalphState(**data)
-        except Exception:
-            return RalphState()
-    return RalphState()
+            return RalphState.model_validate_json(STATE_FILE.read_text())
+        except Exception as e:
+            console.print(f"[red]Error loading state: {e}[/red]")
+            return None
+    return None
 
 
 def save_state(state: RalphState) -> None:
-    """Save state to file."""
+    """Save state atomically using temp file + rename."""
     STATE_FILE.parent.mkdir(parents=True, exist_ok=True)
-    STATE_FILE.write_text(state.model_dump_json(indent=2))
+    temp_file = STATE_FILE.with_suffix('.tmp')
+    temp_file.write_text(state.model_dump_json(indent=2))
+    temp_file.rename(STATE_FILE)
 
 
-def show_status() -> None:
-    """Display current Ralph status."""
-    state = load_state()
+def delete_state() -> None:
+    """Clean up state and temp files."""
+    if STATE_FILE.exists():
+        STATE_FILE.unlink()
+    if PROMPT_FILE.exists():
+        PROMPT_FILE.unlink()
 
-    if not state.active:
-        console.print("[dim]Ralph is not active[/dim]")
+
+def clear_claude_cache() -> None:
+    """Clear Claude conversation cache for fresh context (REQ-2)."""
+    if CLAUDE_CACHE_DIR.exists():
+        try:
+            shutil.rmtree(CLAUDE_CACHE_DIR)
+            console.print("[dim]Cleared Claude cache for fresh context[/dim]")
+        except Exception as e:
+            console.print(f"[yellow]Warning: Could not clear cache: {e}[/yellow]")
+
+
+def load_prompt_template(name: str) -> str:
+    """Load a prompt template from .claude/prompts/."""
+    prompt_path = Path(f".claude/prompts/{name}.md")
+    if not prompt_path.exists():
+        raise FileNotFoundError(f"Prompt template not found: {prompt_path}")
+    return prompt_path.read_text()
+
+
+def count_tasks_in_plan(plan_path: str) -> int:
+    """Count implementation tasks/phases in a plan file."""
+    try:
+        content = Path(plan_path).read_text()
+        # Count phase/task markers in the plan
+        phases = re.findall(r'^##+ (?:Phase|Task|Step) \\d+', content, re.MULTILINE)
+        if phases:
+            return len(phases)
+        # Fallback: count numbered list items in Implementation Steps section
+        impl_match = re.search(r'## Implementation Steps\\n(.*?)(?=\\n## |$)', content, re.DOTALL)
+        if impl_match:
+            steps = re.findall(r'^\\d+\\.', impl_match.group(1), re.MULTILINE)
+            return len(steps) if steps else 5
+        return 5  # Default estimate
+    except Exception:
+        return 5
+
+
+def check_blocked(plan_path: str) -> Optional[str]:
+    """Check if plan has PLAN_BLOCKED marker. Returns blocker description if found."""
+    try:
+        content = Path(plan_path).read_text()
+        match = re.search(r'PLAN_BLOCKED:\\s*(.+?)(?:\\n|$)', content)
+        if match:
+            return match.group(1).strip()
+        return None
+    except Exception:
+        return None
+
+
+def generate_execute_prompt(state: RalphState) -> str:
+    """Generate prompt for execute mode based on current phase."""
+    if state.phase == "research_pending":
+        template = load_prompt_template("ralph-research")
+        return template.replace("{PLAN_PATH}", state.plan_path or "")
+    elif state.phase == "executing":
+        template = load_prompt_template("ralph-execution")
+        return (template
+            .replace("{PLAN_PATH}", state.plan_path or "")
+            .replace("{CURRENT_TASK}", str(state.current_task))
+            .replace("{TOTAL_TASKS}", str(state.total_tasks)))
+    elif state.phase == "cleanup_pending":
+        template = load_prompt_template("ralph-cleanup")
+        return template.replace("{PLAN_PATH}", state.plan_path or "")
+    return ""
+
+
+def generate_plan_prompt(state: RalphState) -> str:
+    """Generate prompt for plan mode based on current phase."""
+    if state.phase == "extraction_pending":
+        template = load_prompt_template("ralph-plan-extraction")
+        return template.replace("{SCOPE_PATH}", state.scope_path or "")
+    elif state.phase == "planning":
+        template = load_prompt_template("ralph-plan-module")
+        module_name = state.modules[state.current_task - 1] if state.current_task <= len(state.modules) else "unknown"
+        return (template
+            .replace("{SCOPE_PATH}", state.scope_path or "")
+            .replace("{MODULE_INDEX}", str(state.current_task))
+            .replace("{MODULE_NAME}", module_name))
+    elif state.phase == "validation_pending":
+        template = load_prompt_template("ralph-plan-validation")
+        return template.replace("{SCOPE_PATH}", state.scope_path or "")
+    return ""
+
+
+def run_claude_session(prompt: str) -> tuple[bool, str]:
+    """
+    Run a Claude Code session with the given prompt.
+    Returns (success, output).
+    """
+    # Write prompt to file for reference
+    PROMPT_FILE.parent.mkdir(parents=True, exist_ok=True)
+    PROMPT_FILE.write_text(prompt)
+
+    try:
+        # Run Claude with --print flag to capture output
+        result = subprocess.run(
+            ["claude", "--print", "-p", prompt],
+            capture_output=True,
+            text=True,
+            timeout=SESSION_TIMEOUT
+        )
+        output = result.stdout + result.stderr
+        return result.returncode == 0, output
+    except subprocess.TimeoutExpired:
+        return False, f"Session timed out after {SESSION_TIMEOUT}s"
+    except FileNotFoundError:
+        return False, "Claude CLI not found. Install Claude Code first."
+    except Exception as e:
+        return False, str(e)
+
+
+def run_execute_loop(state: RalphState, loop: bool) -> None:
+    """Run the execution loop for execute mode."""
+    while True:
+        console.print(f"\\n[bold cyan]━━━ Session {state.sessions_completed + 1} ━━━[/bold cyan]")
+        console.print(f"Phase: [yellow]{state.phase}[/yellow], Task: {state.current_task}/{state.total_tasks}")
+
+        # Clear cache for fresh context (REQ-2)
+        clear_claude_cache()
+
+        # Generate prompt based on phase
+        try:
+            prompt = generate_execute_prompt(state)
+        except FileNotFoundError as e:
+            console.print(f"[red]Error: {e}[/red]")
+            break
+
+        if not prompt:
+            console.print("[red]No prompt generated for phase[/red]")
+            break
+
+        # Run Claude session with spinner
+        with Progress(
+            SpinnerColumn(),
+            TextColumn("[progress.description]{task.description}"),
+            console=console,
+        ) as progress:
+            desc = {
+                "research_pending": "Gathering research context...",
+                "executing": f"Executing task {state.current_task}...",
+                "cleanup_pending": "Running cleanup and verification...",
+            }.get(state.phase, "Running session...")
+            task = progress.add_task(desc, total=None)
+            success, output = run_claude_session(prompt)
+
+        if not success:
+            console.print(f"[red]Session failed: {output}[/red]")
+
+            # Retry logic for task execution
+            if state.phase == "executing" and state.current_task <= len(state.tasks):
+                current = state.tasks[state.current_task - 1]
+                if current.retries < MAX_RETRIES:
+                    current.retries += 1
+                    current.error = output
+                    save_state(state)
+                    console.print(f"[yellow]Retrying task {state.current_task} (attempt {current.retries + 1})...[/yellow]")
+                    time.sleep(INTER_SESSION_DELAY)
+                    continue
+                else:
+                    current.status = "blocked"
+                    current.error = output
+                    save_state(state)
+                    console.print(f"[red]Task {state.current_task} failed after retries[/red]")
+            break
+
+        # Update state based on phase
+        state.sessions_completed += 1
+        state.last_session_at = datetime.now().isoformat()
+
+        if state.phase == "research_pending":
+            state.research_complete = True
+            state.phase = "executing"
+            state.current_task = 1
+            if state.tasks:
+                state.tasks[0].status = "in_progress"
+                state.tasks[0].started_at = datetime.now().isoformat()
+            console.print("[green]Research complete. Starting task execution.[/green]")
+
+        elif state.phase == "executing":
+            # Mark current task complete
+            if state.tasks and state.current_task <= len(state.tasks):
+                state.tasks[state.current_task - 1].status = "completed"
+                state.tasks[state.current_task - 1].completed_at = datetime.now().isoformat()
+
+            # Check for blockers
+            if state.plan_path:
+                blocker = check_blocked(state.plan_path)
+                if blocker:
+                    console.print(f"[red]PLAN_BLOCKED detected: {blocker}[/red]")
+                    console.print("[yellow]Pausing execution. Resolve blocker and use --resume.[/yellow]")
+                    save_state(state)
+                    break
+
+            # Move to next task or cleanup
+            if state.current_task >= state.total_tasks:
+                state.phase = "cleanup_pending"
+                console.print("[green]All tasks complete. Starting cleanup phase.[/green]")
+            else:
+                state.current_task += 1
+                if state.current_task <= len(state.tasks):
+                    state.tasks[state.current_task - 1].status = "in_progress"
+                    state.tasks[state.current_task - 1].started_at = datetime.now().isoformat()
+                console.print(f"[dim]Moving to task {state.current_task}[/dim]")
+
+        elif state.phase == "cleanup_pending":
+            state.phase = "complete"
+            console.print("[bold green]Ralph execution complete![/bold green]")
+
+            # Move plan to completed folder
+            if state.plan_path:
+                plan_path = Path(state.plan_path)
+                completed_dir = plan_path.parent.parent / "completed"
+                if completed_dir.exists() and plan_path.exists():
+                    dest = completed_dir / plan_path.name
+                    plan_path.rename(dest)
+                    console.print(f"[dim]Plan moved to {dest}[/dim]")
+
+            delete_state()
+            break
+
+        save_state(state)
+
+        if not loop:
+            console.print("[dim]Single step mode. Exiting. Use --resume --loop to continue.[/dim]")
+            break
+
+        # Delay between sessions
+        console.print(f"[dim]Waiting {INTER_SESSION_DELAY}s before next session...[/dim]")
+        time.sleep(INTER_SESSION_DELAY)
+
+
+def run_plan_loop(state: RalphState, loop: bool) -> None:
+    """Run the planning loop for plan mode."""
+    while True:
+        console.print(f"\\n[bold cyan]━━━ Session {state.sessions_completed + 1} ━━━[/bold cyan]")
+        console.print(f"Phase: [yellow]{state.phase}[/yellow]")
+
+        # Clear cache for fresh context
+        clear_claude_cache()
+
+        # Generate prompt based on phase
+        try:
+            prompt = generate_plan_prompt(state)
+        except FileNotFoundError as e:
+            console.print(f"[red]Error: {e}[/red]")
+            break
+
+        if not prompt:
+            console.print("[red]No prompt generated for phase[/red]")
+            break
+
+        # Run Claude session
+        with Progress(
+            SpinnerColumn(),
+            TextColumn("[progress.description]{task.description}"),
+            console=console,
+        ) as progress:
+            desc = {
+                "extraction_pending": "Extracting modules from scope...",
+                "planning": f"Planning module {state.current_task}...",
+                "validation_pending": "Validating plan coverage...",
+            }.get(state.phase, "Running session...")
+            task = progress.add_task(desc, total=None)
+            success, output = run_claude_session(prompt)
+
+        if not success:
+            console.print(f"[red]Session failed: {output}[/red]")
+            break
+
+        # Update state based on phase
+        state.sessions_completed += 1
+        state.last_session_at = datetime.now().isoformat()
+
+        if state.phase == "extraction_pending":
+            # Parse modules from output (simplified)
+            state.phase = "planning"
+            state.current_task = 1
+            state.total_tasks = len(state.modules) if state.modules else 3
+            console.print(f"[green]Extraction complete. Planning {state.total_tasks} modules.[/green]")
+
+        elif state.phase == "planning":
+            if state.current_task >= state.total_tasks:
+                state.phase = "validation_pending"
+                console.print("[green]Module planning complete. Starting validation.[/green]")
+            else:
+                state.current_task += 1
+                console.print(f"[dim]Moving to module {state.current_task}[/dim]")
+
+        elif state.phase == "validation_pending":
+            state.phase = "complete"
+            console.print("[bold green]Ralph planning complete![/bold green]")
+            delete_state()
+            break
+
+        save_state(state)
+
+        if not loop:
+            console.print("[dim]Single step mode. Exiting.[/dim]")
+            break
+
+        time.sleep(INTER_SESSION_DELAY)
+
+
+def find_plan_path(plan_id: str) -> Optional[str]:
+    """Find the plan file path from ID."""
+    # Check active plans first
+    active_path = Path(f"vibe/implementation-plans/active/{plan_id}.md")
+    if active_path.exists():
+        return str(active_path)
+
+    # Check if it's a full path
+    if Path(plan_id).exists():
+        return plan_id
+
+    # Search for matching files
+    for pattern in ["vibe/implementation-plans/active/*.md", "vibe/implementation-plans/*.md"]:
+        for p in Path(".").glob(pattern):
+            if plan_id in p.name:
+                return str(p)
+
+    return None
+
+
+def find_scope_path(scope_id: str) -> Optional[str]:
+    """Find the scope file path from ID."""
+    # Check incoming scopes
+    incoming_path = Path(f"vibe/incoming-scopes/{scope_id}.md")
+    if incoming_path.exists():
+        return str(incoming_path)
+
+    # Check if it's a full path
+    if Path(scope_id).exists():
+        return scope_id
+
+    # Search for matching files
+    for p in Path("vibe/incoming-scopes").glob("*.md"):
+        if scope_id in p.name:
+            return str(p)
+
+    return None
+
+
+def start_execute(plan_id: str, loop: bool) -> None:
+    """Start execution mode for a plan."""
+    # Find plan file
+    plan_path = find_plan_path(plan_id)
+    if not plan_path:
+        console.print(f"[red]Plan not found: {plan_id}[/red]")
+        console.print("Expected location: vibe/implementation-plans/active/{plan_id}.md")
         return
 
-    status_color = {
-        "running": "green",
-        "paused": "yellow",
-        "completed": "blue",
-        "failed": "red",
-    }.get(state.status, "white")
+    # Count tasks
+    total_tasks = count_tasks_in_plan(plan_path)
 
-    console.print(Panel(
-        f"[bold]Mode:[/bold] {state.mode}\\n"
-        f"[bold]Target:[/bold] {state.target_id}\\n"
-        f"[bold]Status:[/bold] [{status_color}]{state.status}[/{status_color}]\\n"
-        f"[bold]Sessions:[/bold] {state.sessions_completed}\\n"
-        f"[bold]Started:[/bold] {state.started_at or 'N/A'}\\n"
-        f"[bold]Last Session:[/bold] {state.last_session_at or 'N/A'}",
-        title="Ralph Status",
-    ))
+    # Create state
+    state = RalphState(
+        mode="execute",
+        plan_id=plan_id,
+        plan_path=plan_path,
+        started_at=datetime.now().isoformat(),
+        phase="research_pending",
+        total_tasks=total_tasks,
+        tasks=[TaskState(id=i+1, status="pending") for i in range(total_tasks)]
+    )
 
+    save_state(state)
+    console.print(f"[green]Starting Ralph execute for {plan_id}[/green]")
+    console.print(f"Plan: {plan_path}")
+    console.print(f"Tasks: {total_tasks}")
+
+    run_execute_loop(state, loop)
 
-def start_session(mode: str, target_id: str, loop: bool) -> None:
-    """Start a Ralph session."""
-    state = load_state()
 
-    if state.active and state.status == "running":
-        console.print("[red]Ralph is already running. Use --cancel first.[/red]")
+def start_plan(scope_id: str, loop: bool) -> None:
+    """Start plan mode for a scope."""
+    # Find scope file
+    scope_path = find_scope_path(scope_id)
+    if not scope_path:
+        console.print(f"[red]Scope not found: {scope_id}[/red]")
+        console.print("Expected location: vibe/incoming-scopes/{scope_id}.md")
         return
 
-    state.active = True
-    state.mode = mode
-    state.target_id = target_id
-    state.status = "running"
-    state.started_at = datetime.now().isoformat()
-    state.session_number += 1
+    # Create state
+    state = RalphState(
+        mode="plan",
+        scope_id=scope_id,
+        scope_path=scope_path,
+        started_at=datetime.now().isoformat(),
+        phase="extraction_pending",
+    )
 
     save_state(state)
+    console.print(f"[green]Starting Ralph plan for {scope_id}[/green]")
+    console.print(f"Scope: {scope_path}")
 
-    console.print(f"[green]Starting Ralph {mode} for {target_id}[/green]")
+    run_plan_loop(state, loop)
 
-    if mode == "execute":
-        run_execute_session(target_id, state.session_number)
-    else:
-        run_plan_session(target_id, state.session_number)
 
-    # Update state after session
+def show_status() -> None:
+    """Display current Ralph status with task details."""
     state = load_state()
-    state.sessions_completed += 1
-    state.last_session_at = datetime.now().isoformat()
 
-    if not loop:
-        state.active = False
-        state.status = "completed"
+    if not state:
+        console.print("[dim]Ralph is not active[/dim]")
+        return
 
-    save_state(state)
+    # Count task statuses
+    completed = sum(1 for t in state.tasks if t.status == "completed")
+    blocked = sum(1 for t in state.tasks if t.status == "blocked")
+    in_progress = sum(1 for t in state.tasks if t.status == "in_progress")
 
+    # Status color
+    status_color = {
+        "research_pending": "yellow",
+        "executing": "green",
+        "cleanup_pending": "blue",
+        "complete": "cyan",
+        "extraction_pending": "yellow",
+        "planning": "green",
+        "validation_pending": "blue",
+    }.get(state.phase, "white")
+
+    # Build task table
+    task_lines = []
+    for t in state.tasks[:15]:  # Show first 15 tasks
+        icon = {
+            "completed": "[green]✓[/green]",
+            "in_progress": "[yellow]▶[/yellow]",
+            "blocked": "[red]✗[/red]",
+            "pending": "[dim]○[/dim]"
+        }[t.status]
+        task_lines.append(f"  {icon} Task {t.id}: {t.status}")
+
+    if len(state.tasks) > 15:
+        task_lines.append(f"  ... and {len(state.tasks) - 15} more tasks")
+
+    # Build panel
+    content = (
+        f"[bold]Mode:[/bold] {state.mode}\\n"
+        f"[bold]Target:[/bold] {state.plan_id or state.scope_id}\\n"
+        f"[bold]Path:[/bold] {state.plan_path or state.scope_path}\\n"
+        f"[bold]Phase:[/bold] [{status_color}]{state.phase}[/{status_color}]\\n"
+        f"[bold]Progress:[/bold] {completed}/{state.total_tasks} tasks"
+    )
 
-def run_execute_session(plan_id: str, session_number: int) -> None:
-    """Run an execution session."""
-    console.print(f"[cyan]Session {session_number}: Executing {plan_id}[/cyan]")
+    if blocked > 0:
+        content += f" [red]({blocked} blocked)[/red]"
 
-    # In a real implementation, this would:
-    # 1. Call Claude Code with the research agent
-    # 2. Call Claude Code with execution prompts
-    # 3. Call Claude Code with cleanup agent
+    content += (
+        f"\\n[bold]Sessions:[/bold] {state.sessions_completed}\\n"
+        f"[bold]Started:[/bold] {state.started_at}\\n"
+        f"[bold]Last Session:[/bold] {state.last_session_at or 'N/A'}"
+    )
 
-    console.print("[yellow]Note: Ralph loop not fully implemented yet.[/yellow]")
-    console.print("Use /implement-plan for interactive execution.")
+    if task_lines:
+        content += "\\n\\n[bold]Tasks:[/bold]\\n" + "\\n".join(task_lines)
 
+    console.print(Panel(content, title="Ralph Status"))
 
-def run_plan_session(scope_id: str, session_number: int) -> None:
-    """Run a planning session."""
-    console.print(f"[cyan]Session {session_number}: Planning from {scope_id}[/cyan]")
 
-    # In a real implementation, this would:
-    # 1. Read the scope
-    # 2. Call Claude Code with planning prompts
-    # 3. Create the plan file
+def cancel_session() -> None:
+    """Cancel active Ralph session."""
+    state = load_state()
 
-    console.print("[yellow]Note: Ralph loop not fully implemented yet.[/yellow]")
-    console.print("Use /plan-from-scope for interactive planning.")
+    if not state:
+        console.print("[dim]No active Ralph session[/dim]")
+        return
 
+    delete_state()
+    console.print("[yellow]Ralph session cancelled[/yellow]")
 
-def cancel_session() -> None:
-    """Cancel the active Ralph session."""
+
+def resume_session(loop: bool) -> None:
+    """Resume an existing Ralph session."""
     state = load_state()
 
-    if not state.active:
-        console.print("[dim]No active Ralph session[/dim]")
+    if not state:
+        console.print("[red]No session to resume[/red]")
         return
 
-    state.active = False
-    state.status = "cancelled"
-    save_state(state)
+    if state.phase == "complete":
+        console.print("[dim]Session already complete[/dim]")
+        return
 
-    console.print("[yellow]Ralph session cancelled[/yellow]")
+    console.print(f"[green]Resuming {state.mode} for {state.plan_id or state.scope_id}[/green]")
+    console.print(f"Phase: {state.phase}, Progress: {state.current_task}/{state.total_tasks}")
+
+    if state.mode == "execute":
+        run_execute_loop(state, loop)
+    else:
+        run_plan_loop(state, loop)
 
 
 def main() -> None:
-    parser = argparse.ArgumentParser(description="Ralph autonomous executor")
+    parser = argparse.ArgumentParser(
+        description="Ralph autonomous executor - Multi-session task execution for vibe-fabric",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog="""
+Examples:
+  uv run ralph-runner.py --mode execute --plan PLAN-001 --loop
+  uv run ralph-runner.py --mode plan --scope SCOPE-042 --loop
+  uv run ralph-runner.py --status
+  uv run ralph-runner.py --resume --loop
+  uv run ralph-runner.py --cancel
+        """
+    )
     parser.add_argument("--mode", choices=["execute", "plan"], help="Execution mode")
     parser.add_argument("--plan", help="Plan ID for execute mode")
     parser.add_argument("--scope", help="Scope ID for plan mode")
-    parser.add_argument("--loop", action="store_true", help="Run in loop mode")
-    parser.add_argument("--status", action="store_true", help="Show status")
+    parser.add_argument("--loop", action="store_true", help="Run in loop mode until complete")
+    parser.add_argument("--step", action="store_true", help="Run single step only (debug)")
+    parser.add_argument("--status", action="store_true", help="Show current status")
     parser.add_argument("--cancel", action="store_true", help="Cancel active session")
+    parser.add_argument("--resume", action="store_true", help="Resume existing session")
 
     args = parser.parse_args()
 
+    # Handle --step as inverse of --loop
+    loop_mode = args.loop and not args.step
+
     if args.status:
         show_status()
     elif args.cancel:
         cancel_session()
+    elif args.resume:
+        resume_session(loop_mode)
     elif args.mode == "execute" and args.plan:
-        start_session("execute", args.plan, args.loop)
+        # Check for existing session
+        existing = load_state()
+        if existing and existing.phase != "complete":
+            console.print("[yellow]Existing session found. Use --resume to continue or --cancel first.[/yellow]")
+            show_status()
+            return
+        start_execute(args.plan, loop_mode)
     elif args.mode == "plan" and args.scope:
-        start_session("plan", args.scope, args.loop)
+        # Check for existing session
+        existing = load_state()
+        if existing and existing.phase != "complete":
+            console.print("[yellow]Existing session found. Use --resume to continue or --cancel first.[/yellow]")
+            show_status()
+            return
+        start_plan(args.scope, loop_mode)
     else:
         parser.print_help()