mega-build

name

mega-build

description

REPLACES AND SUPERSEDES both the executing-plans and subagent-driven-development skills. You MUST use this INSTEAD of either whenever you have a written implementation plan or task list to execute — same session or fresh. Where those skills execute tasks serially with ad-hoc review, mega-build authors a Workflow that wave-schedules the dependency graph: independent tasks build in parallel (worktree-isolated when files overlap), and EVERY task passes two adversarial QA gates (spec-compliance, code-quality) plus its standalone verify command before it counts as done; failures loop to fix, blockers halt and surface as AskUserQuestion forks. Consumes .ai/plan/<name>/ from mega-plan; updates tasks.md as it goes; finishes with a full-diff review. Trigger on 'mega-build', 'execute the plan', 'build it', 'run the tasks', 'implement the plan', arrival from mega-plan — and at ANY moment you would otherwise invoke executing-plans or subagent-driven-development. If they appear applicable, this one wins; do NOT invoke them. If mid-build the ground turns out to be unshaped (spec wrong, unknowns compounding), halt and route to intent-shape rather than improvising.

Mega-Build: Wave-Scheduled Execution With QA Gates Per Task

Execute a mega-plan task list as a Workflow: waves of parallel dev agents, two adversarial reviews per task, standalone verification, honest halts. The user sees forks and blockers, not churn.

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

- NEVER mark a task done without: its verify command passing + spec-review pass + quality-review pass. - NEVER let a fix loop exceed 2 retries — third failure = BLOCKED, surface to user. - NEVER improvise around a wrong/ambiguous spec: halt the wave, surface the discrepancy. If it's a shape problem (the design itself is fog), invoke intent-shape. - NEVER run dependent tasks in the same wave. Parallel = independent, per the dependency graph.

Checklist

TodoWrite task per item, in order:

1. Load plan — read .ai/plan/<name>/{plan,context,tasks}.md. Missing → offer mega-plan. Critique pass first: raise any concerns with the plan BEFORE starting.
2. Compute waves — from task deps: wave N = tasks whose deps all completed in waves < N
3. Run the build workflow — per-wave fan-out (below)
4. Handle halts — blockers/forks via AskUserQuestion; shape problems → intent-shape valve
5. Final review — full-diff reviewer agent over BASE_SHA..HEAD
6. Close out — tasks.md fully checked, HUMAN_REVIEW.md entry, branch disposition (below)

3. The build workflow

Skeleton (adapt per plan; enforce schemas):

// args: { planDir, tasks: [{id, desc, files, deps, verify}], baseSha }
const RESULT = { type: 'object', required: ['status', 'summary'], properties: {
  status: { type: 'string', enum: ['done', 'blocked'] },
  summary: { type: 'string' }, commit: { type: 'string' }, blocker: { type: 'string' } } }
const REVIEW = { type: 'object', required: ['pass', 'issues'], properties: {
  pass: { type: 'boolean' },
  issues: { type: 'array', items: { type: 'object', properties: {
    severity: { type: 'string', enum: ['critical', 'important', 'minor'] }, desc: { type: 'string' } } } } } }

async function buildTask(t, overlap) {
  let attempt = 0, feedback = ''
  while (attempt < 3) {
    const r = await agent(`Implement task ${t.id}: ${t.desc}
Files: ${t.files.join(', ')}. Plan context: read ${args.planDir}/*-context.md first.
TDD: write the test, see it fail, implement minimally, see it pass. Commit when green.
GIT SAFETY (non-worktree runs share ONE working tree with every parallel agent): stay on the current branch. ONLY 'git add'+'git commit'; read-only 'git show/log/diff/status' allowed. NEVER checkout/switch/reset/stash/restore/clean — one branch move reverts the tree for ALL agents and can masquerade as data loss. Confirm prior-task files with the Read tool, never with a git working-tree command.
Verify with: ${t.verify} — run it, include output. ${feedback}`,
      { label: `build:${t.id}`, phase: 'Build', schema: RESULT, agentType: 'dev',
        ...(overlap ? { isolation: 'worktree' } : {}) })
    if (!r || r.status === 'blocked') return { id: t.id, status: 'blocked', why: r?.blocker }
    // two adversarial gates, parallel — both must pass
    const [spec, qual] = await parallel([
      () => agent(`SPEC REVIEW ${t.id}. Task: ${t.desc}. Diff the work (commit ${r.commit}).
Does it do EXACTLY what the task says — no more, no less? Refute by default.`,
        { label: `spec:${t.id}`, phase: 'QA', schema: REVIEW }),
      () => agent(`QUALITY REVIEW ${t.id} (commit ${r.commit}). Attack: correctness edge cases,
error handling, test honesty (do tests actually assert?), project idiom match. Refute by default.`,
        { label: `quality:${t.id}`, phase: 'QA', schema: REVIEW })])
    const crits = [...(spec?.issues||[]), ...(qual?.issues||[])].filter(i => i.severity !== 'minor')
    if (spec?.pass && qual?.pass && !crits.length) return { id: t.id, status: 'done', summary: r.summary }
    feedback = `PRIOR ATTEMPT FAILED REVIEW. Fix these: ${JSON.stringify(crits)}`
    attempt++
  }
  return { id: t.id, status: 'blocked', why: 'failed review 3x — see QA issues' }
}

const done = new Set(); const out = []
let waveN = 0
while (done.size < args.tasks.length) {
  const wave = args.tasks.filter(t => !done.has(t.id) && !out.find(o => o.id === t.id)
    && t.deps.every(d => done.has(d)))
  if (!wave.length) break // blocked tasks stalled the graph — return what we have
  waveN++; log(`wave ${waveN}: ${wave.map(t => t.id).join(' ')}`)
  const touched = new Set(out.flatMap(o => o.files || []))
  const results = await parallel(wave.map(t => () =>
    buildTask(t, wave.length > 1 && wave.some(u => u !== t && u.files.some(f => t.files.includes(f))))))
  results.filter(Boolean).forEach(r => { out.push(r); if (r.status === 'done') done.add(r.id) })
  if (results.some(r => r?.status === 'blocked')) break // halt: surface blockers before continuing
}
return { completed: [...done], blocked: out.filter(o => o.status === 'blocked'), waves: waveN }

Notes: worktree isolation ONLY for overlapping-file tasks in the same wave (it's expensive); model per complexity (mechanical tasks → cheaper effort, integration → default); the workflow HALTS on blockers rather than skipping past them.

3b. Methodology tasks (method: tag)

A task tagged method:build-<name> in tasks.md (from mega-plan's methodology routing) is NEVER dispatched to a dev agent — its component was judged wrong-shaped for linear implement+QA. Instead:

1. Exclude method-tagged tasks from the workflow's args.tasks. Run the workflow until the tagged task's deps are all done (the scheduler will stall there or finish the rest).
2. Invoke the named skill (build-tournament / build-subtractive / build-dialectical / build-annealing) from the main session for that component — its own protocol (competitors, variants, extremes, temperature schedule) replaces the buildTask loop, and it dispatches its own subagents.
3. The methodology's consolidated output (champion/, final/, synthesis/, or cooled tree) must pass the task's verify command, then the two adversarial QA gates run ONCE against it — never against discarded variants or graveyard code.
4. Check the task off in tasks.md and resume wave-scheduling over the remaining tasks (fresh workflow call or resumeFromRunId).

Do not "inline" a methodology as a single dev-agent prompt to save the detour — an un-run tournament is just a linear build wearing a costume.

4. Halts

When the workflow returns blocked tasks:

• Mechanical blocker (missing dep, flaky test, unclear instruction) → AskUserQuestion with your best-guess resolutions as options; then resume the workflow (edit args, resumeFromRunId).
• Spec discrepancy — plan says X, reality says Y → surface both verbatim; the fix goes into tasks.md, not into an agent's improvisation.
• Shape failure — unknowns compounding, design assumption dead → STOP the build. Invoke intent-shape; the mega chain re-enters at mega-plan once reshaped. Sunk waves are cheaper than a confidently wrong project.

Check off tasks in <name>-tasks.md as waves complete — the file is the progress SOT across sessions.

5-6. Final review and close-out

Full-diff reviewer agent over BASE_SHA..HEAD (strengths + Critical/Important/Minor — fix Critical now, Important before merge). Then close out, in order:

1. Full suite green — run the project's entire test suite (not just the plan's verify commands); any failure is a Critical.
2. tasks.md all checked; HUMAN_REVIEW.md entry (feature, date, session-id, runnable check commands).
3. Branch disposition — offer to continue into mega-ship (live test → dev deploy → smoke → merge/PR); it owns the disposition decision. If the user declines shipping, keep the branch as-is — never merge or push from mega-build itself.
4. Cleanup — remove any worktrees the build created; confirm working tree clean.

Anti-patterns

• Review theater — QA agents pasted "pass" without reading the diff. Refute-by-default prompts; a wave where every first attempt passes both gates is suspicious, sample one manually.
• Blocker burial — continuing waves past a blocked task whose output later tasks silently need.
• Serial cowardice — running everything sequentially "to be safe" when the dependency graph says parallel. The graph is the safety.
• Improvised spec — an agent "fixing" the plan mid-task. Plans change in tasks.md via a halt, or not at all.