gswd 1.0.1 → 1.1.0

package/lib/compile.ts

@@ -28,6 +28,7 @@ export interface ParsedFR {
   scope: 'v1' | 'v2' | 'out';
   priority: 'P0' | 'P1' | 'P2';
   sourceJourneys: string[];
+  acceptanceCriteria: string[];
 }
 
 export interface ParsedNFR {
@@ -69,6 +70,11 @@ export interface SpecBundle {
   journeys: ParsedJourney[];
   integrations: ParsedIntegration[];
   projectSlug: string;
+  architectureSummary: string;
+  icpHighlights: string;
+  competitionLandscape: string;
+  gtmPositioning: string;
+  journeyInsights: string;
 }
 
 // ─── Constants (all exported) ─────────────────────────────────────────────────
@@ -151,12 +157,26 @@ export function parseFRsFromSpec(
 
     const sourceJourneys = Array.from(frToJourneys.get(pos.id) ?? new Set<string>()).sort();
 
+    // Extract acceptance criteria: lines after "**Acceptance Criteria:**" heading
+    const acceptanceCriteria: string[] = [];
+    const acMatch = section.match(/\*{0,2}Acceptance Criteria:?\*{0,2}:?\s*\n([\s\S]*?)(?=\*\*|###|$)/i);
+    if (acMatch) {
+      const acLines = acMatch[1].split('\n');
+      for (const acLine of acLines) {
+        const bulletMatch = acLine.match(/^[-*]\s+(.+)/);
+        if (bulletMatch) {
+          acceptanceCriteria.push(bulletMatch[1].trim());
+        }
+      }
+    }
+
     return {
       id: pos.id,
       description,
       scope: (scopeMatch?.[1]?.toLowerCase() as 'v1' | 'v2' | 'out') ?? 'v1',
       priority: (priorityMatch?.[1] as 'P0' | 'P1' | 'P2') ?? 'P1',
       sourceJourneys,
+      acceptanceCriteria,
     };
   });
 
@@ -346,6 +366,12 @@ export function parseSpecBundle(
     nfr: string;
     journeys: string;
     integrations: string;
+    architecture?: string;
+    icp?: string;
+    competition?: string;
+    gtm?: string;
+    researchSummary?: string;
+    features?: string;
   },
   statePath?: string
 ): SpecBundle {
@@ -412,6 +438,52 @@ export function parseSpecBundle(
     }
   }
 
+  // Populate new enrichment fields from research files
+  const architectureContent = files.architecture ?? '';
+  const icpContent = files.icp ?? '';
+  const competitionContent = files.competition ?? '';
+  const gtmContent = files.gtm ?? '';
+  const featuresContent = files.features ?? '';
+
+  const architectureSummary =
+    extractHeadingContent(architectureContent, '## Standard Architecture') ??
+    extractHeadingContent(architectureContent, '## Executive Summary') ??
+    '';
+
+  const icpHighlights =
+    extractHeadingContent(icpContent, '## ICP Highlights') ??
+    extractHeadingContent(icpContent, '## Target Users') ??
+    extractHeadingContent(featuresContent, '### Expected Features') ??
+    extractHeadingContent(featuresContent, '## Expected Features') ??
+    '';
+
+  const competitionLandscape =
+    extractHeadingContent(competitionContent, '## Competitor Analysis') ??
+    extractHeadingContent(competitionContent, '## Landscape') ??
+    extractHeadingContent(featuresContent, '## Competitor Feature Analysis') ??
+    '';
+
+  const gtmPositioning =
+    extractHeadingContent(gtmContent, '## GTM Positioning') ??
+    extractHeadingContent(gtmContent, '## Positioning') ??
+    extractHeadingContent(gtmContent, '## Executive Summary') ??
+    '';
+
+  // Synthesize journeyInsights from journeys array
+  const journeyTypeCounts = new Map<string, number>();
+  for (const journey of journeys) {
+    const count = journeyTypeCounts.get(journey.type) ?? 0;
+    journeyTypeCounts.set(journey.type, count + 1);
+  }
+  const journeyInsightParts: string[] = [];
+  for (const journey of journeys) {
+    const frCount = journey.linkedFRs.length;
+    journeyInsightParts.push(`${journey.id} (${journey.name}, type: ${journey.type}, FRs: ${frCount})`);
+  }
+  const journeyInsights = journeyInsightParts.length > 0
+    ? journeyInsightParts.join('\n')
+    : '';
+
   return {
     vision,
     targetUser,
@@ -429,6 +501,11 @@ export function parseSpecBundle(
     journeys,
     integrations,
     projectSlug,
+    architectureSummary,
+    icpHighlights,
+    competitionLandscape,
+    gtmPositioning,
+    journeyInsights,
   };
 }
 
@@ -476,6 +553,96 @@ export function generateProjectDoc(bundle: SpecBundle): string {
   }
   lines.push('');
 
+  // ── ## Context section ──────────────────────────────────────────────────────
+  lines.push('## Context');
+  lines.push('');
+  lines.push('Product context synthesized from GSWD research pipeline. Each subsection summarizes key findings and references the source artifact.');
+  lines.push('');
+
+  // Architecture Summary
+  lines.push('### Architecture Summary');
+  lines.push('');
+  if (bundle.architectureSummary) {
+    lines.push(bundle.architectureSummary);
+  } else {
+    lines.push('*(Architecture research not available — run /gswd:imagine to generate)*');
+  }
+  lines.push('');
+  lines.push('> See: .planning/research/ARCHITECTURE.md for full details');
+  lines.push('');
+
+  // ICP Highlights
+  lines.push('### ICP Highlights');
+  lines.push('');
+  if (bundle.icpHighlights) {
+    lines.push(bundle.icpHighlights);
+  } else {
+    lines.push('*(ICP research not available)*');
+  }
+  lines.push('');
+  lines.push('> See: .planning/research/ICP.md for full details');
+  lines.push('');
+
+  // Competition Landscape
+  lines.push('### Competition Landscape');
+  lines.push('');
+  if (bundle.competitionLandscape) {
+    lines.push(bundle.competitionLandscape);
+  } else {
+    lines.push('*(Competition research not available)*');
+  }
+  lines.push('');
+  lines.push('> See: .planning/research/COMPETITION.md for full details');
+  lines.push('');
+
+  // GTM Positioning
+  lines.push('### GTM Positioning');
+  lines.push('');
+  if (bundle.gtmPositioning) {
+    lines.push(bundle.gtmPositioning);
+  } else {
+    lines.push('*(GTM research not available)*');
+  }
+  lines.push('');
+  lines.push('> See: .planning/research/GTM.md for full details');
+  lines.push('');
+
+  // Journey Insights
+  lines.push('### Journey Insights');
+  lines.push('');
+  if (bundle.journeyInsights) {
+    lines.push(bundle.journeyInsights);
+  } else if (bundle.journeys.length > 0) {
+    // Synthesize from journeys array
+    for (const j of bundle.journeys) {
+      lines.push(`${j.id} (${j.name}, type: ${j.type}, FRs: ${j.linkedFRs.length})`);
+    }
+  } else {
+    lines.push('*(No journeys defined)*');
+  }
+  lines.push('');
+  lines.push('> See: .planning/research/FEATURES.md for full details');
+  lines.push('');
+
+  // GSWD Artifacts table
+  lines.push('### GSWD Artifacts');
+  lines.push('');
+  lines.push('| File | Description |');
+  lines.push('|------|-------------|');
+  lines.push('| .planning/IMAGINE.md | Product vision, target user, and direction |');
+  lines.push('| .planning/DECISIONS.md | Frozen decisions, success metrics, risks |');
+  lines.push('| .planning/SPEC.md | Functional requirements with IDs |');
+  lines.push('| .planning/NFR.md | Non-functional requirements |');
+  lines.push('| .planning/JOURNEYS.md | User journeys with FR linkages |');
+  lines.push('| .planning/INTEGRATIONS.md | External integrations and fallbacks |');
+  lines.push('| .planning/research/ARCHITECTURE.md | Architecture research |');
+  lines.push('| .planning/research/FEATURES.md | Feature landscape research |');
+  lines.push('| .planning/research/PITFALLS.md | Common pitfalls research |');
+  lines.push('| .planning/research/STACK.md | Technology stack research |');
+  lines.push('| .planning/research/SUMMARY.md | Research executive summary |');
+  lines.push('| .planning/research/gswd/SUMMARY.md | GSD-format research bridge |');
+  lines.push('');
+
   return lines.join('\n');
 }
 
@@ -506,11 +673,65 @@ export function generateRequirementsDoc(bundle: SpecBundle): string {
   const v1FRs = sortedFRs.filter((fr) => fr.scope === 'v1');
   const v2FRs = sortedFRs.filter((fr) => fr.scope === 'v2');
 
+  // Build a journey map for quick lookup
+  const journeyMap = new Map<string, ParsedJourney>();
+  for (const journey of bundle.journeys) {
+    journeyMap.set(journey.id, journey);
+  }
+
   lines.push('### v1 (In Scope)');
   lines.push('');
   for (const fr of v1FRs) {
     lines.push(`#### ${fr.id}: ${fr.description}`);
     lines.push(`**Scope:** ${fr.scope}  **Priority:** ${fr.priority}`);
+
+    // Journey origin
+    if (fr.sourceJourneys.length > 0) {
+      const journeyRefs = fr.sourceJourneys
+        .sort()
+        .map((jId) => {
+          const journey = journeyMap.get(jId);
+          return journey ? `${jId}: ${journey.name}` : jId;
+        })
+        .join(', ');
+      lines.push(`**Origin:** From ${journeyRefs}`);
+    }
+
+    // Acceptance criteria
+    if (fr.acceptanceCriteria && fr.acceptanceCriteria.length > 0) {
+      lines.push('**Acceptance Criteria:**');
+      for (const criterion of fr.acceptanceCriteria) {
+        lines.push(`- ${criterion}`);
+      }
+    }
+
+    // NFR constraints — apply heuristic based on NFR category
+    const applicableNFRs: string[] = [];
+    for (const nfr of bundle.nfrs) {
+      const cat = nfr.category.toLowerCase();
+      // Security and performance apply to all v1 FRs
+      if (cat === 'security' || cat === 'performance') {
+        applicableNFRs.push(`${nfr.id} (${nfr.category.charAt(0).toUpperCase() + nfr.category.slice(1)})`);
+        continue;
+      }
+      // Observability applies to all v1 FRs
+      if (cat === 'observability') {
+        applicableNFRs.push(`${nfr.id} (${nfr.category.charAt(0).toUpperCase() + nfr.category.slice(1)})`);
+        continue;
+      }
+      // Privacy applies if FR touches user/data/personal/profile/account keywords
+      if (cat === 'privacy') {
+        const desc = fr.description.toLowerCase();
+        if (desc.includes('user') || desc.includes('data') || desc.includes('personal') ||
+            desc.includes('profile') || desc.includes('account')) {
+          applicableNFRs.push(`${nfr.id} (${nfr.category.charAt(0).toUpperCase() + nfr.category.slice(1)})`);
+        }
+      }
+    }
+    if (applicableNFRs.length > 0) {
+      lines.push(`**Applicable NFR Constraints:** ${applicableNFRs.join(', ')}`);
+    }
+
     lines.push('');
   }
   if (v1FRs.length === 0) {
@@ -614,6 +835,12 @@ export function generateRoadmapDoc(bundle: SpecBundle): string {
       if (journeys.length === 0) {
         lines.push('*(no journeys assigned)*');
       } else {
+        // Emit a Goal line with journey IDs
+        const goalJourneys = journeys
+          .map((j) => `${j.id} (${j.name})`)
+          .join(', ');
+        lines.push(`**Goal:** Implement ${goalJourneys}`);
+        lines.push('');
         for (const j of journeys) {
           lines.push(`- **${j.id}**: ${j.name}`);
           const frRefs = [...j.linkedFRs].sort().join(', ');
@@ -631,6 +858,10 @@ export function generateRoadmapDoc(bundle: SpecBundle): string {
       if (obsSecNFRs.length === 0) {
         lines.push('*(no NFRs assigned)*');
       } else {
+        // Emit a Goal line for Phase 4
+        const nfrGoal = obsSecNFRs.map((nfr) => nfr.id).join(', ');
+        lines.push(`**Goal:** Enforce ${nfrGoal}`);
+        lines.push('');
         for (const nfr of obsSecNFRs) {
           lines.push(`- **${nfr.id}**: ${nfr.description}`);
         }
@@ -643,6 +874,160 @@ export function generateRoadmapDoc(bundle: SpecBundle): string {
   return lines.join('\n');
 }
 
+/**
+ * Generate a GSD-format research SUMMARY.md from SpecBundle.
+ *
+ * Maps GSWD spec content to GSD research template headings.
+ * Pure function — no Date calls, no I/O.
+ * Versioned with <!-- gswd-schema-version: 1 --> header.
+ */
+export function generateResearchSummary(bundle: SpecBundle): string {
+  const lines: string[] = [];
+
+  lines.push('<!-- gswd-schema-version: 1 -->');
+  lines.push('# Project Research Summary');
+  lines.push('');
+  lines.push(`**Project:** ${bundle.projectSlug}`);
+  lines.push('**Domain:** Product specification');
+  lines.push('**Confidence:** HIGH');
+  lines.push('');
+
+  // ## Executive Summary
+  lines.push('## Executive Summary');
+  lines.push('');
+  if (bundle.vision) {
+    lines.push(bundle.vision);
+    lines.push('');
+  }
+  if (bundle.productDirection) {
+    lines.push(bundle.productDirection);
+    lines.push('');
+  }
+
+  // ## Key Findings
+  lines.push('## Key Findings');
+  lines.push('');
+
+  // ### Recommended Stack
+  lines.push('### Recommended Stack');
+  lines.push('');
+  if (bundle.architectureSummary) {
+    lines.push(bundle.architectureSummary);
+  } else {
+    lines.push('*(Stack research not available from GSWD — will be determined during GSD planning)*');
+  }
+  lines.push('');
+
+  // ### Expected Features
+  lines.push('### Expected Features');
+  lines.push('');
+  if (bundle.icpHighlights) {
+    lines.push(bundle.icpHighlights);
+  } else {
+    // Synthesize from FRs
+    const p0FRs = bundle.frs.filter((f) => f.scope === 'v1' && f.priority === 'P0');
+    const p1FRs = bundle.frs.filter((f) => f.scope === 'v1' && f.priority === 'P1');
+
+    if (p0FRs.length > 0) {
+      lines.push('**Must have (table stakes):**');
+      for (const fr of p0FRs) {
+        lines.push(`- ${fr.description}`);
+      }
+      lines.push('');
+    }
+    if (p1FRs.length > 0) {
+      lines.push('**Should have:**');
+      for (const fr of p1FRs) {
+        lines.push(`- ${fr.description}`);
+      }
+    }
+  }
+  lines.push('');
+
+  // ### Architecture Approach
+  lines.push('### Architecture Approach');
+  lines.push('');
+  if (bundle.architectureSummary) {
+    lines.push(bundle.architectureSummary);
+  } else {
+    lines.push('*(Architecture to be determined during GSD planning)*');
+  }
+  lines.push('');
+
+  // ### Critical Pitfalls
+  lines.push('### Critical Pitfalls');
+  lines.push('');
+  if (bundle.risks.length > 0) {
+    for (const risk of bundle.risks) {
+      lines.push(`- ${risk}`);
+    }
+  } else {
+    lines.push('*(No risks identified)*');
+  }
+  lines.push('');
+
+  // ## Implications for Roadmap
+  lines.push('## Implications for Roadmap');
+  lines.push('');
+  // Group journeys by phase and describe implications
+  const phaseJourneyMap = new Map<number, ParsedJourney[]>();
+  for (let i = 1; i <= 4; i++) {
+    phaseJourneyMap.set(i, []);
+  }
+  for (const journey of bundle.journeys) {
+    const phase = JOURNEY_TYPE_TO_PHASE[journey.type] ?? 3;
+    phaseJourneyMap.get(phase)!.push(journey);
+  }
+  for (let phaseNum = 1; phaseNum <= 3; phaseNum++) {
+    const phaseJ = phaseJourneyMap.get(phaseNum)!;
+    if (phaseJ.length > 0) {
+      const journeyList = phaseJ.map((j) => `${j.id} (${j.name})`).join(', ');
+      lines.push(`- **Phase ${phaseNum}**: ${PHASE_NAMES[phaseNum]} — ${journeyList}`);
+    }
+  }
+  const obsSecNFRs = bundle.nfrs.filter(
+    (nfr) => nfr.category === 'observability' || nfr.category === 'security'
+  );
+  if (obsSecNFRs.length > 0) {
+    const nfrList = obsSecNFRs.map((nfr) => nfr.id).join(', ');
+    lines.push(`- **Phase 4**: ${PHASE_NAMES[4]} — enforce ${nfrList}`);
+  }
+  lines.push('');
+
+  // ## Confidence Assessment
+  lines.push('## Confidence Assessment');
+  lines.push('');
+  lines.push('| Area | Confidence | Notes |');
+  lines.push('|------|------------|-------|');
+  lines.push(
+    `| Stack | ${bundle.architectureSummary ? 'HIGH' : 'LOW'} | ${
+      bundle.architectureSummary ? 'From GSWD research' : 'Not researched in GSWD'
+    } |`
+  );
+  lines.push(`| Features | HIGH | ${bundle.frs.length} FRs defined with traceability |`);
+  lines.push(
+    `| Architecture | ${bundle.architectureSummary ? 'HIGH' : 'MEDIUM'} | ${
+      bundle.architectureSummary ? 'From GSWD research' : 'Inferred from requirements'
+    } |`
+  );
+  lines.push(`| Pitfalls | MEDIUM | ${bundle.risks.length} risks identified |`);
+  lines.push('');
+
+  // ## Sources
+  lines.push('## Sources');
+  lines.push('');
+  lines.push('### Primary (HIGH confidence)');
+  lines.push('- GSWD specification pipeline — full imagine/specify/audit/compile cycle');
+  lines.push('');
+
+  lines.push('---');
+  lines.push('*Research completed: via GSWD compile*');
+  lines.push('*Ready for roadmap: yes*');
+  lines.push('');
+
+  return lines.join('\n');
+}
+
 // ─── Validator Types ──────────────────────────────────────────────────────────
 
 export interface ValidatorFinding {
@@ -809,6 +1194,7 @@ export function generateStateDoc(bundle: SpecBundle): string {
 
 /**
  * Read all 6 spec artifact files from a planning directory.
+ * Also reads research files from .planning/research/ directory.
  * Returns a content map keyed by artifact type.
  * Missing files return empty string (does not throw).
  */
@@ -831,6 +1217,25 @@ export function readSpecArtifacts(planningDir: string): Record<string, string> {
     }
   }
 
+  // Read research files from .planning/research/ subdirectory
+  const researchDir = path.join(planningDir, 'research');
+  const researchFileMap: Array<[string, string]> = [
+    ['ARCHITECTURE.md', 'architecture'],
+    ['ICP.md', 'icp'],
+    ['COMPETITION.md', 'competition'],
+    ['GTM.md', 'gtm'],
+    ['SUMMARY.md', 'researchSummary'],
+    ['FEATURES.md', 'features'],
+  ];
+
+  for (const [filename, key] of researchFileMap) {
+    try {
+      result[key] = fs.readFileSync(path.join(researchDir, filename), 'utf-8');
+    } catch {
+      result[key] = '';
+    }
+  }
+
   return result;
 }
 
@@ -841,7 +1246,7 @@ export interface CompileWorkflowResult {
   error?: string;
   validatorResult?: ValidatorResult;
   filesWritten: string[];
-  generated?: { project: string; requirements: string; roadmap: string; state: string };
+  generated?: { project: string; requirements: string; roadmap: string; state: string; researchSummary: string };
 }
 
 // ─── Workflow Orchestrator ────────────────────────────────────────────────────
@@ -879,7 +1284,7 @@ export function runCompileWorkflow(options: {
   // Step 3: Read spec artifacts
   const files = readSpecArtifacts(planningDir);
 
-  // Step 4: Parse into SpecBundle
+  // Step 4: Parse into SpecBundle (includes research file enrichment)
   const bundle = parseSpecBundle(
     {
       imagine: files['imagine'] ?? '',
@@ -888,16 +1293,23 @@ export function runCompileWorkflow(options: {
       nfr: files['nfr'] ?? '',
       journeys: files['journeys'] ?? '',
       integrations: files['integrations'] ?? '',
+      architecture: files['architecture'] ?? '',
+      icp: files['icp'] ?? '',
+      competition: files['competition'] ?? '',
+      gtm: files['gtm'] ?? '',
+      researchSummary: files['researchSummary'] ?? '',
+      features: files['features'] ?? '',
     },
     statePath
   );
 
-  // Step 5: Generate all 4 docs (pure functions)
+  // Step 5: Generate all 4 contract docs + GSD research bridge (pure functions)
   const generated = {
     project: generateProjectDoc(bundle),
     requirements: generateRequirementsDoc(bundle),
     roadmap: generateRoadmapDoc(bundle),
     state: generateStateDoc(bundle),
+    researchSummary: generateResearchSummary(bundle),
   };
 
   // Step 6: Run validator
@@ -909,7 +1321,7 @@ export function runCompileWorkflow(options: {
     return { passed: false, validatorResult, filesWritten: [] };
   }
 
-  // Step 8: Write all 4 docs atomically
+  // Step 8: Write all 4 contract docs atomically
   const fileOutputMap: Array<[string, string]> = [
     ['PROJECT.md', generated.project],
     ['REQUIREMENTS.md', generated.requirements],
@@ -924,6 +1336,16 @@ export function runCompileWorkflow(options: {
     filesWritten.push(filePath);
   }
 
+  // Step 8b: Write GSD research bridge SUMMARY.md to .planning/research/gswd/SUMMARY.md
+  // planningDir resolves to .planning/ in production; research/gswd/ is a subdirectory
+  const gsdResearchDir = path.join(planningDir, 'research', 'gswd');
+  if (!fs.existsSync(gsdResearchDir)) {
+    fs.mkdirSync(gsdResearchDir, { recursive: true });
+  }
+  const summaryPath = path.join(gsdResearchDir, 'SUMMARY.md');
+  safeWriteFile(summaryPath, generated.researchSummary);
+  filesWritten.push(summaryPath);
+
   // Step 9: Update state: stage_status.compile = 'done', stage = 'compile'
   updateStageStatus(statePath, 'compile', 'done');
   const state = readState(statePath);

package/lib/imagine-agents.ts

@@ -10,6 +10,7 @@
 
 import * as fs from 'node:fs';
 import type { StarterBrief } from './imagine-input.js';
+import { extractHeadline } from './render.js';
 
 // ─── Types ───────────────────────────────────────────────────────────────────
 
@@ -30,6 +31,12 @@ export interface AgentResult {
 
 export type SpawnFn = (prompt: string) => Promise<string>;
 
+export type OnAgentComplete = (result: {
+  agent: string;
+  headline: string;
+  status: 'complete' | 'failed';
+}) => void;
+
 // ─── Agent Definitions ───────────────────────────────────────────────────────
 
 /**
@@ -76,7 +83,12 @@ export const IMAGINE_AGENTS: AgentDefinition[] = [
  *
  * Reads agent definition file and injects StarterBrief as context.
  */
-export function buildAgentPrompt(agent: AgentDefinition, brief: StarterBrief): string {
+export function buildAgentPrompt(
+  agent: AgentDefinition,
+  brief: StarterBrief,
+  previousOutput?: string,
+  userFeedback?: string,
+): string {
   let definition: string;
   try {
     definition = fs.readFileSync(agent.definitionPath, 'utf-8');
@@ -86,13 +98,27 @@ export function buildAgentPrompt(agent: AgentDefinition, brief: StarterBrief): s
 
   const briefJson = JSON.stringify(brief, null, 2);
 
-  return `${definition}
+  let prompt = `${definition}
 
 <starter_brief>
 ${briefJson}
-</starter_brief>
+</starter_brief>`;
+
+  // Re-run augmentation (IMAGINE-03): include previous output + user feedback
+  if (previousOutput || userFeedback) {
+    prompt += '\n\n<rerun_context>';
+    if (previousOutput) {
+      prompt += `\n\n## Previous Output\nYour previous research produced the following findings. Build on these — do not start from scratch unless the user feedback explicitly asks for a different direction.\n\n${previousOutput}`;
+    }
+    if (userFeedback) {
+      prompt += `\n\n## User Feedback\nThe user was not satisfied with the previous directions and provided this feedback. Use it to refine your research:\n\n${userFeedback}`;
+    }
+    prompt += '\n</rerun_context>';
+  }
+
+  prompt += `\n\nProduce your output now. Include all required headings: ${agent.requiredHeadings.join(', ')}.`;
 
-Produce your output now. Include all required headings: ${agent.requiredHeadings.join(', ')}.`;
+  return prompt;
 }
 
 // ─── Orchestration ───────────────────────────────────────────────────────────
@@ -115,6 +141,9 @@ export async function orchestrateAgents(
   maxParallel: number,
   brief: StarterBrief,
   spawnFn: SpawnFn,
+  previousOutputs?: Record<string, string>,
+  userFeedback?: string,
+  onComplete?: OnAgentComplete,
 ): Promise<AgentResult[]> {
   const results: AgentResult[] = [];
 
@@ -126,23 +155,40 @@ export async function orchestrateAgents(
     const batchPromises = batch.map(async (agent): Promise<AgentResult> => {
       const start = Date.now();
       try {
-        const prompt = buildAgentPrompt(agent, brief);
+        const previousOutput = previousOutputs?.[agent.name];
+        const prompt = buildAgentPrompt(agent, brief, previousOutput, userFeedback);
         const content = await spawnFn(prompt);
-        return {
+        const result: AgentResult = {
           agent: agent.name,
           content,
           status: 'complete',
           duration_ms: Date.now() - start,
         };
+        if (onComplete) {
+          onComplete({
+            agent: agent.name,
+            headline: extractHeadline(result.content, agent.name),
+            status: result.status,
+          });
+        }
+        return result;
       } catch (err: unknown) {
         const message = err instanceof Error ? err.message : String(err);
-        return {
+        const result: AgentResult = {
           agent: agent.name,
           content: '',
           status: 'failed',
           error: message,
           duration_ms: Date.now() - start,
         };
+        if (onComplete) {
+          onComplete({
+            agent: agent.name,
+            headline: message || 'Agent failed',
+            status: 'failed',
+          });
+        }
+        return result;
       }
     });