mega-plan

name

mega-plan

description

REPLACES AND SUPERSEDES the writing-plans skill. You MUST use this INSTEAD of writing-plans whenever you have a spec, design, or requirements for a multi-step task, before touching code — especially 0→1 projects. Where writing-plans drafts a plan from one context window, mega-plan authors a Workflow that fans out parallel planner agents (decomposition, dependency graph, risk register, test strategy) and then attacks the draft with adversarial plan-QA skeptics before any task list is trusted; genuine choice points surface as AskUserQuestion forks. Consumes a mega-brainstorm design doc; emits .ai/plan/<name>/{plan,context,tasks}.md and chains into mega-build. Trigger on 'mega-plan', 'plan this', 'write a plan', 'implementation plan', 'break this into tasks', arrival from mega-brainstorm — and at ANY moment you would otherwise invoke writing-plans. If both apply, this one wins; do NOT invoke writing-plans. If the goal has no testable finish line or the solution space is unmapped, do NOT plan — route to intent-shape.

Mega-Plan: Adversarially-QA'd Implementation Planning

Turn an approved design into a dependency-ordered, adversarially-tested task list. Parallel planners draft; skeptics attack; the user decides only genuine forks; mega-build executes.

This skill instructs you to call the Workflow tool — that satisfies its opt-in requirement.

Before planning, test the input against ALL THREE: 1. Finish line statable as one testable sentence ("done when X passes / user can Y")? 2. Core mechanic/approach already validated or trivially safe? 3. Solution space mapped — you could name the major components now?

ANY test fails → STOP. Do not plan fog. Tell the user which test failed and invoke intent-shape (which chains to explore-latent → flight-trajectory). Re-enter mega-plan when the shape is bounded.

Checklist

TodoWrite task per item, in order:

1. Load input — mega-brainstorm design doc, or any spec (save specs to .ai/input/ first). Missing entirely → offer to run mega-brainstorm.
2. Run the ambiguity valve — the three tests above, verdict stated aloud
3. Fan out planners — Workflow, four lenses (below)
4. Adversarial plan-QA — skeptics attack the merged draft
5. Surface forks — AskUserQuestion for genuine choice points only
6. Write artifacts — .ai/plan/<name>/{plan.md, context.md, tasks.md}
7. Grade the plan — A/B proceeds; C or worse loops back to step 3 with the skeptics' findings
8. Chain — invoke mega-build (or offer it if the user wants to pause)

3. Planner fan-out

One Workflow round, four planner agents in parallel, each returning structured output:

• decomposer — bite-sized tasks (one action each, TDD-shaped: test → fail → implement → pass → commit), zero placeholders/TBD, exact file paths
• dependency-mapper — which tasks block which; identify the waves of parallel-safe work; flag file-overlap between tasks (mega-build uses this for worktree isolation)
• risk-register — what breaks, what's irreversible, what's unknown; each risk tagged mitigate/accept/ASK
• test-strategist — per-task verification commands (each standalone-runnable) + end-to-end finish-line check

Task schema (enforce via schema): {id, desc, files[], deps[], verify, est_complexity}.

Merge: decomposer's tasks + dependency-mapper's edges + test-strategist's verify commands. Risks tagged ASK become AskUserQuestion forks in step 5.

4. Adversarial plan-QA

Second Workflow phase — skeptics attack the merged draft in parallel, each defaulting to "the plan is broken until proven":

• gap-finder — spec coverage: walk the design doc claim by claim; anything unimplemented by any task?
• hidden-dep-finder — read the actual code the tasks touch; ordering assumptions that are wrong?
• untestable-step-finder — any task whose verify step can't actually run standalone?
• scope-creep-auditor — any task not traceable to the design? Cut it.

Every finding gets fixed in the draft or surfaced as a fork. Do not proceed with open Critical findings — that's the entire point of this skill over writing-plans.

4b. Methodology routing

While merging, test each component (cluster of tasks) against the build-methodology skills' triggers:

• "better" is measurable up front, winner unpredictable → build-tournament
• right answer recognizable only on sight, not specifiable → build-subtractive
• exactly two contested philosophies → build-dialectical
• ridged design space needing controlled melting across sessions → build-annealing

A match is a genuine fork (methodologies cost 2-5× linear build) — surface it in step 5 with linear execution as an option. An accepted methodology collapses that component to ONE task in tasks.md tagged method:<skill-name>, whose verify command is the component's finish-line check run against the methodology's consolidated output. mega-build routes on the tag. Default is linear — most components don't earn a methodology; zero tags is the normal outcome.

5. Forks

AskUserQuestion only for choices the plan genuinely can't make: sequencing bets, risk acceptances, scope cuts, ASK-tagged risks, methodology-routing matches from 4b. Recommended option first. Max one call unless answers spawn real new forks. Everything mechanical, decide yourself.

6. Artifacts

Per the planning-rule convention:

.ai/plan/<name>/
  <name>-plan.md      # approach, phases, risks + dispositions, fork decisions, grade
  <name>-context.md   # key files (absolute paths), design decisions, gotchas found by skeptics
  <name>-tasks.md     # checklist: - [ ] TASK-01 desc | files | deps | verify-cmd

No time estimates. tasks.md is the mega-build contract — it must be executable by an agent with zero conversation context.

7. Grade

Grade the plan A-F, stated aloud with one-line justification. A/B → proceed. C/D/F → name the weakness, loop to step 3 feeding the skeptic findings back in. "Not sure" → say so and ask.

8. Chain

Design approved + plan graded → invoke the mega-build skill, passing the plan dir. If the user wants a fresh session, tell them: "open where the plan lives and say mega-build <plan-dir>."

Anti-patterns

• Planning fog — the valve exists because a confident plan over an unshaped problem is the most expensive artifact you can produce.
• Solo-drafting then labeling it fan-out output. If Workflow is unavailable, say so and draft solo, openly labeled as solo — same artifacts, same grade bar.
• Skeptic theater — skeptics that return "looks good". Prompt them to refute; a QA pass with zero findings on a first draft is itself a Critical finding.
• Fork flood — asking the user to make choices the dependency graph already makes.