hybrid-ralph

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, 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 (migrated to src/plan_cascade/state/)

Context filtering functionality is now provided by the main package.

# Get story details
uv run python -m plan_cascade.state.context_filter get-story story-001

# Get context for a story
uv run python -m plan_cascade.state.context_filter get-context story-001

# Get execution batch
uv run python -m plan_cascade.state.context_filter get-batch 1

# Show full execution plan
uv run python -m plan_cascade.state.context_filter plan-batches

state_manager.py

Thread-safe file operations with platform-specific locking.

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

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

# 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 and enter review mode. Auto-generates user stories with priorities, dependencies, and acceptance criteria for parallel execution.

/hybrid:auto [options] <task description> [design-doc-path]

Parameters:

Parameter	Description
--flow <quick|standard|full>	Execution flow depth controlling quality gate strictness
--tdd <off|on|auto>	Test-Driven Development mode
--confirm	Require batch confirmation during execution
--no-confirm	Disable batch confirmation
--spec <off|auto|on>	Spec interview before PRD generation
--first-principles	Enable first-principles questioning in spec interview
--max-questions N	Max questions in spec interview
--agent <name>	Agent to use for PRD generation
design-doc-path	Optional path to existing design document

Parameters are saved to prd.json and propagated to /approve.

/hybrid:manual

Load an existing PRD file and enter review mode.

/hybrid:manual [path/to/prd.json]

/hybrid:worktree

Start a new task in an isolated Git worktree with Hybrid Ralph PRD mode. Creates worktree, branch, loads existing PRD or auto-generates from description.

/hybrid:worktree [options] <task-name> <target-branch> <prd-path-or-description> [design-doc-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)
• prd-path-or-description: Either a task description to generate PRD, or path to existing PRD file

Parameters:

Parameter	Description
--flow <quick|standard|full>	Execution flow depth controlling quality gate strictness
--tdd <off|on|auto>	Test-Driven Development mode
--confirm	Require batch confirmation during execution
--no-confirm	Disable batch confirmation
--spec <off|auto|on>	Spec interview before PRD generation
--first-principles	Enable first-principles questioning in spec interview
--max-questions N	Max questions in spec interview
--agent <name>	Agent to use for PRD generation
design-doc-path	Optional path to existing design document

Parameters are saved to the worktree's prd.json, ensuring isolation from other tasks.

/approve

Approve PRD and begin parallel story execution. Analyzes dependencies, creates execution batches, launches background Task agents, and monitors progress.

/approve [options]

Parameters:

Parameter	Description
--flow <quick|standard|full>	Override execution flow depth (quality gate strictness)
--tdd <off|on|auto>	Control TDD mode for story execution
--confirm	Require confirmation before each batch
--no-confirm	Disable batch confirmation (even in full flow)
--agent <name>	Global agent override for all stories
--impl-agent <name>	Agent for implementation phase
--retry-agent <name>	Agent for retry phase (after failures)
--no-verify	Skip AI verification gate
--verify-agent <name>	Agent for verification phase
--no-review	Skip code review gate
--no-fallback	Disable agent fallback chain
--auto-run	Use Python-based full-auto execution with retry

Flow Levels:

Flow	Gate Mode	AI Verification	Code Review	Test Enforcement
quick	soft (warnings)	disabled	no	no
standard	soft (warnings)	enabled	no	no
full	hard (blocking)	enabled	required	required

Execution Modes:

Mode	Description
Auto	Automatically progresses through batches, pauses on errors
Manual	Requires user approval before each batch
Full Auto	Python-based execution with auto-retry (up to 3 attempts)

/hybrid:complete

Complete a worktree task. Verifies all stories are complete, commits code changes (excluding planning files), merges to target branch, and removes worktree.

/hybrid:complete [target-branch]

/edit

Edit the PRD in your default editor. Opens prd.json, validates after saving, and re-displays review.

/edit

/status

Show execution status of all stories. Displays batch progress, individual story states, completion percentage, and recent activity.

/status

/show-dependencies

Display the dependency graph for all stories in the PRD. Shows visual ASCII graph, critical path analysis, and detects issues like circular dependencies.

/show-dependencies

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:

<!-- @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:

[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/<story-id>.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 uv run python 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 - Base planning skill
• Ralph Loop - Original Ralph concept