| 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":[{"matcher":"Write|Edit|Bash|Task","hooks":"[Truncated]"}],"PostToolUse":[{"matcher":"Write|Edit|Bash|Task","hooks":"[Truncated]"}]} |
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:
/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
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:
- 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:
/mega:approve
Or with automatic PRD approval for all features:
/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
/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:
- Verify all features are complete
- Merge features in dependency order
- Clean up worktrees and branches
- 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": [
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
/mega:plan "Project description"
/mega:approve
/mega:status
cd .worktree/feature-auth
/approve
cd .worktree/feature-products
/approve
/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.
uv run python mega_generator.py validate
uv run python mega_generator.py batches
uv run python mega_generator.py progress
mega_state.py
Thread-safe state management.
uv run python mega_state.py read-plan
uv run python mega_state.py read-status
uv run python mega_state.py sync-worktrees
feature_orchestrator.py
Orchestrates feature execution.
uv run python feature_orchestrator.py plan
uv run python feature_orchestrator.py status
merge_coordinator.py
Coordinates final merge.
uv run python merge_coordinator.py verify
uv run python merge_coordinator.py plan
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
Error: Worktree already exists
Solution: Remove stale worktree or use different feature name.
Merge Conflict
Error: Merge conflict in feature-001
Solution:
- Resolve conflict in target branch
- Re-run
/mega:complete
Incomplete Features
Error: Incomplete features: feature-002, feature-003
Solution:
- Check
/mega:status for details
- Complete stories in incomplete features
- Re-run
/mega:complete
See Also
