maestro-flow 0.4.19 → 0.4.20

package/workflows/swarm/wf-analyze.js

@@ -0,0 +1,186 @@
+export const meta = {
+  name: 'wf-analyze',
+  description: 'Multi-dimensional parallel analysis aligned with maestro-analyze 6-dimension scoring',
+  whenToUse: 'Accelerate maestro-analyze with parallel codebase exploration + dimension scoring + synthesis',
+  phases: [
+    { title: 'Explore', detail: '3-layer codebase exploration via cli-explore-agent' },
+    { title: 'Score', detail: 'Parallel 6-dimension scoring via workflow-analyzer' },
+    { title: 'Synthesize', detail: 'Cross-dimension synthesis with Go/No-Go recommendation' },
+  ],
+}
+
+const DIMENSIONS = [
+  { key: 'feasibility', focus: 'Technical difficulty, team capability, time constraints, tooling availability, infrastructure readiness' },
+  { key: 'impact', focus: 'User value, business value, tech debt reduction, developer experience improvement, ecosystem contribution' },
+  { key: 'risk', focus: 'Failure modes, security vulnerabilities, scalability limits, regression potential, data integrity threats' },
+  { key: 'complexity', focus: 'Integration points, dependency count, learning curve, testing difficulty, migration path complexity' },
+  { key: 'dependencies', focus: 'External services, internal module coupling, data dependencies, infrastructure requirements, third-party stability' },
+  { key: 'alternatives', focus: 'Compare 2+ approaches with tradeoffs, evaluate build-vs-buy, assess migration paths, weigh technology options' },
+]
+
+const EXPLORATION_SCHEMA = {
+  type: 'object',
+  properties: {
+    relevant_files: { type: 'array', items: { type: 'object', properties: { path: { type: 'string' }, role: { type: 'string' }, relevance: { type: 'string' } }, required: ['path', 'role'] } },
+    call_chains: { type: 'array', items: { type: 'object', properties: { entry: { type: 'string' }, chain: { type: 'array', items: { type: 'string' } }, purpose: { type: 'string' } }, required: ['entry', 'chain'] } },
+    data_flows: { type: 'array', items: { type: 'object', properties: { source: { type: 'string' }, sink: { type: 'string' }, transforms: { type: 'array', items: { type: 'string' } } }, required: ['source', 'sink'] } },
+    code_anchors: { type: 'array', items: { type: 'object', properties: { file: { type: 'string' }, line: { type: 'number' }, snippet: { type: 'string' }, significance: { type: 'string' } }, required: ['file', 'significance'] } },
+    module_boundaries: { type: 'array', items: { type: 'object', properties: { module: { type: 'string' }, exports: { type: 'array', items: { type: 'string' } }, depends_on: { type: 'array', items: { type: 'string' } } }, required: ['module'] } },
+  },
+  required: ['relevant_files', 'code_anchors'],
+}
+
+const DIMENSION_SCHEMA = {
+  type: 'object',
+  properties: {
+    dimension: { type: 'string' },
+    score: { type: 'number', minimum: 1, maximum: 5 },
+    confidence: { type: 'number', minimum: 0, maximum: 100 },
+    evidence: { type: 'array', items: { type: 'object', properties: { claim: { type: 'string' }, source: { type: 'string' }, strength: { type: 'string', enum: ['strong', 'moderate', 'weak'] } }, required: ['claim', 'source', 'strength'] } },
+    risks: { type: 'array', items: { type: 'object', properties: { risk: { type: 'string' }, probability: { type: 'string', enum: ['high', 'medium', 'low'] }, impact: { type: 'string', enum: ['critical', 'high', 'medium', 'low'] }, mitigation: { type: 'string' } }, required: ['risk', 'probability', 'impact'] } },
+    summary: { type: 'string' },
+  },
+  required: ['dimension', 'score', 'confidence', 'evidence', 'summary'],
+}
+
+const SYNTHESIS_SCHEMA = {
+  type: 'object',
+  properties: {
+    overall_score: { type: 'number', minimum: 1, maximum: 5 },
+    overall_confidence: { type: 'number', minimum: 0, maximum: 100 },
+    recommendation: { type: 'string', enum: ['go', 'conditional-go', 'no-go'] },
+    scope_verdict: { type: 'string', enum: ['large', 'medium', 'small'] },
+    risk_matrix: { type: 'array', items: { type: 'object', properties: { risk: { type: 'string' }, probability: { type: 'string' }, impact: { type: 'string' }, dimension: { type: 'string' } }, required: ['risk', 'probability', 'impact', 'dimension'] } },
+    decisions: { type: 'array', items: { type: 'object', properties: { id: { type: 'string' }, decision: { type: 'string' }, status: { type: 'string', enum: ['locked', 'free', 'deferred'] }, rationale: { type: 'string' }, options_considered: { type: 'array', items: { type: 'string' } } }, required: ['id', 'decision', 'status', 'rationale'] } },
+    implementation_scope: { type: 'array', items: { type: 'object', properties: { objective: { type: 'string' }, acceptance_criteria: { type: 'string' }, priority: { type: 'string', enum: ['high', 'medium', 'low'] }, target_files: { type: 'array', items: { type: 'string' } } }, required: ['objective', 'priority'] } },
+    executive_summary: { type: 'string' },
+  },
+  required: ['overall_score', 'overall_confidence', 'recommendation', 'scope_verdict', 'risk_matrix', 'decisions', 'executive_summary'],
+}
+
+const target = args?.target || 'the current codebase'
+const scope = args?.scope || ''
+const context = args?.context || ''
+const phase = args?.phase || null
+const selectedDimensions = args?.dimensions
+  ? DIMENSIONS.filter(d => args.dimensions.includes(d.key))
+  : DIMENSIONS
+
+// Phase 1: Codebase Exploration via cli-explore-agent
+phase('Explore')
+log('Launching 3-layer codebase exploration via cli-explore-agent...')
+
+const exploration = await agent(
+  `Perform 3-layer codebase exploration for: ${target}
+${scope ? 'File scope: ' + scope : 'Explore the full project structure.'}
+${context ? 'Additional context: ' + context : ''}
+${phase ? 'Phase context: ' + phase : ''}
+
+Layer 1 — Module Discovery (Breadth):
+  Search by topic keywords, identify ALL relevant files, map module boundaries.
+
+Layer 2 — Structure Tracing (Depth):
+  Top 3-5 key files: trace call chains 2-3 levels deep, identify data flow.
+
+Layer 3 — Code Anchor Extraction (Detail):
+  Each key finding: extract code snippet (20-50 lines) with file:line reference.
+
+Return structured exploration results.`,
+  { label: 'explore:codebase', phase: 'Explore', schema: EXPLORATION_SCHEMA, agentType: 'cli-explore-agent' }
+)
+
+const explorationContext = exploration
+  ? `Relevant files: ${exploration.relevant_files.map(f => f.path).join(', ')}
+Call chains: ${(exploration.call_chains || []).map(c => c.entry + ' → ' + c.chain.join(' → ')).join('; ')}
+Code anchors: ${exploration.code_anchors.map(a => a.file + ':' + (a.line || '?') + ' — ' + a.significance).join('\n')}`
+  : 'No exploration results available.'
+
+log(`Exploration complete: ${exploration ? exploration.relevant_files.length : 0} files, ${exploration ? exploration.code_anchors.length : 0} anchors`)
+
+// Phase 2: Parallel 6-Dimension Scoring via workflow-analyzer
+phase('Score')
+log(`Scoring ${selectedDimensions.length} dimensions in parallel via workflow-analyzer...`)
+
+const scores = await parallel(
+  selectedDimensions.map(dim => () =>
+    agent(
+      `Evaluate dimension: ${dim.key}
+Focus areas: ${dim.focus}
+Target: ${target}
+${phase ? 'Phase: ' + phase : ''}
+
+Codebase exploration context:
+${explorationContext}
+
+Score this dimension on a 1-5 scale with specific evidence from the codebase:
+- 1: Critical issues, blocks progress
+- 2: Significant concerns, requires major effort
+- 3: Manageable, standard effort required
+- 4: Good position, minor concerns only
+- 5: Excellent, minimal risk
+
+Every score must have specific file:line evidence, not general impressions.
+Include confidence percentage (0-100) based on evidence strength.
+For Risk dimension: include probability × impact matrix entries.`,
+      { label: `score:${dim.key}`, phase: 'Score', schema: DIMENSION_SCHEMA, agentType: 'workflow-analyzer' }
+    )
+  )
+)
+
+const validScores = scores.filter(Boolean)
+log(`${validScores.length}/${selectedDimensions.length} dimensions scored`)
+
+// Phase 3: Cross-Dimension Synthesis
+phase('Synthesize')
+
+const scoreDigest = validScores.map(s =>
+  `${s.dimension}: ${s.score}/5 (confidence: ${s.confidence}%)\n  ${s.summary}\n  Evidence: ${s.evidence.slice(0, 3).map(e => e.claim + ' [' + e.strength + ']').join('; ')}\n  Risks: ${(s.risks || []).map(r => r.risk + ' (' + r.probability + '/' + r.impact + ')').join('; ') || 'none identified'}`
+).join('\n\n')
+
+const synthesis = await agent(
+  `Synthesize multi-dimensional analysis results into a Go/No-Go recommendation.
+
+Target: ${target}
+${phase ? 'Phase: ' + phase : ''}
+
+Dimension Scores:
+${scoreDigest}
+
+Codebase Exploration:
+${explorationContext}
+
+Tasks:
+1. Calculate weighted overall score (Feasibility .25, Impact .20, Risk .20, Complexity .15, Dependencies .15, Alternatives .05)
+2. Build probability-impact risk matrix from all dimension risks
+3. Determine scope_verdict:
+   - "large": 3+ independent subsystems or hard serial dependencies
+   - "medium": 1-2 subsystems, parallelizable
+   - "small": single-file or few-file change
+4. Extract decisions (locked/free/deferred) based on findings
+5. Define implementation_scope with objectives, acceptance criteria, and target files
+6. Make Go/No-Go/Conditional-Go recommendation with confidence level
+7. Write executive summary (2-3 paragraphs)
+
+Recommendation rules:
+- Any dimension at 1/5 with high confidence → no-go (unless mitigated)
+- Average < 2.5 → no-go
+- Average 2.5-3.5 with risks → conditional-go (list conditions)
+- Average > 3.5 → go`,
+  { label: 'synthesize', phase: 'Synthesize', schema: SYNTHESIS_SCHEMA, agentType: 'workflow-analyzer' }
+)
+
+return {
+  exploration: exploration,
+  dimensions: validScores,
+  synthesis: synthesis,
+  metadata: {
+    target: target,
+    scope: scope,
+    phase: phase,
+    dimension_count: selectedDimensions.length,
+    completed_count: validScores.length,
+    overall_score: synthesis ? synthesis.overall_score : null,
+    recommendation: synthesis ? synthesis.recommendation : null,
+    scope_verdict: synthesis ? synthesis.scope_verdict : null,
+  },
+}

package/workflows/swarm/wf-brainstorm.js

@@ -0,0 +1,284 @@
+export const meta = {
+  name: 'wf-brainstorm',
+  description: 'Multi-role parallel brainstorm with cross-role reviewer synthesis, aligned with maestro-brainstorm',
+  whenToUse: 'Accelerate maestro-brainstorm with parallel role analysis and cross-role conflict/synergy detection',
+  phases: [
+    { title: 'Analyze', detail: 'Parallel multi-role analysis via role-design-author' },
+    { title: 'CrossReview', detail: 'Cross-role conflict detection via cross-role-reviewer' },
+    { title: 'Synthesize', detail: 'Resolution synthesis into guidance specification' },
+  ],
+}
+
+const VALID_ROLES = [
+  { key: 'system-architect', focus: 'System design, scalability, maintainability, module boundaries, technical debt, design patterns, infrastructure' },
+  { key: 'product-manager', focus: 'User value, market fit, MVP scope, prioritization, success metrics, stakeholder management, feature ROI' },
+  { key: 'test-strategist', focus: 'Testability, quality assurance, test pyramid, coverage strategy, risk-based testing, regression prevention' },
+  { key: 'ux-expert', focus: 'User experience, interaction patterns, accessibility, cognitive load, information architecture, user flows' },
+  { key: 'subject-matter-expert', focus: 'Domain knowledge, business rules, industry standards, compliance requirements, edge cases from domain' },
+  { key: 'data-architect', focus: 'Data modeling, storage strategy, query patterns, migration paths, data integrity, caching, consistency' },
+  { key: 'ui-designer', focus: 'Visual design, component hierarchy, design tokens, responsive layout, motion, color and typography' },
+  { key: 'product-owner', focus: 'Business priorities, backlog management, acceptance criteria, stakeholder value, sprint planning' },
+  { key: 'scrum-master', focus: 'Process efficiency, team dynamics, impediment removal, delivery cadence, continuous improvement' },
+]
+
+const ROLE_ANALYSIS_SCHEMA = {
+  type: 'object',
+  properties: {
+    role: { type: 'string' },
+    decision_digest: {
+      type: 'array',
+      items: {
+        type: 'object',
+        properties: {
+          id: { type: 'string' },
+          feature: { type: 'string' },
+          stance: { type: 'string' },
+          priority: { type: 'string', enum: ['must-have', 'should-have', 'nice-to-have'] },
+          rationale: { type: 'string' },
+        },
+        required: ['id', 'feature', 'stance', 'priority'],
+      },
+    },
+    interfaces: {
+      type: 'array',
+      items: {
+        type: 'object',
+        properties: {
+          contract: { type: 'string' },
+          consumers: { type: 'array', items: { type: 'string' } },
+          provider: { type: 'string' },
+        },
+        required: ['contract', 'consumers'],
+      },
+    },
+    cross_cutting_positions: {
+      type: 'array',
+      items: {
+        type: 'object',
+        properties: {
+          topic: { type: 'string' },
+          position: { type: 'string' },
+          strength: { type: 'string', enum: ['strong', 'moderate', 'weak'] },
+        },
+        required: ['topic', 'position', 'strength'],
+      },
+    },
+    findings: {
+      type: 'array',
+      items: {
+        type: 'object',
+        properties: {
+          finding: { type: 'string' },
+          impact: { type: 'string' },
+          evidence: { type: 'string' },
+        },
+        required: ['finding', 'impact'],
+      },
+    },
+    key_insight: { type: 'string' },
+  },
+  required: ['role', 'decision_digest', 'cross_cutting_positions', 'findings', 'key_insight'],
+}
+
+const CROSS_REVIEW_SCHEMA = {
+  type: 'object',
+  properties: {
+    conflicts: {
+      type: 'array',
+      items: {
+        type: 'object',
+        properties: {
+          id: { type: 'string' },
+          roles: { type: 'array', items: { type: 'string' } },
+          topic: { type: 'string' },
+          stances: { type: 'array', items: { type: 'object', properties: { role: { type: 'string' }, stance: { type: 'string' } }, required: ['role', 'stance'] } },
+          resolution_suggestion: { type: 'string' },
+          severity: { type: 'string', enum: ['blocking', 'significant', 'minor'] },
+        },
+        required: ['id', 'roles', 'topic', 'stances', 'severity'],
+      },
+    },
+    synergies: {
+      type: 'array',
+      items: {
+        type: 'object',
+        properties: {
+          roles: { type: 'array', items: { type: 'string' } },
+          topic: { type: 'string' },
+          combined_value: { type: 'string' },
+        },
+        required: ['roles', 'topic', 'combined_value'],
+      },
+    },
+    gaps: {
+      type: 'array',
+      items: {
+        type: 'object',
+        properties: {
+          area: { type: 'string' },
+          missing_perspective: { type: 'string' },
+          impact: { type: 'string' },
+        },
+        required: ['area', 'missing_perspective'],
+      },
+    },
+  },
+  required: ['conflicts', 'synergies', 'gaps'],
+}
+
+const GUIDANCE_SCHEMA = {
+  type: 'object',
+  properties: {
+    guidelines: {
+      type: 'array',
+      items: {
+        type: 'object',
+        properties: {
+          id: { type: 'string' },
+          guideline: { type: 'string' },
+          category: { type: 'string', enum: ['must', 'must-not', 'should', 'should-not', 'may'] },
+          source_roles: { type: 'array', items: { type: 'string' } },
+          rationale: { type: 'string' },
+          resolved_conflict: { type: 'string' },
+        },
+        required: ['id', 'guideline', 'category', 'source_roles', 'rationale'],
+      },
+    },
+    resolved_conflicts: {
+      type: 'array',
+      items: {
+        type: 'object',
+        properties: {
+          conflict_id: { type: 'string' },
+          resolution: { type: 'string' },
+          rationale: { type: 'string' },
+          winner_role: { type: 'string' },
+        },
+        required: ['conflict_id', 'resolution', 'rationale'],
+      },
+    },
+    open_questions: { type: 'array', items: { type: 'string' } },
+    executive_summary: { type: 'string' },
+  },
+  required: ['guidelines', 'resolved_conflicts', 'executive_summary'],
+}
+
+const topic = args?.topic || 'the proposed system'
+const context = args?.context || ''
+const roleCount = args?.count || 3
+const selectedRoles = args?.roles
+  ? VALID_ROLES.filter(r => args.roles.includes(r.key))
+  : VALID_ROLES.slice(0, roleCount)
+
+// Phase 1: Parallel multi-role analysis via role-design-author
+phase('Analyze')
+log(`Launching ${selectedRoles.length} role analyses in parallel via role-design-author...`)
+
+const analyses = await parallel(
+  selectedRoles.map(role => () =>
+    agent(
+      `You are the ${role.key} role analyzing: ${topic}
+${context ? 'Context: ' + context : ''}
+
+Your focus areas: ${role.focus}
+
+Produce a structured role analysis with:
+1. Decision Digest — your stances on each feature/aspect (id, feature, stance, priority, rationale)
+2. Interfaces — contracts you propose/consume (contract, consumers, provider)
+3. Cross-Cutting Positions — your stance on shared topics (topic, position, strength)
+4. Findings — discoveries with impact and evidence
+5. Key Insight — your single most important observation
+
+Read relevant source files if needed to ground your analysis in reality.
+Be specific and opinionated — take clear stances with rationale.`,
+      { label: `role:${role.key}`, phase: 'Analyze', schema: ROLE_ANALYSIS_SCHEMA, agentType: 'role-design-author' }
+    )
+  )
+)
+
+const validAnalyses = analyses.filter(Boolean)
+log(`${validAnalyses.length}/${selectedRoles.length} role analyses completed`)
+
+// Phase 2: Cross-role review via cross-role-reviewer
+phase('CrossReview')
+log('Cross-role conflict and synergy detection...')
+
+const analysesDigest = validAnalyses.map(a => {
+  const decisions = a.decision_digest.map(d => `  ${d.id}: [${d.priority}] ${d.feature} — ${d.stance}`).join('\n')
+  const positions = a.cross_cutting_positions.map(p => `  ${p.topic}: ${p.position} [${p.strength}]`).join('\n')
+  const findings = a.findings.map(f => `  - ${f.finding} (impact: ${f.impact})`).join('\n')
+  return `## ${a.role}\nKey insight: ${a.key_insight}\n\nDecisions:\n${decisions}\n\nPositions:\n${positions}\n\nFindings:\n${findings}`
+}).join('\n\n---\n\n')
+
+const crossReview = await agent(
+  `Compare these ${validAnalyses.length} role analyses for conflicts, gaps, and synergies.
+
+${analysesDigest}
+
+Identify:
+1. CONFLICTS: Same feature/topic with contradictory stances between roles. Include severity (blocking/significant/minor).
+2. SYNERGIES: Compatible positions that reinforce each other when combined.
+3. GAPS: Areas where an important perspective is missing — a topic addressed by one role but not by another that should.
+
+For each conflict, suggest a resolution direction.`,
+  { label: 'cross-review', phase: 'CrossReview', schema: CROSS_REVIEW_SCHEMA, agentType: 'cross-role-reviewer' }
+)
+
+// Phase 3: Synthesis into guidance specification
+phase('Synthesize')
+log('Synthesizing guidance specification...')
+
+const conflictDigest = crossReview.conflicts.map(c =>
+  `[${c.severity}] ${c.topic}: ${c.stances.map(s => s.role + '→' + s.stance).join(' vs ')}\n  Suggestion: ${c.resolution_suggestion}`
+).join('\n')
+
+const synergyDigest = crossReview.synergies.map(s =>
+  `${s.roles.join(' + ')}: ${s.topic} — ${s.combined_value}`
+).join('\n')
+
+const guidance = await agent(
+  `Synthesize a unified guidance specification from multi-role brainstorm results.
+
+Topic: ${topic}
+
+Role Analyses:
+${analysesDigest}
+
+Cross-Review Findings:
+Conflicts (${crossReview.conflicts.length}):
+${conflictDigest || 'None'}
+
+Synergies (${crossReview.synergies.length}):
+${synergyDigest || 'None'}
+
+Gaps: ${crossReview.gaps.map(g => g.area + ' — missing ' + g.missing_perspective).join('; ') || 'None'}
+
+Produce:
+1. Unified guidelines using RFC-2119 categories (MUST, MUST NOT, SHOULD, SHOULD NOT, MAY)
+2. For each conflict: resolve by weighing evidence strength, severity, and downstream impact
+3. Attribute each guideline to source roles
+4. List remaining open questions that need user input
+5. Executive summary (2-3 paragraphs)
+
+Priority rules for conflict resolution:
+- Security > correctness > user experience > performance > convenience
+- "must-have" from multiple roles > "must-have" from single role
+- Stances with strong evidence > moderate > weak`,
+  { label: 'guidance', phase: 'Synthesize', schema: GUIDANCE_SCHEMA }
+)
+
+return {
+  analyses: validAnalyses,
+  crossReview: crossReview,
+  guidance: guidance,
+  metadata: {
+    topic: topic,
+    role_count: selectedRoles.length,
+    completed_count: validAnalyses.length,
+    conflict_count: crossReview.conflicts.length,
+    blocking_conflicts: crossReview.conflicts.filter(c => c.severity === 'blocking').length,
+    synergy_count: crossReview.synergies.length,
+    gap_count: crossReview.gaps.length,
+    guideline_count: guidance ? guidance.guidelines.length : 0,
+  },
+}

package/workflows/swarm/wf-execute.js

@@ -0,0 +1,203 @@
+export const meta = {
+  name: 'wf-execute',
+  description: 'Wave-based parallel task execution via workflow-executor agents',
+  whenToUse: 'Accelerate maestro-execute with parallel task implementation within waves',
+  phases: [
+    { title: 'Load', detail: 'Load plan and resolve task dependencies' },
+    { title: 'Execute', detail: 'Wave-based parallel task execution via workflow-executor' },
+    { title: 'Report', detail: 'Execution summary and status collection' },
+  ],
+}
+
+const TASK_RESULT_SCHEMA = {
+  type: 'object',
+  properties: {
+    task_id: { type: 'string' },
+    status: { type: 'string', enum: ['completed', 'failed', 'blocked'] },
+    files_changed: { type: 'array', items: { type: 'string' } },
+    summary: { type: 'string' },
+    convergence_met: { type: 'boolean' },
+    unmet_criteria: { type: 'array', items: { type: 'string' } },
+    commit_hash: { type: 'string' },
+    error: { type: 'string' },
+  },
+  required: ['task_id', 'status', 'summary'],
+}
+
+const REPORT_SCHEMA = {
+  type: 'object',
+  properties: {
+    status: { type: 'string', enum: ['DONE', 'DONE_WITH_CONCERNS', 'NEEDS_RETRY'] },
+    total_tasks: { type: 'number' },
+    completed: { type: 'number' },
+    failed: { type: 'number' },
+    blocked: { type: 'number' },
+    waves_executed: { type: 'number' },
+    files_changed: { type: 'array', items: { type: 'string' } },
+    failed_tasks: { type: 'array', items: { type: 'object', properties: { task_id: { type: 'string' }, error: { type: 'string' }, unmet_criteria: { type: 'array', items: { type: 'string' } } }, required: ['task_id'] } },
+    summary: { type: 'string' },
+  },
+  required: ['status', 'total_tasks', 'completed', 'failed', 'summary'],
+}
+
+const planDir = args?.plan_dir || ''
+const specs = args?.specs || ''
+const codebaseContext = args?.codebase_context || ''
+const wikiContext = args?.wiki_context || ''
+const autoCommit = args?.auto_commit !== false
+
+// Phase 1: Load plan and resolve waves
+phase('Load')
+log('Loading plan and resolving task dependency waves...')
+
+const planLoad = await agent(
+  `Load the execution plan and resolve task waves.
+
+Plan directory: ${planDir || 'Find the most recent pending plan in .workflow/scratch/'}
+
+Steps:
+1. Read plan.json to get task_ids[], waves[], approach
+2. Read each .task/TASK-{NNN}.json to get: description, scope, focus_paths, depends_on, convergence.criteria, files[], implementation[], read_first[], test.commands
+3. Verify dependency order: tasks in wave N must have all depends_on satisfied by waves < N
+4. Filter: only include tasks with status="pending" (skip completed/blocked)
+5. Return the wave structure with full task context for each pending task
+
+Return the complete wave plan as structured data.`,
+  {
+    label: 'load:plan',
+    phase: 'Load',
+    schema: {
+      type: 'object',
+      properties: {
+        plan_dir: { type: 'string' },
+        plan_summary: { type: 'string' },
+        waves: {
+          type: 'array',
+          items: {
+            type: 'object',
+            properties: {
+              wave_index: { type: 'number' },
+              tasks: {
+                type: 'array',
+                items: {
+                  type: 'object',
+                  properties: {
+                    task_id: { type: 'string' },
+                    description: { type: 'string' },
+                    scope: { type: 'string' },
+                    focus_paths: { type: 'array', items: { type: 'string' } },
+                    depends_on: { type: 'array', items: { type: 'string' } },
+                    convergence_criteria: { type: 'array', items: { type: 'string' } },
+                    test_commands: { type: 'array', items: { type: 'string' } },
+                    files_to_create: { type: 'array', items: { type: 'string' } },
+                  },
+                  required: ['task_id', 'description'],
+                },
+              },
+            },
+            required: ['wave_index', 'tasks'],
+          },
+        },
+        total_pending: { type: 'number' },
+      },
+      required: ['plan_dir', 'waves', 'total_pending'],
+    },
+    agentType: 'workflow-planner',
+  }
+)
+
+if (!planLoad || !planLoad.waves || planLoad.waves.length === 0) {
+  log('No pending tasks found')
+  return { report: { status: 'DONE', total_tasks: 0, completed: 0, failed: 0, summary: 'No pending tasks.' }, metadata: { waves_executed: 0 } }
+}
+
+log(`Plan loaded: ${planLoad.total_pending} pending tasks across ${planLoad.waves.length} waves`)
+
+// Phase 2: Execute waves sequentially, tasks within each wave in parallel
+phase('Execute')
+
+const allResults = []
+let waveIndex = 0
+
+for (const wave of planLoad.waves) {
+  waveIndex++
+  log(`Wave ${waveIndex}/${planLoad.waves.length}: executing ${wave.tasks.length} tasks in parallel...`)
+
+  const waveResults = await parallel(
+    wave.tasks.map(task => () =>
+      agent(
+        `Execute task: ${task.task_id}
+Description: ${task.description}
+Scope: ${task.scope || 'project root'}
+Focus paths: ${(task.focus_paths || []).join(', ') || 'see task JSON'}
+Plan directory: ${planLoad.plan_dir}
+
+${specs ? 'Project specs (MUST comply):\n' + specs : ''}
+${codebaseContext ? 'Codebase architecture:\n' + codebaseContext : ''}
+${wikiContext ? 'Wiki knowledge:\n' + wikiContext : ''}
+
+Process:
+1. Read the full task JSON at ${planLoad.plan_dir}/.task/${task.task_id}.json
+2. Read all files in read_first[] before any modification
+3. Read reference.files for patterns to follow
+4. Implement changes following implementation[] steps in order
+5. Verify every convergence criterion: ${(task.convergence_criteria || []).join('; ') || 'see task JSON'}
+6. Run test commands: ${(task.test_commands || []).join('; ') || 'none defined'}
+${autoCommit ? '7. Create atomic git commit with message referencing ' + task.task_id : ''}
+8. Write summary to ${planLoad.plan_dir}/.summaries/${task.task_id}-summary.md
+9. Update task status to "completed" in the task JSON
+
+Stay within scope. Do not modify files outside focus_paths unless explicitly required by the task.`,
+        { label: `exec:${task.task_id}`, phase: 'Execute', schema: TASK_RESULT_SCHEMA, agentType: 'workflow-executor', isolation: 'worktree' }
+      )
+    )
+  )
+
+  allResults.push(...waveResults.filter(Boolean))
+
+  const waveFailed = waveResults.filter(r => r && r.status === 'failed')
+  if (waveFailed.length > 0) {
+    log(`Wave ${waveIndex}: ${waveFailed.length} tasks failed — ${waveFailed.map(f => f.task_id).join(', ')}`)
+  }
+}
+
+// Phase 3: Execution report
+phase('Report')
+
+const completed = allResults.filter(r => r.status === 'completed')
+const failed = allResults.filter(r => r.status === 'failed')
+const blocked = allResults.filter(r => r.status === 'blocked')
+
+const report = await agent(
+  `Generate execution report.
+
+Results: ${completed.length} completed, ${failed.length} failed, ${blocked.length} blocked out of ${planLoad.total_pending} total.
+
+Completed tasks:
+${completed.map(r => `- ${r.task_id}: ${r.summary} (${(r.files_changed || []).length} files)`).join('\n') || 'None'}
+
+Failed tasks:
+${failed.map(r => `- ${r.task_id}: ${r.error || r.summary}\n  Unmet: ${(r.unmet_criteria || []).join(', ') || 'unknown'}`).join('\n') || 'None'}
+
+Determine:
+- DONE: all tasks completed, no failures
+- DONE_WITH_CONCERNS: some failures but majority succeeded
+- NEEDS_RETRY: critical failures blocking downstream work
+
+Summarize what was accomplished and what needs attention.`,
+  { label: 'report', phase: 'Report', schema: REPORT_SCHEMA }
+)
+
+return {
+  report: report,
+  results: allResults,
+  metadata: {
+    plan_dir: planLoad.plan_dir,
+    waves_executed: waveIndex,
+    total_tasks: planLoad.total_pending,
+    completed: completed.length,
+    failed: failed.length,
+    blocked: blocked.length,
+    all_files_changed: completed.flatMap(r => r.files_changed || []),
+  },
+}