gswd 1.0.0 → 1.1.0

package/dist/lib/imagine-synthesis.js

@@ -0,0 +1,453 @@
+"use strict";
+/**
+ * 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
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AGENT_DISPLAY_NAMES = void 0;
+exports.synthesizeDirections = synthesizeDirections;
+exports.scoreIcpOptions = scoreIcpOptions;
+exports.buildResearchSummary = buildResearchSummary;
+exports.autoSelectDirection = autoSelectDirection;
+/**
+ * User-friendly display names for imagine agents.
+ */
+exports.AGENT_DISPLAY_NAMES = {
+    'market-researcher': 'Market Landscape',
+    'icp-persona': 'Ideal Customer',
+    'positioning': 'Positioning and GTM',
+    'brainstorm-alternatives': 'Product Directions',
+    'devils-advocate': 'Risks and Challenges',
+};
+// ─── 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, keywords) {
+    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, agentName) {
+    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) {
+    const directions = [];
+    // Match ## Direction N: ... or ## Direction N — ...
+    const regex = /^##\s+(Direction\s+\d+[:\s—–-]*[^\n]*)/gm;
+    const matches = [];
+    let match;
+    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, fieldName) {
+    const regex = new RegExp(`\\*\\*${fieldName}:\\*\\*\\s*(.+?)(?=\\n\\*\\*|$)`, 'is');
+    const match = body.match(regex);
+    return match ? match[1].trim() : '';
+}
+/**
+ * Build evidence-based rationale bullets by cross-referencing agent content.
+ * Returns 2-4 bullets traceable to specific agent findings.
+ */
+function buildRationale(directionBody, marketContent, icpContent, positioningContent) {
+    const rationale = [];
+    // Extract market evidence
+    if (marketContent) {
+        const marketMatch = marketContent.match(/##\s*Market (?:Overview|Gaps?)\s*\n+([\s\S]*?)(?=\n##|$)/);
+        if (marketMatch) {
+            const firstBullet = marketMatch[1].trim().split('\n')
+                .filter(l => l.trim().startsWith('-') || l.trim().startsWith('*'))
+                .map(l => l.replace(/^[-*]\s*/, '').trim())
+                .find(l => l.length > 10);
+            if (firstBullet) {
+                rationale.push(`Market evidence: ${firstBullet}`);
+            }
+        }
+    }
+    // Extract ICP evidence
+    if (icpContent) {
+        const painMatch = icpContent.match(/##\s*Pain Points?\s*\n+([\s\S]*?)(?=\n##|$)/);
+        if (painMatch) {
+            const firstPain = painMatch[1].trim().split('\n')
+                .filter(l => l.trim().startsWith('-') || l.trim().startsWith('*'))
+                .map(l => l.replace(/^[-*]\s*/, '').trim())
+                .find(l => l.length > 10);
+            if (firstPain) {
+                rationale.push(`ICP insight: ${firstPain}`);
+            }
+        }
+    }
+    // Extract positioning evidence
+    if (positioningContent) {
+        const vpMatch = positioningContent.match(/##\s*Value Proposition\s*\n+([\s\S]*?)(?=\n##|$)/);
+        if (vpMatch) {
+            const firstLine = vpMatch[1].trim().split('\n')[0];
+            if (firstLine && firstLine.length > 10) {
+                rationale.push(`Competitive advantage: ${firstLine}`);
+            }
+        }
+    }
+    // Extract direction-specific evidence from the body itself
+    const diffField = extractField(directionBody, 'Differentiator');
+    if (diffField && diffField.length > 10 && rationale.length < 4) {
+        rationale.push(`Direction differentiator: ${diffField}`);
+    }
+    // Ensure at least one rationale bullet
+    if (rationale.length === 0) {
+        rationale.push('Rationale unavailable — agent data incomplete');
+    }
+    return rationale;
+}
+/**
+ * Build a Direction from parsed section data, enriched with ICP and risk data.
+ */
+function buildDirection(label, body, icpContent, risksContent, marketContent, positioningContent) {
+    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);
+    const rationale = buildRationale(body, marketContent || '', icpContent, positioningContent || '');
+    return { label, icp_summary: icp, problem_framing: problem, wedge, differentiator, risks, rationale };
+}
+/**
+ * Extract a short ICP summary from the icp-persona agent output.
+ */
+function extractIcpSummary(content) {
+    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) {
+    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.
+ */
+function synthesizeDirections(agentResults) {
+    const warnings = [];
+    const rawOutputs = {};
+    // 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;
+    let alternatives;
+    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, marketContent, positioningContent);
+            alternatives = [
+                buildDirection(sections[1].label, sections[1].body, icpContent, risksContent, marketContent, positioningContent),
+                buildDirection(sections[2].label, sections[2].body, icpContent, risksContent, marketContent, positioningContent),
+            ];
+        }
+        else if (sections.length >= 1) {
+            // Partial parse — use what we have
+            proposed = buildDirection(sections[0].label, sections[0].body, icpContent, risksContent, marketContent, positioningContent);
+            alternatives = sections.slice(1).map(s => buildDirection(s.label, s.body, icpContent, risksContent, marketContent, positioningContent));
+            // 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, icpContent, positioningContent, risksContent) {
+    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,
+        rationale: ['Rationale unavailable — insufficient agent data'],
+    };
+}
+/**
+ * Extract value proposition from positioning agent output.
+ */
+function extractValueProp(content) {
+    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"
+ */
+function scoreIcpOptions(directions) {
+    const scores = 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 };
+}
+// ─── Research Summary ────────────────────────────────────────────────────────
+/**
+ * Extract takeaway bullets from agent content.
+ * Looks for bullet items under headings, returns up to maxItems.
+ */
+function extractTakeaways(content, maxItems = 5) {
+    if (!content)
+        return [];
+    const bullets = [];
+    const lines = content.split('\n');
+    for (const line of lines) {
+        const trimmed = line.trim();
+        if (/^[-*]\s+/.test(trimmed) && trimmed.length > 10) {
+            bullets.push(trimmed.replace(/^[-*]\s+/, ''));
+            if (bullets.length >= maxItems)
+                break;
+        }
+    }
+    return bullets;
+}
+/**
+ * Build structured research summary from agent results.
+ * Each section: agent display name, 3-5 takeaway bullets, bridging paragraph.
+ * Product-contextualized using brief.vision and brief.target_user.
+ */
+function buildResearchSummary(agentResults, brief) {
+    const sections = [];
+    for (const result of agentResults) {
+        const displayName = exports.AGENT_DISPLAY_NAMES[result.agent] || result.agent;
+        if (result.status === 'failed' || !result.content) {
+            sections.push({
+                agentName: result.agent,
+                displayName,
+                takeaways: ['Agent failed — no findings available'],
+                bridge: `These findings could not shape the directions below due to agent failure.`,
+            });
+            continue;
+        }
+        const takeaways = extractTakeaways(result.content);
+        // Ensure at least 3 takeaways; pad with content excerpts if needed
+        if (takeaways.length < 3) {
+            const lines = result.content.split('\n')
+                .filter(l => l.trim().length > 20 && !l.trim().startsWith('#'))
+                .slice(0, 3 - takeaways.length);
+            for (const line of lines) {
+                takeaways.push(line.trim().slice(0, 150));
+            }
+        }
+        // Build product-contextualized bridge paragraph
+        const userCtx = brief.target_user || 'target users';
+        const visionCtx = brief.vision || 'the product';
+        const bridge = `These findings shaped the directions below by revealing how ${visionCtx} can best serve ${userCtx} in this domain.`;
+        sections.push({
+            agentName: result.agent,
+            displayName,
+            takeaways: takeaways.slice(0, 5),
+            bridge,
+        });
+    }
+    return sections;
+}
+// ─── 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
+ */
+function autoSelectDirection(synthesis) {
+    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 = [
+        {
+            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 };
+}

package/dist/lib/imagine.d.ts

@@ -0,0 +1,56 @@
+/**
+ * GSWD Imagine Workflow Orchestrator
+ *
+ * Full pipeline: input -> agents -> synthesis -> gate -> artifacts -> state
+ * Implements GSWD_SPEC Section 8.2 end-to-end.
+ *
+ * Both interactive and auto modes are supported:
+ * - Interactive: presents direction checkpoint, awaits selection
+ * - Auto: scores directions via pain x WTP x reachability, selects highest
+ *
+ * Schema: GSWD_SPEC.md Section 8.2
+ */
+import type { IntakeAnswers } from './imagine-input.js';
+import type { SpawnFn } from './imagine-agents.js';
+import type { Direction, AutoDecision, ResearchSummarySection } from './imagine-synthesis.js';
+import type { GateResult } from './imagine-gate.js';
+export interface ImagineOptions {
+    ideaFilePath?: string;
+    intakeAnswers?: IntakeAnswers;
+    autoMode?: boolean;
+    skipResearch?: boolean;
+    planningDir?: string;
+    configPath?: string;
+    spawnFn?: SpawnFn;
+    selectedDirectionIndex?: number;
+    previousAgentOutputs?: Record<string, string>;
+    userFeedback?: string;
+    visionStatement?: string;
+}
+export interface ImagineResult {
+    status: 'complete' | 'gate_failed' | 'error';
+    artifacts_written: string[];
+    gate_result?: GateResult;
+    auto_decisions?: AutoDecision[];
+    selected_direction?: Direction;
+    research_summary?: ResearchSummarySection[];
+    vision_statement?: string;
+    agent_headlines?: Array<{
+        agent: string;
+        headline: string;
+        status: 'complete' | 'failed';
+    }>;
+    error?: string;
+}
+/**
+ * Run the Imagine workflow end-to-end.
+ *
+ * Implements GSWD_SPEC Section 8.2 Steps 1-6:
+ * 1. Load state and config
+ * 2. Collect founder input (file or intake)
+ * 3. Spawn parallel agents
+ * 4. Synthesize into proposed direction + 2 alternatives
+ * 5. Decision gate (must freeze)
+ * 6. Write docs and update state
+ */
+export declare function runImagine(options: ImagineOptions): Promise<ImagineResult>;