Mega Plan

A project-level orchestration system that sits above hybrid-ralph to manage multiple parallel features as a unified project plan.

Auto-Recovery Protocol (CRITICAL)

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

•
Check if .mega-execution-context.md exists in the project root
•
If YES:
- •Read the file content using Read tool
- •Display: "Detected ongoing mega-plan execution"
- •Show current batch and active worktrees from the file
- •CRITICAL: All feature work MUST happen in worktrees, NOT main branch
- •If unsure of state, suggest: /plan-cascade:mega-resume --auto-prd
•
If NO but mega-plan.json exists:
- •Run: uv run python "${CLAUDE_PLUGIN_ROOT}/skills/mega-plan/scripts/mega-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

Architecture

code

Level 1: Mega Plan (Project Level)
    └── Level 2: Features (Feature Level) = hybrid:worktree
              └── Level 3: Stories (Story Level) = hybrid internal parallelism

Quick Start

Create a Mega Plan

Generate a mega-plan from your project description:

code

/mega:plan Build an e-commerce platform with user authentication, product catalog, shopping cart, and order processing

This will:

•Analyze your project description
•Break it into features with dependencies
•Create mega-plan.json, mega-findings.md, .mega-status.json
•Display the plan for review

Approve and Execute

After reviewing the mega-plan:

code

/mega:approve

Or with automatic PRD approval for all features:

code

/mega:approve --auto-prd

This will:

•Calculate feature batches based on dependencies
•Create worktrees for Batch 1 features
•Generate PRDs in each worktree
•Wait for PRD approvals (or auto-approve with --auto-prd)
•Execute story batches within each feature
•Progress to next feature batch when complete

Monitor Progress

code

/mega:status

Shows:

•Overall project progress percentage
•Feature status by batch
•Story progress within each feature
•Current batch details

Complete and Merge

When all features are complete:

code

/mega:complete

This will:

•Verify all features are complete
•Merge features in dependency order
•Clean up worktrees and branches
•Remove mega-plan files

File Structure

code

project-root/
├── mega-plan.json              # Project-level plan
├── mega-findings.md            # Shared findings (read-only in worktrees)
├── .mega-status.json           # Execution status
├── .worktree/
│   ├── feature-auth/
│   │   ├── prd.json           # Feature PRD
│   │   ├── findings.md        # Feature-specific findings
│   │   ├── progress.txt       # Story progress
│   │   ├── mega-findings.md   # Read-only link to shared findings
│   │   └── .planning-config.json
│   └── feature-products/
│       └── ...

Commands Reference

/mega:plan

Generate a mega-plan from project description.

code

/mega:plan <project description>

Example:

code

/mega:plan Create a blog platform with user accounts, article management, comments, and RSS feeds

/mega:edit

Edit the mega-plan in your default editor.

code

/mega:edit

/mega:approve

Approve the mega-plan and begin execution.

code

/mega:approve [--auto-prd]

Options:

•--auto-prd: Automatically approve all generated PRDs (skip manual review)

Approval Modes:

Mode	Trigger	Use Case
Manual PRD Review	`/mega:approve`	Need to review each feature's PRD
Auto PRD Approval	`/mega:approve --auto-prd`	Trust PRD generation, want fast execution

/mega:status

Show detailed execution status.

code

/mega:status

/mega:complete

Complete the mega-plan and merge all features.

code

/mega:complete [target-branch]

Arguments:

•target-branch (optional): Override the target branch from mega-plan

mega-plan.json Format

json

{
  "metadata": {
    "created_at": "2026-01-28T10:00:00Z",
    "version": "1.0.0"
  },
  "goal": "Project goal",
  "description": "Original user description",
  "execution_mode": "auto",
  "target_branch": "main",
  "features": [
    {
      "id": "feature-001",
      "name": "feature-auth",
      "title": "User Authentication",
      "description": "Detailed description for PRD generation",
      "priority": "high",
      "dependencies": [],
      "status": "pending"
    }
  ]
}

Feature Status Flow

code

pending → prd_generated → approved → in_progress → complete
                                           ↓
                                        failed

Status	Description
`pending`	Feature not yet started
`prd_generated`	Worktree created, PRD generated
`approved`	PRD approved, ready for execution
`in_progress`	Stories are being executed
`complete`	All stories complete
`failed`	Feature execution failed

Execution Modes

Auto Mode

Features and their story batches execute automatically:

code

Batch 1 (Features) → PRDs generated → approved → stories execute → complete
         ↓
Batch 2 (Features) → PRDs generated → approved → stories execute → complete
         ↓
All complete → /mega:complete

Manual Mode

Each batch waits for explicit confirmation:

code

Batch 1 → PRDs generated → [you review] → /approve in each worktree
         ↓
Batch 2 → PRDs generated → [you review] → /approve in each worktree
         ↓
All complete → /mega:complete

Workflows

Complete Workflow

code

1. /mega:plan "Build e-commerce platform"
   ↓
2. Review generated mega-plan.json
   ↓
3. /mega:edit (if needed) or /mega:approve
   ↓
4. Feature worktrees created (Batch 1)
   ↓
5. PRDs generated in each worktree
   ↓
6. Review and /approve in each worktree (or use --auto-prd)
   ↓
7. Stories execute in parallel
   ↓
8. Monitor with /mega:status
   ↓
9. Batch 2 features start when Batch 1 complete
   ↓
10. All complete → /mega:complete

Multi-Terminal Workflow

bash

# Terminal 1: Main orchestration
/mega:plan "Project description"
/mega:approve
/mega:status  # Monitor progress

# Terminal 2: Feature 1 work
cd .worktree/feature-auth
/approve  # Approve PRD
# ... stories execute ...

# Terminal 3: Feature 2 work (parallel!)
cd .worktree/feature-products
/approve  # Approve PRD
# ... stories execute ...

# Terminal 1: After all complete
/mega:complete

Relationship with Hybrid Ralph

Mega Plan orchestrates multiple hybrid-ralph workflows:

Component	Mega Plan	Hybrid Ralph
Scope	Project-level	Feature-level
Unit	Features	Stories
Files	mega-plan.json	prd.json
Findings	mega-findings.md (shared)	findings.md (per-feature)
Worktrees	Creates for features	Works within worktree
Merge	All features → target	N/A (handled by mega)

Core Python Modules

mega_generator.py

Generates mega-plan from project descriptions.

bash

# Validate mega-plan
uv run python mega_generator.py validate

# Show execution batches
uv run python mega_generator.py batches

# Show progress
uv run python mega_generator.py progress

mega_state.py

Thread-safe state management.

bash

# Read mega-plan
uv run python mega_state.py read-plan

# Read status
uv run python mega_state.py read-status

# Sync from worktrees
uv run python mega_state.py sync-worktrees

feature_orchestrator.py

Orchestrates feature execution.

bash

# Show execution plan
uv run python feature_orchestrator.py plan

# Show status
uv run python feature_orchestrator.py status

merge_coordinator.py

Coordinates final merge.

bash

# Verify all complete
uv run python merge_coordinator.py verify

# Show merge plan
uv run python merge_coordinator.py plan

# Complete (merge & cleanup)
uv run python merge_coordinator.py complete

Findings Management

Shared Findings (mega-findings.md)

•Located at project root
•Contains findings relevant to all features
•Read-only copy placed in each worktree
•Updated only from project root

Feature Findings (findings.md)

•Located in each feature worktree
•Contains feature-specific discoveries
•Tagged with story IDs
•Independent per feature

Best Practices

•Clear Feature Boundaries: Each feature should be independent enough to develop in isolation
•Minimize Dependencies: Fewer dependencies mean more parallelism
•Meaningful Names: Use descriptive feature names (they become directory names)
•Review PRDs: Take time to review generated PRDs before approving
•Monitor Progress: Use /mega:status regularly to track execution
•Handle Failures: If a feature fails, fix it in its worktree before completing

Troubleshooting

Worktree Conflict

code

Error: Worktree already exists

Solution: Remove stale worktree or use different feature name.

Merge Conflict

code

Error: Merge conflict in feature-001

Solution:

•Resolve conflict in target branch
•Re-run /mega:complete

Incomplete Features

code

Error: Incomplete features: feature-002, feature-003

Solution:

•Check /mega:status for details
•Complete stories in incomplete features
•Re-run /mega:complete

Mega Plan

Auto-Recovery Protocol (CRITICAL)

Architecture

Quick Start

Create a Mega Plan

Approve and Execute

Monitor Progress

Complete and Merge

File Structure

Commands Reference

/mega:plan

/mega:edit

/mega:approve

/mega:status

/mega:complete

mega-plan.json Format

Feature Status Flow

Execution Modes

Auto Mode

Manual Mode

Workflows

Complete Workflow

Multi-Terminal Workflow

Relationship with Hybrid Ralph

Core Python Modules

mega_generator.py

mega_state.py

feature_orchestrator.py

merge_coordinator.py

Findings Management

Shared Findings (mega-findings.md)

Feature Findings (findings.md)

Best Practices

Troubleshooting

Worktree Conflict

Merge Conflict

Incomplete Features

See Also