gswd 1.0.1 → 1.1.0

package/lib/render.ts

@@ -7,6 +7,9 @@
  * Schema: GSWD_SPEC.md Section 7.1-7.3
  */
 
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+
 // ─── Status Symbols ──────────────────────────────────────────────────────────
 
 export const SYMBOLS = {
@@ -18,6 +21,82 @@ export const SYMBOLS = {
   warning: '\u26A0',        // ⚠
 } as const;
 
+// ─── Colors ──────────────────────────────────────────────────────────────────
+
+/**
+ * ANSI color codes for GSWD branding.
+ * Electric orange/amber is the brand color (per CONTEXT.md locked decision).
+ * 256-color code \x1b[38;5;208m; dim uses \x1b[2m.
+ */
+export const COLORS = {
+  orange: '\x1b[38;5;208m',
+  dim: '\x1b[2m',
+  reset: '\x1b[0m',
+} as const;
+
+/**
+ * Wrap text in ANSI color. No-op when stdout is not a TTY (CI/Docker/pipe safety).
+ * Respects FORCE_COLOR env var to override TTY detection.
+ */
+export function colorize(text: string, color: keyof typeof COLORS): string {
+  if (!process.stdout.isTTY && !process.env.FORCE_COLOR) {
+    return text;
+  }
+  return `${COLORS[color]}${text}${COLORS.reset}`;
+}
+
+// ─── Logo ────────────────────────────────────────────────────────────────────
+
+/**
+ * Render the GSWD ASCII logo with catchphrase.
+ * Logo shape matches GSD's block-letter style from install.js.
+ * Static string — no figlet (STATE.md architectural decision).
+ *
+ * @param version - Optional version string (e.g., "1.0.1")
+ */
+export function renderLogo(version?: string): string {
+  const lines = [
+    '   \u2588\u2588\u2588\u2588\u2588\u2588\u2557 \u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2557\u2588\u2588\u2557    \u2588\u2588\u2557\u2588\u2588\u2588\u2588\u2588\u2588\u2557 ',
+    '  \u2588\u2588\u2554\u2550\u2550\u2550\u2550\u255D \u2588\u2588\u2554\u2550\u2550\u2550\u2550\u255D\u2588\u2588\u2551    \u2588\u2588\u2551\u2588\u2588\u2554\u2550\u2550\u2588\u2588\u2557',
+    '  \u2588\u2588\u2551  \u2588\u2588\u2588\u2557\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2557\u2588\u2588\u2551 \u2588\u2557 \u2588\u2588\u2551\u2588\u2588\u2551  \u2588\u2588\u2551',
+    '  \u2588\u2588\u2551   \u2588\u2588\u2551\u255A\u2550\u2550\u2550\u2550\u2588\u2588\u2551\u2588\u2588\u2551\u2588\u2588\u2588\u2557\u2588\u2588\u2551\u2588\u2588\u2551  \u2588\u2588\u2551',
+    '  \u255A\u2588\u2588\u2588\u2588\u2588\u2588\u2554\u255D\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2551\u255A\u2588\u2588\u2588\u2554\u2588\u2588\u2588\u2554\u255D\u2588\u2588\u2588\u2588\u2588\u2588\u2554\u255D',
+    '   \u255A\u2550\u2550\u2550\u2550\u2550\u255D \u255A\u2550\u2550\u2550\u2550\u2550\u2550\u255D \u255A\u2550\u2550\u255D\u255A\u2550\u2550\u255D \u255A\u2550\u2550\u2550\u2550\u2550\u255D ',
+  ].join('\n');
+
+  const coloredLogo = colorize(lines, 'orange');
+  const tagline = '  Spec clarity before code.';
+  const versionStr = version ? colorize(`  v${version}`, 'dim') : '';
+
+  return [coloredLogo, '', tagline, versionStr].filter(Boolean).join('\n');
+}
+
+// ─── First Run Guide ─────────────────────────────────────────────────────────
+
+/**
+ * Render the condensed first-run command guide.
+ * Per CONTEXT.md: primary commands only, no descriptions.
+ * Followed by automatic /gswd:start proposal for zero-friction onboarding.
+ */
+export function renderFirstRunGuide(): string {
+  const commands = [
+    '/gswd:start',
+    '/gswd:imagine',
+    '/gswd:specify',
+    '/gswd:compile',
+  ];
+
+  const lines = [
+    'Commands:',
+    '',
+    ...commands.map(cmd => `  ${colorize(cmd, 'orange')}`),
+    '',
+    'Run /gswd:start to begin.',
+  ];
+
+  return lines.join('\n');
+}
+
 // ─── Helpers ─────────────────────────────────────────────────────────────────
 
 /**
@@ -46,7 +125,7 @@ export function padRight(str: string, width: number): string {
  */
 export function renderBanner(stageName: string): string {
   const BANNER_WIDTH = 55;
-  const border = '\u2501'.repeat(BANNER_WIDTH);
+  const border = colorize('\u2501'.repeat(BANNER_WIDTH), 'orange');
   const title = ` GSWD \u25B6 ${stageName.toUpperCase()}`;
   return `${border}\n${title}\n${border}`;
 }
@@ -73,13 +152,13 @@ export function renderCheckpoint(
   const BOX_WIDTH = 56;
   const INNER_WIDTH = BOX_WIDTH - 4; // 52 (accounting for "│ " and " │")
 
-  const topBorder    = `\u250C${'\u2500'.repeat(BOX_WIDTH - 2)}\u2510`;
-  const midBorder    = `\u251C${'\u2500'.repeat(BOX_WIDTH - 2)}\u2524`;
-  const bottomBorder = `\u2514${'\u2500'.repeat(BOX_WIDTH - 2)}\u2518`;
+  const topBorder    = colorize(`\u250C${'\u2500'.repeat(BOX_WIDTH - 2)}\u2510`, 'orange');
+  const midBorder    = colorize(`\u251C${'\u2500'.repeat(BOX_WIDTH - 2)}\u2524`, 'orange');
+  const bottomBorder = colorize(`\u2514${'\u2500'.repeat(BOX_WIDTH - 2)}\u2518`, 'orange');
 
   const line = (text: string): string => {
     const padded = padRight(text, INNER_WIDTH);
-    return `\u2502 ${padded} \u2502`;
+    return `${colorize('\u2502', 'orange')} ${padded} ${colorize('\u2502', 'orange')}`;
   };
 
   const blankLine = line('');
@@ -198,3 +277,485 @@ export function renderProgressBar(
   const bar = '\u2588'.repeat(filled) + '\u2591'.repeat(empty);
   return `Progress: ${bar} ${percent}%`;
 }
+
+// ─── Stage Summary ────────────────────────────────────────────────────────────
+
+/**
+ * Input for stage summary rendering.
+ * Used at manual-mode checkpoints to show what a stage produced.
+ */
+export interface StageSummarySection {
+  name: string;
+  summary: string;
+}
+
+export interface StageSummaryInput {
+  stageName: string;
+  headline: string;
+  sections: StageSummarySection[];
+  filesCreated: string[];
+}
+
+/**
+ * Render a structured stage summary for manual-mode checkpoints.
+ * Consistent template per CONTEXT.md locked decision:
+ *   Headline -> section paragraphs -> file list
+ *
+ * ```
+ * ## Imagine Complete
+ *
+ * Imagine produced 3 product directions with ICP, GTM, and competition analysis.
+ *
+ * **Key outputs:**
+ * - ICP Analysis: Identified 2 primary personas with distinct pain points...
+ * - GTM Strategy: Recommended freemium launch with enterprise upgrade path...
+ *
+ * **Created:** IMAGINE.md, ICP.md, GTM.md, COMPETITION.md, DECISIONS.md
+ * ```
+ */
+// ─── Research Summary ────────────────────────────────────────────────────────
+
+/**
+ * Research summary section for post-agent display.
+ * Mirrors ResearchSummarySection from imagine-synthesis.ts.
+ */
+export interface RenderResearchSection {
+  displayName: string;
+  takeaways: string[];
+  bridge: string;
+}
+
+/**
+ * Render structured research summary after agent completion.
+ * Product-contextualized: section intros reference user's product.
+ * Per CONTEXT.md: 3-5 takeaway bullets per section, bridging paragraph per section.
+ *
+ * @param sections - Research summary sections from buildResearchSummary
+ * @param productContext - Brief description of the product (from brief.vision)
+ * @param targetUser - Who the product is for (from brief.target_user)
+ */
+export function renderResearchSummary(
+  sections: RenderResearchSection[],
+  productContext: string,
+  targetUser: string,
+): string {
+  const parts: string[] = [];
+  parts.push('## Research Summary');
+  parts.push('');
+
+  for (const section of sections) {
+    // Product-contextualized intro
+    parts.push(`### ${section.displayName}`);
+    parts.push(`*For a product helping ${targetUser}:*`);
+    parts.push('');
+
+    // Takeaway bullets (3-5)
+    for (const takeaway of section.takeaways) {
+      parts.push(`- ${takeaway}`);
+    }
+    parts.push('');
+
+    // Bridging paragraph
+    parts.push(section.bridge);
+    parts.push('');
+  }
+
+  return parts.join('\n');
+}
+
+// ─── Direction Cards ─────────────────────────────────────────────────────────
+
+/**
+ * Direction card input for rendering.
+ */
+export interface RenderDirectionInput {
+  label: string;
+  rationale: string[];
+  icp_summary: string;
+  problem_framing: string;
+  wedge: string;
+  differentiator: string;
+  risks: string[];
+}
+
+/**
+ * Render a direction card with "Why this makes sense" rationale section.
+ * Per CONTEXT.md: rationale section comes FIRST, before existing fields.
+ * Recommended direction gets a visual marker.
+ *
+ * @param direction - Direction data
+ * @param index - 0-based index for display numbering
+ * @param isRecommended - Whether this is the proposed/recommended direction
+ */
+export function renderDirectionCard(
+  direction: RenderDirectionInput,
+  index: number,
+  isRecommended: boolean,
+): string {
+  const marker = isRecommended ? ' **(Recommended)**' : '';
+  const parts: string[] = [];
+
+  parts.push(`### ${direction.label}${marker}`);
+  parts.push('');
+
+  // Rationale section FIRST per CONTEXT.md locked decision
+  if (direction.rationale.length > 0) {
+    parts.push('**Why this makes sense:**');
+    for (const r of direction.rationale) {
+      parts.push(`- ${r}`);
+    }
+    parts.push('');
+  }
+
+  // Existing fields
+  parts.push(`**ICP:** ${direction.icp_summary}`);
+  parts.push(`**Problem:** ${direction.problem_framing}`);
+  parts.push(`**Wedge:** ${direction.wedge}`);
+  parts.push(`**Differentiator:** ${direction.differentiator}`);
+  parts.push(`**Risks:** ${direction.risks.join('; ')}`);
+
+  return parts.join('\n');
+}
+
+// ─── Stage Summary ───────────────────────────────────────────────────────────
+
+export function renderStageSummary(input: StageSummaryInput): string {
+  const parts: string[] = [];
+
+  // Headline
+  parts.push(`## ${input.stageName} Complete`);
+  parts.push('');
+  parts.push(input.headline);
+  parts.push('');
+
+  // Key outputs (section summaries)
+  if (input.sections.length > 0) {
+    parts.push('**Key outputs:**');
+    for (const section of input.sections) {
+      parts.push(`- **${section.name}:** ${section.summary}`);
+    }
+    parts.push('');
+  }
+
+  // Files created
+  if (input.filesCreated.length > 0) {
+    parts.push(`**Created:** ${input.filesCreated.join(', ')}`);
+  }
+
+  return parts.join('\n');
+}
+
+// ─── Product Context ────────────────────────────────────────────────────────
+
+/**
+ * Minimal product context for contextual messaging throughout the pipeline.
+ * Extracted from INTAKE.json and DECISIONS.md with graceful fallbacks.
+ */
+export interface ProductContext {
+  /** Product domain (e.g., "spec-writing tool") */
+  domain: string;
+  /** Target user (e.g., "solo founders") */
+  targetUser: string;
+  /** Stage-specific context string */
+  stageContext: string;
+  /** Whether this is a re-run (changes banner messaging) */
+  isRerun: boolean;
+  /** Re-run feedback context (if re-run) */
+  rerunContext?: string;
+}
+
+/**
+ * Extract product context from DECISIONS.md and INTAKE.json.
+ * DECISIONS.md is preferred (more precise, available after Imagine).
+ * INTAKE.json is fallback (available from pipeline start).
+ * Returns safe defaults if neither file exists.
+ *
+ * @param planningDir - Path to .planning/ directory
+ * @param isRerun - Whether this is a re-run
+ */
+export function extractProductContext(planningDir: string, isRerun: boolean = false): ProductContext {
+  let domain = 'your product';
+  let targetUser = 'your users';
+
+  // Try DECISIONS.md first (more precise, available after Imagine)
+  try {
+    const decisionsPath = path.join(planningDir, 'DECISIONS.md');
+    const decisions = fs.readFileSync(decisionsPath, 'utf-8');
+    const targetMatch = decisions.match(/\*\*Target User:\*\*\s*(?:Auto-chosen:\s*)?(.+)/);
+    if (targetMatch) targetUser = targetMatch[1].trim();
+    const directionMatch = decisions.match(/\*\*Product Direction:\*\*\s*(?:Auto-chosen:\s*)?(.+)/);
+    if (directionMatch) domain = directionMatch[1].trim();
+  } catch {
+    // Fall through to INTAKE.json
+  }
+
+  // Fallback to INTAKE.json (available from pipeline start)
+  if (domain === 'your product') {
+    try {
+      const gswdDir = path.join(planningDir, 'gswd');
+      const intakePath = path.join(gswdDir, 'INTAKE.json');
+      const intake = JSON.parse(fs.readFileSync(intakePath, 'utf-8'));
+      if (intake.product_description) {
+        // Use first sentence as domain
+        const firstSentence = intake.product_description.split('.')[0];
+        if (firstSentence && firstSentence.trim().length > 0) {
+          domain = firstSentence.trim();
+        }
+      }
+    } catch {
+      // Use defaults
+    }
+  }
+
+  return { domain, targetUser, stageContext: '', isRerun, rerunContext: undefined };
+}
+
+// ─── Stage Context Templates ────────────────────────────────────────────────
+
+/**
+ * Stage-specific context line generators for contextual banners.
+ * Each returns a product-contextualized one-liner for the banner.
+ * Compile is deliberately excluded (per CONTEXT.md: deterministic, no banner needed).
+ */
+export const STAGE_CONTEXT_TEMPLATES: Record<string, (ctx: ProductContext) => string> = {
+  imagine: (ctx) => ctx.isRerun
+    ? `Refining directions based on your feedback${ctx.rerunContext ? ` about ${ctx.rerunContext}` : ''}`
+    : `Validating product direction for ${ctx.domain} targeting ${ctx.targetUser}`,
+  specify: (ctx) => `Building the execution-grade spec: journeys, requirements, and architecture for ${ctx.domain}`,
+  audit: (ctx) => `Verifying spec completeness \u2014 every journey, requirement, and edge case for ${ctx.domain} must trace`,
+};
+
+// ─── Agent Briefing Templates ───────────────────────────────────────────────
+
+/**
+ * Product-contextualized one-liner descriptions for Imagine research agents.
+ * Each function receives ProductContext and returns a purpose string.
+ */
+export const IMAGINE_AGENT_BRIEFINGS: Record<string, (ctx: ProductContext) => string> = {
+  'market-researcher': (ctx) => `mapping the ${ctx.domain} landscape to find gaps`,
+  'icp-persona': (ctx) => `profiling ${ctx.targetUser} who need ${ctx.domain}`,
+  'positioning': (ctx) => `finding the angle that makes ${ctx.domain} obviously necessary`,
+  'brainstorm-alternatives': (ctx) => `exploring 3 distinct product directions for ${ctx.domain}`,
+  'devils-advocate': (ctx) => `stress-testing assumptions before you commit to a direction`,
+};
+
+/**
+ * Product-contextualized one-liner descriptions for Specify agents.
+ */
+export const SPECIFY_AGENT_BRIEFINGS: Record<string, (ctx: ProductContext) => string> = {
+  'journey-mapper': (ctx) => `mapping user journeys for ${ctx.targetUser} through ${ctx.domain}`,
+  'architecture-drafter': (ctx) => `designing the system architecture for ${ctx.domain}`,
+  'integrations-checker': (ctx) => `evaluating external services ${ctx.domain} needs to connect with`,
+};
+
+// ─── Contextual Banner ──────────────────────────────────────────────────────
+
+/**
+ * Render a stage banner with a product-contextualized line below the title.
+ * Extension of renderBanner() for consultant-style messaging (Phase 16).
+ *
+ * ```
+ * ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ *  GSWD ► IMAGINE
+ *  Validating product direction for a spec-writing tool targeting founders
+ * ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ * ```
+ *
+ * @param stageName - Stage name (will be uppercased)
+ * @param contextLine - Product-contextualized one-liner
+ */
+export function renderContextBanner(stageName: string, contextLine: string): string {
+  const BANNER_WIDTH = 55;
+  const border = colorize('\u2501'.repeat(BANNER_WIDTH), 'orange');
+  const title = ` GSWD \u25B6 ${stageName.toUpperCase()}`;
+  const context = ` ${contextLine}`;
+  return `${border}\n${title}\n${context}\n${border}`;
+}
+
+// ─── Agent Briefing ─────────────────────────────────────────────────────────
+
+/**
+ * Input for agent pre-briefing display.
+ */
+export interface AgentBriefingEntry {
+  name: string;
+  productPurpose: string;
+}
+
+/**
+ * Render agent pre-briefing block before spawning.
+ * Technical transparency: name each agent explicitly with product-specific purpose.
+ *
+ * ```
+ * ◆ Spawning 5 research agents:
+ *   → market-researcher: mapping the spec-tooling landscape to find gaps
+ *   → icp-persona: profiling founders who struggle with product specification
+ * ```
+ *
+ * @param agents - Array of agent names with product-contextualized purposes
+ * @param stageContext - Optional stage context description
+ */
+export function renderAgentBriefing(agents: AgentBriefingEntry[], stageContext?: string): string {
+  const parts: string[] = [];
+  parts.push(`${SYMBOLS.inProgress} Spawning ${agents.length} research agents:`);
+
+  for (const agent of agents) {
+    parts.push(`  \u2192 ${agent.name}: ${agent.productPurpose}`);
+  }
+
+  if (stageContext) {
+    parts.push('');
+    parts.push(stageContext);
+  }
+
+  return parts.join('\n');
+}
+
+// ─── Agent Completion ───────────────────────────────────────────────────────
+
+/**
+ * Render a single agent completion line with its key finding headline.
+ *
+ * ✓ market-researcher: 3 direct competitors in the spec-tooling space
+ * ✗ icp-persona: Agent failed — timeout
+ *
+ * @param agentName - Agent name
+ * @param headline - Key finding or error message
+ * @param status - Agent completion status
+ */
+export function renderAgentCompletion(
+  agentName: string,
+  headline: string,
+  status: 'complete' | 'failed',
+): string {
+  const symbol = status === 'complete' ? SYMBOLS.complete : SYMBOLS.failed;
+  return `${symbol} ${agentName}: ${headline}`;
+}
+
+// ─── Agent Progress ─────────────────────────────────────────────────────────
+
+/**
+ * Render full agent progress block showing pending and completed agents.
+ * Pending agents show ○, completed show ✓ with headline, failed show ✗.
+ *
+ * ✓ market-researcher: 3 direct competitors found
+ * ✓ icp-persona: primary persona is technical founder
+ * ○ positioning (pending)
+ * ○ brainstorm-alternatives (pending)
+ * ○ devils-advocate (pending)
+ */
+export function renderAgentProgress(
+  agents: Array<{ name: string; status: 'pending' | 'complete' | 'failed'; headline?: string }>,
+): string {
+  const lines: string[] = [];
+
+  for (const agent of agents) {
+    switch (agent.status) {
+      case 'complete':
+        lines.push(`${SYMBOLS.complete} ${agent.name}: ${agent.headline || 'complete'}`);
+        break;
+      case 'failed':
+        lines.push(`${SYMBOLS.failed} ${agent.name}: ${agent.headline || 'failed'}`);
+        break;
+      case 'pending':
+        lines.push(`${SYMBOLS.pending} ${agent.name} (pending)`);
+        break;
+    }
+  }
+
+  return lines.join('\n');
+}
+
+// ─── File Inventory ──────────────────────────────────────────────────────────
+
+/**
+ * Render a file inventory table listing all generated files with descriptions.
+ * Used at pipeline end to give users a deliverable checklist.
+ *
+ * @param files - Array of { path, description } objects
+ * @returns Markdown table string
+ */
+export function renderFileInventory(files: Array<{ path: string; description: string }>): string {
+  if (files.length === 0) return '';
+
+  const lines: string[] = [];
+  lines.push('| File | Description |');
+  lines.push('|------|-------------|');
+  for (const file of files) {
+    lines.push(`| \`${file.path}\` | ${file.description} |`);
+  }
+  return lines.join('\n');
+}
+
+// ─── Headline Extraction ────────────────────────────────────────────────────
+
+/**
+ * Extract a one-line headline from agent output for completion display.
+ * Multi-strategy extraction with robust fallback.
+ *
+ * Strategy priority:
+ * 1. First sentence after "## Summary" heading
+ * 2. Text after "Key finding:" prefix
+ * 3. First non-heading, non-empty line
+ * 4. Fallback: "{agentName} analysis complete"
+ *
+ * Truncates to 80 chars. Never returns empty string.
+ *
+ * @param agentOutput - Raw agent output content
+ * @param agentName - Agent name (for fallback)
+ */
+export function extractHeadline(agentOutput: string, agentName: string): string {
+  const MAX_LENGTH = 80;
+
+  if (!agentOutput || agentOutput.trim().length === 0) {
+    return `${agentName} analysis complete`;
+  }
+
+  const lines = agentOutput.split('\n');
+
+  // Strategy 1: First sentence after "## Summary" heading
+  for (let i = 0; i < lines.length; i++) {
+    if (/^##\s+Summary\s*$/i.test(lines[i].trim())) {
+      // Look at next non-empty lines for the first sentence
+      for (let j = i + 1; j < lines.length; j++) {
+        const line = lines[j].trim();
+        if (line.length === 0) continue;
+        if (line.startsWith('#')) break; // next heading, stop
+        // Take up to first period
+        const periodIdx = line.indexOf('.');
+        const sentence = periodIdx > 0 ? line.slice(0, periodIdx + 1) : line;
+        return truncateHeadline(sentence, MAX_LENGTH);
+      }
+    }
+  }
+
+  // Strategy 2: "Key finding:" prefix
+  for (const line of lines) {
+    const match = line.match(/Key finding:\s*(.+)/i);
+    if (match) {
+      return truncateHeadline(match[1].trim(), MAX_LENGTH);
+    }
+  }
+
+  // Strategy 3: First non-heading, non-empty line
+  for (const line of lines) {
+    const trimmed = line.trim();
+    if (trimmed.length === 0) continue;
+    if (trimmed.startsWith('#')) continue;
+    if (trimmed.startsWith('---')) continue;
+    if (trimmed.startsWith('```')) continue;
+    return truncateHeadline(trimmed, MAX_LENGTH);
+  }
+
+  // Strategy 4: Fallback
+  return `${agentName} analysis complete`;
+}
+
+/**
+ * Truncate a string to maxLength, adding "..." if truncated.
+ */
+function truncateHeadline(text: string, maxLength: number): string {
+  const cleaned = text.trim();
+  if (cleaned.length <= maxLength) return cleaned;
+  return cleaned.slice(0, maxLength - 3) + '...';
+}

package/lib/specify-agents.ts

@@ -11,6 +11,8 @@
 
 import * as fs from 'node:fs';
 import type { Journey, FunctionalRequirement } from './specify-journeys.js';
+import { extractHeadline } from './render.js';
+import type { OnAgentComplete } from './imagine-agents.js';
 
 // ─── Types ───────────────────────────────────────────────────────────────────
 
@@ -204,6 +206,7 @@ export async function orchestrateSpecifyAgents(
   agents: SpecifyAgentDefinition[],
   context: SpecifyAgentContext,
   spawnFn: SpawnFn,
+  onComplete?: OnAgentComplete,
 ): Promise<AgentResult[]> {
   const results: AgentResult[] = [];
 
@@ -212,14 +215,33 @@ export async function orchestrateSpecifyAgents(
   for (const agent of sequentialAgents) {
     const result = await runSingleAgent(agent, context, spawnFn);
     results.push(result);
+    if (onComplete) {
+      onComplete({
+        agent: result.agent,
+        headline: result.status === 'complete'
+          ? extractHeadline(result.content, result.agent)
+          : (result.error || 'Agent failed'),
+        status: result.status,
+      });
+    }
   }
 
   // Phase 2: Parallel agents
   const parallelAgents = agents.filter((a) => a.phase === 'parallel');
   if (parallelAgents.length > 0) {
-    const parallelPromises = parallelAgents.map((agent) =>
-      runSingleAgent(agent, context, spawnFn)
-    );
+    const parallelPromises = parallelAgents.map(async (agent) => {
+      const result = await runSingleAgent(agent, context, spawnFn);
+      if (onComplete) {
+        onComplete({
+          agent: result.agent,
+          headline: result.status === 'complete'
+            ? extractHeadline(result.content, result.agent)
+            : (result.error || 'Agent failed'),
+          status: result.status,
+        });
+      }
+      return result;
+    });
     const parallelResults = await Promise.all(parallelPromises);
     results.push(...parallelResults);
   }