gswd 0.1.0

package/lib/imagine-input.ts

@@ -0,0 +1,242 @@
+/**
+ * GSWD Imagine Input Module — Input collection with file parsing and intake building
+ *
+ * Two input paths converge to a single StarterBrief interface:
+ * 1. parseIdeaFile: Parse @idea.md into a starter brief
+ * 2. buildFromIntake: Build from 3-question intake answers
+ *
+ * Schema: GSWD_SPEC.md Section 8.2, Steps 1-2
+ */
+
+import * as fs from 'node:fs';
+
+// ─── Types ───────────────────────────────────────────────────────────────────
+
+export interface StarterBrief {
+  vision: string;        // What the product does / core value prop
+  target_user: string;   // Who it's for — ICP signal
+  why_now: string;       // Why build this now — timing/opportunity
+  raw_themes: string[];  // Key themes extracted from input
+  source: 'file' | 'intake';
+}
+
+export interface IntakeAnswers {
+  vision: string;
+  user: string;
+  whyNow: string;
+}
+
+export interface ValidationResult {
+  valid: boolean;
+  missing: string[];
+}
+
+// ─── Helpers ─────────────────────────────────────────────────────────────────
+
+/**
+ * Find the first sentence containing any of the given keywords.
+ * Returns the full sentence or null if no match.
+ */
+function findSentenceWithKeywords(content: string, keywords: string[]): string | null {
+  // Split into sentences (rough: split on . ! ? followed by space or end)
+  const sentences = content.split(/(?<=[.!?])\s+/);
+  const lowerKeywords = keywords.map(k => k.toLowerCase());
+
+  for (const sentence of sentences) {
+    const lower = sentence.toLowerCase();
+    for (const keyword of lowerKeywords) {
+      if (lower.includes(keyword)) {
+        return sentence.trim();
+      }
+    }
+  }
+  return null;
+}
+
+/**
+ * Extract the first meaningful paragraph (>20 chars, not a heading).
+ */
+function extractFirstParagraph(content: string): string {
+  const lines = content.split('\n');
+  let paragraph = '';
+
+  for (const line of lines) {
+    const trimmed = line.trim();
+    // Skip headings and empty lines
+    if (trimmed.startsWith('#') || trimmed === '') {
+      if (paragraph.length > 20) return paragraph.trim();
+      paragraph = '';
+      continue;
+    }
+    paragraph += (paragraph ? ' ' : '') + trimmed;
+  }
+
+  return paragraph.length > 20 ? paragraph.trim() : '';
+}
+
+/**
+ * Extract raw themes from content: headings, bullets, bold text.
+ * Deduplicates and limits to 20 items.
+ */
+function extractThemes(content: string): string[] {
+  const themes = new Set<string>();
+  const lines = content.split('\n');
+
+  for (const line of lines) {
+    const trimmed = line.trim();
+
+    // Headings (strip # prefix)
+    if (trimmed.startsWith('#')) {
+      const heading = trimmed.replace(/^#+\s*/, '').trim();
+      if (heading.length > 2) themes.add(heading);
+    }
+
+    // Bullet points (strip - or * prefix)
+    if (/^[-*]\s+/.test(trimmed)) {
+      const bullet = trimmed.replace(/^[-*]\s+/, '').trim();
+      if (bullet.length > 2) themes.add(bullet);
+    }
+
+    // Numbered items
+    if (/^\d+[.)]\s+/.test(trimmed)) {
+      const item = trimmed.replace(/^\d+[.)]\s+/, '').trim();
+      if (item.length > 2) themes.add(item);
+    }
+  }
+
+  // Also extract bold text (**text**)
+  const boldRegex = /\*\*([^*]+)\*\*/g;
+  let match: RegExpExecArray | null;
+  while ((match = boldRegex.exec(content)) !== null) {
+    const bold = match[1].trim();
+    if (bold.length > 2) themes.add(bold);
+  }
+
+  return Array.from(themes).slice(0, 20);
+}
+
+/**
+ * Extract themes from intake answers by splitting on delimiters.
+ */
+function extractIntakeThemes(combined: string): string[] {
+  const themes = new Set<string>();
+
+  // Split on commas, semicolons, and " and " conjunctions
+  const parts = combined.split(/[,;]|\s+and\s+/i);
+
+  for (const part of parts) {
+    const trimmed = part.trim();
+    // Filter out very short fragments and common filler words
+    if (trimmed.length > 3) {
+      themes.add(trimmed);
+    }
+  }
+
+  return Array.from(themes).slice(0, 20);
+}
+
+// ─── Public API ──────────────────────────────────────────────────────────────
+
+/**
+ * Parse an @idea.md file into a StarterBrief.
+ *
+ * Extracts vision, target user, timing, and themes from freeform markdown.
+ * Falls back to first 200 chars if specific fields can't be extracted.
+ * Throws on empty or non-existent files.
+ */
+export function parseIdeaFile(filePath: string): StarterBrief {
+  // Read file
+  let content: string;
+  try {
+    content = fs.readFileSync(filePath, 'utf-8');
+  } catch (err: unknown) {
+    const message = err instanceof Error ? err.message : String(err);
+    throw new Error(`Cannot read idea file "${filePath}": ${message}`);
+  }
+
+  // Check for empty file
+  if (content.trim().length < 10) {
+    throw new Error(`Idea file "${filePath}" is too short (< 10 chars). Provide a more detailed description.`);
+  }
+
+  const fallback = content.trim().slice(0, 200);
+
+  // Extract vision: first heading content or first paragraph
+  const headingMatch = content.match(/^#+\s+(.+)$/m);
+  let vision = headingMatch ? headingMatch[1].trim() : '';
+  if (!vision || vision.length <= 20) {
+    const para = extractFirstParagraph(content);
+    vision = para || fallback;
+  }
+
+  // Extract target user
+  const userKeywords = ['for', 'target', 'customer', 'audience', 'users', 'people who', 'designed for', 'built for'];
+  let target_user = findSentenceWithKeywords(content, userKeywords) || '';
+  if (!target_user) {
+    target_user = fallback;
+  }
+
+  // Extract why now
+  const whyNowKeywords = ['because', 'opportunity', 'problem', 'pain', 'frustration', 'gap', 'trend', 'growing', 'increasing'];
+  let why_now = findSentenceWithKeywords(content, whyNowKeywords) || '';
+  if (!why_now) {
+    why_now = fallback;
+  }
+
+  // Extract themes
+  const raw_themes = extractThemes(content);
+
+  return {
+    vision,
+    target_user,
+    why_now,
+    raw_themes,
+    source: 'file',
+  };
+}
+
+/**
+ * Build a StarterBrief from 3-question intake answers.
+ *
+ * Maps: vision -> vision, user -> target_user, whyNow -> why_now.
+ * Extracts themes by splitting answers on delimiters.
+ */
+export function buildFromIntake(answers: IntakeAnswers): StarterBrief {
+  const combined = `${answers.vision}, ${answers.user}, ${answers.whyNow}`;
+  const raw_themes = extractIntakeThemes(combined);
+
+  return {
+    vision: answers.vision.trim(),
+    target_user: answers.user.trim(),
+    why_now: answers.whyNow.trim(),
+    raw_themes,
+    source: 'intake',
+  };
+}
+
+/**
+ * Validate that a StarterBrief has sufficient signal for research agents.
+ *
+ * Checks: vision > 10 chars, target_user > 5 chars, why_now > 5 chars, raw_themes >= 1.
+ */
+export function validateBrief(brief: StarterBrief): ValidationResult {
+  const missing: string[] = [];
+
+  if (!brief.vision || brief.vision.length <= 10) {
+    missing.push('vision');
+  }
+  if (!brief.target_user || brief.target_user.length <= 5) {
+    missing.push('target_user');
+  }
+  if (!brief.why_now || brief.why_now.length <= 5) {
+    missing.push('why_now');
+  }
+  if (!brief.raw_themes || brief.raw_themes.length < 1) {
+    missing.push('raw_themes');
+  }
+
+  return {
+    valid: missing.length === 0,
+    missing,
+  };
+}

package/lib/imagine-synthesis.ts

@@ -0,0 +1,402 @@
+/**
+ * GSWD Imagine Synthesis Module — Direction synthesis and auto-mode scoring
+ *
+ * Combines research from 5 agents into 3 direction options.
+ * Provides auto-mode scoring (pain x willingness-to-pay x reachability)
+ * for unattended decision-making per GSWD_SPEC Section 8.2 Step 4 and Section 10.
+ *
+ * Schema: GSWD_SPEC.md Section 8.2 Steps 4-5, Section 10
+ */
+
+import type { AgentResult } from './imagine-agents.js';
+
+// ─── Types ───────────────────────────────────────────────────────────────────
+
+export interface Direction {
+  label: string;           // "Direction 1: [Name]"
+  icp_summary: string;     // Who this targets
+  problem_framing: string; // The problem being solved
+  wedge: string;           // MVP boundary / entry point
+  differentiator: string;  // What makes this unique
+  risks: string[];         // Top 2-3 risks for this direction
+}
+
+export interface AutoDecision {
+  type: string;        // 'icp' | 'wedge' | 'direction' | 'metric'
+  chosen: string;      // What was selected
+  rationale: string;   // Why — human-readable
+  score?: number;      // Numeric score if applicable
+  recorded_at: string; // ISO timestamp
+}
+
+export interface SynthesisResult {
+  proposed: Direction;       // Primary recommendation
+  alternatives: Direction[]; // 2 alternatives
+  agent_warnings: string[];  // Any agents that failed or had issues
+  raw_agent_outputs: Record<string, string>; // agent name -> content
+}
+
+export interface ScoreEntry {
+  label: string;
+  score: number;
+  rationale: string;
+}
+
+export interface ScoreResult {
+  index: number;
+  scores: ScoreEntry[];
+}
+
+// ─── Keyword Lists for Scoring ──────────────────────────────────────────────
+
+const PAIN_KEYWORDS = [
+  'pain', 'frustration', 'struggle', 'hate', 'waste', 'broken',
+  'manual', 'slow', 'expensive', 'tedious', 'annoying', 'difficult',
+  'complex', 'error-prone', 'time-consuming', 'inefficient',
+];
+
+const WTP_KEYWORDS = [
+  'pay', 'budget', 'spend', 'invest', 'subscribe', 'cost',
+  'pricing', 'premium', 'revenue', 'monetize', 'purchase',
+  'willing to pay', 'price point', 'subscription',
+];
+
+const REACHABILITY_KEYWORDS = [
+  'community', 'forum', 'slack', 'twitter', 'meetup', 'conference',
+  'newsletter', 'open source', 'reddit', 'discord', 'linkedin',
+  'github', 'youtube', 'blog', 'podcast', 'channel',
+];
+
+// ─── Internal Helpers ────────────────────────────────────────────────────────
+
+/**
+ * Count keyword occurrences in text (case-insensitive).
+ * Returns a score clamped to [0, 10].
+ */
+function countKeywords(text: string, keywords: string[]): number {
+  const lower = text.toLowerCase();
+  let count = 0;
+  for (const kw of keywords) {
+    // Count all occurrences of each keyword
+    let idx = 0;
+    while (true) {
+      const found = lower.indexOf(kw, idx);
+      if (found === -1) break;
+      count++;
+      idx = found + kw.length;
+    }
+  }
+  // Clamp to 0-10 range
+  return Math.min(10, count);
+}
+
+/**
+ * Extract content for a specific agent from the results array.
+ * Returns empty string if agent not found or failed.
+ */
+function getAgentContent(results: AgentResult[], agentName: string): string {
+  const result = results.find(r => r.agent === agentName);
+  if (!result || result.status === 'failed') return '';
+  return result.content;
+}
+
+/**
+ * Parse direction sections from brainstorm-alternatives output.
+ * Looks for ## Direction 1/2/3 headings and extracts sub-fields.
+ */
+function parseDirectionSections(content: string): { label: string; body: string }[] {
+  const directions: { label: string; body: string }[] = [];
+  // Match ## Direction N: ... or ## Direction N — ...
+  const regex = /^##\s+(Direction\s+\d+[:\s—–-]*[^\n]*)/gm;
+  const matches: { label: string; index: number }[] = [];
+
+  let match: RegExpExecArray | null;
+  while ((match = regex.exec(content)) !== null) {
+    matches.push({ label: match[1].trim(), index: match.index });
+  }
+
+  for (let i = 0; i < matches.length; i++) {
+    const start = matches[i].index;
+    const end = i + 1 < matches.length ? matches[i + 1].index : content.length;
+    const body = content.slice(start, end).trim();
+    directions.push({ label: matches[i].label, body });
+  }
+
+  return directions;
+}
+
+/**
+ * Extract a named field from a direction body.
+ * Looks for **FieldName:** pattern.
+ */
+function extractField(body: string, fieldName: string): string {
+  const regex = new RegExp(`\\*\\*${fieldName}:\\*\\*\\s*(.+?)(?=\\n\\*\\*|$)`, 'is');
+  const match = body.match(regex);
+  return match ? match[1].trim() : '';
+}
+
+/**
+ * Build a Direction from parsed section data, enriched with ICP and risk data.
+ */
+function buildDirection(
+  label: string,
+  body: string,
+  icpContent: string,
+  risksContent: string,
+): Direction {
+  const icp = extractField(body, 'ICP') || extractIcpSummary(icpContent);
+  const problem = extractField(body, 'Problem') || 'See agent research outputs';
+  const wedge = extractField(body, 'Wedge') || extractField(body, 'MVP scope') || 'To be refined';
+  const differentiator = extractField(body, 'Differentiator') || 'To be refined';
+  const riskField = extractField(body, 'Risk');
+  const risks = riskField ? [riskField] : extractRiskList(risksContent);
+
+  return { label, icp_summary: icp, problem_framing: problem, wedge, differentiator, risks };
+}
+
+/**
+ * Extract a short ICP summary from the icp-persona agent output.
+ */
+function extractIcpSummary(content: string): string {
+  if (!content) return 'ICP data unavailable (agent failed)';
+  // Try to find ## ICP Profile section and grab first meaningful line
+  const profileMatch = content.match(/##\s*ICP Profile\s*\n+([\s\S]*?)(?=\n##|\n$|$)/);
+  if (profileMatch) {
+    const lines = profileMatch[1].trim().split('\n').filter(l => l.trim().length > 0);
+    return lines.slice(0, 2).join('; ') || content.slice(0, 200);
+  }
+  return content.slice(0, 200);
+}
+
+/**
+ * Extract risk items from the devils-advocate agent output.
+ */
+function extractRiskList(content: string): string[] {
+  if (!content) return ['Risk data unavailable (agent failed)'];
+  const risksMatch = content.match(/##\s*Risks\s*\n+([\s\S]*?)(?=\n##|$)/);
+  if (risksMatch) {
+    const lines = risksMatch[1].trim().split('\n')
+      .filter(l => l.trim().startsWith('-') || l.trim().startsWith('*'))
+      .map(l => l.replace(/^[-*]\s*/, '').trim())
+      .filter(l => l.length > 0);
+    return lines.slice(0, 3);
+  }
+  return ['See devils-advocate output for risk details'];
+}
+
+// ─── Synthesis ──────────────────────────────────────────────────────────────
+
+/**
+ * Synthesize 5 agent results into 3 direction options.
+ *
+ * Handles missing agent data gracefully — failed agents produce degraded
+ * output with warnings, not crashes.
+ */
+export function synthesizeDirections(agentResults: AgentResult[]): SynthesisResult {
+  const warnings: string[] = [];
+  const rawOutputs: Record<string, string> = {};
+
+  // Collect raw outputs and track failures
+  for (const result of agentResults) {
+    if (result.status === 'complete') {
+      rawOutputs[result.agent] = result.content;
+    } else {
+      warnings.push(`Agent '${result.agent}' failed: ${result.error || 'unknown error'}`);
+    }
+  }
+
+  // Extract content per agent
+  const marketContent = getAgentContent(agentResults, 'market-researcher');
+  const icpContent = getAgentContent(agentResults, 'icp-persona');
+  const positioningContent = getAgentContent(agentResults, 'positioning');
+  const brainstormContent = getAgentContent(agentResults, 'brainstorm-alternatives');
+  const risksContent = getAgentContent(agentResults, 'devils-advocate');
+
+  let proposed: Direction;
+  let alternatives: Direction[];
+
+  if (brainstormContent) {
+    // Parse 3 directions from brainstorm agent
+    const sections = parseDirectionSections(brainstormContent);
+
+    if (sections.length >= 3) {
+      proposed = buildDirection(sections[0].label, sections[0].body, icpContent, risksContent);
+      alternatives = [
+        buildDirection(sections[1].label, sections[1].body, icpContent, risksContent),
+        buildDirection(sections[2].label, sections[2].body, icpContent, risksContent),
+      ];
+    } else if (sections.length >= 1) {
+      // Partial parse — use what we have
+      proposed = buildDirection(sections[0].label, sections[0].body, icpContent, risksContent);
+      alternatives = sections.slice(1).map(s => buildDirection(s.label, s.body, icpContent, risksContent));
+      // Fill missing alternatives with degraded entries
+      while (alternatives.length < 2) {
+        alternatives.push(buildDegradedDirection(alternatives.length + 2, icpContent, positioningContent, risksContent));
+      }
+      warnings.push('Brainstorm agent produced fewer than 3 directions; some alternatives are degraded');
+    } else {
+      // No parseable directions — build fully degraded
+      proposed = buildDegradedDirection(1, icpContent, positioningContent, risksContent);
+      alternatives = [
+        buildDegradedDirection(2, icpContent, positioningContent, risksContent),
+        buildDegradedDirection(3, icpContent, positioningContent, risksContent),
+      ];
+      warnings.push('Could not parse directions from brainstorm agent output');
+    }
+  } else {
+    // Brainstorm agent failed entirely — build from remaining data
+    proposed = buildDegradedDirection(1, icpContent, positioningContent, risksContent);
+    alternatives = [
+      buildDegradedDirection(2, icpContent, positioningContent, risksContent),
+      buildDegradedDirection(3, icpContent, positioningContent, risksContent),
+    ];
+    if (!warnings.some(w => w.includes('brainstorm-alternatives'))) {
+      warnings.push('Brainstorm-alternatives agent data unavailable; directions are degraded');
+    }
+  }
+
+  // Enrich proposed direction with positioning data
+  if (positioningContent && proposed.differentiator === 'To be refined') {
+    const vpMatch = positioningContent.match(/##\s*Value Proposition\s*\n+([\s\S]*?)(?=\n##|$)/);
+    if (vpMatch) {
+      const firstLine = vpMatch[1].trim().split('\n')[0];
+      if (firstLine) proposed.differentiator = firstLine;
+    }
+  }
+
+  return { proposed, alternatives, agent_warnings: warnings, raw_agent_outputs: rawOutputs };
+}
+
+/**
+ * Build a degraded direction when brainstorm data is unavailable.
+ */
+function buildDegradedDirection(
+  num: number,
+  icpContent: string,
+  positioningContent: string,
+  risksContent: string,
+): Direction {
+  const icp = extractIcpSummary(icpContent);
+  const differentiator = positioningContent
+    ? extractValueProp(positioningContent)
+    : 'Requires manual definition';
+  const risks = extractRiskList(risksContent);
+
+  return {
+    label: `Direction ${num}: Requires manual elaboration`,
+    icp_summary: icp,
+    problem_framing: 'Derived from available agent data — needs founder input',
+    wedge: 'To be defined',
+    differentiator,
+    risks,
+  };
+}
+
+/**
+ * Extract value proposition from positioning agent output.
+ */
+function extractValueProp(content: string): string {
+  const vpMatch = content.match(/##\s*Value Proposition\s*\n+([\s\S]*?)(?=\n##|$)/);
+  if (vpMatch) {
+    const firstLine = vpMatch[1].trim().split('\n')[0];
+    if (firstLine) return firstLine;
+  }
+  return 'See positioning agent output';
+}
+
+// ─── Scoring ────────────────────────────────────────────────────────────────
+
+/**
+ * Score directions using pain x willingness-to-pay x reachability heuristic.
+ *
+ * Uses keyword counting as a proxy since these are text-derived signals.
+ * Formula: pain * 0.4 + wtp * 0.3 + reachability * 0.3
+ *
+ * Per GSWD_SPEC: "choose ICP with highest pain x willingness-to-pay x reachability score"
+ */
+export function scoreIcpOptions(directions: Direction[]): ScoreResult {
+  const scores: ScoreEntry[] = directions.map(dir => {
+    // Combine all text fields for keyword analysis
+    const text = [
+      dir.icp_summary,
+      dir.problem_framing,
+      dir.wedge,
+      dir.differentiator,
+      ...dir.risks,
+    ].join(' ');
+
+    const painScore = countKeywords(text, PAIN_KEYWORDS);
+    const wtpScore = countKeywords(text, WTP_KEYWORDS);
+    const reachScore = countKeywords(text, REACHABILITY_KEYWORDS);
+
+    const composite = painScore * 0.4 + wtpScore * 0.3 + reachScore * 0.3;
+    // Round to 2 decimal places
+    const score = Math.round(composite * 100) / 100;
+
+    return {
+      label: dir.label,
+      score,
+      rationale: `Pain: ${painScore}/10, WTP: ${wtpScore}/10, Reachability: ${reachScore}/10 => weighted ${score}`,
+    };
+  });
+
+  // Sort descending by score
+  scores.sort((a, b) => b.score - a.score);
+
+  // Find index in original array of highest-scoring direction
+  const topLabel = scores[0]?.label;
+  const index = directions.findIndex(d => d.label === topLabel);
+
+  return { index: index >= 0 ? index : 0, scores };
+}
+
+// ─── Auto Selection ─────────────────────────────────────────────────────────
+
+/**
+ * Auto-select the best direction and generate decision records.
+ *
+ * Per GSWD_SPEC Section 8.2 Auto behavior:
+ * - Choose ICP with highest pain x WTP x reachability score
+ * - Choose wedge with smallest scope that still hits an "aha"
+ * - Record decisions as Auto-chosen with rationale
+ */
+export function autoSelectDirection(
+  synthesis: SynthesisResult,
+): { selected: Direction; decisions: AutoDecision[] } {
+  const allDirections = [synthesis.proposed, ...synthesis.alternatives];
+  const scoreResult = scoreIcpOptions(allDirections);
+
+  const selected = allDirections[scoreResult.index];
+  const topScore = scoreResult.scores[0];
+  const now = new Date().toISOString();
+
+  const decisions: AutoDecision[] = [
+    {
+      type: 'direction',
+      chosen: selected.label,
+      rationale: `Auto-selected as highest-scoring direction. ${topScore.rationale}`,
+      score: topScore.score,
+      recorded_at: now,
+    },
+    {
+      type: 'icp',
+      chosen: selected.icp_summary,
+      rationale: `ICP from ${selected.label} scored highest on pain x WTP x reachability composite`,
+      recorded_at: now,
+    },
+    {
+      type: 'wedge',
+      chosen: selected.wedge,
+      rationale: `Wedge selected as smallest scope delivering the "aha" moment from ${selected.label}`,
+      recorded_at: now,
+    },
+    {
+      type: 'metric',
+      chosen: 'Activation rate, week-1 retention',
+      rationale: 'Default metrics aligned with wedge strategy per GSWD_SPEC auto-mode policy',
+      recorded_at: now,
+    },
+  ];
+
+  return { selected, decisions };
+}