clavix 4.11.2 → 5.0.0

package/dist/templates/slash-commands/_components/sections/file-saving-protocol.md

@@ -1,18 +1,12 @@
-## Saving the {{OUTPUT_TYPE}} (REQUIRED)
+## Saving the {{OUTPUT_TYPE}} (REQUIRED - v5 Agentic-First)
 
-After displaying the {{OUTPUT_DESC}}, you MUST save it to ensure it's available for the prompt lifecycle workflow.
+After displaying the {{OUTPUT_DESC}}, you MUST save it using your native tools.
 
-**If user ran CLI command** (`clavix {{CLI_COMMAND}} "prompt"`):
-- {{OUTPUT_TYPE}} is automatically saved ✓
-- Skip to "Executing the Saved {{OUTPUT_TYPE}}" section below
-
-**If you are executing this slash command** (`/clavix:{{SLASH_COMMAND}}`):
-- You MUST save the {{OUTPUT_TYPE}} manually
-- Follow these steps:
+**In v5, you save files directly - no CLI commands involved.**
 
 ### Step 1: Create Directory Structure
 ```bash
-mkdir -p .clavix/outputs/prompts/{{OUTPUT_DIR}}
+mkdir -p .clavix/outputs/prompts
 ```
 
 ### Step 2: Generate Unique {{OUTPUT_TYPE}} ID
@@ -21,27 +15,26 @@ Create a unique identifier using this format:
 - **Example**: `{{OUTPUT_DIR}}-20250117-143022-a3f2`
 - Use current timestamp + random 4-character suffix
 
-### Step 3: Save {{OUTPUT_TYPE}} File
+### Step 3: Save {{OUTPUT_TYPE}} File with Frontmatter
 Use the Write tool to create the {{OUTPUT_TYPE}} file at:
-- **Path**: `.clavix/outputs/prompts/{{OUTPUT_DIR}}/<{{OUTPUT_TYPE}}-id>.md`
-
-### Step 4: Update Index File
-Use the Write tool to update the index at `.clavix/outputs/prompts/{{OUTPUT_DIR}}/.index.json`:
+- **Path**: `.clavix/outputs/prompts/<{{OUTPUT_TYPE}}-id>.md`
 
-**If index file doesn't exist**, create it with:
-```json
-{
-  "version": "1.0",
-  "prompts": []
-}
-```
+**File format:**
+```markdown
+---
+id: <{{OUTPUT_TYPE}}-id>
+timestamp: <ISO-8601 timestamp>
+executed: false
+originalPrompt: "<user's original text>"
+---
 
-**Then add a new metadata entry** to the `prompts` array.
+# {{OUTPUT_TYPE}}
 
-**Important**: Read the existing index first, append the new entry to the `prompts` array, then write the updated index back.
+<content here>
+```
 
-### Step 5: Verify Saving Succeeded
+### Step 4: Verify Saving Succeeded
 Confirm:
-- File exists at `.clavix/outputs/prompts/{{OUTPUT_DIR}}/<{{OUTPUT_TYPE}}-id>.md`
-- Index file updated with new entry
+- File exists at `.clavix/outputs/prompts/<{{OUTPUT_TYPE}}-id>.md`
+- File has valid frontmatter with id, timestamp, executed fields
 - Display success message: `✓ {{OUTPUT_TYPE}} saved: <{{OUTPUT_TYPE}}-id>.md`

package/dist/templates/slash-commands/_components/sections/pattern-visibility.md

@@ -29,8 +29,8 @@ Patterns: 7 applied (comprehensive depth)
   StructureOrganizer → Reorganized into 4 sections
   TechnicalContextEnricher → Added React 18, TypeScript context
   CompletenessValidator → Flagged 3 missing requirements
-  EdgeCaseIdentifier → Added 4 edge cases (auth, network, state, browser)
-  ValidationChecklistCreator → Generated 6-item verification checklist
+  DomainContextEnricher → Added best practices for React components
+  SuccessCriteriaEnforcer → Added measurable acceptance criteria
 ```
 
 ### Pattern Impact Indicators
@@ -43,43 +43,32 @@ Patterns: 7 applied (comprehensive depth)
 
 ### Available Patterns Reference
 
-**Standard Patterns (both scopes):**
+**v4.12: Core Patterns (standard + comprehensive, scope='both'):**
 | Pattern | Priority | What It Does |
 |---------|----------|--------------|
-| ConcisenessFilter | 4 | Removes pleasantries, filler words, redundant phrases |
 | ObjectiveClarifier | 9 | Adds clear objective/goal statement if missing |
-| StructureOrganizer | 8 | Reorders into logical flow: context→requirements→constraints→output |
-| ActionabilityEnhancer | 4 | Converts vague language to specific, actionable terms |
-| TechnicalContextEnricher | 5 | Adds missing technical context (frameworks, tools, versions) |
-| CompletenessValidator | 6 | Identifies and flags missing required elements |
-| StepDecomposer | 5 | Breaks complex prompts into sequential steps |
-| ContextPrecisionBooster | 6 | Adds precise context when missing |
 | AmbiguityDetector | 9 | Identifies and flags ambiguous terms |
+| StructureOrganizer | 8 | Reorders into logical flow: context→requirements→constraints→output |
 | OutputFormatEnforcer | 7 | Adds explicit output format specifications |
 | SuccessCriteriaEnforcer | 7 | Adds measurable success criteria |
+| ContextPrecisionBooster | 6 | Adds precise context when missing |
+| CompletenessValidator | 6 | Identifies and flags missing required elements |
+| TechnicalContextEnricher | 5 | Adds missing technical context (frameworks, tools, versions) |
+| StepDecomposer | 5 | Breaks complex prompts into sequential steps |
 | DomainContextEnricher | 5 | Adds domain-specific best practices |
+| ConcisenessFilter | 4 | Removes pleasantries, filler words, redundant phrases |
+| ActionabilityEnhancer | 4 | Converts vague language to specific, actionable terms |
 
-**Comprehensive Depth Exclusive Patterns:**
+**v4.12 PRD Mode Patterns (comprehensive only):**
 | Pattern | Priority | What It Does |
 |---------|----------|--------------|
-| AlternativePhrasingGenerator | 3 | Generates 2-3 alternative prompt structures |
-| EdgeCaseIdentifier | 4 | Identifies domain-specific edge cases |
-| ValidationChecklistCreator | 3 | Creates implementation verification checklist |
-| AssumptionExplicitizer | 6 | Makes implicit assumptions explicit |
-| ScopeDefiner | 5 | Adds explicit scope boundaries |
 | PRDStructureEnforcer | 9 | Ensures PRD completeness (PRD mode only) |
-| ErrorToleranceEnhancer | 5 | Adds error handling requirements |
-| PrerequisiteIdentifier | 6 | Identifies prerequisites and dependencies |
-
-**v4.3.2 PRD Mode Patterns (comprehensive):**
-| Pattern | Priority | What It Does |
-|---------|----------|--------------|
 | RequirementPrioritizer | 7 | Separates must-have from nice-to-have requirements |
-| UserPersonaEnricher | 6 | Adds missing user context and personas |
 | SuccessMetricsEnforcer | 7 | Ensures measurable success criteria exist |
+| UserPersonaEnricher | 6 | Adds missing user context and personas |
 | DependencyIdentifier | 5 | Identifies technical and external dependencies |
 
-**v4.3.2 Conversational Mode Patterns (comprehensive):**
+**v4.12 Conversational Mode Patterns (comprehensive only):**
 | Pattern | Priority | What It Does |
 |---------|----------|--------------|
 | ConversationSummarizer | 8 | Extracts structured requirements from messages |
@@ -107,23 +96,17 @@ Skipped patterns:
 ### Pattern Categories Summary
 
 ```
-Standard (both scopes):
-  ConcisenessFilter, ObjectiveClarifier, StructureOrganizer,
-  ActionabilityEnhancer, TechnicalContextEnricher, CompletenessValidator,
-  StepDecomposer, ContextPrecisionBooster,
-  AmbiguityDetector, OutputFormatEnforcer, SuccessCriteriaEnforcer,
-  DomainContextEnricher
-
-Comprehensive only:
-  AlternativePhrasingGenerator, EdgeCaseIdentifier, ValidationChecklistCreator,
-  AssumptionExplicitizer, ScopeDefiner, PRDStructureEnforcer,
-  ErrorToleranceEnhancer, PrerequisiteIdentifier
-
-v4.3.2 PRD mode (comprehensive):
-  RequirementPrioritizer, UserPersonaEnricher, SuccessMetricsEnforcer,
-  DependencyIdentifier
-
-v4.3.2 Conversational mode (comprehensive):
+v4.12: Core patterns (standard + comprehensive, 12 patterns):
+  ObjectiveClarifier, AmbiguityDetector, StructureOrganizer,
+  OutputFormatEnforcer, SuccessCriteriaEnforcer, ContextPrecisionBooster,
+  CompletenessValidator, TechnicalContextEnricher, StepDecomposer,
+  DomainContextEnricher, ConcisenessFilter, ActionabilityEnhancer
+
+PRD mode (comprehensive only, 5 patterns):
+  PRDStructureEnforcer, RequirementPrioritizer, SuccessMetricsEnforcer,
+  UserPersonaEnricher, DependencyIdentifier
+
+Conversational mode (comprehensive only, 3 patterns):
   ConversationSummarizer, TopicCoherenceAnalyzer, ImplicitRequirementExtractor
 ```
 
@@ -131,9 +114,9 @@ v4.3.2 Conversational mode (comprehensive):
 
 | Depth | Patterns Available | Typical Applied |
 |------|-------------------|-----------------|
-| Standard | 12 patterns | 4-7 patterns |
-| Comprehensive | 27 patterns | 8-14 patterns |
-| PRD mode | 12+ patterns | 8-12 patterns |
-| Conversational | 3+ patterns | 1-3 patterns |
+| Standard | 12 patterns | 4-8 patterns |
+| Comprehensive | 20 patterns | 8-15 patterns |
+| PRD mode | 17 patterns | 8-12 patterns |
+| Conversational | 15 patterns | 6-10 patterns |
 
-**Note:** Comprehensive depth has access to all 27 patterns. Pattern selection varies by intent - some patterns only apply to specific intents (e.g., PRDStructureEnforcer only for prd-generation), so typical applied count is 8-14.
+**Note:** v4.12 has 20 total patterns after removing 7 boilerplate patterns that generated static output. Pattern selection varies by intent - some patterns only apply to specific intents (e.g., PRDStructureEnforcer only for prd-generation). Standard depth gets 12 core patterns; comprehensive adds mode-specific patterns.

package/dist/templates/slash-commands/_components/troubleshooting/file-not-saved.md

@@ -2,13 +2,12 @@
 
 **Error: Cannot create directory**
 ```bash
-mkdir -p .clavix/outputs/prompts/{{OUTPUT_DIR}}
+mkdir -p .clavix/outputs/prompts
 ```
 
-**Error: Index file corrupted or invalid JSON**
-```bash
-echo '{"version":"1.0","prompts":[]}' > .clavix/outputs/prompts/{{OUTPUT_DIR}}/.index.json
-```
+**Error: Prompt file has invalid frontmatter**
+- Re-save the file with valid YAML frontmatter
+- Ensure id, timestamp, and executed fields are present in frontmatter
 
 **Error: Duplicate {{OUTPUT_TYPE}} ID**
 - Generate a new ID with a different timestamp or random suffix

package/dist/types/config.d.ts

@@ -14,12 +14,69 @@ export interface ClavixConfig {
  * v4.4 Intelligence Configuration
  * Configure pattern behavior, enable/disable patterns, adjust priorities
  * v4.11: Removed defaultMode (fast/deep replaced by improve with auto-detection)
+ * v4.12: Added escalation thresholds configuration
  */
 export interface IntelligenceConfig {
     /** Pattern-specific settings */
     patterns?: PatternSettingsConfig;
     /** Enable verbose pattern logging */
     verbosePatternLogs?: boolean;
+    /** v4.12: Escalation threshold configuration */
+    escalation?: EscalationThresholdsConfig;
+    /** v4.12: Quality assessment weight overrides */
+    qualityWeights?: QualityWeightsConfig;
+}
+/**
+ * v4.12: Configurable escalation thresholds
+ * These control when comprehensive analysis is recommended vs standard
+ */
+export interface EscalationThresholdsConfig {
+    /**
+     * Quality score threshold for comprehensive mode (default: 75)
+     * Prompts >= this score get comprehensive analysis
+     */
+    comprehensiveAbove?: number;
+    /**
+     * Quality score threshold for standard mode floor (default: 60)
+     * Prompts between standardFloor and comprehensiveAbove get standard optimization
+     */
+    standardFloor?: number;
+    /**
+     * Intent confidence threshold for auto-proceed (default: 50)
+     * Below this, ask user to confirm intent
+     */
+    intentConfidenceMin?: number;
+    /**
+     * Escalation score threshold for strong recommendation (default: 75)
+     * Above this, strongly recommend comprehensive mode
+     */
+    strongRecommendAbove?: number;
+    /**
+     * Escalation score threshold for suggestion (default: 45)
+     * Above this, suggest comprehensive mode as option
+     */
+    suggestAbove?: number;
+}
+/**
+ * v4.12: Quality dimension weight overrides by intent
+ * Allows customizing how quality scores are weighted per intent type
+ */
+export interface QualityWeightsConfig {
+    /** Override weights for specific intents */
+    byIntent?: Record<string, QualityDimensionWeights>;
+    /** Default weights for all intents (overrides built-in defaults) */
+    defaults?: QualityDimensionWeights;
+}
+/**
+ * Weight distribution across quality dimensions (must sum to 100)
+ */
+export interface QualityDimensionWeights {
+    clarity?: number;
+    efficiency?: number;
+    structure?: number;
+    completeness?: number;
+    actionability?: number;
+    specificity?: number;
 }
 /**
  * Pattern-specific settings

package/dist/utils/legacy-command-cleanup.js

@@ -1,9 +1,34 @@
 import * as path from 'path';
 import { FileSystem } from './file-system.js';
+/**
+ * v4.12: Deprecated commands that have been replaced
+ * - fast → improve (unified with auto-depth)
+ * - deep → improve --comprehensive
+ */
+const DEPRECATED_COMMANDS = ['fast', 'deep'];
 export async function collectLegacyCommandFiles(adapter, commandNames) {
     const legacyPaths = new Set();
     const extension = adapter.fileExtension;
     const commandDir = path.resolve(adapter.getCommandPath());
+    // v4.12: Clean up deprecated fast/deep commands
+    for (const deprecatedName of DEPRECATED_COMMANDS) {
+        // Check for various naming patterns across adapters
+        const candidates = [
+            path.resolve(commandDir, `${deprecatedName}${extension}`),
+            path.resolve(commandDir, `clavix-${deprecatedName}${extension}`),
+            path.resolve(commandDir, `clavix:${deprecatedName}${extension}`),
+        ];
+        // For Claude Code with subdirectory structure
+        if (adapter.name === 'claude-code') {
+            const clavixDir = path.resolve(commandDir, 'clavix');
+            candidates.push(path.resolve(clavixDir, `${deprecatedName}${extension}`), path.resolve(clavixDir, `clavix-${deprecatedName}${extension}`));
+        }
+        for (const candidate of candidates) {
+            if (await FileSystem.exists(candidate)) {
+                legacyPaths.add(candidate);
+            }
+        }
+    }
     for (const name of commandNames) {
         const newFilePath = path.resolve(commandDir, adapter.getTargetFilename(name));
         const defaultFilePath = path.resolve(commandDir, `${name}${extension}`);
@@ -15,22 +40,24 @@ export async function collectLegacyCommandFiles(adapter, commandNames) {
             ];
             for (const candidate of oldCandidates) {
                 const resolvedCandidate = path.resolve(candidate);
-                if (resolvedCandidate !== newFilePath && await FileSystem.exists(resolvedCandidate)) {
+                if (resolvedCandidate !== newFilePath && (await FileSystem.exists(resolvedCandidate))) {
                     legacyPaths.add(resolvedCandidate);
                 }
             }
-            if (defaultFilePath !== newFilePath && await FileSystem.exists(defaultFilePath)) {
+            if (defaultFilePath !== newFilePath && (await FileSystem.exists(defaultFilePath))) {
                 legacyPaths.add(defaultFilePath);
             }
             continue;
         }
         if (adapter.name === 'gemini' || adapter.name === 'qwen') {
             const namespaced = commandDir.endsWith(path.join('commands', 'clavix'));
-            if (!namespaced && defaultFilePath !== newFilePath && await FileSystem.exists(defaultFilePath)) {
+            if (!namespaced &&
+                defaultFilePath !== newFilePath &&
+                (await FileSystem.exists(defaultFilePath))) {
                 legacyPaths.add(defaultFilePath);
             }
         }
-        else if (defaultFilePath !== newFilePath && await FileSystem.exists(defaultFilePath)) {
+        else if (defaultFilePath !== newFilePath && (await FileSystem.exists(defaultFilePath))) {
             legacyPaths.add(defaultFilePath);
         }
     }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "clavix",
-  "version": "4.11.2",
-  "description": "Clavix Intelligence™ for AI coding. Automatically optimizes prompts with intent detection, quality assessment, and adaptive patterns—no framework to learn. Works with Claude Code, Cursor, Windsurf, and 19+ other AI coding tools.",
+  "version": "5.0.0",
+  "description": "Agentic-first prompt workflows. Markdown templates that teach AI agents how to optimize prompts, create PRDs, and manage implementation. Works with Claude Code, Cursor, Windsurf, and 19+ other AI coding tools.",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -42,7 +42,7 @@
     "ai",
     "prompt",
     "prompt-optimization",
-    "prompt-intelligence",
+    "prompt-structuring",
     "intent-detection",
     "quality-assessment",
     "prd",
@@ -53,7 +53,8 @@
     "developer-tools",
     "prompt-engineering",
     "ai-coding-tools",
-    "requirements"
+    "requirements",
+    "workflow"
   ],
   "author": "ClavixDev",
   "license": "Apache-2.0",

package/dist/cli/commands/analyze.d.ts

@@ -1,17 +0,0 @@
-import { Command } from '@oclif/core';
-export default class Analyze extends Command {
-    static description: string;
-    static examples: string[];
-    static flags: {
-        pretty: import("@oclif/core/interfaces").BooleanFlag<boolean>;
-    };
-    static args: {
-        prompt: import("@oclif/core/interfaces").Arg<string, Record<string, unknown>>;
-    };
-    run(): Promise<void>;
-    /**
-     * v4.11: Calculate escalation with unified improve mode
-     */
-    private calculateEscalation;
-}
-//# sourceMappingURL=analyze.d.ts.map

package/dist/cli/commands/analyze.js

@@ -1,133 +0,0 @@
-import { Command, Args, Flags } from '@oclif/core';
-import { UniversalOptimizer } from '../../core/intelligence/index.js';
-export default class Analyze extends Command {
-    static description = 'Analyze a prompt and return structured JSON with intent, quality, and escalation data';
-    static examples = [
-        '<%= config.bin %> <%= command.id %> "Create a login page"',
-        '<%= config.bin %> <%= command.id %> "Build an API for user management" --pretty',
-    ];
-    static flags = {
-        pretty: Flags.boolean({
-            char: 'p',
-            description: 'Pretty-print the JSON output',
-            default: false,
-        }),
-    };
-    static args = {
-        prompt: Args.string({
-            description: 'The prompt to analyze',
-            required: true,
-        }),
-    };
-    async run() {
-        const { args, flags } = await this.parse(Analyze);
-        if (!args.prompt || args.prompt.trim().length === 0) {
-            const errorOutput = {
-                error: 'No prompt provided',
-                message: 'Please provide a prompt to analyze',
-            };
-            console.log(JSON.stringify(errorOutput, null, flags.pretty ? 2 : 0));
-            this.exit(1);
-            return;
-        }
-        const optimizer = new UniversalOptimizer();
-        // v4.11: Use 'improve' mode for analysis
-        const result = await optimizer.optimize(args.prompt, 'improve');
-        // Calculate escalation score and recommendation
-        const escalation = this.calculateEscalation(result);
-        // Build the analysis result
-        const analysisResult = {
-            intent: result.intent.primaryIntent,
-            confidence: result.intent.confidence,
-            quality: {
-                overall: Math.round(result.quality.overall),
-                clarity: Math.round(result.quality.clarity),
-                efficiency: Math.round(result.quality.efficiency),
-                structure: Math.round(result.quality.structure),
-                completeness: Math.round(result.quality.completeness),
-                actionability: Math.round(result.quality.actionability),
-                specificity: Math.round(result.quality.specificity ?? 0),
-            },
-            escalation,
-            characteristics: {
-                hasCodeContext: result.intent.characteristics.hasCodeContext,
-                hasTechnicalTerms: result.intent.characteristics.hasTechnicalTerms,
-                isOpenEnded: result.intent.characteristics.isOpenEnded,
-                needsStructure: result.intent.characteristics.needsStructure,
-            },
-        };
-        // Output as JSON
-        console.log(JSON.stringify(analysisResult, null, flags.pretty ? 2 : 0));
-    }
-    /**
-     * v4.11: Calculate escalation with unified improve mode
-     */
-    calculateEscalation(result) {
-        const factors = [];
-        let score = 0;
-        // Quality-based factors
-        if (result.quality.overall < 50) {
-            score += 30;
-            factors.push('low overall quality');
-        }
-        else if (result.quality.overall < 65) {
-            score += 15;
-            factors.push('moderate quality - could be improved');
-        }
-        if (result.quality.clarity < 50) {
-            score += 15;
-            factors.push('unclear objective');
-        }
-        if (result.quality.completeness < 50) {
-            score += 20;
-            factors.push('missing technical requirements');
-        }
-        if (result.quality.actionability < 50) {
-            score += 15;
-            factors.push('vague scope');
-        }
-        // Intent-based factors
-        if (result.intent.primaryIntent === 'planning') {
-            score += 15;
-            factors.push('planning intent - benefits from exploration');
-        }
-        if (result.intent.primaryIntent === 'prd-generation') {
-            score += 25;
-            factors.push('PRD generation - needs strategic planning');
-        }
-        // Characteristics-based factors
-        if (result.intent.characteristics.isOpenEnded && result.intent.characteristics.needsStructure) {
-            score += 10;
-            factors.push('open-ended without structure');
-        }
-        // Confidence-based factors
-        if (result.intent.confidence < 70) {
-            score += 10;
-            factors.push('low intent confidence');
-        }
-        // v4.11: Determine recommendation based on score and intent
-        let recommend = 'improve';
-        let recommendedDepth = 'standard';
-        if (result.intent.primaryIntent === 'prd-generation') {
-            recommend = 'prd';
-        }
-        else if (score >= 60 || result.quality.overall < 50) {
-            recommendedDepth = 'comprehensive';
-        }
-        else if (score >= 35) {
-            recommendedDepth = 'comprehensive';
-        }
-        // Check for strategic keywords that suggest PRD mode
-        const strategicIntents = ['planning', 'prd-generation', 'documentation'];
-        if (strategicIntents.includes(result.intent.primaryIntent) && score >= 50) {
-            recommend = 'prd';
-        }
-        return {
-            score: Math.min(100, score),
-            recommend,
-            recommendedDepth: recommend === 'improve' ? recommendedDepth : undefined,
-            factors,
-        };
-    }
-}
-//# sourceMappingURL=analyze.js.map

package/dist/cli/commands/archive.d.ts

@@ -1,36 +0,0 @@
-import { Command } from '@oclif/core';
-export default class Archive extends Command {
-    static description: string;
-    static examples: string[];
-    static args: {
-        project: import("@oclif/core/interfaces").Arg<string | undefined, Record<string, unknown>>;
-    };
-    static flags: {
-        list: import("@oclif/core/interfaces").BooleanFlag<boolean>;
-        force: import("@oclif/core/interfaces").BooleanFlag<boolean>;
-        yes: import("@oclif/core/interfaces").BooleanFlag<boolean>;
-        restore: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
-    };
-    run(): Promise<void>;
-    /**
-     * Interactive archive mode - show list of archivable projects
-     */
-    private interactiveArchive;
-    /**
-     * Archive a specific project by name
-     */
-    private archiveSpecificProject;
-    /**
-     * List all archived projects
-     */
-    private listArchivedProjects;
-    /**
-     * Restore an archived project
-     */
-    private restoreProject;
-    /**
-     * Display project details (helper for formatting)
-     */
-    private displayProjectInfo;
-}
-//# sourceMappingURL=archive.d.ts.map