clavix 2.8.2 → 3.0.1

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

@@ -0,0 +1,296 @@
+export class QualityAssessor {
+    /**
+     * Assess quality of a prompt (backward compatibility wrapper)
+     * @deprecated Use assess() method instead for full quality metrics
+     */
+    assessQuality(prompt, intent) {
+        // Create minimal IntentAnalysis from string intent
+        const intentAnalysis = {
+            primaryIntent: intent,
+            confidence: 100,
+            characteristics: {
+                hasCodeContext: false,
+                hasTechnicalTerms: false,
+                isOpenEnded: false,
+                needsStructure: false
+            }
+        };
+        // Call existing assess method with same prompt for both original and enhanced
+        const result = this.assess(prompt, prompt, intentAnalysis);
+        // Return only the numeric scores (exclude strengths and improvements arrays)
+        return {
+            clarity: result.clarity,
+            efficiency: result.efficiency,
+            structure: result.structure,
+            completeness: result.completeness,
+            actionability: result.actionability,
+            overall: result.overall
+        };
+    }
+    /**
+     * Assess quality of a prompt
+     */
+    assess(original, enhanced, intent) {
+        const clarity = this.assessClarity(enhanced, intent);
+        const efficiency = this.assessEfficiency(enhanced);
+        const structure = this.assessStructure(enhanced, intent);
+        const completeness = this.assessCompleteness(enhanced, intent);
+        const actionability = this.assessActionability(enhanced, intent);
+        const overall = this.calculateOverall({ clarity, efficiency, structure, completeness, actionability }, intent);
+        const strengths = this.identifyStrengths(enhanced, { clarity, efficiency, structure, completeness, actionability });
+        const improvements = this.identifyImprovements(original, enhanced);
+        return {
+            clarity,
+            efficiency,
+            structure,
+            completeness,
+            actionability,
+            overall,
+            strengths,
+            improvements
+        };
+    }
+    assessClarity(prompt, intent) {
+        let score = 100;
+        const lowerPrompt = prompt.toLowerCase();
+        // Check for objective statement
+        if (!this.hasObjective(prompt)) {
+            score -= 20;
+        }
+        // Check for technical specifications (for code generation)
+        if (intent.primaryIntent === 'code-generation') {
+            if (!this.hasTechStack(prompt)) {
+                score -= 15;
+            }
+            if (!this.hasOutputFormat(prompt)) {
+                score -= 15;
+            }
+        }
+        // Check for success criteria
+        if (!this.hasSuccessCriteria(prompt)) {
+            score -= 10;
+        }
+        // Check for vague language
+        const vagueTerms = ['something', 'somehow', 'maybe', 'kind of', 'sort of', 'stuff', 'things'];
+        const vagueCount = vagueTerms.filter(term => lowerPrompt.includes(term)).length;
+        score -= vagueCount * 5;
+        return Math.max(0, Math.min(100, score));
+    }
+    assessEfficiency(prompt) {
+        let score = 100;
+        // Check for pleasantries
+        const pleasantries = ['please', 'thank you', 'thanks', 'could you', 'would you'];
+        const lowerPrompt = prompt.toLowerCase();
+        const pleasantryCount = pleasantries.filter(p => lowerPrompt.includes(p)).length;
+        score -= pleasantryCount * 5;
+        // Check for fluff words
+        const fluffWords = ['very', 'really', 'just', 'basically', 'simply', 'actually', 'literally'];
+        const fluffCount = fluffWords.filter(w => lowerPrompt.includes(w)).length;
+        score -= fluffCount * 3;
+        // Calculate signal-to-noise ratio
+        const words = prompt.split(/\s+/);
+        const signalWords = this.countSignalWords(prompt);
+        const ratio = words.length > 0 ? signalWords / words.length : 0;
+        if (ratio < 0.6) {
+            score -= 30;
+        }
+        else if (ratio < 0.75) {
+            score -= 15;
+        }
+        return Math.max(0, Math.min(100, score));
+    }
+    assessStructure(prompt, intent) {
+        let score = 100;
+        // Check for logical flow: context → requirements → constraints → output
+        const hasContext = this.hasSection(prompt, ['context', 'background', 'currently']);
+        const hasRequirements = this.hasSection(prompt, ['requirement', 'need', 'should', 'must']);
+        const hasConstraints = this.hasSection(prompt, ['constraint', 'limit', 'within']);
+        const hasOutput = this.hasSection(prompt, ['output', 'result', 'deliverable', 'expected']);
+        // Penalize missing sections based on intent
+        if (intent.primaryIntent !== 'refinement' && !hasContext) {
+            score -= 20;
+        }
+        if (!hasRequirements) {
+            score -= 25;
+        }
+        if (!hasOutput) {
+            score -= 15;
+        }
+        // Check for markdown structure
+        const hasHeaders = /^#+\s+/m.test(prompt);
+        if (hasHeaders) {
+            score += 10; // Bonus for using headers
+        }
+        return Math.max(0, Math.min(100, score));
+    }
+    assessCompleteness(prompt, intent) {
+        let score = 100;
+        const lowerPrompt = prompt.toLowerCase();
+        // Intent-specific completeness checks
+        if (intent.primaryIntent === 'code-generation') {
+            if (!this.hasTechStack(prompt))
+                score -= 20;
+            if (!this.hasInputOutput(prompt))
+                score -= 20;
+            if (!this.hasEdgeCases(prompt))
+                score -= 10;
+        }
+        else if (intent.primaryIntent === 'planning') {
+            if (!this.hasProblemStatement(prompt))
+                score -= 25;
+            if (!this.hasGoal(prompt))
+                score -= 25;
+            if (!this.hasConstraints(prompt))
+                score -= 15;
+        }
+        else if (intent.primaryIntent === 'debugging') {
+            if (!lowerPrompt.includes('error'))
+                score -= 20;
+            if (!this.hasExpectedBehavior(prompt))
+                score -= 15;
+            if (!this.hasActualBehavior(prompt))
+                score -= 15;
+        }
+        return Math.max(0, Math.min(100, score));
+    }
+    assessActionability(prompt, intent) {
+        let score = 100;
+        const lowerPrompt = prompt.toLowerCase();
+        // Check for ambiguous terms
+        const ambiguousTerms = ['etc', 'and so on', 'or something', 'whatever', 'anything'];
+        const ambiguousCount = ambiguousTerms.filter(term => lowerPrompt.includes(term)).length;
+        score -= ambiguousCount * 10;
+        // Check for concrete examples
+        const hasExamples = this.hasExamples(prompt);
+        if (!hasExamples && intent.primaryIntent === 'code-generation') {
+            score -= 15;
+        }
+        // Check for clear success criteria
+        if (!this.hasSuccessCriteria(prompt)) {
+            score -= 20;
+        }
+        // Check for too many questions (makes it un-actionable)
+        const questionCount = (prompt.match(/\?/g) || []).length;
+        if (questionCount > 3) {
+            score -= questionCount * 5;
+        }
+        return Math.max(0, Math.min(100, score));
+    }
+    calculateOverall(scores, intent) {
+        // Intent-specific weights
+        if (intent.primaryIntent === 'code-generation') {
+            return (scores.clarity * 0.25 +
+                scores.completeness * 0.30 +
+                scores.actionability * 0.25 +
+                scores.efficiency * 0.10 +
+                scores.structure * 0.10);
+        }
+        else if (intent.primaryIntent === 'planning') {
+            return (scores.structure * 0.30 +
+                scores.completeness * 0.30 +
+                scores.clarity * 0.25 +
+                scores.efficiency * 0.10 +
+                scores.actionability * 0.05);
+        }
+        else if (intent.primaryIntent === 'debugging') {
+            return (scores.actionability * 0.35 +
+                scores.completeness * 0.30 +
+                scores.clarity * 0.20 +
+                scores.structure * 0.10 +
+                scores.efficiency * 0.05);
+        }
+        // Default weights
+        return (scores.clarity * 0.20 +
+            scores.efficiency * 0.15 +
+            scores.structure * 0.20 +
+            scores.completeness * 0.25 +
+            scores.actionability * 0.20);
+    }
+    identifyStrengths(prompt, scores) {
+        const strengths = [];
+        if (scores.clarity >= 85)
+            strengths.push('Clear objective and goals');
+        if (scores.efficiency >= 85)
+            strengths.push('Concise and focused');
+        if (scores.structure >= 85)
+            strengths.push('Well-structured with logical flow');
+        if (scores.completeness >= 85)
+            strengths.push('Comprehensive with all necessary details');
+        if (scores.actionability >= 85)
+            strengths.push('Immediately actionable');
+        return strengths;
+    }
+    identifyImprovements(original, enhanced) {
+        const improvements = [];
+        // This is a simplified version - in real implementation,
+        // we'd track what changed between original and enhanced
+        if (enhanced.length > original.length * 1.2) {
+            improvements.push('Added missing context and specifications');
+        }
+        if (enhanced.includes('# Objective') && !original.includes('# Objective')) {
+            improvements.push('Added clear objective statement');
+        }
+        if (enhanced.includes('# Technical Constraints') && !original.includes('# Technical Constraints')) {
+            improvements.push('Added technical context');
+        }
+        return improvements;
+    }
+    // Helper methods
+    hasObjective(prompt) {
+        return /objective|goal|purpose|need to|want to|^#+\s*objective/im.test(prompt);
+    }
+    hasTechStack(prompt) {
+        const techTerms = [
+            'python', 'javascript', 'typescript', 'java', 'rust', 'go', 'php',
+            'react', 'vue', 'angular', 'django', 'flask', 'express', 'spring'
+        ];
+        const lowerPrompt = prompt.toLowerCase();
+        return techTerms.some(term => lowerPrompt.includes(term));
+    }
+    hasOutputFormat(prompt) {
+        return /output|return|result|format|structure|response/i.test(prompt);
+    }
+    hasSuccessCriteria(prompt) {
+        return /success|criteria|metric|measure|test|verify|validate/i.test(prompt);
+    }
+    hasSection(prompt, keywords) {
+        const lowerPrompt = prompt.toLowerCase();
+        return keywords.some(keyword => lowerPrompt.includes(keyword));
+    }
+    countSignalWords(prompt) {
+        // Count words that carry meaning (not stop words)
+        const stopWords = new Set([
+            'the', 'a', 'an', 'and', 'or', 'but', 'in', 'on', 'at', 'to', 'for',
+            'of', 'with', 'by', 'from', 'as', 'is', 'was', 'are', 'were', 'been',
+            'be', 'have', 'has', 'had', 'do', 'does', 'did', 'will', 'would', 'could',
+            'should', 'may', 'might', 'can', 'this', 'that', 'these', 'those'
+        ]);
+        const words = prompt.toLowerCase().split(/\s+/);
+        return words.filter(word => !stopWords.has(word) && word.length > 2).length;
+    }
+    hasInputOutput(prompt) {
+        return /input|output|parameter|argument|return/i.test(prompt);
+    }
+    hasEdgeCases(prompt) {
+        return /edge case|empty|null|zero|negative|invalid|error/i.test(prompt);
+    }
+    hasProblemStatement(prompt) {
+        return /problem|issue|challenge|currently|pain point/i.test(prompt);
+    }
+    hasGoal(prompt) {
+        return /goal|objective|aim|purpose|achieve|accomplish/i.test(prompt);
+    }
+    hasConstraints(prompt) {
+        return /constraint|limit|must not|cannot|within|maximum|minimum/i.test(prompt);
+    }
+    hasExpectedBehavior(prompt) {
+        return /expected|should|supposed to|intended/i.test(prompt);
+    }
+    hasActualBehavior(prompt) {
+        return /actual|currently|instead|but|however|getting/i.test(prompt);
+    }
+    hasExamples(prompt) {
+        return /example|for instance|such as|like|e\.g\.|```/i.test(prompt);
+    }
+}
+//# sourceMappingURL=quality-assessor.js.map

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

@@ -0,0 +1,81 @@
+export type PromptIntent = 'code-generation' | 'planning' | 'refinement' | 'debugging' | 'documentation' | 'prd-generation';
+export type QualityDimension = 'clarity' | 'efficiency' | 'structure' | 'completeness' | 'actionability';
+export type ImpactLevel = 'low' | 'medium' | 'high';
+export type OptimizationMode = 'fast' | 'deep';
+export interface IntentAnalysis {
+    primaryIntent: PromptIntent;
+    confidence: number;
+    characteristics: {
+        hasCodeContext: boolean;
+        hasTechnicalTerms: boolean;
+        isOpenEnded: boolean;
+        needsStructure: boolean;
+    };
+    suggestedMode?: OptimizationMode;
+}
+export interface QualityMetrics {
+    clarity: number;
+    efficiency: number;
+    structure: number;
+    completeness: number;
+    actionability: number;
+    overall: number;
+    strengths: string[];
+    improvements: string[];
+    remainingIssues?: string[];
+}
+export interface Improvement {
+    dimension: QualityDimension;
+    description: string;
+    impact: ImpactLevel;
+}
+export interface PatternContext {
+    intent: IntentAnalysis;
+    mode: OptimizationMode;
+    originalPrompt: string;
+}
+export interface PatternResult {
+    enhancedPrompt: string;
+    improvement: Improvement;
+    applied: boolean;
+}
+export interface PatternSummary {
+    name: string;
+    description: string;
+    impact: ImpactLevel;
+}
+export interface OptimizationResult {
+    original: string;
+    enhanced: string;
+    intent: IntentAnalysis;
+    quality: QualityMetrics;
+    improvements: Improvement[];
+    appliedPatterns: PatternSummary[];
+    mode: OptimizationMode;
+    processingTimeMs: number;
+}
+export interface AlternativeApproach {
+    title: string;
+    description: string;
+    prompt: string;
+}
+export interface AlternativeStructure {
+    type: 'step-by-step' | 'template-based' | 'example-driven';
+    title: string;
+    content: string;
+}
+export interface ValidationItem {
+    description: string;
+    checked: boolean;
+}
+export interface EdgeCase {
+    scenario: string;
+    consideration: string;
+}
+export interface DeepModeExtras {
+    alternatives: AlternativeApproach[];
+    structures: AlternativeStructure[];
+    validation: ValidationItem[];
+    edgeCases: EdgeCase[];
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/core/intelligence/types.js

@@ -0,0 +1,3 @@
+// Core types for the universal prompt intelligence system
+export {};
+//# sourceMappingURL=types.js.map

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

@@ -0,0 +1,31 @@
+import { IntentDetector } from './intent-detector.js';
+import { PatternLibrary } from './pattern-library.js';
+import { QualityAssessor } from './quality-assessor.js';
+import { OptimizationResult, OptimizationMode } from './types.js';
+export declare class UniversalOptimizer {
+    private intentDetector;
+    private patternLibrary;
+    private qualityAssessor;
+    constructor(intentDetector?: IntentDetector, patternLibrary?: PatternLibrary, qualityAssessor?: QualityAssessor);
+    /**
+     * Optimize a prompt using the universal intelligence system
+     */
+    optimize(prompt: string, mode: OptimizationMode): Promise<OptimizationResult>;
+    /**
+     * Determine if deep mode should be recommended (for fast mode results)
+     */
+    shouldRecommendDeepMode(result: OptimizationResult): boolean;
+    /**
+     * Get recommendation message for user
+     */
+    getRecommendation(result: OptimizationResult): string | null;
+    /**
+     * Get statistics about the optimizer
+     */
+    getStatistics(): {
+        totalPatterns: number;
+        fastModePatterns: number;
+        deepModePatterns: number;
+    };
+}
+//# sourceMappingURL=universal-optimizer.d.ts.map

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

@@ -0,0 +1,118 @@
+import { IntentDetector } from './intent-detector.js';
+import { PatternLibrary } from './pattern-library.js';
+import { QualityAssessor } from './quality-assessor.js';
+export class UniversalOptimizer {
+    intentDetector;
+    patternLibrary;
+    qualityAssessor;
+    constructor(intentDetector, patternLibrary, qualityAssessor) {
+        this.intentDetector = intentDetector || new IntentDetector();
+        this.patternLibrary = patternLibrary || new PatternLibrary();
+        this.qualityAssessor = qualityAssessor || new QualityAssessor();
+    }
+    /**
+     * Optimize a prompt using the universal intelligence system
+     */
+    async optimize(prompt, mode) {
+        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 3: Apply patterns sequentially
+        let enhanced = prompt;
+        const improvements = [];
+        const appliedPatterns = [];
+        const context = {
+            intent,
+            mode,
+            originalPrompt: prompt
+        };
+        for (const pattern of patterns) {
+            try {
+                const result = pattern.apply(enhanced, context);
+                if (result.applied) {
+                    enhanced = result.enhancedPrompt;
+                    improvements.push(result.improvement);
+                    appliedPatterns.push({
+                        name: pattern.name,
+                        description: pattern.description,
+                        impact: result.improvement.impact
+                    });
+                }
+            }
+            catch (error) {
+                // Log error but continue with other patterns
+                console.error(`Error applying pattern ${pattern.id}:`, error);
+            }
+        }
+        // Step 4: Assess quality
+        const quality = this.qualityAssessor.assess(prompt, enhanced, intent);
+        // Step 5: Calculate processing time
+        const processingTimeMs = Date.now() - startTime;
+        return {
+            original: prompt,
+            enhanced,
+            intent,
+            quality,
+            improvements,
+            appliedPatterns,
+            mode,
+            processingTimeMs
+        };
+    }
+    /**
+     * Determine if deep mode should be recommended (for fast mode results)
+     */
+    shouldRecommendDeepMode(result) {
+        // Planning tasks benefit from deep mode
+        if (result.intent.primaryIntent === 'planning') {
+            return true;
+        }
+        // Low quality score suggests need for deep analysis
+        if (result.quality.overall < 65) {
+            return true;
+        }
+        // Open-ended tasks without clear structure
+        if (result.intent.characteristics.isOpenEnded && result.intent.characteristics.needsStructure) {
+            return true;
+        }
+        // Very short prompts with low completeness
+        if (result.original.length < 50 && result.quality.completeness < 70) {
+            return true;
+        }
+        return false;
+    }
+    /**
+     * Get recommendation message for user
+     */
+    getRecommendation(result) {
+        if (result.mode === 'fast' && this.shouldRecommendDeepMode(result)) {
+            return 'This prompt would benefit from comprehensive analysis. Run: /clavix:deep for alternative approaches and validation checklist';
+        }
+        if (result.quality.overall >= 90) {
+            return 'Excellent! Your prompt is AI-ready.';
+        }
+        if (result.quality.overall >= 80) {
+            return 'Good quality. Ready to use!';
+        }
+        if (result.quality.overall >= 70) {
+            return 'Decent quality. Consider the improvements listed above.';
+        }
+        return null;
+    }
+    /**
+     * Get statistics about the optimizer
+     */
+    getStatistics() {
+        const totalPatterns = this.patternLibrary.getPatternCount();
+        const fastModePatterns = this.patternLibrary.getPatternsByMode('fast').length;
+        const deepModePatterns = this.patternLibrary.getPatternsByMode('deep').length;
+        return {
+            totalPatterns,
+            fastModePatterns,
+            deepModePatterns
+        };
+    }
+}
+//# sourceMappingURL=universal-optimizer.js.map

package/dist/core/prd-generator.d.ts

@@ -63,11 +63,11 @@ export declare class PrdGenerator {
     /**
      * Generate full PRD document
      */
-    private generateFullPrd;
+    generateFullPrd(data: Record<string, unknown>, outputPath: string): Promise<void>;
     /**
      * Generate quick PRD document
      */
-    private generateQuickPrd;
+    generateQuickPrd(data: Record<string, unknown>, outputPath: string): Promise<void>;
     /**
      * Format timestamp for display
      */

package/dist/core/task-manager.js

@@ -130,7 +130,7 @@ export class TaskManager {
      * Generate phases from core features with intelligent grouping
      * CRITICAL FIX: Group related features instead of 1 phase per bullet
      */
-    generatePhasesFromCoreFeatures(coreContent, options) {
+    generatePhasesFromCoreFeatures(coreContent, _options) {
         const bullets = this.extractListItems(coreContent);
         if (bullets.length === 0) {
             return [];
@@ -188,7 +188,6 @@ export class TaskManager {
             'Integration & Release': [],
         };
         features.forEach((feature) => {
-            const lower = feature.toLowerCase();
             // Config/setup phase
             if (/\b(config|configuration|setup|install|package|tsconfig|dependencies|environment)\b/i.test(feature)) {
                 groups['Configuration & Setup'].push(feature);
@@ -291,7 +290,6 @@ export class TaskManager {
      */
     buildFeatureTaskDescriptions(feature) {
         const formattedFeature = this.formatInlineText(feature);
-        const featureLower = feature.toLowerCase();
         // Detect task type
         const isConfig = /\b(config|configuration|setup|install|update.*json|tsconfig|package\.json)\b/i.test(feature);
         const isTest = /\b(test|testing|coverage|validation|verify)\b/i.test(feature);
@@ -627,6 +625,7 @@ export class TaskManager {
                 const checkbox = task.completed ? '[x]' : '[ ]';
                 const reference = task.prdReference ? ` (ref: ${task.prdReference})` : '';
                 content += `- ${checkbox} ${task.description}${reference}\n`;
+                content += `  Task ID: ${task.id}\n`;
             }
             content += '\n';
         }
@@ -653,7 +652,8 @@ export class TaskManager {
         const lines = content.split('\n');
         let currentPhase = null;
         let taskCounter = 0;
-        for (const line of lines) {
+        for (let i = 0; i < lines.length; i++) {
+            const line = lines[i];
             // Check for phase header (## Phase Name)
             const phaseMatch = line.match(/^##\s+(.+)$/);
             if (phaseMatch) {
@@ -674,8 +674,21 @@ export class TaskManager {
                 const description = taskMatch[2].trim();
                 const reference = taskMatch[3]?.trim();
                 taskCounter++;
+                // Check next line for Task ID
+                let taskId;
+                const nextLine = i + 1 < lines.length ? lines[i + 1] : null;
+                const taskIdMatch = nextLine?.trim().match(/^Task ID:\s+(.+)$/);
+                if (taskIdMatch) {
+                    // Use Task ID from file (preferred)
+                    taskId = taskIdMatch[1].trim();
+                    i++; // Skip the Task ID line in next iteration
+                }
+                else {
+                    // Fallback: regenerate ID from phase name (backward compatibility)
+                    taskId = `${this.sanitizeId(currentPhase.name)}-${taskCounter}`;
+                }
                 currentPhase.tasks.push({
-                    id: `${this.sanitizeId(currentPhase.name)}-${taskCounter}`,
+                    id: taskId,
                     description,
                     phase: currentPhase.name,
                     completed,

package/dist/templates/agents/agents.md

@@ -12,8 +12,8 @@ Use these instructions when your agent can only read documentation (no slash-com
 | Command | Purpose |
 | --- | --- |
 | `clavix init` | Interactive setup. Select providers and generate documentation/command files. |
-| `clavix fast "<prompt>"` | CLEAR (C/L/E) analysis with improved prompt output. CLI auto-saves to `.clavix/outputs/prompts/fast/`. When using slash commands, agent must save manually per template instructions. |
-| `clavix deep "<prompt>"` | Full CLEAR (C/L/E/A/R) analysis, alternative variations, validation checklists. CLI auto-saves to `.clavix/outputs/prompts/deep/`. When using slash commands, agent must save manually per template instructions. |
+| `clavix fast "<prompt>"` | Quick prompt optimization with quality assessment (Clarity, Efficiency, Structure, Completeness, Actionability). CLI auto-saves to `.clavix/outputs/prompts/fast/`. When using slash commands, agent must save manually per template instructions. |
+| `clavix deep "<prompt>"` | Comprehensive analysis with alternatives, edge cases, and validation checklists. CLI auto-saves to `.clavix/outputs/prompts/deep/`. When using slash commands, agent must save manually per template instructions. |
 | `clavix execute [--latest]` | Execute saved prompts from fast/deep optimization. Interactive selection or `--latest` for most recent. |
 | `clavix prompts list` | View all saved prompts with status (NEW, EXECUTED, OLD, STALE) and storage statistics. |
 | `clavix prompts clear` | Manage prompt cleanup. Supports `--executed`, `--stale`, `--fast`, `--deep`, `--all` flags. |