VIBN Frontend for Coolify deployment

lib/types/phase-handoff.ts

@@ -0,0 +1,257 @@
+/**
+ * Phase Handoff Protocol
+ * 
+ * Defines the structured handoff between phases in the Vibn workflow.
+ * Each phase (extraction, vision, mvp, marketing) produces a handoff that:
+ * - Declares confidence and readiness for next phase
+ * - Separates confirmed facts from uncertain/missing items
+ * - Provides questions to resolve ambiguity
+ * - References source evidence
+ */
+
+/**
+ * Phase identifier for handoffs
+ */
+export type PhaseType = 'collector' | 'extraction' | 'vision' | 'mvp' | 'marketing';
+
+/**
+ * Structured handoff between phases
+ * 
+ * Produced by each phase agent to communicate confidence, gaps, and questions
+ * to the next phase or back to the user.
+ */
+export interface PhaseHandoff {
+  /** Which phase produced this handoff */
+  phase: PhaseType;
+  
+  /** Is this phase ready to hand off to the next one? */
+  readyForNextPhase: boolean;
+  
+  /** Overall confidence score (0-1) for this phase's outputs */
+  confidence: number;
+  
+  /** Items that are confirmed and high-confidence */
+  confirmed: Record<string, any>;
+  
+  /** Items that are uncertain or low-confidence */
+  uncertain: Record<string, any>;
+  
+  /** Items that are completely missing or unknown */
+  missing: string[];
+  
+  /** Questions for the user to resolve gaps or ambiguity */
+  questionsForUser: string[];
+  
+  /** References to source knowledge items or extractions that support this handoff */
+  sourceEvidence: string[];
+  
+  /** Version of the handoff schema (for future evolution) */
+  version: string;
+  
+  /** When this handoff was created */
+  timestamp: string;
+  
+  /** Optional metadata specific to this phase */
+  metadata?: Record<string, any>;
+}
+
+/**
+ * Handoff from the Collector phase
+ * 
+ * After gathering project materials, confirm readiness for extraction.
+ */
+export interface CollectorPhaseHandoff extends PhaseHandoff {
+  phase: 'collector';
+  
+  /** Checklist status */
+  confirmed: {
+    /** Has user uploaded documents? */
+    hasDocuments?: boolean;
+    
+    /** Number of documents uploaded */
+    documentCount?: number;
+    
+    /** Has user connected GitHub repo? */
+    githubConnected?: boolean;
+    
+    /** GitHub repo full name (e.g., 'user/repo') */
+    githubRepo?: string;
+    
+    /** Has user installed browser extension and linked to project? */
+    extensionLinked?: boolean;
+  };
+  
+  /** Items the user said "no" or "not yet" to */
+  uncertain: {
+    /** User declined or hasn't set up extension */
+    extensionDeclined?: boolean;
+    
+    /** User doesn't have a GitHub repo yet */
+    noGithubYet?: boolean;
+  };
+  
+  /** What's missing before moving to extraction */
+  missing: string[]; // e.g., ["documents", "github repo", "extension"]
+}
+
+/**
+ * Handoff from the Extraction phase
+ * 
+ * After analyzing all chat_extractions, summarize what's known about the product.
+ */
+export interface ExtractionPhaseHandoff extends PhaseHandoff {
+  phase: 'extraction';
+  
+  /** High-confidence product signals */
+  confirmed: {
+    /** Product one-liner (if clear) */
+    oneLiner?: string;
+    
+    /** Core problem statement */
+    problemStatement?: string;
+    
+    /** Target user personas */
+    targetUsers?: string[];
+    
+    /** Confirmed features */
+    features?: string[];
+    
+    /** Known tech stack */
+    techStack?: string[];
+  };
+  
+  /** Low-confidence or conflicting signals */
+  uncertain: {
+    /** Ambiguous or conflicting features */
+    features?: string[];
+    
+    /** Unclear business model */
+    businessModel?: string;
+  };
+  
+  /** What's missing to build a solid product model */
+  missing: string[]; // e.g., ["target market size", "pricing strategy"]
+}
+
+/**
+ * Handoff from the Vision phase
+ * 
+ * After creating canonicalProductModel, declare what's locked vs tentative.
+ */
+export interface VisionPhaseHandoff extends PhaseHandoff {
+  phase: 'vision';
+  
+  confirmed: {
+    /** Core value proposition (locked) */
+    valueProposition?: string;
+    
+    /** Primary user persona (locked) */
+    primaryPersona?: string;
+    
+    /** Must-have features for MVP */
+    mustHaveFeatures?: string[];
+  };
+  
+  uncertain: {
+    /** Nice-to-have features (not decided for MVP) */
+    niceToHaveFeatures?: string[];
+    
+    /** Unclear scope decisions */
+    scopeDecisions?: string[];
+  };
+  
+  missing: string[]; // e.g., ["competitive analysis", "pricing model"]
+}
+
+/**
+ * Handoff from the MVP phase
+ * 
+ * After creating mvpPlan, declare what's ready to build vs needs clarification.
+ */
+export interface MVPPhaseHandoff extends PhaseHandoff {
+  phase: 'mvp';
+  
+  confirmed: {
+    /** Locked feature scope */
+    featureScope?: string[];
+    
+    /** Tech stack decisions */
+    techStack?: string[];
+    
+    /** Build timeline estimate */
+    timelineEstimate?: string;
+  };
+  
+  uncertain: {
+    /** Features with unclear requirements */
+    unclearFeatures?: string[];
+    
+    /** Technical risks or unknowns */
+    technicalRisks?: string[];
+  };
+  
+  missing: string[]; // e.g., ["API design", "database schema"]
+}
+
+/**
+ * Handoff from the Marketing phase
+ * 
+ * After creating marketingPlan, declare launch readiness.
+ */
+export interface MarketingPhaseHandoff extends PhaseHandoff {
+  phase: 'marketing';
+  
+  confirmed: {
+    /** Launch channels */
+    launchChannels?: string[];
+    
+    /** Target launch date */
+    launchDate?: string;
+    
+    /** Marketing messaging */
+    messaging?: string;
+  };
+  
+  uncertain: {
+    /** Unconfirmed distribution channels */
+    uncertainChannels?: string[];
+    
+    /** Budget constraints */
+    budgetConstraints?: string;
+  };
+  
+  missing: string[]; // e.g., ["landing page copy", "email sequences"]
+}
+
+/**
+ * Union type for all phase handoffs
+ */
+export type AnyPhaseHandoff =
+  | CollectorPhaseHandoff
+  | ExtractionPhaseHandoff
+  | VisionPhaseHandoff
+  | MVPPhaseHandoff
+  | MarketingPhaseHandoff;
+
+/**
+ * Helper to create a minimal phase handoff
+ */
+export function createPhaseHandoff(
+  phase: PhaseType,
+  partial: Partial<PhaseHandoff>
+): PhaseHandoff {
+  return {
+    phase,
+    readyForNextPhase: false,
+    confidence: 0.5,
+    confirmed: {},
+    uncertain: {},
+    missing: [],
+    questionsForUser: [],
+    sourceEvidence: [],
+    version: '1.0',
+    timestamp: new Date().toISOString(),
+    ...partial,
+  };
+}
+