/mega-plan

description: "Generate a mega-plan for project-level multi-feature orchestration. Breaks a complex project into parallel features with dependencies. Usage: /plan-cascade:mega-plan [--flow <quick|standard|full>] [--tdd <off|on|auto>] [--confirm] [--no-confirm] [--spec <off|auto|on>] [--first-principles] [--max-questions N] <project description> [design-doc-path]"

Mega Plan - Project-Level Feature Orchestration

You are creating a **Mega Plan** - a project-level plan that orchestrates multiple features in parallel.

Execution Flow Parameters

This command accepts flow control parameters that propagate to all feature executions:

Parameter Priority

Parameters flow through three stages in mega-plan execution:

1. **Command-line flags to THIS command** (highest priority)

• Example: `/plan-cascade:mega-plan --flow full --tdd on "Build platform"`
• Saved to `mega-plan.json` as `flow_config`, `tdd_config`, `spec_config`, etc.

2. **Command-line flags to `/plan-cascade:mega-approve`**

• Can override values saved in `mega-plan.json`
• Propagated to all feature PRDs

3. **PRD-level overrides** (per feature, if needed)

• Individual features can have custom parameters in their PRDs
• Rarely used; usually all features use mega-plan settings

4. **Default values** (lowest priority)

**Parameter Propagation Chain:**

# Step 1: Create mega-plan with parameters
/plan-cascade:mega-plan --flow full --tdd on --spec auto "Build e-commerce"
# → Saves to mega-plan.json:
#   flow_config: {level: "full", propagate_to_features: true}
#   tdd_config: {mode: "on", propagate_to_features: true}
#   spec_config: {mode: "auto", ...}

# Step 2: Execute with saved parameters
/plan-cascade:mega-approve
# → Reads from mega-plan.json
# → For each feature: creates PRD with inherited flow/tdd settings
# → Sub-agents execute stories with these settings

# Step 3: Execute with override
/plan-cascade:mega-approve --flow standard
# → Uses flow="standard" (overrides mega-plan.json)
# → All features get flow="standard", tdd="on" (from mega-plan.json)

**Note:** Spec interview parameters (--spec, --first-principles, --max-questions) are used by the orchestrator in `mega-approve` Step 6.0, NOT propagated to feature agents.

`--flow <quick|standard|full>`

Override the execution flow depth for all feature approve phases.

| Flow | Gate Mode | AI Verification | Code Review | Test Enforcement | |------|-----------|-----------------|-------------|------------------| | `quick` | soft | disabled | no | no | | `standard` | soft | enabled | no | no | | `full` | **hard** | enabled | **required** | **required** |

`--tdd <off|on|auto>`

Control Test-Driven Development mode for all feature story executions.

| Mode | Description | |------|-------------| | `off` | TDD disabled | | `on` | TDD enabled with prompts and compliance checks | | `auto` | Automatically decide based on risk assessment (default) |

`--confirm`

Require confirmation before each **feature batch** execution.

**Batch-Level Confirmation**: In mega-plan execution, confirmation happens at the batch level (before launching parallel sub-agents), not inside individual feature executions. This allows human oversight while preserving parallelism.

`--no-confirm`

Disable batch-level confirmation, even when using FULL flow.

• Overrides `--confirm` flag
• Overrides FULL flow's default confirmation behavior
• Useful for CI pipelines that want strict quality gates without interactive confirmation

`--spec <off|auto|on>`

Record spec interview configuration for later execution in `mega-approve` (interviews must run in the orchestrator, never inside per-feature subagents).

• `auto` (default): enabled when `--flow full`, otherwise disabled
• `on`: always run spec interview per feature before PRD finalization
• `off`: never run spec interview

`--first-principles`

Enable first-principles questions (only when spec interview runs).

`--max-questions N`

Soft cap for interview length (recorded in `.state/spec-interview.json` per feature).

Prerequisites Check

**CRITICAL**: If this is your first time using Plan Cascade, run `/plan-cascade:init` first to set up the environment.

# Quick check - if this fails, run /plan-cascade:init
uv run python -c "print('Environment OK')" 2>/dev/null || echo "Warning: Run /plan-cascade:init to set up environment"

Path Storage Modes

Plan Cascade supports two path storage modes for runtime files:

New Mode (Default)

Runtime files are stored in a user directory:

• **Windows**: `%APPDATA%/plan-cascade/<project-id>/`
• **Unix/macOS**: `~/.plan-cascade/<project-id>/`

File locations in new mode:

• `mega-plan.json`: `<user-dir>/mega-plan.json`
• `.mega-status.json`: `<user-dir>/.state/.mega-status.json`
• Feature worktrees: `<user-dir>/.worktree/<feature-name>/`
• `mega-findings.md`: `<project-root>/mega-findings.md` (user-visible, stays in project)

Legacy Mode

All files in project root:

• `mega-plan.json`: `<project-root>/mega-plan.json`
• `.mega-status.json`: `<project-root>/.mega-status.json`
• Feature worktrees: `<project-root>/.worktree/<feature-name>/`

To check which mode is active:

uv run python -c "from plan_cascade.state.path_resolver import PathResolver; from pathlib import Path; r=PathResolver(Path.cwd()); print('Mode:', 'legacy' if r.is_legacy_mode() else 'new'); print('Mega plan:', r.get_mega_plan_path())"

Architecture

Level 1: Mega Plan (This level - Project)
    └── Level 2: Features (hybrid:worktree tasks)
              └── Level 3: Stories (hybrid-ralph internal parallelism)

Step 0: Ensure .gitignore Configuration

**IMPORTANT**: Before creating any planning files, ensure the project's `.gitignore` is configured to ignore Plan Cascade temporary files:

# Check and update .gitignore for Plan Cascade entries
uv run python -c "from plan_cascade.utils.gitignore import ensure_gitignore; from pathlib import Path;