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.
Generates PRDs from task descriptions and orchestrates parallel story execution with dependency-aware context filtering.
/plugin marketplace add taoidle/plan-cascade/plugin install plan-cascade@plan-cascadeThis skill is limited to using the following tools:
commands/approve.mdcommands/auto.mdcommands/complete.mdcommands/edit.mdcommands/manual.mdcommands/show-dependencies.mdcommands/status.mdcommands/worktree.mdcore/__init__.pycore/agent_executor.pycore/agent_monitor.pycore/cross_platform_detector.pycore/iteration_loop.pycore/orchestrator.pycore/phase_config.pycore/prd_generator.pycore/quality_gate.pycore/retry_manager.pycore/state_manager.pyscripts/agent-exec.pyA hybrid architecture combining the best of three approaches:
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:
/hybrid:resume --autoIf NO but prd.json exists:
uv run python "${CLAUDE_PLUGIN_ROOT}/skills/hybrid-ralph/scripts/hybrid-context-reminder.py" bothThis 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
Generate a PRD from your task description:
/hybrid:auto Implement a user authentication system with login, registration, and password reset
This will:
Load an existing PRD file:
/hybrid:manual path/to/prd.json
After reviewing the PRD:
/approve
This begins parallel execution of stories according to the dependency graph.
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.json file contains:
id: Unique story identifier (story-001, story-002, etc.)title: Short story titledescription: Detailed story descriptionpriority: high, medium, or lowdependencies: Array of story IDs this story depends onstatus: pending, in_progress, or completeacceptance_criteria: List of completion criteriacontext_estimate: small, medium, large, or xlargetags: Array of tags for categorizationStories are organized into execution batches:
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
Each agent receives only relevant context:
This keeps context windows focused and efficient.
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
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
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
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
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.
Load an existing PRD file and enter review mode.
/hybrid:manual [path/to/prd.json]
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 fileParameters:
| 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 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) |
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 the PRD in your default editor. Opens prd.json, validates after saving, and re-displays review.
/edit
Show execution status of all stories. Displays batch progress, individual story states, completion percentage, and recent activity.
/status
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
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
1. Create prd.json (or use template)
↓
2. /hybrid:manual prd.json
↓
3. Review and edit as needed
↓
4. /approve
↓
5. Execution begins
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.
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
The state manager uses platform-specific locking:
Lock files are stored in .locks/ directory.
If PRD validation fails:
/edit to fix issuesIf a story fails:
.agent-outputs/<story-id>.logIf dependency cycles are detected:
/show-dependencies output/edit to break cycles/hybrid:manualThis skill integrates seamlessly with planning-with-files:
/hybrid:manualUse the provided templates as starting points:
templates/prd.json.example - Example PRD structuretemplates/prd_review.md - PRD review display templatetemplates/findings.md - Structured findings templateError: No PRD found in current directory
Solution: Use /hybrid:auto to generate or /hybrid:manual to load.
TimeoutError: Could not acquire lock within 30s
Solution: Run uv run python state_manager.py cleanup-locks to remove stale locks.
Validation Error: Unknown dependency 'story-005'
Solution: Edit PRD to fix dependency reference or add missing story.
Activates when the user asks about AI prompts, needs prompt templates, wants to search for prompts, or mentions prompts.chat. Use for discovering, retrieving, and improving prompts.
Search, retrieve, and install Agent Skills from the prompts.chat registry using MCP tools. Use when the user asks to find skills, browse skill catalogs, install a skill for Claude, or extend Claude's capabilities with reusable AI agent components.
Creating algorithmic art using p5.js with seeded randomness and interactive parameter exploration. Use this when users request creating art using code, generative art, algorithmic art, flow fields, or particle systems. Create original algorithmic art rather than copying existing artists' work to avoid copyright violations.