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:

•
Check if .hybrid-execution-context.md exists in the current directory
•
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
•
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:

code

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

This will:

•Launch a Planning Agent to analyze your task
•Generate a PRD with user stories
•Show the PRD for review
•Wait for your approval

Manual PRD Loading

Load an existing PRD file:

code

/hybrid:manual path/to/prd.json

Approval and Execution

After reviewing the PRD:

code

/approve

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

Architecture

File Structure

code

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:

•Batch 1: Stories with no dependencies (run in parallel)
•Batch 2+: Stories whose dependencies are complete (run in parallel)

code

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
uv run python context_filter.py get-story story-001

# Get context for a story
uv run python context_filter.py get-context story-001

# Get execution batch
uv run python context_filter.py get-batch 1

# Show full execution plan
uv run python context_filter.py plan-batches

state_manager.py

Thread-safe file operations with platform-specific locking.

bash

# Read PRD
uv run python state_manager.py read-prd

# Mark story complete
uv run python state_manager.py mark-complete story-001

# Get all story statuses
uv run python state_manager.py get-statuses

prd_generator.py

Generates PRD from task descriptions and manages story dependencies.

bash

# Validate PRD
uv run python prd_generator.py validate

# Show execution batches
uv run python prd_generator.py batches

# Create sample PRD
uv run python prd_generator.py sample

orchestrator.py

Manages parallel execution of stories.

bash

# Show execution plan
uv run python orchestrator.py plan

# Show execution status
uv run python orchestrator.py status

# Execute a batch
uv run python orchestrator.py execute-batch 1

Commands Reference

/hybrid:auto

Generate PRD from task description.

code

/hybrid:auto <task description>

/hybrid:manual

Load existing PRD file.

code

/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.

code

/hybrid:worktree <task-name> <target-branch> <task-description-or-prd-path>

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:

•
Parse Parameters: Extract task-name, target-branch, and PRD argument
•
Verify Git Repository: Ensure we're in a git repository
•
Detect Default Branch: Auto-detect main/master branch
•
Set Variables:

bash

TASK_BRANCH="$TASK_NAME"
ORIGINAL_BRANCH=$(git branch --show-current)
ROOT_DIR=$(pwd)
WORKTREE_DIR="$ROOT_DIR/.worktree/$(basename $TASK_NAME)"

•
Determine PRD Mode: Check if third argument is existing file or task description
•
Check for Existing Worktree: If worktree exists, navigate to it; otherwise create new worktree
•
Create Git Worktree (if new):

bash

git worktree add -b "$TASK_BRANCH" "$WORKTREE_DIR" "$TARGET_BRANCH"

•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

•
Create Initial Files in worktree (findings.md, progress.txt)
•
Navigate to Worktree:

bash

cd "$WORKTREE_DIR"

•
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
•
Validate and Display PRD: Show the generated/loaded PRD with review
•
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.

code

/approve

Execution Steps:

•
Verify PRD Exists: Check if prd.json exists in current directory
•
Read and Validate PRD: Validate structure and required fields
•
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

•

Choose Execution Mode: Ask user to select execution mode:

code

==========================================
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):

•
Initialize Progress Tracking: Create/initialize progress.txt with execution mode

•

Launch Batch 1 Agents: For each story in Batch 1, launch a background Task agent with this prompt:

code

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 <!-- @tags: {story_id} -->)
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.

•
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
•
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.

code

/edit

/status

Show execution status.

code

/status

Workflows

Complete Workflow

code

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

code

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

<!-- @tags: story-001,story-002 -->

## 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:

code

[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:

•Check for duplicate story IDs
•Verify all dependencies exist
•Ensure required fields are present
•Use /edit to fix issues

Execution Failures

If a story fails:

•Check .agent-outputs/<story-id>.log
•Review progress.txt for error messages
•Fix issues manually or with agent help
•Re-run the story

Dependency Cycles

If dependency cycles are detected:

•Review /show-dependencies output
•Use /edit to break cycles
•Re-validate with /hybrid:manual

Best Practices

•Write Clear Descriptions: Agents work better with specific, detailed descriptions
•Use Acceptance Criteria: Define what "done" means for each story
•Tag Findings: Always tag findings with relevant story IDs
•Update Progress: Mark stories complete promptly
•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

code

Error: No PRD found in current directory

Solution: Use /hybrid:auto to generate or /hybrid:manual to load.

Lock Timeout

code

TimeoutError: Could not acquire lock within 30s

Solution: Run uv run python state_manager.py cleanup-locks to remove stale locks.

Dependency Not Found

code

Validation Error: Unknown dependency 'story-005'

Solution: Edit PRD to fix dependency reference or add missing story.

Hybrid Ralph + Planning-with-Files

Auto-Recovery Protocol (CRITICAL)

Quick Start

Automatic PRD Generation

Manual PRD Loading

Approval and Execution

Architecture

File Structure

The PRD Format

Parallel Execution Model

Context Filtering

Core Python Modules

context_filter.py

state_manager.py

prd_generator.py

orchestrator.py

Commands Reference

/hybrid:auto

/hybrid:manual

/hybrid:worktree

/approve

/edit

/status

Workflows

Complete Workflow

Manual PRD Workflow

Findings Tagging

Progress Tracking

File Locking

Error Handling

Validation Errors

Execution Failures

Dependency Cycles

Best Practices

Integration with Planning-with-Files

Templates

Troubleshooting

PRD Not Found

Lock Timeout

Dependency Not Found

See Also