clavix 4.3.1 → 4.4.0

package/dist/core/intelligence/patterns/topic-coherence-analyzer.js

@@ -0,0 +1,282 @@
+import { BasePattern } from './base-pattern.js';
+/**
+ * v4.4 Conversational Pattern: TopicCoherenceAnalyzer
+ *
+ * Detects topic shifts and multi-topic conversations.
+ * Helps organize scattered discussions into coherent themes.
+ * Enhanced with expanded topic dictionary and better detection.
+ */
+export class TopicCoherenceAnalyzer extends BasePattern {
+    id = 'topic-coherence-analyzer';
+    name = 'TopicCoherenceAnalyzer';
+    description = 'Detects topic shifts and multi-topic conversations';
+    applicableIntents = ['summarization', 'planning'];
+    mode = 'deep';
+    priority = 6;
+    // Expanded topic indicators (~15 topics with more keywords)
+    topicIndicators = {
+        'User Interface': [
+            'ui',
+            'interface',
+            'design',
+            'layout',
+            'button',
+            'form',
+            'page',
+            'screen',
+            'component',
+            'modal',
+            'dialog',
+            'navigation',
+            'menu',
+            'sidebar',
+            'header',
+            'footer',
+        ],
+        'Backend/API': [
+            'api',
+            'backend',
+            'server',
+            'endpoint',
+            'route',
+            'controller',
+            'service',
+            'middleware',
+            'rest',
+            'graphql',
+            'websocket',
+        ],
+        Database: [
+            'database',
+            'db',
+            'schema',
+            'table',
+            'query',
+            'migration',
+            'model',
+            'orm',
+            'sql',
+            'nosql',
+            'index',
+            'relationship',
+        ],
+        Authentication: [
+            'auth',
+            'login',
+            'password',
+            'session',
+            'token',
+            'permission',
+            'role',
+            'oauth',
+            'jwt',
+            'sso',
+            'mfa',
+            '2fa',
+        ],
+        Performance: [
+            'performance',
+            'speed',
+            'cache',
+            'optimize',
+            'latency',
+            'load time',
+            'bundle',
+            'lazy',
+            'memory',
+            'cpu',
+        ],
+        Testing: [
+            'test',
+            'spec',
+            'coverage',
+            'qa',
+            'validation',
+            'unit test',
+            'integration',
+            'e2e',
+            'mock',
+            'fixture',
+        ],
+        Deployment: [
+            'deploy',
+            'ci/cd',
+            'pipeline',
+            'release',
+            'environment',
+            'production',
+            'staging',
+            'docker',
+            'kubernetes',
+        ],
+        'User Experience': [
+            'ux',
+            'usability',
+            'accessibility',
+            'user flow',
+            'journey',
+            'experience',
+            'onboarding',
+            'feedback',
+        ],
+        'Business Logic': [
+            'business',
+            'workflow',
+            'process',
+            'rule',
+            'logic',
+            'requirement',
+            'feature',
+            'use case',
+        ],
+        Integration: [
+            'integration',
+            'third-party',
+            'external',
+            'webhook',
+            'sync',
+            'connect',
+            'import',
+            'export',
+        ],
+        Security: [
+            'security',
+            'encryption',
+            'vulnerability',
+            'xss',
+            'csrf',
+            'injection',
+            'sanitize',
+            'audit',
+        ],
+        Analytics: [
+            'analytics',
+            'tracking',
+            'metrics',
+            'dashboard',
+            'report',
+            'insight',
+            'data',
+            'statistics',
+        ],
+        'Error Handling': [
+            'error',
+            'exception',
+            'fallback',
+            'retry',
+            'timeout',
+            'failure',
+            'recovery',
+            'logging',
+        ],
+        Documentation: [
+            'documentation',
+            'docs',
+            'readme',
+            'guide',
+            'tutorial',
+            'api docs',
+            'comment',
+            'jsdoc',
+        ],
+        'State Management': [
+            'state',
+            'store',
+            'redux',
+            'context',
+            'global state',
+            'local state',
+            'persist',
+            'hydrate',
+        ],
+    };
+    apply(prompt, _context) {
+        // Detect topics in the content
+        const topics = this.detectTopics(prompt);
+        // If single topic or already organized, skip
+        if (topics.length <= 1) {
+            return {
+                enhancedPrompt: prompt,
+                improvement: {
+                    dimension: 'structure',
+                    description: 'Single coherent topic detected',
+                    impact: 'low',
+                },
+                applied: false,
+            };
+        }
+        // Check if already has topic organization
+        if (this.hasTopicOrganization(prompt)) {
+            return {
+                enhancedPrompt: prompt,
+                improvement: {
+                    dimension: 'structure',
+                    description: 'Topics already organized',
+                    impact: 'low',
+                },
+                applied: false,
+            };
+        }
+        // Add topic organization
+        const enhanced = this.organizeByTopic(prompt, topics);
+        return {
+            enhancedPrompt: enhanced,
+            improvement: {
+                dimension: 'structure',
+                description: `Organized ${topics.length} distinct topics for clarity`,
+                impact: 'medium',
+            },
+            applied: true,
+        };
+    }
+    detectTopics(prompt) {
+        const topics = [];
+        const lowerPrompt = prompt.toLowerCase();
+        for (const [topic, keywords] of Object.entries(this.topicIndicators)) {
+            const hasKeyword = keywords.some((kw) => lowerPrompt.includes(kw));
+            if (hasKeyword) {
+                topics.push(topic);
+            }
+        }
+        return topics;
+    }
+    hasTopicOrganization(prompt) {
+        // Check for existing topic headers
+        const topicHeaders = /##\s*(user interface|backend|database|auth|performance|testing|deploy)/i;
+        return topicHeaders.test(prompt);
+    }
+    organizeByTopic(prompt, topics) {
+        // Add topic summary at the beginning
+        let organized = '### Topics Covered\n';
+        organized += 'This conversation touches on multiple areas:\n';
+        organized += topics.map((t, i) => `${i + 1}. **${t}**`).join('\n');
+        organized += '\n\n---\n\n';
+        // Extract content relevant to each topic
+        organized += '### Discussion by Topic\n\n';
+        for (const topic of topics) {
+            const relevantContent = this.extractTopicContent(prompt, topic);
+            if (relevantContent) {
+                organized += `#### ${topic}\n`;
+                organized += relevantContent + '\n\n';
+            }
+        }
+        organized += '---\n\n**Full Context:**\n' + prompt;
+        return organized;
+    }
+    extractTopicContent(prompt, topic) {
+        const keywords = this.topicIndicators[topic] || [];
+        const sentences = this.extractSentences(prompt);
+        const relevantSentences = sentences.filter((sentence) => {
+            const lower = sentence.toLowerCase();
+            return keywords.some((kw) => lower.includes(kw));
+        });
+        if (relevantSentences.length === 0) {
+            return `- Discussion related to ${topic}`;
+        }
+        return relevantSentences
+            .slice(0, 3)
+            .map((s) => `- ${s.trim()}`)
+            .join('\n');
+    }
+}
+//# sourceMappingURL=topic-coherence-analyzer.js.map

package/dist/core/intelligence/patterns/user-persona-enricher.d.ts

@@ -0,0 +1,22 @@
+import { BasePattern } from './base-pattern.js';
+import { PromptIntent, OptimizationMode, PatternContext, PatternResult } from '../types.js';
+/**
+ * v4.3.2 PRD Pattern: UserPersonaEnricher
+ *
+ * Adds missing user context and personas to PRD content.
+ * Ensures the "who" is clearly defined alongside the "what".
+ */
+export declare class UserPersonaEnricher extends BasePattern {
+    id: string;
+    name: string;
+    description: string;
+    applicableIntents: PromptIntent[];
+    mode: OptimizationMode | 'both';
+    priority: number;
+    apply(prompt: string, _context: PatternContext): PatternResult;
+    private hasUserContext;
+    private needsUserContext;
+    private addUserPersona;
+    private inferUserType;
+}
+//# sourceMappingURL=user-persona-enricher.d.ts.map

package/dist/core/intelligence/patterns/user-persona-enricher.js

@@ -0,0 +1,124 @@
+import { BasePattern } from './base-pattern.js';
+/**
+ * v4.3.2 PRD Pattern: UserPersonaEnricher
+ *
+ * Adds missing user context and personas to PRD content.
+ * Ensures the "who" is clearly defined alongside the "what".
+ */
+export class UserPersonaEnricher extends BasePattern {
+    id = 'user-persona-enricher';
+    name = 'UserPersonaEnricher';
+    description = 'Adds missing user context and personas';
+    applicableIntents = ['prd-generation', 'planning'];
+    mode = 'deep';
+    priority = 6;
+    apply(prompt, _context) {
+        // Check if user/persona context already exists
+        if (this.hasUserContext(prompt)) {
+            return {
+                enhancedPrompt: prompt,
+                improvement: {
+                    dimension: 'completeness',
+                    description: 'User context already present',
+                    impact: 'low',
+                },
+                applied: false,
+            };
+        }
+        // Check if this is PRD-like content that needs users
+        if (!this.needsUserContext(prompt)) {
+            return {
+                enhancedPrompt: prompt,
+                improvement: {
+                    dimension: 'completeness',
+                    description: 'Content does not require user persona',
+                    impact: 'low',
+                },
+                applied: false,
+            };
+        }
+        // Add user persona section
+        const enhanced = this.addUserPersona(prompt);
+        return {
+            enhancedPrompt: enhanced,
+            improvement: {
+                dimension: 'completeness',
+                description: 'Added user persona context (who will use this)',
+                impact: 'medium',
+            },
+            applied: true,
+        };
+    }
+    hasUserContext(prompt) {
+        const userKeywords = [
+            'user persona',
+            'target user',
+            'end user',
+            'user profile',
+            'audience',
+            'stakeholder',
+            'as a user',
+            'users can',
+            'users will',
+            'for users',
+            'customer',
+            'developer',
+            'admin',
+            'target audience',
+        ];
+        return this.hasSection(prompt, userKeywords);
+    }
+    needsUserContext(prompt) {
+        // PRD-like content that talks about features but not users
+        const featureKeywords = [
+            'feature',
+            'build',
+            'create',
+            'implement',
+            'functionality',
+            'should',
+            'must',
+            'requirement',
+        ];
+        return this.hasSection(prompt, featureKeywords);
+    }
+    addUserPersona(prompt) {
+        // Detect the likely user type from content
+        const userType = this.inferUserType(prompt);
+        const personaSection = `\n\n### Target Users\n` +
+            `**Primary User:** ${userType}\n` +
+            `- Goals: [What they want to achieve]\n` +
+            `- Pain Points: [Current frustrations]\n` +
+            `- Context: [When and how they'll use this]`;
+        return prompt + personaSection;
+    }
+    inferUserType(prompt) {
+        const lowerPrompt = prompt.toLowerCase();
+        // Try to infer user type from content
+        if (lowerPrompt.includes('api') ||
+            lowerPrompt.includes('sdk') ||
+            lowerPrompt.includes('library')) {
+            return 'Developers integrating with the system';
+        }
+        if (lowerPrompt.includes('admin') ||
+            lowerPrompt.includes('manage') ||
+            lowerPrompt.includes('dashboard')) {
+            return 'Administrators managing the system';
+        }
+        if (lowerPrompt.includes('e-commerce') ||
+            lowerPrompt.includes('shop') ||
+            lowerPrompt.includes('buy')) {
+            return 'Customers making purchases';
+        }
+        if (lowerPrompt.includes('content') ||
+            lowerPrompt.includes('blog') ||
+            lowerPrompt.includes('cms')) {
+            return 'Content creators and editors';
+        }
+        if (lowerPrompt.includes('mobile') || lowerPrompt.includes('app')) {
+            return 'Mobile app users';
+        }
+        return '[Define primary user type]';
+    }
+}
+//# sourceMappingURL=user-persona-enricher.js.map

package/dist/core/intelligence/quality-assessor.js

@@ -11,6 +11,8 @@ export class QualityAssessor {
         'security-review': ['scope', 'threat-model', 'compliance-requirements', 'known-issues'],
         learning: ['current-knowledge', 'learning-goal', 'preferred-depth', 'context'],
         'prd-generation': ['product-vision', 'user-personas', 'features', 'success-metrics'],
+        // v4.3.2: Conversational mode intent
+        summarization: ['conversation-context', 'key-requirements', 'constraints', 'success-criteria'],
     };
     /**
      * Assess quality of a prompt (backward compatibility wrapper)

package/dist/core/intelligence/types.d.ts

@@ -1,7 +1,9 @@
-export type PromptIntent = 'code-generation' | 'planning' | 'refinement' | 'debugging' | 'documentation' | 'prd-generation' | 'testing' | 'migration' | 'security-review' | 'learning';
+export type PromptIntent = 'code-generation' | 'planning' | 'refinement' | 'debugging' | 'documentation' | 'prd-generation' | 'testing' | 'migration' | 'security-review' | 'learning' | 'summarization';
 export type QualityDimension = 'clarity' | 'efficiency' | 'structure' | 'completeness' | 'actionability' | 'specificity';
 export type ImpactLevel = 'low' | 'medium' | 'high';
-export type OptimizationMode = 'fast' | 'deep';
+export type OptimizationMode = 'fast' | 'deep' | 'prd' | 'conversational';
+export type OptimizationPhase = 'question-validation' | 'output-generation' | 'conversation-tracking' | 'summarization';
+export type DocumentType = 'full-prd' | 'quick-prd' | 'mini-prd' | 'prompt';
 export interface IntentAnalysis {
     primaryIntent: PromptIntent;
     confidence: number;
@@ -55,6 +57,9 @@ export interface PatternContext {
     intent: IntentAnalysis;
     mode: OptimizationMode;
     originalPrompt: string;
+    phase?: OptimizationPhase;
+    documentType?: DocumentType;
+    questionId?: string;
 }
 export interface PatternResult {
     enhancedPrompt: string;

package/dist/core/intelligence/universal-optimizer.d.ts

@@ -1,7 +1,16 @@
 import { IntentDetector } from './intent-detector.js';
 import { PatternLibrary } from './pattern-library.js';
 import { QualityAssessor } from './quality-assessor.js';
-import { OptimizationResult, OptimizationMode, EscalationAnalysis } from './types.js';
+import { OptimizationResult, OptimizationMode, OptimizationPhase, DocumentType, EscalationAnalysis } from './types.js';
+/**
+ * v4.3.2: Extended context options for PRD and Conversational modes
+ */
+export interface OptimizationContextOverride {
+    phase?: OptimizationPhase;
+    documentType?: DocumentType;
+    questionId?: string;
+    intent?: string;
+}
 export declare class UniversalOptimizer {
     private intentDetector;
     private patternLibrary;
@@ -9,8 +18,24 @@ export declare class UniversalOptimizer {
     constructor(intentDetector?: IntentDetector, patternLibrary?: PatternLibrary, qualityAssessor?: QualityAssessor);
     /**
      * Optimize a prompt using Clavix Intelligence
+     * @param prompt The prompt to optimize
+     * @param mode The optimization mode
+     * @param contextOverride Optional context override for PRD/Conversational modes
+     */
+    optimize(prompt: string, mode: OptimizationMode, contextOverride?: OptimizationContextOverride): Promise<OptimizationResult>;
+    /**
+     * v4.3.2: Validate a PRD answer and provide friendly suggestions
+     * Uses adaptive threshold (< 50% quality triggers suggestions)
+     */
+    validatePRDAnswer(answer: string, questionId: string): Promise<{
+        needsClarification: boolean;
+        suggestion?: string;
+        quality: number;
+    }>;
+    /**
+     * v4.3.2: Generate a friendly, non-intrusive suggestion for low-quality answers
      */
-    optimize(prompt: string, mode: OptimizationMode): Promise<OptimizationResult>;
+    private generateFriendlySuggestion;
     /**
      * Determine if deep mode should be recommended (for fast mode results)
      * @deprecated Use analyzeEscalation() for more detailed analysis

package/dist/core/intelligence/universal-optimizer.js

@@ -12,13 +12,24 @@ export class UniversalOptimizer {
     }
     /**
      * Optimize a prompt using Clavix Intelligence
+     * @param prompt The prompt to optimize
+     * @param mode The optimization mode
+     * @param contextOverride Optional context override for PRD/Conversational modes
      */
-    async optimize(prompt, mode) {
+    async optimize(prompt, mode, contextOverride) {
         const startTime = Date.now();
-        // Step 1: Detect intent
-        const intent = this.intentDetector.analyze(prompt);
-        // Step 2: Select applicable patterns
-        const patterns = this.patternLibrary.selectPatterns(intent, mode);
+        // Step 1: Detect intent (or use override)
+        let intent = this.intentDetector.analyze(prompt);
+        if (contextOverride?.intent) {
+            intent = {
+                ...intent,
+                primaryIntent: contextOverride.intent,
+            };
+        }
+        // Step 2: Select applicable patterns using mode-aware selection
+        const patterns = mode === 'prd' || mode === 'conversational'
+            ? this.patternLibrary.selectPatternsForMode(mode, intent, contextOverride?.phase)
+            : this.patternLibrary.selectPatterns(intent, mode);
         // Step 3: Apply patterns sequentially
         let enhanced = prompt;
         const improvements = [];
@@ -27,6 +38,10 @@ export class UniversalOptimizer {
             intent,
             mode,
             originalPrompt: prompt,
+            // v4.3.2: Extended context
+            phase: contextOverride?.phase,
+            documentType: contextOverride?.documentType,
+            questionId: contextOverride?.questionId,
         };
         for (const pattern of patterns) {
             try {
@@ -61,6 +76,51 @@ export class UniversalOptimizer {
             processingTimeMs,
         };
     }
+    /**
+     * v4.3.2: Validate a PRD answer and provide friendly suggestions
+     * Uses adaptive threshold (< 50% quality triggers suggestions)
+     */
+    async validatePRDAnswer(answer, questionId) {
+        const result = await this.optimize(answer, 'prd', {
+            phase: 'question-validation',
+            questionId,
+            intent: 'prd-generation',
+        });
+        // Adaptive threshold: only suggest improvements for very vague answers
+        if (result.quality.overall < 50) {
+            return {
+                needsClarification: true,
+                suggestion: this.generateFriendlySuggestion(result, questionId),
+                quality: result.quality.overall,
+            };
+        }
+        return {
+            needsClarification: false,
+            quality: result.quality.overall,
+        };
+    }
+    /**
+     * v4.3.2: Generate a friendly, non-intrusive suggestion for low-quality answers
+     */
+    generateFriendlySuggestion(result, questionId) {
+        const suggestions = {
+            q1: ["the problem you're solving", 'why this matters', 'who benefits'],
+            q2: ['specific features', 'user actions', 'key functionality'],
+            q3: ['technologies', 'frameworks', 'constraints'],
+            q4: ["what's explicitly out of scope", 'features to avoid', 'limitations'],
+            q5: ['additional context', 'constraints', 'timeline considerations'],
+        };
+        const questionSuggestions = suggestions[questionId] || suggestions.q5;
+        // Pick the most relevant suggestion based on what's missing
+        let detail = questionSuggestions[0];
+        if (result.quality.completeness < 40) {
+            detail = questionSuggestions[Math.min(1, questionSuggestions.length - 1)];
+        }
+        if (result.quality.specificity < 40) {
+            detail = questionSuggestions[Math.min(2, questionSuggestions.length - 1)];
+        }
+        return `adding ${detail} would help`;
+    }
     /**
      * Determine if deep mode should be recommended (for fast mode results)
      * @deprecated Use analyzeEscalation() for more detailed analysis

package/dist/templates/slash-commands/_canonical/deep.md

@@ -93,6 +93,7 @@ Deep mode provides **Clavix Intelligence™** with comprehensive analysis that g
    - **migration**: Version upgrades, porting code between frameworks
    - **security-review**: Security audits, vulnerability checks
    - **learning**: Conceptual understanding, tutorials, explanations
+   - **summarization**: Extracting requirements from conversations
 
 3. **Strategic Scope Detection** (before detailed analysis):
 
@@ -178,7 +179,7 @@ Deep mode provides **Clavix Intelligence™** with comprehensive analysis that g
 
 ---
 
-## Agent Transparency (v4.1)
+## Agent Transparency (v4.4)
 
 ### Quality Output Format
 {{INCLUDE:agent-protocols/quality-output.md}}

package/dist/templates/slash-commands/_canonical/execute.md

@@ -109,7 +109,7 @@ clavix prompts clear --executed
 
 ---
 
-## Agent Transparency (v4.1)
+## Agent Transparency (v4.4)
 
 ### File Format Reference
 {{INCLUDE:agent-protocols/file-formats.md}}

package/dist/templates/slash-commands/_canonical/fast.md

@@ -91,6 +91,7 @@ Clavix provides **Clavix Intelligence™** that automatically detects intent and
    - **migration**: Version upgrades, porting code between frameworks
    - **security-review**: Security audits, vulnerability checks
    - **learning**: Conceptual understanding, tutorials, explanations
+   - **summarization**: Extracting requirements from conversations
 
 3. **Quality Assessment** - Evaluate across 6 dimensions:
 
@@ -157,7 +158,7 @@ Clavix provides **Clavix Intelligence™** that automatically detects intent and
 
 ---
 
-## Agent Transparency (v4.1)
+## Agent Transparency (v4.4)
 
 ### Quality Output Format
 {{INCLUDE:agent-protocols/quality-output.md}}

package/dist/templates/slash-commands/_canonical/implement.md

@@ -315,7 +315,7 @@ To find the task ID programmatically, read tasks.md and look for the pattern `ph
 
 ---
 
-## Agent Transparency (v4.1)
+## Agent Transparency (v4.4)
 
 ### Workflow State Detection
 {{INCLUDE:agent-protocols/state-awareness.md}}

package/dist/templates/slash-commands/_canonical/plan.md

@@ -288,7 +288,7 @@ The generated `tasks.md` will look like:
 
 ---
 
-## Agent Transparency (v4.1)
+## Agent Transparency (v4.4)
 
 ### Workflow State Detection
 {{INCLUDE:agent-protocols/state-awareness.md}}

package/dist/templates/slash-commands/_canonical/prd.md

@@ -316,7 +316,7 @@ The validation ensures generated PRDs are immediately usable for AI consumption
 
 ---
 
-## Agent Transparency (v4.1)
+## Agent Transparency (v4.4)
 
 ### Quality Output Format
 {{INCLUDE:agent-protocols/quality-output.md}}