mega-plan

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:
3. Read the file content using Read tool
4. Display: "Detected ongoing mega-plan execution"
5. Show current batch and active worktrees from the file
6. CRITICAL: All feature work MUST happen in worktrees, NOT main branch
7. If unsure of state, suggest: /mega:resume --auto-prd

1. If NO but mega-plan.json exists:
2. Run: uv run python "${CLAUDE_PLUGIN_ROOT}/skills/mega-plan/scripts/mega-context-reminder.py" both
3. 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 batch | | --no-confirm | Disable batch confirmation | | --spec <off\|auto\|on> | Spec interview before plan generation | | --first-principles | Enable first-principles questioning in spec interview | | --max-questions N | Max questions in spec interview | | design-doc-path | Optional path to existing design document |

Parameters are saved to mega-plan.json and propagated to /mega:approve and feature-level /approve commands.

Example:

/mega:plan --flow full --tdd auto Create a blog platform with user accounts, article management, comments, and RSS feeds

/mega:edit

Edit the mega-plan interactively. Add, remove, or modify features.

/mega:edit

/mega:approve

Approve the mega-plan and start feature execution. Creates worktrees and generates PRDs for each feature in batch-by-batch order.

/mega:approve [options]

Parameters:

| Parameter | Description | |-----------|-------------| | --flow <quick\|standard\|full> | Execution flow depth for feature execution | | --tdd <off\|on\|auto> | TDD mode propagated to feature execution | | --confirm | Require confirmation before each batch | | --no-confirm | Disable batch confirmation | | --spec <off\|auto\|on> | Spec interview for feature PRD generation | | --first-principles | First-principles questioning for spec interviews | | --max-questions N | Max questions in spec interviews | | --auto-prd | Auto-approve all generated PRDs (skip manual review) | | --agent <name> | Global agent override | | --prd-agent <name> | Agent for PRD generation phase | | --impl-agent <name> | Agent for story implementation phase |

Approval Modes:

| Mode | Trigger | Use Case | |------|---------|----------| | Manual PRD Review | /mega:approve | Review each feature's PRD before execution | | Auto PRD Approval | /mega:approve --auto-prd | Trust PRD generation, fully automated execution |

/mega:status

Show detailed status of mega-plan execution including feature progress, story completion, and batch summary.

/mega:status

/mega:complete

Complete the mega-plan by cleaning up planning files. All features should already be merged via /mega:approve.

/mega:complete

mega-plan.json Format

{
  "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

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:

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:

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

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

# Terminal 1: Mai