| name | megaplan-epic |
| description | Run an epic — a chain of sprint-sized megaplans driven sequentially via `megaplan chain`. Use when the work is bigger than ~2 weeks and needs to be decomposed into multiple plans with state, ordering, and failure semantics handled by the harness. |
Megaplan Epic
An epic is work too big for a single megaplan, decomposed into an ordered chain of sprint-sized megaplans driven sequentially by megaplan chain. Each milestone in the chain is a full megaplan run (its own brief, plan, critique, execute, review); the chain handles ordering, state persistence, branch/PR lifecycle, and failure semantics.
If your work fits in one megaplan, you don't need this skill — read megaplan-prep and run a single sprint. Reach for the epic flow when the answer to "size each megaplan to ~2 weeks of work" is "this doesn't fit."
When to reach for an epic
- Scope is genuinely >2 weeks and the deliverable is a single coherent thing (a feature, a migration, a cross-cutting refactor) — not separate unrelated efforts that should each be their own sprint.
- Sequential dependencies between sprints — milestone B needs the schema / interface / artifact that milestone A produces. Each handoff is a written artifact the next milestone can cite.
- Multiple major architectural decisions that each deserve their own brief + critique pass — pretending it's one sprint flattens decisions that need separate deliberation.
- You want the chain to keep running unattended — chains persist state and resume; one milestone failing doesn't lose the work the prior milestones produced.
When NOT to use an epic
- Single sprint fits the work. If you can hold the whole scope in a 2-week brief, a chain just adds ceremony.
- Exploration / discovery work where you don't yet know the milestone breakdown. Run a single megaplan first to scope; then write the chain spec.
- Truly independent sprints. If sprints don't depend on each other, just run them sequentially as plain
megaplan init calls — a chain spec is overhead with no benefit.
- Anything where the milestone breakdown isn't pre-decided. Chains run unattended through the declared spec; if you'd want to look at milestone 1's output and decide what milestone 2 should be, just run them as separate megaplans.
Terminology — epic vs chain vs megaplan epic
Three names, three meanings:
- Epic (this skill) — the concept: multi-sprint work decomposed into a chain of megaplans.
megaplan chain — the imperative verb that drives the flow. This is what you actually run.megaplan epic — a data-admin verb for snapshot / migrate / export of the editorial epic record. Not the orchestration entry point. Don't confuse the two.
The spec — chain.yaml
A chain spec is a YAML file declaring the base branch, an optional seed plan, and an ordered list of milestones. Each milestone has its own rubric knobs (profile, robustness, depth, vendor, prep/feedback flags).
Store durable epic artifacts under .megaplan/briefs/<epic-slug>/: put the executable chain.yaml there and keep the milestone brief files beside it. Single-plan idea briefs that are not part of an epic live directly under .megaplan/briefs/<slug>.md. .megaplan/plans/ remains generated runtime state; .megaplan/briefs/ is the committed source material that creates runs.
base_branch: main
seed:
plan: scoping-from-docs-20260415-0217
milestones:
- label: m1-schema
idea: .megaplan/briefs/artifact-store/m1-schema.md
branch: epic/m1-schema
profile: apex
robustness: thorough
depth: high
- label: m2-storage
idea: .megaplan/briefs/artifact-store/m2-storage.md
profile: premium
robustness: thorough
depth: high
- label: m3-api
idea: .megaplan/briefs/artifact-store/m3-api.md
profile: partnered
depth: medium
- label: m4-docs
idea: .megaplan/briefs/artifact-store/m4-docs.md
profile: directed
on_failure:
abort: stop_chain
on_escalate:
abort: stop_chain
merge_policy: auto
driver:
robustness: standard
auto_approve: true
max_iterations: 60
poll_sleep: 8.0
Milestone fields
| Field | Required | Meaning |
|---|
label | yes | Short identifier (e.g. m1, m2-storage). Used in branch names and state files. |
idea | yes | Path to the brief markdown file. Same as megaplan init <idea>. |
profile | no | solo / directed / partnered / premium / apex. See megaplan-prep. |
robustness | no | bare / light / full / thorough / extreme. Falls back to driver.robustness. |
depth | no | low / medium / high / xhigh / max. |
vendor | no | claude / codex. |
with_prep, with_feedback | no | Booleans. |
phase_model | no | List of phase=spec strings — the surgical escape hatch. |
deepseek_provider | no | direct / fireworks. |
bakeoff | no | Bake-off spec; rarely needed inside a chain. |
notes | no | Free text retained in state for the audit trail. |
Failure semantics
Two knobs control what the chain does when a milestone fails (on_failure) or hits an escalation (on_escalate):
stop_chain — halt. The chain state is preserved; you re-run after fixing whatever broke.skip_milestone — record the milestone as skipped, continue to the next.retry_milestone — re-attempt the same milestone from scratch.
Default is stop_chain for both — failures should halt unless you've deliberately said otherwise.
Per-milestone rubric — same dials as megaplan-prep
Each milestone is a full megaplan. The three dials (profile / robustness / depth) apply per-milestone — see megaplan-prep for how to pick them. Milestones in the same chain can be different tiers. A typical epic has one or two high-stakes milestones at premium or apex and several mechanical milestones at partnered or directed.
The shorthand from megaplan-prep works for chain-spec notes: a milestone block annotated # partnered//high +prep in your chain.yaml comments tells the reader the intent at a glance.
Running the chain
megaplan chain start --spec /path/to/chain.yaml
megaplan chain start --spec /path/to/chain.yaml --one
megaplan chain status --spec /path/to/chain.yaml
Flags worth knowing
--one — single-step the chain. Useful when you want to inspect each milestone's output before letting the next one kick off, or when running under an external supervisor that wants tick-by-tick control.--no-git-refresh — skip the automatic base-branch checkout + pull that runs before each milestone. Use this on dev checkouts where chain shouldn't stomp the currently checked-out branch.--no-push — disable branch creation, PR creation, commits, and pushes. For local / no-network runs.
State and resuming
Progress is persisted under .megaplan/plans/.chains/<spec-stem>-<digest>.json. The digest is computed from the resolved spec path, so the same spec resumes deterministically. To resume after an interruption, just re-run megaplan chain start --spec <same path> — the driver reads the state file, skips completed milestones, and picks up at the current one.
State persistence means:
- A crash, restart, or SIGINT mid-milestone doesn't lose prior milestones' work.
- Failed milestones can be re-attempted by deleting the milestone's plan directory and re-running — the chain will redrive that milestone.
- Editing the spec after milestones have completed only affects un-started milestones; completed entries in state stay as-is.
Cloud chain mode
For chains that need to outlive your terminal session, run them inside megaplan cloud with mode: chain in cloud.yaml. The container drives the chain unattended; you observe via megaplan cloud status / cloud logs / cloud attach. See docs/cloud.md for the cloud reference.
When supervising a long cloud chain, follow the cadence in the main megaplan skill: check after launch, again after 10-15 min, then hourly.
End-to-end example
Scope: build a new artifact store that downstream sprints will consume. ~5 weeks of work, four sequential milestones.
1. Decompose into milestones. Create an epic directory under .megaplan/briefs/ and write one idea file per milestone, each sized to ~1 week:
.megaplan/briefs/artifact-store/m1-schema.md # schema + invariants
.megaplan/briefs/artifact-store/m2-storage.md # storage layer against the schema
.megaplan/briefs/artifact-store/m3-api.md # public API over storage
.megaplan/briefs/artifact-store/m4-docs.md # docs + migration guide
.megaplan/briefs/artifact-store/chain.yaml # chain spec
Each idea file is a full brief (see the "What goes in the brief" section of megaplan-prep) — outcome, scope, locked decisions, open questions, constraints, done criteria, touchpoints, anti-scope. Briefs are locked at init; later edits are not re-read.
2. Write chain.yaml (see the spec example above). Pick a tier per milestone:
- m1 schema →
apex (kernel invariant, every downstream sprint depends on it)
- m2 storage →
premium (production migration logic)
- m3 api →
partnered (cross-cutting but mechanical once schema+storage are locked)
- m4 docs →
directed (docs benefit from a smart plan; execution is cheap)
3. Drive it.
megaplan chain start --spec .megaplan/briefs/artifact-store/chain.yaml
For a long unattended run, do this inside megaplan cloud so it survives the terminal.
4. Observe.
megaplan chain status --spec .megaplan/briefs/artifact-store/chain.yaml
Shows current milestone index, current plan name, last state, completed milestones, and PR state if applicable.
5. If a milestone fails or escalates, the chain halts (with default stop_chain). Investigate the failing plan via megaplan status --plan <name> and megaplan audit --plan <name>. Once you've fixed the brief or escalated the rubric (via megaplan override set-profile etc.), re-run megaplan chain start --spec and the chain resumes.
Common pitfalls
- Don't decompose so finely that each milestone is <2 days of work. A chain of 10 micro-milestones is harder to follow than 4 right-sized ones, and the harness overhead dominates the actual work.
- Don't reach for a chain when you don't know the breakdown yet. Run a scoping megaplan first; let it produce the milestone list; then write the chain spec.
- Don't tier-flatten — uniformly picking
partnered for every milestone misses the point of the per-milestone rubric. Differentiate; the high-stakes milestone deserves a higher tier and the cheap milestone doesn't.
- Don't bake-off inside a chain unless you genuinely need it. Bakeoffs are independent runs; nesting them inside a chain spec multiplies the cost without typically producing useful signal.
- Don't edit the spec mid-flight expecting completed milestones to re-run. State is sticky for completed entries by design — that's how resume works.
