/hybrid-ralph

name: hybrid-ralph
version: "3.2.0"
description: Hybrid architecture combining Ralph's PRD format with Planning-with-Files' structured approach. Auto-generates PRDs from task descriptions, manages parallel story execution with dependency resolution, and provides context-filtered agents for efficient multi-story development.
user-invocable: true
allowed-tools:
  - Read
  - Write
  - Edit
  - Bash
  - Task
  - Glob
  - Grep
  - AskUserQuestion
hooks:
  PreToolUse:
    # Show execution context and current story for relevant tools
    - matcher: "Write|Edit|Bash|Task"
      hooks:
        - type: command
          command: |
            # Show hybrid execution context if we're in a hybrid task
            if [ -f "prd.json" ] || [ -f ".planning-config.json" ] || [ -f ".hybrid-execution-context.md" ]; then
              if command -v uv &> /dev/null; then
                # Update and display context reminder
                uv run python "${CLAUDE_PLUGIN_ROOT}/skills/hybrid-ralph/scripts/hybrid-context-reminder.py" both 2>/dev/null || true
              fi
            fi
            # Show current story context if we're executing a story
            if [ -f ".current-story" ]; then
              STORY_ID=$(cat .current-story 2>/dev/null || echo "")
              if [ -n "$STORY_ID" ]; then
                echo ""
                echo "=== Current Story: $STORY_ID ==="
                # Show story details from prd.json if available
                if command -v uv &> /dev/null; then
                  (cd "${CLAUDE_PLUGIN_ROOT}" && uv run python -m plan_cascade.state.context_filter get-story "$STORY_ID" 2>/dev/null | head -20) || true
                fi
                echo ""
              fi
            fi
  PostToolUse:
    # Update context file and remind to update findings after significant operations
    - matcher: "Write|Edit|Bash|Task"
      hooks:
        - type: command
          command: |
            # Update execution context file
            # Best-effort: script exits silently if no hybrid context is detected.
            if command -v uv &> /dev/null; then
              uv run python "${CLAUDE_PLUGIN_ROOT}/skills/hybrid-ralph/scripts/hybrid-context-reminder.py" update 2>/dev/null || true
            elif command -v python &> /dev/null; then
              python "${CLAUDE_PLUGIN_ROOT}/skills/hybrid-ralph/scripts/hybrid-context-reminder.py" update 2>/dev/null || true
            fi
            # Remind about findings
            if [ -f ".current-story" ]; then
              STORY_ID=$(cat .current-story 2>/dev/null || echo "")
              if [ -n "$STORY_ID" ]; then
                echo "[hybrid-ralph] Consider updating findings.md with this discovery (tag with <!-- @tags: $STORY_ID -->)"
              fi
            fi
  Stop:
    # Verify story completion before stopping
    - hooks:
        - type: command
          command: |
            if [ -f ".current-story" ]; then
              STORY_ID=$(cat .current-story 2>/dev/null || echo "")
              if [ -n "$STORY_ID" ]; then
                echo ""
                echo "=== Story Completion Check ==="
                echo "Current story: $STORY_ID"
                echo "Mark complete in progress.txt with: [COMPLETE] $STORY_ID"
                echo ""
              fi
            fi

Hybrid Ralph + Planning-with-Files

A hybrid architecture combining the best of three approaches:

Auto-Recovery Protocol (CRITICAL)

**At the START of any interaction**, perform this check to recover context after compression/truncation:

1. Check if `.hybrid-execution-context.md` exists in the current directory 2. If YES:

• Read the file content using Read tool
• Display: "Detected ongoing hybrid task execution"
• Show current batch and pending stories from the file
• Resume story execution based on the state
• If unsure of state, suggest: `/hybrid:resume --auto`

3. If NO but `prd.json` exists:

• Run: `uv run python "${CLAUDE_PLUGIN_ROOT}/skills/hybrid-ralph/scripts/hybrid-context-reminder.py" both`
• This will generate the context file and display current state

This ensures context recovery even after:

• Context compression (AI summarizes old messages)
• Context truncation (old messages deleted)
• New conversation session
• Claude Code restart

• **Ralph**: Structured PRD format (prd.json), progress tracking patterns, small task philosophy
• **Planning-with-Files**: 3-file planning pattern (task_plan.md, findings.md, progress.txt), Git Worktree support
• **Claude Code Native**: Task tool with subagents for parallel story execution

Quick Start

Automatic PRD Generation

Generate a PRD from your task description:

/hybrid:auto Implement a user authentication system with login, registration, and password reset

This will: 1. Launch a Planning Agent to analyze your task 2. Generate a PRD with user stories 3. Show the PRD for review 4. Wait for your approval

Manual PRD Loading

Load an existing PRD file:

/hybrid:manual path/to/prd.json

Approval and Execution

After reviewing the PRD:

/approve

This begins parallel execution of stories according to the dependency graph.

Architecture

File Structure

project-root/
├── prd.json                 # Product Requirements Document
├── findings.md              # Research findings (tagged by story)
├── progress.txt             # Progress tracking
├── .current-story           # Currently executing story
├── .locks/                  # File locks for concurrent access
└── .agent-outputs/          # Individual agent logs

The PRD Format

The `prd.json` file contains:

• **metadata**: Creation date, version, description
• **goal**: One-sentence project goal
• **objectives**: List of specific objectives
• **stories**: Array of user stories with:
• `id`: Unique story identifier (story-001, story-002, etc.)
• `title`: Short story title
• `description`: Detailed story description
• `priority`: high, medium,