/mega-plan

name: mega-plan
version: "3.2.0"
description: Project-level multi-task orchestration system. Manages multiple hybrid:worktree features in parallel with dependency resolution, coordinated PRD generation, and unified merge workflow.
user-invocable: true
allowed-tools:
  - Read
  - Write
  - Edit
  - Bash
  - Task
  - Glob
  - Grep
  - AskUserQuestion
hooks:
  PreToolUse:
    # Show mega-plan context and parallel execution reminder for relevant tools
    - matcher: "Write|Edit|Bash|Task"
      hooks:
        - type: command
          command: |
            # Show mega-plan context if we're in a mega-plan project
            if [ -f "mega-plan.json" ] || [ -f ".mega-execution-context.md" ]; then
              if command -v uv &> /dev/null; then
                # Update and display context reminder
                uv run python "${CLAUDE_PLUGIN_ROOT}/skills/mega-plan/scripts/mega-context-reminder.py" both 2>/dev/null || true
              fi
            fi
            # Detect potential wrong-branch execution
            if [ -f "mega-plan.json" ] && [ -d ".worktree" ]; then
              CURRENT_BRANCH=$(git branch --show-current 2>/dev/null)
              if [ "$CURRENT_BRANCH" = "main" ] || [ "$CURRENT_BRANCH" = "master" ]; then
                echo ""
                echo "!!! WARNING: You are on $CURRENT_BRANCH but worktrees exist !!!"
                echo "!!! Feature work should happen in .worktree/<feature>/ directories !!!"
                echo ""
              fi
            fi
  PostToolUse:
    # Sync status and update context file after significant operations
    - matcher: "Write|Edit|Bash|Task"
      hooks:
        - type: command
          command: |
            # Best-effort: scripts exit silently if no mega-plan context is detected.
            if command -v uv &> /dev/null; then
              uv run python "${CLAUDE_PLUGIN_ROOT}/skills/mega-plan/scripts/mega-sync.py" 2>/dev/null || true
              uv run python "${CLAUDE_PLUGIN_ROOT}/skills/mega-plan/scripts/mega-context-reminder.py" update 2>/dev/null || true
            elif command -v python &> /dev/null; then
              python "${CLAUDE_PLUGIN_ROOT}/skills/mega-plan/scripts/mega-sync.py" 2>/dev/null || true
              python "${CLAUDE_PLUGIN_ROOT}/skills/mega-plan/scripts/mega-context-reminder.py" update 2>/dev/null || true
            fi

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:

1. Check if `.mega-execution-context.md` exists in the project root 2. 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: `/mega:resume --auto-prd`

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

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:

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

This will: 1. Analyze your project description 2. Break it into features with dependencies 3. Create `mega-plan.json`, `mega-findings.md`, `.mega-status.json` 4. Display the plan for review

Approve and Execute

After reviewing the mega-plan:

/mega:approve

Or with automatic PRD approval for all features:

/mega:approve --auto-prd

This will: 1. Calculate feature batches based on dependencies 2. Create worktrees for Batch 1 features 3. Generate PRDs in each worktree 4. Wait for PRD approvals (or auto-approve with `--auto-prd`) 5. Execute story batches within each feature 6. Progress to next feature batch when complete

Monitor Progress

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

/mega:complete

This will: 1. Verify all features are complete 2. Merge features in dependency order 3. Clean up worktrees and branches 4. Remove mega-plan files

File Structure

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 for project-level multi-feature orchestration. Breaks a complex project into parallel features with dependencies.

/mega:plan [options] <project 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 for feature execution | | `--confirm` | Require confirmation before each ba