--- 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 python3 &> /dev/null; then # Update and display context reminder python3 "${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 python3 &> /dev/null; then python3 "${CLAUDE_PLUGIN_ROOT}/skills/hybrid-ralph/core/context_filter.py" 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" hooks: - type: command command: | # Update execution context file if [ -f "prd.json" ]; then if command -v python3 &> /dev/null; then python3 "${CLAUDE_PLUGIN_ROOT}/skills/hybrid-ralph/scripts/hybrid-context-reminder.py" update 2>/dev/null || true fi 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 )" 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: `/plan-cascade:hybrid-resume --auto` 3. If NO but `prd.json` exists: - Run: `python3 "${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, or low - `dependencies`: Array of story IDs this story depends on - `status`: pending, in_progress, or complete - `acceptance_criteria`: List of completion criteria - `context_estimate`: small, medium, large, or xlarge - `tags`: Array of tags for categorization ### Parallel Execution Model Stories are organized into **execution batches**: 1. **Batch 1**: Stories with no dependencies (run in parallel) 2. **Batch 2+**: Stories whose dependencies are complete (run in parallel) ``` Batch 1 (Parallel): - story-001: Design database schema - story-002: Design API endpoints Batch 2 (After story-001 complete): - story-003: Implement database schema Batch 3 (After story-002, story-003 complete): - story-004: Implement API endpoints ``` ### Context Filtering Each agent receives **only relevant context**: - Their story description and acceptance criteria - Summaries of completed dependencies - Findings tagged with their story ID This keeps context windows focused and efficient. ## Core Python Modules ### context_filter.py Filters and extracts relevant context for specific stories. ```bash # Get story details python3 context_filter.py get-story story-001 # Get context for a story python3 context_filter.py get-context story-001 # Get execution batch python3 context_filter.py get-batch 1 # Show full execution plan python3 context_filter.py plan-batches ``` ### state_manager.py Thread-safe file operations with platform-specific locking. ```bash # Read PRD python3 state_manager.py read-prd # Mark story complete python3 state_manager.py mark-complete story-001 # Get all story statuses python3 state_manager.py get-statuses ``` ### prd_generator.py Generates PRD from task descriptions and manages story dependencies. ```bash # Validate PRD python3 prd_generator.py validate # Show execution batches python3 prd_generator.py batches # Create sample PRD python3 prd_generator.py sample ``` ### orchestrator.py Manages parallel execution of stories. ```bash # Show execution plan python3 orchestrator.py plan # Show execution status python3 orchestrator.py status # Execute a batch python3 orchestrator.py execute-batch 1 ``` ## Commands Reference ### /hybrid:auto Generate PRD from task description. ``` /hybrid:auto ``` ### /hybrid:manual Load existing PRD file. ``` /hybrid:manual [path/to/prd.json] ``` ### /hybrid:worktree Create a new Git worktree with isolated environment and initialize Hybrid Ralph mode. This is the **primary command** for multi-task parallel development. ``` /hybrid:worktree ``` **Arguments:** - `task-name`: Name for the worktree (e.g., "feature-auth", "fix-api-bug") - `target-branch`: Branch to merge into (default: auto-detect main/master) - `task-description-or-prd-path`: Either a task description to generate PRD, or path to existing PRD file **Execution Steps:** When `/hybrid:worktree` is invoked, execute the following: 1. **Parse Parameters**: Extract task-name, target-branch, and PRD argument 2. **Verify Git Repository**: Ensure we're in a git repository 3. **Detect Default Branch**: Auto-detect main/master branch 4. **Set Variables**: ```bash TASK_BRANCH="$TASK_NAME" ORIGINAL_BRANCH=$(git branch --show-current) ROOT_DIR=$(pwd) WORKTREE_DIR="$ROOT_DIR/.worktree/$(basename $TASK_NAME)" ``` 5. **Determine PRD Mode**: Check if third argument is existing file or task description 6. **Check for Existing Worktree**: If worktree exists, navigate to it; otherwise create new worktree 7. **Create Git Worktree** (if new): ```bash git worktree add -b "$TASK_BRANCH" "$WORKTREE_DIR" "$TARGET_BRANCH" ``` 8. **Create Planning Configuration** in worktree: ```bash cat > "$WORKTREE_DIR/.planning-config.json" << EOF { "mode": "hybrid", "task_name": "$TASK_NAME", "task_branch": "$TASK_BRANCH", "target_branch": "$TARGET_BRANCH", "worktree_dir": "$WORKTREE_DIR", "original_branch": "$ORIGINAL_BRANCH", "root_dir": "$ROOT_DIR", "created_at": "$(date -u +%Y-%m-%dT%H:%M:%SZ)" } EOF ``` 9. **Create Initial Files** in worktree (findings.md, progress.txt) 10. **Navigate to Worktree**: ```bash cd "$WORKTREE_DIR" ``` 11. **Handle PRD**: - If `PRD_MODE` is "load": Copy PRD file to worktree - If `PRD_MODE` is "generate": Use Task tool with run_in_background=true to generate PRD - IMPORTANT: After launching Task, immediately use TaskOutput with block=true to wait for completion - DO NOT use sleep loops 12. **Validate and Display PRD**: Show the generated/loaded PRD with review 13. **Show Ready Summary** with next steps **Smart PRD Detection:** - If third argument is an existing file → Load that PRD - If third argument is not a file → Use as task description to generate PRD ### /approve Approve PRD and begin parallel story execution with batch progression. ``` /approve ``` **Execution Steps:** 1. **Verify PRD Exists**: Check if `prd.json` exists in current directory 2. **Read and Validate PRD**: Validate structure and required fields 3. **Calculate Execution Batches**: Analyze dependencies and create parallel execution batches - Batch 1: Stories with no dependencies (can run in parallel) - Batch 2+: Stories whose dependencies are complete 4. **Choose Execution Mode**: Ask user to select execution mode: ``` ========================================== Select Execution Mode ========================================== [1] Auto Mode - Automatically progress through batches Pause only on errors [2] Manual Mode - Require approval before each batch Full control and review ========================================== Enter choice [1/2] (default: 1): ``` 5. **Initialize Progress Tracking**: Create/initialize `progress.txt` with execution mode 6. **Launch Batch 1 Agents**: For each story in Batch 1, launch a background Task agent with this prompt: ``` You are executing story {story_id}: {title} Description: {description} Acceptance Criteria: {criteria} Your task: 1. Read relevant code and documentation 2. Implement the story according to acceptance criteria 3. Test your implementation 4. Update findings.md with discoveries (use ) 5. Mark complete by appending to progress.txt: [COMPLETE] {story_id} Execute all necessary bash/powershell commands directly to complete the story. Work methodically and document your progress. ``` 7. **Monitor and Progress Through Batches**: Based on selected mode: **Auto Mode:** - Poll progress.txt for completion every 10 seconds - When Batch 1 completes, automatically launch Batch 2 - Continue until all batches complete or error detected - Pause only on [ERROR] or [FAILED] markers **Manual Mode:** - Poll progress.txt for completion every 10 seconds - When Batch 1 completes, prompt user for confirmation - Ask: "Launch Batch 2? [Y/n]:" - If confirmed, launch Batch 2 - Continue until all batches complete or error detected - Pause only on [ERROR] or [FAILED] markers 8. **Show Completion Status**: When all batches complete, show summary **Important:** - In both modes, agents execute commands directly without confirmation - Execution mode ONLY controls batch-to-batch progression - DO NOT add timeout or iteration limits to polling loops ### /edit Edit the PRD in your default editor. ``` /edit ``` ### /status Show execution status. ``` /status ``` ## Workflows ### Complete Workflow ``` 1. /hybrid:auto "Implement feature X" ↓ 2. Review generated PRD ↓ 3. /edit (if needed) or /approve ↓ 4. Agents execute stories in parallel batches ↓ 5. Monitor with /status ↓ 6. All stories complete ``` ### Manual PRD Workflow ``` 1. Create prd.json (or use template) ↓ 2. /hybrid:manual prd.json ↓ 3. Review and edit as needed ↓ 4. /approve ↓ 5. Execution begins ``` ## Findings Tagging When updating `findings.md`, tag sections with relevant story IDs: ```markdown ## Database Schema Discovery The existing schema uses UUIDs for primary keys... ``` This allows agents to receive only relevant findings. ## Progress Tracking Track progress in `progress.txt`: ``` [2024-01-15 10:00:00] story-001: [IN_PROGRESS] story-001 [2024-01-15 10:15:00] story-001: [COMPLETE] story-001 [2024-01-15 10:15:00] story-002: [IN_PROGRESS] story-002 ``` ## File Locking The state manager uses platform-specific locking: - **Linux/Mac**: fcntl for advisory file locking - **Windows**: msvcrt for file locking - **Fallback**: PID-based lock files Lock files are stored in `.locks/` directory. ## Error Handling ### Validation Errors If PRD validation fails: 1. Check for duplicate story IDs 2. Verify all dependencies exist 3. Ensure required fields are present 4. Use `/edit` to fix issues ### Execution Failures If a story fails: 1. Check `.agent-outputs/.log` 2. Review progress.txt for error messages 3. Fix issues manually or with agent help 4. Re-run the story ### Dependency Cycles If dependency cycles are detected: 1. Review `/show-dependencies` output 2. Use `/edit` to break cycles 3. Re-validate with `/hybrid:manual` ## Best Practices 1. **Write Clear Descriptions**: Agents work better with specific, detailed descriptions 2. **Use Acceptance Criteria**: Define what "done" means for each story 3. **Tag Findings**: Always tag findings with relevant story IDs 4. **Update Progress**: Mark stories complete promptly 5. **Review Before Approval**: Always review the PRD before approving ## Integration with Planning-with-Files This skill integrates seamlessly with planning-with-files: - **Standard Mode**: Use alongside existing task_plan.md, findings.md, progress.md - **Worktree Mode**: Each worktree can have its own PRD and story execution - **Session Recovery**: Resume work after /clear with `/hybrid:manual` ## Templates Use the provided templates as starting points: - `templates/prd.json.example` - Example PRD structure - `templates/prd_review.md` - PRD review display template - `templates/findings.md` - Structured findings template ## Troubleshooting ### PRD Not Found ``` Error: No PRD found in current directory ``` Solution: Use `/hybrid:auto` to generate or `/hybrid:manual` to load. ### Lock Timeout ``` TimeoutError: Could not acquire lock within 30s ``` Solution: Run `python3 state_manager.py cleanup-locks` to remove stale locks. ### Dependency Not Found ``` Validation Error: Unknown dependency 'story-005' ``` Solution: Edit PRD to fix dependency reference or add missing story. ## See Also - [planning-with-files](../planning-with-files/SKILL.md) - Base planning skill - [Ralph Loop](https://github.com/anthropics/ralph-loop) - Original Ralph concept